库存 - Curosa

概览

库存 (Inventory) 端点允许您获取产品的工厂库存信息。工厂库存代表在分配给特定配送中心或订单之前，存放在您的制造工厂或仓库中的可用库存。该端点提供了总库存量、已分配量和可用量（空闲量）的透明度。

理解库存数量

库存总量 (Stock Quantity)：工厂/仓库中可用的总库存。
已分配量 (Allocated Quantity)：已为特定订单预留或分配的库存。
可用量 (Free Quantity)：可供分配的可用库存 (stock_quantity - stock_quantity_allocated)。

使用此端点可以监控您的工厂库存水平，并识别可能需要补货或有超额库存可供分配的产品。

身份验证

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

列出工厂库存

获取产品的所有工厂库存水平列表。

请求

curl -X GET "https://api.curosa.com/v1/factory-stocks" \
  -H "Authorization: Bearer YOUR_API_KEY"

可选查询参数

您可以使用以下查询参数按数量范围过滤工厂库存：

stock_quantity_gte (整数，可选)：过滤库存总量大于或等于此值的产品
stock_quantity_lte (整数，可选)：过滤库存总量小于或等于此值的产品
stock_quantity_allocated_gte (整数，可选)：过滤已分配库存量大于或等于此值的产品
stock_quantity_allocated_lte (整数，可选)：过滤已分配库存量小于或等于此值的产品

带过滤器的示例：

curl -X GET "https://api.curosa.com/v1/factory-stocks?stock_quantity_gte=10&stock_quantity_lte=100" \
  -H "Authorization: Bearer YOUR_API_KEY"

响应

所有响应均以 JSON 格式返回：

{
    "data": [
        {
            "sku": "T3272P287613",
            "platform_sku": "367.983.903",
            "stock_quantity": 150,
            "stock_quantity_allocated": 0,
            "stock_quantity_free": 150
        },
        {
            "sku": "T3272P355456",
            "platform_sku": "107.871.472",
            "stock_quantity": 0,
            "stock_quantity_allocated": 0,
            "stock_quantity_free": 0
        }
    ],
    "links": {
        "first": null,
        "last": null,
        "prev": null,
        "next": "https://curosa.com/api/v1/factory-stocks?cursor=eyJmYWN0b3J5X3N0b2Nrcy5pZCI6MiwiX3BvaW50c1RvTmV4dEl0ZW1zIjp0cnVlfQ"
    },
    "meta": {
        "path": "https://curosa.com/api/v1/factory-stocks",
        "per_page": 2500,
        "next_cursor": "eyJmYWN0b3J5X3N0b2Nrcy5pZCI6MiwiX3BvaW50c1RvTmV4dEl0ZW1zIjp0cnVlfQ",
        "prev_cursor": null
    }
}

响应字段：

sku (字符串)：您的产品内部 SKU 标识符
platform_sku (字符串)：Curosa 平台的产品 SKU 标识符
stock_quantity (整数)：工厂可用的总库存量
stock_quantity_allocated (整数)：已分配给订单或配送中心的数量
stock_quantity_free (整数)：可供分配的空闲可用数量（计算公式为 stock_quantity - stock_quantity_allocated）

分页：

此端点使用基于游标的分页。响应包括：

links：用于分页的导航链接（first、last、prev、next）
meta：分页元数据
- path：此端点的基础路径
- per_page：每页条目数（默认为 2500）
- next_cursor：下一页的游标令牌（在 cursor 查询参数中使用）
- prev_cursor：前一页的游标令牌（在 cursor 查询参数中使用）

要获取下一页，请在 cursor 查询参数中包含来自 meta.next_cursor 的值：

curl -X GET "https://api.curosa.com/v1/factory-stocks?cursor=eyJmYWN0b3J5X3N0b2Nrcy5pZCI6MiwiX3BvaW50c1RvTmV4dEl0ZW1zIjp0cnVlfQ" \
  -H "Authorization: Bearer YOUR_API_KEY"

更新工厂库存水平

通过提供 SKU 和新的库存数量，更新单个产品的工厂库存数量。

请求

curl -X POST "https://api.curosa.com/v1/factory-stocks/update" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "sku": "ABC123",
    "stock_quantity": 10
  }'

请求体字段：

sku (字符串，必填)：您的产品内部 SKU 标识符
stock_quantity (整数，必填)：为此产品设置的新的总库存量

响应

响应包含成功更新的条目以及遇到的任何错误：

{
    "updated": [
        {
            "platform_sku": "880.033.390",
            "sku": "ABC123",
            "stock_quantity": 10
        }
    ],
    "errors": []
}

响应字段：

updated (数组)：成功更新的库存条目数组
- platform_sku (字符串)：Curosa 平台 SKU 标识符
- sku (字符串)：您的内部 SKU 标识符
- stock_quantity (整数)：更新后的库存数量
errors (数组)：更新失败的条目数组（如果有）
- platform_sku (字符串|null)：如果找到则为平台 SKU，否则为 null
- sku (字符串)：失败的内部 SKU 标识符
- stock_quantity (整数|null)：请求的库存数量，如果未找到产品则为 null
- error (字符串)：描述更新失败原因的错误消息（例如 "Product not found"）

带有错误的示例：

{
    "updated": [],
    "errors": [
        {
            "platform_sku": null,
            "sku": "ABC1234",
            "stock_quantity": null,
            "error": "Product not found"
        }
    ]
}

批量更新工厂库存水平

在单个请求中更新多个产品的工厂库存数量。这比为每个产品发送单独的更新请求更高效。

请求

curl -X POST "https://api.curosa.com/v1/factory-stocks/bulk-update" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '[
    {
        "sku": "ABC123",
        "stock_quantity": 10
    },
    {
        "sku": "DEF456",
        "stock_quantity": 25
    },
    {
        "sku": "GHI789",
        "stock_quantity": 5
    }
  ]'

请求体：

请求体是一个对象数组，每个对象包含：

sku (字符串，必填)：您的产品内部 SKU 标识符
stock_quantity (整数，必填)：为此产品设置的新的总库存量

响应

响应包含成功更新的条目以及遇到的任何错误。条目是独立处理的，因此某些条目可能会成功，而其他条目可能会失败：

{
    "updated": [
        {
            "platform_sku": "880.033.390",
            "sku": "ABC123",
            "stock_quantity": 10
        },
        {
            "platform_sku": "574.478.508",
            "sku": "DEF456",
            "stock_quantity": 25
        }
    ],
    "errors": [
        {
            "platform_sku": null,
            "sku": "GHI789",
            "stock_quantity": null,
            "error": "Product not found"
        }
    ]
}

响应字段：

updated (数组)：成功更新的库存条目数组
- platform_sku (字符串)：Curosa 平台 SKU 标识符
- sku (字符串)：您的内部 SKU 标识符
- stock_quantity (整数)：更新后的库存数量
errors (数组)：更新失败的条目数组
- platform_sku (字符串|null)：如果找到则为平台 SKU，否则为 null
- sku (字符串)：失败的内部 SKU 标识符
- stock_quantity (整数|null)：请求的库存数量，或 null（如果未找到产品）
- error (字符串)：描述更新失败原因的错误消息

重要提示：

批量更新中的每个条目都是独立处理的。如果一个条目失败，其他条目仍可成功。
updated 和 errors 数组将包含请求中所有条目的结果。
请务必检查 errors 数组以识别无法更新的任何产品。
更新多个产品时请使用批量更新，以减少 API 调用次数并提高性能。