API 简介

欢迎使用 Curosa API v1

Curosa API 允许您通过编程方式管理供应商账户、产品、订单和库存。我们的 REST API 使用标准 HTTP 方法并返回 JSON 响应。

基础 URL

所有 API 请求应首先使用沙箱环境进行测试：

https://sandbox.curosa.com/api/v1

正式系统可以通过以下地址访问：

https://curosa.com/api/v1

身份验证

Curosa API 使用 API 令牌（token）进行身份验证。您可以通过调用身份验证端点并提供供应商门户的电子邮件地址和密码来生成 API 令牌。

错误处理

当发生错误时，API 会返回相应的 HTTP 状态码和错误详情：

错误响应格式：

{
  "error": {
    "code": "invalid_parameter",
    "message": "The 'sku' field is required",
    "field": "sku"
  }
}

分页

列表端点使用基于游标（cursor）的分页，以便高效地浏览大型数据集。当数据更新频繁时，基于游标的分页能提供更好的性能和一致性。

请求页面

要获取下一页结果，请使用 cursor 查询参数，其值为上一次响应中 meta.next_cursor 字段的值：

curl --location 'https://curosa.com/api/v1/products?cursor=eyJwcm9kdWN0cy5pZCI6MTAwLCJfcG9pbnRzVG9OZXh0SXRlbXMiOnRydWV9' \
--header 'Authorization: Bearer YOUR_API_TOKEN'

分页响应格式

分页响应包含导航链接和元数据：

{
  "data": [
    {
      "sku": "T3272P287613",
      "platform_sku": "367.983.903",
      "name": "Example Product"
    }
  ],
  "links": {
    "first": null,
    "last": null,
    "prev": null,
    "next": "https://curosa.com/api/v1/products?cursor=eyJwcm9kdWN0cy5pZCI6MTAwLCJfcG9pbnRzVG9OZXh0SXRlbXMiOnRydWV9"
  },
  "meta": {
    "path": "https://curosa.com/api/v1/products",
    "per_page": 100,
    "next_cursor": "eyJwcm9kdWN0cy5pZCI6MTAwLCJfcG9pbnRzVG9OZXh0SXRlbXMiOnRydWV9",
    "prev_cursor": null
  }
}

响应字段：

• links: 用于分页的导航链接
  • first: 首页链接（对于基于游标的分页，通常为 null）
  • last: 尾页链接（对于基于游标的分页，通常为 null）
  • prev: 上一页链接（如果可用，请使用 meta.prev_cursor）
  • next: 下一页链接（如果可用，请使用 meta.next_cursor）
• meta: 分页元数据
  • path: 此端点的基础路径
  • per_page: 每页项目数（因端点而异）
  • next_cursor: 下一页的游标令牌（在 cursor 查询参数中使用）
  • prev_cursor: 上一页的游标令牌（在 cursor 查询参数中使用，如果在第一页则为 null）

页面导航

• 第一页：在不带 cursor 参数的情况下发起请求
• 下一页：在 cursor 查询参数中使用 meta.next_cursor 的值
• 上一页：在 cursor 查询参数中使用 meta.prev_cursor 的值（如果可用）
• 没有更多页面：当 meta.next_cursor 为 null 时，表示您已到达结果末尾

后续步骤

• 身份验证 - 了解如何获取和使用您的 API 令牌
• 速率限制 - 了解速率限制和最佳实践
• 产品 - 管理您的产品目录