库存 - Curosa

概述

Inventory（库存）端点允许您获取产品的工厂库存信息。工厂库存是指在分配到特定配送中心或订单之前，存放在您的制造工厂或仓库中的库存。该端点提供了总库存量、已分配量和空闲（可用）量的可见性。

理解库存数量

Stock Quantity (库存总量)：工厂/仓库中的库存总数
Allocated Quantity (已分配量)：已为特定订单预留或分配的库存
Free Quantity (空闲量)：可用于分配的可用库存（计算方式为 stock_quantity - stock_quantity_allocated）

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

身份验证

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

获取工厂库存列表

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

请求

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

可选查询参数

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

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

带过滤条件的示例：

curl --location 'https://curosa.com/api/v1/factory-stocks?stock_quantity_gte=10&stock_quantity_lte=100' \
--header 'Authorization: Bearer YOUR_API_TOKEN'

响应

所有响应均以 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）

分页：

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

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

要获取下一页，请包含 cursor 查询参数，其值为 meta.next_cursor：

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

更新工厂库存水平

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

请求

curl --location 'https://curosa.com/api/v1/factory-stocks' \
--header 'Authorization: Bearer YOUR_API_TOKEN' \
--header 'Content-Type: application/json' \
--data '{
    "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 --location 'https://curosa.com/api/v1/factory-stocks/bulk-update' \
--header 'Authorization: Bearer YOUR_API_TOKEN' \
--header 'Content-Type: application/json' \
--data '[
    {
        "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 调用次数并提高性能。

速率限制

工厂库存端点的速率限制为 每小时 3,600 次请求。当前的限制和剩余请求量将在响应头中以 x-ratelimit-limit 和 x-ratelimit-remaining 的形式返回。