圈货、备货库存查询接口

提供圈货和备货类型的库存查询能力，支持查询特定SKU在指定发货区域的圈货、备货库存信息，包含批次、有效期等关键信息。

适用场景

查询圈货和备货类型的库存数量及批次信息

按发货区域筛选圈货/备货库存

了解圈货/备货库存的到期时间和服务类型

接口类型

POST

请求频率限制

默认频率：以平台配额为准

请求说明

请求URL

正式环境：https://www.westmonth.com/openapi/v2/CircleGoods/query
测试环境：https://testing.westmonth.com/openapi/v2/CircleGoods/query

请求参数

Header参数

参数名	类型	必填	示例值	说明
Authorization	string	是	authorization	身份验证Token
Content-Type	string	是	application/json	建议固定传此值

Body参数

根字段

参数名	类型	必填	默认值	可选值	说明
skus	array	否	-	-	SKU列表，最多不超过20个；不传默认查询全部
deliveryRegionCode	string	否	-	-	发货区域编码，当传入SKU列表时，该字段为必填项
uID	string	否	-	-	用户ID（需要联系西之月开通权限）

响应字段说明

成功响应（HTTP 200）

根字段

字段	类型	说明
code	integer	业务状态码（0表示成功）
msg	string	提示信息（成功时为空）
data	array	业务数据列表，包含圈货和备货库存信息

data数组字段

字段	类型	说明
typeName	string	库存类型（圈货、备货）
stockBatch	string	库存批次编号（如：BA2024112616216）
deliveryMode	string	服务类型（如：包邮、自提）
sku	string	SKU编码
depotName	string	仓库名称（如：美国1仓）
qty	integer	可用库存数量
expirationTime	string	库存到期时间（格式：yyyy-MM-dd HH:mm:ss）

调用示例

URL请求

请求示例

{
    "skus": [
        "JAA01-A010-2-GN1",
        "EEA08-A046-120-RD1"
    ],
    "deliveryRegionCode": "us"
}

成功返回示例

{
    "code": 0,
    "msg": "",
    "data": [
        {
            "typeName": "圈货",
            "stockBatch": "BA2024112616216",
            "deliveryMode": "包邮",
            "sku": "JAA01-A010-2-GN1",
            "depotName": "美国1仓",
            "qty": 250,
            "expirationTime": "2026-04-24 14:04:54"
        },
        {
            "typeName": "圈货",
            "stockBatch": "BA2024112686748",
            "deliveryMode": "自提",
            "sku": "EEA08-A046-120-RD1",
            "depotName": "美国1仓",
            "qty": 71,
            "expirationTime": "2026-12-22 18:00:00"
        }
    ]
}

失败返回示例

{
    "code": 3,
    "msg": "授权无效 authorization timestamp error",
    "data": []
}

错误处理

公共错误码

HTTP status code	错误码	错误信息	描述

注意事项

当传入skus参数时，deliveryRegionCode为必填项，否则会返回参数错误

若未传入skus参数，将查询指定发货区域（或所有区域）的全部圈货和备货库存

uID参数需要单独向平台申请开通权限，未开通时传入该参数不生效

库存批次（stockBatch）可用于追踪库存的来源和批次信息

到期时间（expirationTime）表示该批次库存的有效截止时间，过期后可能无法使用

常见问题

Q1：为什么传入SKU列表后，接口返回参数错误？

A：当传入skus参数时，deliveryRegionCode为必填项，请检查是否遗漏该参数。

Q2：如何区分圈货和备货库存？

A：通过typeName字段区分，"圈货"表示圈货库存，"备货"表示备货库存。

Q3：uID参数的作用是什么？

A：uID用于获取特定用户的圈货/备货权限，需要联系西之月开通，未开通时可不传该参数。

Q4：库存数量（qty）为0表示什么？

A：表示该批次的圈货/备货库存已售罄或已过期。

版本历史

版本	日期	修改说明
v1.0	2025-05-01	初始版本，支持圈货和备货库存查询

application/json

Bodyapplication/json

示例

{
    "code": 0,
    "msg": "",
    "data": [
        {
            "typeName": "圈货",
            "stockBatch": "BA2024112616216",
            "deliveryMode": "包邮",
            "sku": "JAA01-A010-2-GN1",
            "depotName": "美国1仓",
            "qty": 250,
            "expirationTime": "2026-04-24 14:04:54"
        },
        {
            "typeName": "圈货",
            "stockBatch": "BA2024112686748",
            "deliveryMode": "自提",
            "sku": "EEA08-A046-120-RD1",
            "depotName": "美国1仓",
            "qty": 71,
            "expirationTime": "2026-12-22 18:00:00"
        }
    ]
}

圈货、备货库存查询

圈货、备货库存查询接口

适用场景

接口类型

请求频率限制

请求说明

请求参数

Header参数

Body参数

响应字段说明

调用示例

URL请求

请求示例

成功返回示例

失败返回示例

错误处理

注意事项

常见问题

Q1：为什么传入SKU列表后，接口返回参数错误？

Q2：如何区分圈货和备货库存？

Q3：uID参数的作用是什么？

Q4：库存数量（qty）为0表示什么？

版本历史

请求参数

请求示例代码

返回响应

圈货、备货库存查询

圈货、备货库存查询接口#

适用场景#

接口类型#

请求频率限制#

请求说明#

请求参数#

Header参数#

Body参数#

响应字段说明#

调用示例#

URL请求#

请求示例#

成功返回示例#

失败返回示例#

错误处理#

注意事项#

常见问题#

Q1：为什么传入SKU列表后，接口返回参数错误？#

Q2：如何区分圈货和备货库存？#

Q3：uID参数的作用是什么？#

Q4：库存数量（qty）为0表示什么？#

版本历史#

请求参数

请求示例代码

返回响应

圈货、备货库存查询接口

适用场景

接口类型

请求频率限制

请求说明

请求参数

Header参数

Body参数

响应字段说明

调用示例

URL请求

请求示例

成功返回示例

失败返回示例

错误处理

注意事项

常见问题

Q1：为什么传入SKU列表后，接口返回参数错误？

Q2：如何区分圈货和备货库存？

Q3：uID参数的作用是什么？

Q4：库存数量（qty）为0表示什么？

版本历史