OpenAPI文档

本文档面向第三方系统开发人员，说明如何通过 OpenAPI 查询仓库、物流渠道、库存，进行订单出库创建，并查询订单状态与订单物流信息。

在线调试 >

1. 概述

项目	说明
协议	HTTPS
数据格式	`application/json; charset=UTF-8`
请求方式	均为 `POST`
字符编码	UTF-8
鉴权方式	AppKey + HMAC-SHA256 签名（无需登录 Token）

接口清单（共 13 个）：

序号	接口名称	路径
1	获取仓库列表	`POST /openapi/warehouse/list`
2	获取物流渠道列表	`POST /openapi/shipping/list`
3	按 SKU 查询库存	`POST /openapi/inventory/query`
4	分页查询库存	`POST /openapi/inventory/page`
5	订单出库创建	`POST /openapi/order/create`
6	根据计划id查询订单列表	`POST /openapi/order/listByPlan`
7	订单状态查询	`POST /openapi/order/status`
8	订单物流查询	`POST /openapi/order/tracking`
9	查询产品分类树	`POST /openapi/goods/category/list`
10	创建商品	`POST /openapi/goods/create`
11	更新商品	`POST /openapi/goods/update`
12	查询商品SKU	`POST /openapi/goods/get`
13	查询商品SKU 分页	`POST /openapi/goods/page`

Base URL 由运营方在开通 AppKey 时提供，下文以 {baseUrl} 表示，例如 https://wms.example.com。

2. 鉴权与签名

