Curosa
Supplier Portal API Reference New

Core resources

产品

在您的 Curosa 目录中检索、查看和创建产品

概述

Products（产品）端点允许您列出产品、查看单个产品以及创建新产品。您可以筛选列表结果，并使用 scope 查询参数请求额外的关联字段。

身份验证

此端点需要身份验证。请在 Authorization 标头中包含您的 API 令牌。有关获取令牌的更多信息，请参阅身份验证指南。

列出产品

检索分页的产品列表。

端点： GET https://curosa.com/api/v1/products

请求

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

查询参数

参数 类型 描述
platform_status string 按平台状态筛选：pending（待处理）、active（已激活）、inactive（未激活）、declined（已拒绝）
status string 按供应商状态筛选：active（已激活）、inactive（未激活）
search string 按 name（名称）、sku 或 platform_sku（平台 SKU）搜索
scope string 要包含的额外字段的逗号分隔列表
cursor string 用于分页的游标令牌

响应

返回 200 OK 响应：

{
    "data": [
        {
            "sku": "T3272P287613",
            "platform_sku": "367.983.903",
            "name": "Supplier Product Description",
            "status": "active",
            "platform_status": "active"
        }
    ],
    "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
    }
}

响应字段

字段 类型 描述
sku string 您的内部 SKU
platform_sku string Curosa 平台 SKU
name string 产品名称
status string 面向供应商的状态
platform_status string 平台状态
declined_reason string|null 当 platform_status 为 declined 时包含

可用的 scope 值

  • images (图片)
  • variants (变体)
  • description (描述)
  • site_pricing (站点定价)
  • distribution_centre_stock (配送中心库存)
  • factory_stock (工厂库存)
  • inbound_shipments (入库货运)

Scope 请求示例

curl --location 'https://curosa.com/api/v1/products?scope=inbound_shipments&per_page=10' \
--header 'Authorization: Bearer YOUR_API_TOKEN'

查看产品

通过 SKU 或平台 SKU 检索单个产品。

端点： GET https://curosa.com/api/v1/products/{sku_or_platform_sku}

请求

curl --location 'https://curosa.com/api/v1/products/201.228.141' \
--header 'Authorization: Bearer YOUR_API_TOKEN'

响应

返回 200 OK 响应：

{
    "data": {
        "sku": "DEMO006",
        "platform_sku": "823.115.780",
        "name": "Demo Product 6",
        "description": "This is the description of this demo product. It is required to be at least 100 chars long before it can be enriched by the Curosa Marketing Team",
        "status": "pending",
        "platform_status": "inactive",
        "images": [],
        "site_pricing": [],
        "variants": [],
        "distribution_centre_stock": [],
        "factory_stock": {
            "sku": "DEMO006",
            "platform_sku": "823.115.780",
            "stock_quantity": 50,
            "stock_quantity_allocated": 0,
            "stock_quantity_free": 50
        },
        "inbound_shipments": []
    }
}

响应字段

字段 类型 描述
sku string 您的内部 SKU
platform_sku string Curosa 平台 SKU
name string 产品名称
description string 产品描述
status string 面向供应商的状态
platform_status string 平台状态
images array 产品图片对象
site_pricing array 按站点定价
variants array 变体分组
distribution_centre_stock array 按配送中心划分的库存
factory_stock object 工厂库存摘要
inbound_shipments array 入库货运分配

创建产品

创建一个新产品。

端点： POST https://curosa.com/api/v1/products

请求

curl --location 'https://curosa.com/api/v1/products' \
--header 'Authorization: Bearer YOUR_API_TOKEN' \
--header 'Content-Type: application/json' \
--data '{
    "sku": "DEMO001",
    "name": "Demo Product 1",
    "description": "This is the description of this demo product. It is required to be at least 100 chars long before it can be enriched by the Curosa Marketing Team",
    "brand": "Demo Brand",
    "range": "Demo Range",
    "images": [
        {
            "url": "https://picsum.photos/1000/1000",
            "is_primary": true,
            "type": "lifestyle"
        }
    ],
    "site_pricing": [
        {
            "site_code": "UK",
            "price": "50.00",
            "price_currency": "GBP",
            "tax_rate_id": 1,
            "preorder_discount_percent": "0.00",
            "factory_stock_discount_percent": "0.00"
        }
    ],
    "distribution_centre_stock": [
        {
            "distribution_centre_code": "DEMO-DC",
            "stock_quantity": 50
        }
    ],
    "factory_stock": {
        "stock_quantity": 50
    }
}'

响应

返回 201 Created 响应：

{
    "data": {
        "sku": "DEMO006",
        "platform_sku": "823.115.780",
        "name": "Demo Product 6",
        "status": "pending",
        "platform_status": "inactive",
        "images": [
            {
                "id": 42789,
                "url": "https://curosa-prod.lon1.digitaloceanspaces.com/product_media/823/115/780/images/DEMO006_001.webp",
                "type": "lifestyle",
                "is_primary": true
            }
        ],
        "site_pricing": [
            {
                "site": {
                    "code": "UK",
                    "name": "United Kingdom"
                },
                "price": "50.00",
                "price_currency": "GBP"
            }
        ],
        "distribution_centre_stock": [
            {
                "distribution_centre_code": "DEMO-DC",
                "stock_quantity": 50
            }
        ],
        "factory_stock": {
            "stock_quantity": 50
        }
    }
}

速率限制

此端点组的速率限制为每小时 3,600 次请求。当前的限制和剩余请求数会在响应标头中以 x-ratelimit-limit 和 x-ratelimit-remaining 返回。