OpenAPI Documentation

This document is intended for third-party system developers, explaining how to query warehouses, logistics channels, and inventory through OpenAPI, perform order outbound creation, and query order status and order logistics information.

Online Debugging >

1. Overview

Item	Description
Protocol	HTTPS
Data Format	application/json; charset=UTF-8
Request Method	All are POST
Character Encoding	UTF-8
Authentication Method	AppKey + HMAC-SHA256 signature (no login token required)

API List (13 total):

No.	API Name	Path
1	Get Warehouse List	POST /openapi/warehouse/list
2	Get Logistics Channel List	POST /openapi/shipping/list
3	Query Inventory by SKU	POST /openapi/inventory/query
4	Paginated Inventory Query	POST /openapi/inventory/page
5	Order Outbound Creation	POST /openapi/order/create
6	Query Order List by Plan ID	POST /openapi/order/listByPlan
7	Order Status Query	POST /openapi/order/status
8	Order Logistics Query	POST /openapi/order/tracking
9	Query Product Category Tree	POST /openapi/goods/category/list
10	Create Product	POST /openapi/goods/create
11	Update Product	POST /openapi/goods/update
12	Query Product SKU	POST /openapi/goods/get
13	Query Product SKU Paginated	POST /openapi/goods/page

Base URL is provided by the operator when activating the AppKey. In the following text, it is represented as {baseUrl}, for example https://wms.example.com.

2. Authentication and Signature

All /openapi/** APIs need to include the following 4 fields in the HTTP request headers:

Request Header	Required	Description
App-Key	Yes	Client identifier assigned by the open platform, format: T{6-digit tenant ID}_xxx, for example T123456_merchant_a
Timestamp	Yes	Unix timestamp (seconds), deviation from server time must not exceed 5 minutes
Nonce	Yes	Random string, must not repeat within 5 minutes (anti-replay)
Sign	Yes	Request signature, see algorithm below

2.1 Signature Algorithm

1. Get the string to participate in signature from the request body (use empty string "" when there is no body)

2. JSON Normalization: If the request body is a JSON object or array, first parse it and then compact serialize it (remove line breaks/indentation, field order is based on parsing result). Therefore, formatted JSON can be used in Postman, as long as the content is consistent with the signature.

3. Concatenate strings in order:

signRaw = AppKey + Timestamp + Nonce + RequestBody

4. Use AppSecret to perform HMAC-SHA256 on signRaw, output uppercase hexadecimal string (fixed 64 characters), which is the Sign

Java Example:

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 Example:

import hmac
import hashlib

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

2.2 Signature Example

Assume:

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

Then:

signRaw = T123456_test1719500000abc123def456{"warehouseCode":"JP001"}
Sign    = HMAC-SHA256(signRaw, your_secret) → Uppercase HEX (64 characters)

2.3 Joint Debugging Signature Tool (Recommended)

For development and joint debugging, you can call the internal API POST /openApi/debug/buildHeaders (requires login whitelist), request example:

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

• body: Nested JSON, no need to escape (recommended)
• Returns headers which can be directly copied to business OpenAPI request headers
• Returns requestBody which is the normalized JSON string participating in signature
• Business API body format can be different from body field format (line breaks/indentation do not affect), as long as JSON content is consistent

2.4 Rate Limiting

Each AppKey default limit: 60 times / 60 seconds. Returns code=429 when exceeded.

3. Unified Response Format

All OpenAPI API responses are JSON, with the following structure:

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

Field	Type	Description
code	int	Business status code, 0 indicates success
message	string	Status description
data	object / array / null	Business data, usually null when failed

3.1 Status Code Description

Authentication Layer Errors (Filter interception, not entering business logic):

code	message	Description
0	success	Success
401	AppKey Invalid	AppKey missing, format error, or tenant invalid
402	Sign Invalid	Signature incorrect
403	Client Not Found	Client does not exist or not bound to merchant
404	Client Disabled	Client disabled or expired
406	Request Expired	Timestamp exceeds 5-minute window
407	Duplicate Request	Nonce repeated (replay request)
429	Request Rate Limited	Rate limit triggered
500	System Error	System exception

Business Layer Errors (Returned after entering Controller):

code	Common message	Description
500	Client not bound to merchant	Client corresponding to AppKey not associated with merchant
500	Warehouse does not exist or is disabled	Passed warehouseCode is invalid or warehouse is disabled
500	Order does not exist	No corresponding order outbound record found by sourceOrderNo
500	warehouseCode cannot be empty	Parameter validation failed
500	orderList cannot be empty	Parameter validation failed
500	orderList maximum 200 items	Order list exceeds limit
500	sourceOrderNo cannot be empty	Parameter validation failed
500	skuList cannot be empty	Parameter validation failed
500	skuList maximum 200 items	SKU list exceeds limit
500	specifiedCarrier only allows yamato_takkyubin (Yamato Transport·Home Delivery Service)	Specified shipping method is illegal
500	deliveryDate format must be yyyy-MM-dd	Delivery date format error
500	deliveryTimeSlot only allows 812, 1416, 1618, 1820, 1921	Delivery time slot is illegal

HTTP status code is always 200, please use code in response body to determine success.

4. API Details

Please go to the OpenAPI platform to view API details

View API details >

5. Complete Call Example (cURL)

Taking "Get Warehouse List" as example:

# Variables (please replace with actual values)
BASE_URL="https://wms.example.com"
APP_KEY="T123456_your_client"
APP_SECRET="your_app_secret"
TIMESTAMP=$(date +%s)
NONCE=$(uuidgen | tr -d '-')
BODY='{}'

# Calculate signature (need to implement HMAC-SHA256 yourself, or use tool language described below)
SIGN_RAW="${APP_KEY}${TIMESTAMP}${NONCE}${BODY}"
# SIGN = HMAC-SHA256(SIGN_RAW, APP_SECRET) Uppercase 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. Integration Suggestions

1. Call warehouse list first: Get valid warehouseCode, then call logistics channel and inventory APIs.

2. Inventory synchronization strategy:

   • When SKU quantity is small and precise query is needed, use /inventory/query
   • When full synchronization is needed, use /inventory/page paginated pull (recommended pageSize=500)

3. Nonce generation: Recommend using UUID or snowflake ID, ensure uniqueness for each request.

4. Clock synchronization: Client server time deviation from standard time should be controlled within 5 minutes.

5. Error retry: For 407 Duplicate Request, please change Nonce and retry; for 429, please reduce frequency or backoff retry; for 406, please calibrate time and retry.

6. Data isolation: Order and inventory data only includes data for AppKey bound merchant, cannot query other merchant data.

7. Order query suggestion: After creating order, can use /openapi/order/status to poll latest status; when needing logistics number, carrier and other information, call /openapi/order/tracking.

7. Appendix: Inventory Field Description

Field	Business Meaning
availableQty	Current inventory quantity available for ordering/allocation
lockedQty	Quantity already occupied by orders or business, not yet shipped
onwayQty	Quantity already shipped in transit, not yet completed warehousing