所有 /openapi/** 接口均需在 HTTP 请求头中携带以下 4 个字段：

请求头	必填	说明
`App-Key`	是	开放平台分配的客户端标识，格式：`T{6位租户ID}_xxx`，例如 `T123456_merchant_a`
`Timestamp`	是	Unix 时间戳（秒），与服务端时间偏差不得超过 5 分钟
`Nonce`	是	随机字符串，5 分钟内不可重复（防重放）
`Sign`	是	请求签名，见下方算法

2.1 签名算法

取请求体参与签名的字符串（无 Body 时使用空字符串 ""）
JSON 规范化：若请求体为 JSON 对象或数组，先解析再紧凑序列化（去除换行/缩进，字段顺序以解析结果为准）。因此 Postman 中可使用格式化 JSON，只要内容与签名时一致即可。
按顺序拼接字符串：

signRaw = AppKey + Timestamp + Nonce + RequestBody

使用 AppSecret 对 signRaw 做 HMAC-SHA256，输出大写十六进制 字符串（固定 64 位），即为 Sign

Java 示例：

java

Mac mac = Mac.getInstance("HmacSHA256");
mac.init(new SecretKeySpec(appSecret.getBytes(StandardCharsets.UTF_8), "HmacSHA256"));
byte[] digest = mac.doFinal(signRaw.getBytes(StandardCharsets.UTF_8));
String sign = HexFormat.of().formatHex(digest).toUpperCase();

Python 示例：

python

import hmac
import hashlib

sign = hmac.new(
    app_secret.encode("utf-8"),
    sign_raw.encode("utf-8"),
    hashlib.sha256
).hexdigest().upper()

2.2 签名示例

假设：

AppKey = T123456_test
AppSecret = your_secret
Timestamp = 1719500000
Nonce = abc123def456
RequestBody = {"warehouseCode":"JP001"}

则：

signRaw = T123456_test1719500000abc123def456{"warehouseCode":"JP001"}
Sign    = HMAC-SHA256(signRaw, your_secret) → 大写 HEX（64 位）

2.3 联调签名工具（推荐）

开发联调可调用内部接口 POST /openApi/debug/buildHeaders（需登录白名单），请求示例：

json

{
  "appKey": "T755003_xxxx",
  "appSecret": "your_secret",
  "body": {
    "warehouseCode": "JP001",
    "orderList": []
  }
}

body：嵌套 JSON，无需转义（推荐）
返回 headers 可直接复制到业务 OpenAPI 请求头
返回 requestBody 为参与签名的规范化 JSON 字符串
业务接口 Body 可与 body 字段格式不同（换行/缩进不影响），JSON 内容一致即可

2.4 限流

每个 AppKey 默认限制：60 次 / 60 秒。超出后返回 code=429。

3. 统一响应格式

所有 OpenAPI 接口响应均为 JSON，结构如下：

json

{
  "code": 0,
  "message": "success",
  "data": {}
}

字段	类型	说明
`code`	int	业务状态码，`0` 表示成功
`message`	string	状态描述
`data`	object / array / null	业务数据，失败时通常为 `null`

3.1 状态码说明

鉴权层错误（Filter 拦截，未进入业务逻辑）：

code	message	说明
`0`	success	成功
`401`	AppKey Invalid	AppKey 缺失、格式错误或租户无效
`402`	Sign Invalid	签名不正确
`403`	Client Not Found	客户端不存在或未绑定商户
`404`	Client Disabled	客户端已禁用或已过期
`406`	Request Expired	时间戳超出 5 分钟窗口
`407`	Duplicate Request	Nonce 重复（重放请求）
`429`	Request Rate Limited	触发限流
`500`	System Error	系统异常

业务层错误（进入 Controller 后返回）：

code	常见 message	说明
`500`	客户端未绑定商户	AppKey 对应客户端未关联商户
`500`	仓库不存在或已停用	传入的 `warehouseCode` 无效或仓库已禁用
`500`	订单不存在	按 `sourceOrderNo` 未查到对应订单出库记录
`500`	`warehouseCode`不能为空	参数校验失败
`500`	`orderList`不能为空	参数校验失败
`500`	`orderList`最多200条	订单列表超过上限
`500`	`sourceOrderNo`不能为空	参数校验失败
`500`	`skuList`不能为空	参数校验失败
`500`	`skuList`最多200条	SKU 列表超过上限
`500`	`specifiedCarrier`仅允许yamato_takkyubin（ヤマト運輸•宅配便）	指定发送方式不合法
`500`	`deliveryDate`格式须为yyyy-MM-dd	配送日期格式错误
`500`	`deliveryTimeSlot`仅允许812、1416、1618、1820、1921	配送时间段不合法

HTTP 状态码始终为 200，请以响应体中的 code 判断是否成功。

4. 接口详情

请前往OpenAPI开放平台查看接口详情

查看接口详情 >

5. 完整调用示例（cURL）

以「获取仓库列表」为例：

bash

# 变量（请替换为实际值）
BASE_URL="https://wms.example.com"
APP_KEY="T123456_your_client"
APP_SECRET="your_app_secret"
TIMESTAMP=$(date +%s)
NONCE=$(uuidgen | tr -d '-')
BODY='{}'

# 计算签名（需自行实现 HMAC-SHA256，或使用下方说明的工具语言）
SIGN_RAW="${APP_KEY}${TIMESTAMP}${NONCE}${BODY}"
# SIGN = HMAC-SHA256(SIGN_RAW, APP_SECRET) 大写 HEX

curl -X POST "${BASE_URL}/openapi/warehouse/list" \
  -H "Content-Type: application/json" \
  -H "App-Key: ${APP_KEY}" \
  -H "Timestamp: ${TIMESTAMP}" \
  -H "Nonce: ${NONCE}" \
  -H "Sign: ${SIGN}" \
  -d "${BODY}"

6. 对接建议

先调仓库列表：获取有效的 warehouseCode，再调用物流渠道与库存接口。
库存同步策略：
- SKU 数量较少、需精确查询时，使用 /inventory/query
- 需全量同步时，使用 /inventory/page 分页拉取（建议 pageSize=500）
Nonce 生成：建议使用 UUID 或雪花 ID，确保每次请求唯一。
时钟同步：客户端服务器时间与标准时间偏差应控制在 5 分钟以内。
错误重试：407 Duplicate Request 请更换 Nonce 后重试；429 请降频或退避重试；406 请校准时间后重试。
数据隔离：订单与库存数据仅包含 AppKey 绑定商户的数据，无法查询其他商户数据。
订单查询建议：创建订单后可用 /openapi/order/status 轮询最新状态；需要物流单号、承运商等信息时，调用 /openapi/order/tracking。

7. 附录：库存字段说明

字段	业务含义
`availableQty`	当前可用于下单/分配的库存数量
`lockedQty`	已被订单或业务占用、尚未出库的数量
`onwayQty`	已发货在途、尚未入库完成的数量

OpenAPI文档 ​

1. 概述 ​

2. 鉴权与签名 ​

2.1 签名算法 ​

2.2 签名示例 ​

2.3 联调签名工具（推荐） ​

2.4 限流 ​

3. 统一响应格式 ​

3.1 状态码说明 ​

4. 接口详情 ​

请前往OpenAPI开放平台查看接口详情 ​

5. 完整调用示例（cURL） ​

6. 对接建议 ​

7. 附录：库存字段说明 ​