{"openapi": "3.1.0", "info": {"title": "仓信AI / Cangxin AI Open API", "version": "1.0.0", "description": "REST API for sellers' systems and ERPs (Lingxing and others). appKey = the seller code (header `X-WMS-Key`), appSecret = the API key: send `Authorization: Bearer <appSecret>` (or `X-API-Key`), or sign each request with HMAC-SHA256 (optional, see the hmacKey scheme). A test account is delivered as exactly three values: test domain, appKey and appSecret. Nothing else is needed to call the API. Lingxing function mapping: `info.x-erp-mapping`. Keys, scopes and webhooks are managed in the seller portal (/my/wms/api); public documentation: /api/docs (Chinese PDF: /api/docs/pdf).\n\n卖家系统 / ERP（领星等）对接接口。appKey = 卖家代码（请求头 `X-WMS-Key`），appSecret = API 密钥：请求头带 `Authorization: Bearer <appSecret>`，或可选用 HMAC-SHA256 请求签名。测试账号只交付三项：测试域名、appKey、appSecret。调用接口不需要其他参数。领星功能对应关系见 `info.x-erp-mapping`。密钥、权限范围和 Webhook 在卖家门户 /my/wms/api 管理。", "x-erp-mapping": {"credentials": [{"field": "API domain / API 域名", "meaning": "Base URL of the environment, ending in /api/v1 (production, or the separate test environment for a test account)", "meaning_zh": "接口地址，以 /api/v1 结尾（正式环境；测试账号则为独立测试环境的地址）", "header": "-"}, {"field": "appKey", "meaning": "The seller code (GET /me returns it as key.appkey). Identifies the seller, not a secret", "meaning_zh": "卖家代码（GET /me 返回的 key.appkey），用于识别卖家，不是密钥", "header": "X-WMS-Key"}, {"field": "appSecret", "meaning": "The API key (shown once when created; stored hashed). Sent as a Bearer token, or not sent at all when requests are signed with HMAC-SHA256 (optional)", "meaning_zh": "API 密钥（生成时只显示一次，服务器只存哈希）。作为 Bearer 令牌发送；或可选用 HMAC-SHA256 请求签名，此时密钥本身不发送", "header": "Authorization: Bearer <appSecret> | X-WMS-Signature"}], "test_account": {"values": ["test domain", "appKey", "appSecret"], "note": "A test account is delivered as exactly three values: test domain, appKey and appSecret. Nothing else is needed to call the API.", "note_zh": "测试账号只交付三项：测试域名、appKey、appSecret。调用接口不需要其他参数。"}, "lingxing_functions": [{"no": 1, "lingxing": "基础对接（商品、仓库、库存、订单）", "function": "Base data: SKUs, warehouses, inventory, orders", "endpoints": ["GET /api/v1/skus", "POST /api/v1/skus", "PUT /api/v1/skus/{id}", "GET /api/v1/warehouses", "GET /api/v1/inventory", "GET /api/v1/orders", "GET /api/v1/orders/{id}"], "webhooks": [], "related_endpoints": []}, {"no": 2, "lingxing": "FBA 备货入库（入库预报）", "function": "FBA stock inbound: inbound notice (ASN) and received quantities", "endpoints": ["POST /api/v1/inbound", "GET /api/v1/inbound", "GET /api/v1/inbound/{id}"], "webhooks": ["inbound.received"], "related_endpoints": ["POST /api/v1/transfers", "GET /api/v1/transfers/{id}"]}, {"no": 3, "lingxing": "出库发货（推单、跟踪号回传、截单）", "function": "Outbound: push orders, tracking number back, cancel / intercept", "endpoints": ["POST /api/v1/orders", "GET /api/v1/orders/{id}", "GET /api/v1/orders/by-external/{external_id}", "POST /api/v1/orders/{id}/cancel", "POST /api/v1/orders/{id}/hold"], "webhooks": ["order.label_created", "order.shipped"], "related_endpoints": []}, {"no": 4, "lingxing": "退件入库", "function": "Returns: announce a return, inspection result, instruction", "endpoints": ["POST /api/v1/returns", "GET /api/v1/returns", "GET /api/v1/returns/{id}", "POST /api/v1/returns/{id}/instruction"], "webhooks": ["return.awaiting_instruction"], "related_endpoints": []}]}}, "servers": [{"url": "https://cangxinai.com"}], "security": [{"bearerAuth": []}, {"apiKeyHeader": []}, {"hmacKey": [], "hmacTimestamp": [], "hmacNonce": [], "hmacSignature": []}], "tags": [{"name": "General"}, {"name": "SKUs"}, {"name": "Orders"}, {"name": "Inbound"}, {"name": "Inventory"}, {"name": "Returns"}, {"name": "Value-added services"}, {"name": "FBA / transfers"}, {"name": "Billing"}], "paths": {"/api/v1/me": {"get": {"operationId": "api_me", "tags": ["General"], "summary": "Current API key, user and seller", "description": "Scope (any of): `any`", "parameters": [], "responses": {"200": {"description": "OK", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Me"}}}}, "400": {"description": "Invalid JSON or header / 请求格式错误", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Error"}}}}, "401": {"description": "Missing, invalid, expired or revoked API key; invalid, expired or replayed signature; appkey mismatch / 密钥或签名无效", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Error"}}}}, "403": {"description": "Insufficient scope, warehouse not contracted or IP not allowed / 权限不足、仓库未签约或 IP 不在白名单", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Error"}}}}, "404": {"description": "Not found (also for records of other sellers) / 不存在", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Error"}}}}, "409": {"description": "Conflict (duplicate order, already shipped, ...) / 冲突", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Error"}}}}, "422": {"description": "Validation error / 校验失败", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Error"}}}}, "429": {"description": "Rate limited, see Retry-After / 请求过于频繁", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Error"}}}}}}}, "/api/v1/warehouses": {"get": {"operationId": "api_warehouses", "tags": ["General"], "summary": "Contracted warehouses", "description": "Scope (any of): `any`", "parameters": [], "responses": {"200": {"description": "OK", "content": {"application/json": {"schema": {"type": "object", "properties": {"data": {"type": "array", "items": {"$ref": "#/components/schemas/Warehouse"}}, "pagination": {"$ref": "#/components/schemas/Pagination"}}}}}}, "400": {"description": "Invalid JSON or header / 请求格式错误", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Error"}}}}, "401": {"description": "Missing, invalid, expired or revoked API key; invalid, expired or replayed signature; appkey mismatch / 密钥或签名无效", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Error"}}}}, "403": {"description": "Insufficient scope, warehouse not contracted or IP not allowed / 权限不足、仓库未签约或 IP 不在白名单", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Error"}}}}, "404": {"description": "Not found (also for records of other sellers) / 不存在", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Error"}}}}, "409": {"description": "Conflict (duplicate order, already shipped, ...) / 冲突", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Error"}}}}, "422": {"description": "Validation error / 校验失败", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Error"}}}}, "429": {"description": "Rate limited, see Retry-After / 请求过于频繁", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Error"}}}}}}}, "/api/v1/skus": {"get": {"operationId": "api_skus_list", "tags": ["SKUs"], "summary": "List SKUs", "description": "Scope (any of): `stock, inbound, orders`", "parameters": [{"name": "sku", "in": "query", "required": false, "schema": {"type": "string"}, "description": "Exact SKU code / SKU 编码"}, {"name": "barcode", "in": "query", "required": false, "schema": {"type": "string"}, "description": "Exact barcode / 条码"}, {"name": "search", "in": "query", "required": false, "schema": {"type": "string"}, "description": "Code, name, barcode or FNSKU contains / 模糊搜索"}, {"name": "updated_since", "in": "query", "required": false, "schema": {"type": "string"}, "description": "ISO 8601 date-time: only records changed since / 只返回此时间之后更新的记录"}, {"name": "page", "in": "query", "required": false, "schema": {"type": "integer"}, "description": "Page number, starting at 1 / 页码，从 1 开始"}, {"name": "page_size", "in": "query", "required": false, "schema": {"type": "integer"}, "description": "Items per page (default 50, max 200) / 每页条数（默认 50，最多 200）"}], "responses": {"200": {"description": "OK", "content": {"application/json": {"schema": {"type": "object", "properties": {"data": {"type": "array", "items": {"$ref": "#/components/schemas/Sku"}}, "pagination": {"$ref": "#/components/schemas/Pagination"}}}}}}, "400": {"description": "Invalid JSON or header / 请求格式错误", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Error"}}}}, "401": {"description": "Missing, invalid, expired or revoked API key; invalid, expired or replayed signature; appkey mismatch / 密钥或签名无效", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Error"}}}}, "403": {"description": "Insufficient scope, warehouse not contracted or IP not allowed / 权限不足、仓库未签约或 IP 不在白名单", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Error"}}}}, "404": {"description": "Not found (also for records of other sellers) / 不存在", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Error"}}}}, "409": {"description": "Conflict (duplicate order, already shipped, ...) / 冲突", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Error"}}}}, "422": {"description": "Validation error / 校验失败", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Error"}}}}, "429": {"description": "Rate limited, see Retry-After / 请求过于频繁", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Error"}}}}}}, "post": {"operationId": "api_skus_create", "tags": ["SKUs"], "summary": "Create a SKU", "description": "Scope (any of): `inbound`", "parameters": [{"name": "Idempotency-Key", "in": "header", "required": false, "schema": {"type": "string"}, "description": "Same key + same body within 7 days returns the stored response instead of creating again / 相同的幂等键 7 天内重复提交返回首次结果"}], "responses": {"201": {"description": "OK", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Sku"}}}}, "400": {"description": "Invalid JSON or header / 请求格式错误", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Error"}}}}, "401": {"description": "Missing, invalid, expired or revoked API key; invalid, expired or replayed signature; appkey mismatch / 密钥或签名无效", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Error"}}}}, "403": {"description": "Insufficient scope, warehouse not contracted or IP not allowed / 权限不足、仓库未签约或 IP 不在白名单", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Error"}}}}, "404": {"description": "Not found (also for records of other sellers) / 不存在", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Error"}}}}, "409": {"description": "Conflict (duplicate order, already shipped, ...) / 冲突", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Error"}}}}, "422": {"description": "Validation error / 校验失败", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Error"}}}}, "429": {"description": "Rate limited, see Retry-After / 请求过于频繁", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Error"}}}}}, "requestBody": {"required": true, "content": {"application/json": {"schema": {"$ref": "#/components/schemas/SkuInput"}}}}}}, "/api/v1/skus/{id}": {"get": {"operationId": "api_skus_get", "tags": ["SKUs"], "summary": "Get a SKU", "description": "Scope (any of): `stock, inbound, orders`", "parameters": [{"name": "id", "in": "path", "required": true, "schema": {"type": "integer"}}], "responses": {"200": {"description": "OK", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Sku"}}}}, "400": {"description": "Invalid JSON or header / 请求格式错误", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Error"}}}}, "401": {"description": "Missing, invalid, expired or revoked API key; invalid, expired or replayed signature; appkey mismatch / 密钥或签名无效", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Error"}}}}, "403": {"description": "Insufficient scope, warehouse not contracted or IP not allowed / 权限不足、仓库未签约或 IP 不在白名单", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Error"}}}}, "404": {"description": "Not found (also for records of other sellers) / 不存在", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Error"}}}}, "409": {"description": "Conflict (duplicate order, already shipped, ...) / 冲突", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Error"}}}}, "422": {"description": "Validation error / 校验失败", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Error"}}}}, "429": {"description": "Rate limited, see Retry-After / 请求过于频繁", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Error"}}}}}}, "put": {"operationId": "api_skus_update", "tags": ["SKUs"], "summary": "Update a SKU (only the fields sent)", "description": "Scope (any of): `inbound`", "parameters": [{"name": "id", "in": "path", "required": true, "schema": {"type": "integer"}}], "responses": {"200": {"description": "OK", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Sku"}}}}, "400": {"description": "Invalid JSON or header / 请求格式错误", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Error"}}}}, "401": {"description": "Missing, invalid, expired or revoked API key; invalid, expired or replayed signature; appkey mismatch / 密钥或签名无效", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Error"}}}}, "403": {"description": "Insufficient scope, warehouse not contracted or IP not allowed / 权限不足、仓库未签约或 IP 不在白名单", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Error"}}}}, "404": {"description": "Not found (also for records of other sellers) / 不存在", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Error"}}}}, "409": {"description": "Conflict (duplicate order, already shipped, ...) / 冲突", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Error"}}}}, "422": {"description": "Validation error / 校验失败", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Error"}}}}, "429": {"description": "Rate limited, see Retry-After / 请求过于频繁", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Error"}}}}}, "requestBody": {"required": true, "content": {"application/json": {"schema": {"$ref": "#/components/schemas/SkuInput"}}}}}}, "/api/v1/orders": {"post": {"operationId": "api_orders_create", "tags": ["Orders"], "summary": "Create an outbound order", "description": "Scope (any of): `orders`", "parameters": [{"name": "Idempotency-Key", "in": "header", "required": false, "schema": {"type": "string"}, "description": "Same key + same body within 7 days returns the stored response instead of creating again / 相同的幂等键 7 天内重复提交返回首次结果"}], "responses": {"201": {"description": "OK", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Order"}}}}, "400": {"description": "Invalid JSON or header / 请求格式错误", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Error"}}}}, "401": {"description": "Missing, invalid, expired or revoked API key; invalid, expired or replayed signature; appkey mismatch / 密钥或签名无效", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Error"}}}}, "403": {"description": "Insufficient scope, warehouse not contracted or IP not allowed / 权限不足、仓库未签约或 IP 不在白名单", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Error"}}}}, "404": {"description": "Not found (also for records of other sellers) / 不存在", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Error"}}}}, "409": {"description": "Conflict (duplicate order, already shipped, ...) / 冲突", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Error"}}}}, "422": {"description": "Validation error / 校验失败", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Error"}}}}, "429": {"description": "Rate limited, see Retry-After / 请求过于频繁", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Error"}}}}}, "requestBody": {"required": true, "content": {"application/json": {"schema": {"$ref": "#/components/schemas/OrderInput"}}}}}, "get": {"operationId": "api_orders_list", "tags": ["Orders"], "summary": "List outbound orders", "description": "Scope (any of): `orders`", "parameters": [{"name": "status", "in": "query", "required": false, "schema": {"type": "string"}, "description": "pending | processing | on_hold | shipped | cancelled"}, {"name": "external_id", "in": "query", "required": false, "schema": {"type": "string"}, "description": "Your order number / 你的订单号"}, {"name": "warehouse_id", "in": "query", "required": false, "schema": {"type": "integer"}, "description": "Contracted warehouse id / 签约仓库 ID"}, {"name": "updated_since", "in": "query", "required": false, "schema": {"type": "string"}, "description": "ISO 8601 date-time: only records changed since / 只返回此时间之后更新的记录"}, {"name": "page", "in": "query", "required": false, "schema": {"type": "integer"}, "description": "Page number, starting at 1 / 页码，从 1 开始"}, {"name": "page_size", "in": "query", "required": false, "schema": {"type": "integer"}, "description": "Items per page (default 50, max 200) / 每页条数（默认 50，最多 200）"}], "responses": {"200": {"description": "OK", "content": {"application/json": {"schema": {"type": "object", "properties": {"data": {"type": "array", "items": {"$ref": "#/components/schemas/Order"}}, "pagination": {"$ref": "#/components/schemas/Pagination"}}}}}}, "400": {"description": "Invalid JSON or header / 请求格式错误", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Error"}}}}, "401": {"description": "Missing, invalid, expired or revoked API key; invalid, expired or replayed signature; appkey mismatch / 密钥或签名无效", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Error"}}}}, "403": {"description": "Insufficient scope, warehouse not contracted or IP not allowed / 权限不足、仓库未签约或 IP 不在白名单", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Error"}}}}, "404": {"description": "Not found (also for records of other sellers) / 不存在", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Error"}}}}, "409": {"description": "Conflict (duplicate order, already shipped, ...) / 冲突", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Error"}}}}, "422": {"description": "Validation error / 校验失败", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Error"}}}}, "429": {"description": "Rate limited, see Retry-After / 请求过于频繁", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Error"}}}}}}}, "/api/v1/orders/{id}": {"get": {"operationId": "api_orders_get", "tags": ["Orders"], "summary": "Order status and tracking", "description": "Scope (any of): `orders`", "parameters": [{"name": "id", "in": "path", "required": true, "schema": {"type": "integer"}}], "responses": {"200": {"description": "OK", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Order"}}}}, "400": {"description": "Invalid JSON or header / 请求格式错误", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Error"}}}}, "401": {"description": "Missing, invalid, expired or revoked API key; invalid, expired or replayed signature; appkey mismatch / 密钥或签名无效", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Error"}}}}, "403": {"description": "Insufficient scope, warehouse not contracted or IP not allowed / 权限不足、仓库未签约或 IP 不在白名单", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Error"}}}}, "404": {"description": "Not found (also for records of other sellers) / 不存在", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Error"}}}}, "409": {"description": "Conflict (duplicate order, already shipped, ...) / 冲突", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Error"}}}}, "422": {"description": "Validation error / 校验失败", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Error"}}}}, "429": {"description": "Rate limited, see Retry-After / 请求过于频繁", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Error"}}}}}}}, "/api/v1/orders/{id}/cancel": {"post": {"operationId": "api_orders_cancel", "tags": ["Orders"], "summary": "Cancel an order (before picking starts)", "description": "Scope (any of): `orders`", "parameters": [{"name": "id", "in": "path", "required": true, "schema": {"type": "integer"}}, {"name": "Idempotency-Key", "in": "header", "required": false, "schema": {"type": "string"}, "description": "Same key + same body within 7 days returns the stored response instead of creating again / 相同的幂等键 7 天内重复提交返回首次结果"}], "responses": {"200": {"description": "OK", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Order"}}}}, "400": {"description": "Invalid JSON or header / 请求格式错误", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Error"}}}}, "401": {"description": "Missing, invalid, expired or revoked API key; invalid, expired or replayed signature; appkey mismatch / 密钥或签名无效", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Error"}}}}, "403": {"description": "Insufficient scope, warehouse not contracted or IP not allowed / 权限不足、仓库未签约或 IP 不在白名单", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Error"}}}}, "404": {"description": "Not found (also for records of other sellers) / 不存在", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Error"}}}}, "409": {"description": "Conflict (duplicate order, already shipped, ...) / 冲突", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Error"}}}}, "422": {"description": "Validation error / 校验失败", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Error"}}}}, "429": {"description": "Rate limited, see Retry-After / 请求过于频繁", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Error"}}}}}, "requestBody": {"required": true, "content": {"application/json": {"schema": {"$ref": "#/components/schemas/ReasonInput"}}}}}}, "/api/v1/orders/{id}/hold": {"post": {"operationId": "api_orders_hold", "tags": ["Orders"], "summary": "Ask the warehouse to hold / intercept an order", "description": "Scope (any of): `orders`", "parameters": [{"name": "id", "in": "path", "required": true, "schema": {"type": "integer"}}, {"name": "Idempotency-Key", "in": "header", "required": false, "schema": {"type": "string"}, "description": "Same key + same body within 7 days returns the stored response instead of creating again / 相同的幂等键 7 天内重复提交返回首次结果"}], "responses": {"200": {"description": "OK", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Order"}}}}, "400": {"description": "Invalid JSON or header / 请求格式错误", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Error"}}}}, "401": {"description": "Missing, invalid, expired or revoked API key; invalid, expired or replayed signature; appkey mismatch / 密钥或签名无效", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Error"}}}}, "403": {"description": "Insufficient scope, warehouse not contracted or IP not allowed / 权限不足、仓库未签约或 IP 不在白名单", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Error"}}}}, "404": {"description": "Not found (also for records of other sellers) / 不存在", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Error"}}}}, "409": {"description": "Conflict (duplicate order, already shipped, ...) / 冲突", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Error"}}}}, "422": {"description": "Validation error / 校验失败", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Error"}}}}, "429": {"description": "Rate limited, see Retry-After / 请求过于频繁", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Error"}}}}}, "requestBody": {"required": true, "content": {"application/json": {"schema": {"$ref": "#/components/schemas/ReasonInput"}}}}}}, "/api/v1/orders/by-external/{external_id}": {"get": {"operationId": "api_orders_by_external_get", "tags": ["Orders"], "summary": "Order status and tracking, by your order number", "description": "Scope (any of): `orders`", "parameters": [{"name": "external_id", "in": "path", "required": true, "schema": {"type": "string"}, "description": "Your order number (URL-encoded; must not contain '/') / 你的订单号（URL 编码，不能含 /）"}], "responses": {"200": {"description": "OK", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Order"}}}}, "400": {"description": "Invalid JSON or header / 请求格式错误", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Error"}}}}, "401": {"description": "Missing, invalid, expired or revoked API key; invalid, expired or replayed signature; appkey mismatch / 密钥或签名无效", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Error"}}}}, "403": {"description": "Insufficient scope, warehouse not contracted or IP not allowed / 权限不足、仓库未签约或 IP 不在白名单", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Error"}}}}, "404": {"description": "Not found (also for records of other sellers) / 不存在", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Error"}}}}, "409": {"description": "Conflict (duplicate order, already shipped, ...) / 冲突", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Error"}}}}, "422": {"description": "Validation error / 校验失败", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Error"}}}}, "429": {"description": "Rate limited, see Retry-After / 请求过于频繁", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Error"}}}}}}}, "/api/v1/orders/by-external/{external_id}/cancel": {"post": {"operationId": "api_orders_by_external_cancel", "tags": ["Orders"], "summary": "Cancel an order by your order number (before picking starts)", "description": "Scope (any of): `orders`", "parameters": [{"name": "external_id", "in": "path", "required": true, "schema": {"type": "string"}, "description": "Your order number (URL-encoded; must not contain '/') / 你的订单号（URL 编码，不能含 /）"}, {"name": "Idempotency-Key", "in": "header", "required": false, "schema": {"type": "string"}, "description": "Same key + same body within 7 days returns the stored response instead of creating again / 相同的幂等键 7 天内重复提交返回首次结果"}], "responses": {"200": {"description": "OK", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Order"}}}}, "400": {"description": "Invalid JSON or header / 请求格式错误", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Error"}}}}, "401": {"description": "Missing, invalid, expired or revoked API key; invalid, expired or replayed signature; appkey mismatch / 密钥或签名无效", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Error"}}}}, "403": {"description": "Insufficient scope, warehouse not contracted or IP not allowed / 权限不足、仓库未签约或 IP 不在白名单", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Error"}}}}, "404": {"description": "Not found (also for records of other sellers) / 不存在", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Error"}}}}, "409": {"description": "Conflict (duplicate order, already shipped, ...) / 冲突", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Error"}}}}, "422": {"description": "Validation error / 校验失败", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Error"}}}}, "429": {"description": "Rate limited, see Retry-After / 请求过于频繁", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Error"}}}}}, "requestBody": {"required": true, "content": {"application/json": {"schema": {"$ref": "#/components/schemas/ReasonInput"}}}}}}, "/api/v1/orders/by-external/{external_id}/hold": {"post": {"operationId": "api_orders_by_external_hold", "tags": ["Orders"], "summary": "Hold / intercept an order by your order number", "description": "Scope (any of): `orders`", "parameters": [{"name": "external_id", "in": "path", "required": true, "schema": {"type": "string"}, "description": "Your order number (URL-encoded; must not contain '/') / 你的订单号（URL 编码，不能含 /）"}, {"name": "Idempotency-Key", "in": "header", "required": false, "schema": {"type": "string"}, "description": "Same key + same body within 7 days returns the stored response instead of creating again / 相同的幂等键 7 天内重复提交返回首次结果"}], "responses": {"200": {"description": "OK", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Order"}}}}, "400": {"description": "Invalid JSON or header / 请求格式错误", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Error"}}}}, "401": {"description": "Missing, invalid, expired or revoked API key; invalid, expired or replayed signature; appkey mismatch / 密钥或签名无效", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Error"}}}}, "403": {"description": "Insufficient scope, warehouse not contracted or IP not allowed / 权限不足、仓库未签约或 IP 不在白名单", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Error"}}}}, "404": {"description": "Not found (also for records of other sellers) / 不存在", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Error"}}}}, "409": {"description": "Conflict (duplicate order, already shipped, ...) / 冲突", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Error"}}}}, "422": {"description": "Validation error / 校验失败", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Error"}}}}, "429": {"description": "Rate limited, see Retry-After / 请求过于频繁", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Error"}}}}}, "requestBody": {"required": true, "content": {"application/json": {"schema": {"$ref": "#/components/schemas/ReasonInput"}}}}}}, "/api/v1/inbound": {"post": {"operationId": "api_inbound_create", "tags": ["Inbound"], "summary": "Create an inbound notice (ASN)", "description": "Scope (any of): `inbound`", "parameters": [{"name": "Idempotency-Key", "in": "header", "required": false, "schema": {"type": "string"}, "description": "Same key + same body within 7 days returns the stored response instead of creating again / 相同的幂等键 7 天内重复提交返回首次结果"}], "responses": {"201": {"description": "OK", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Inbound"}}}}, "400": {"description": "Invalid JSON or header / 请求格式错误", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Error"}}}}, "401": {"description": "Missing, invalid, expired or revoked API key; invalid, expired or replayed signature; appkey mismatch / 密钥或签名无效", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Error"}}}}, "403": {"description": "Insufficient scope, warehouse not contracted or IP not allowed / 权限不足、仓库未签约或 IP 不在白名单", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Error"}}}}, "404": {"description": "Not found (also for records of other sellers) / 不存在", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Error"}}}}, "409": {"description": "Conflict (duplicate order, already shipped, ...) / 冲突", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Error"}}}}, "422": {"description": "Validation error / 校验失败", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Error"}}}}, "429": {"description": "Rate limited, see Retry-After / 请求过于频繁", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Error"}}}}}, "requestBody": {"required": true, "content": {"application/json": {"schema": {"$ref": "#/components/schemas/InboundInput"}}}}}, "get": {"operationId": "api_inbound_list", "tags": ["Inbound"], "summary": "List inbound notices", "description": "Scope (any of): `inbound`", "parameters": [{"name": "status", "in": "query", "required": false, "schema": {"type": "string"}, "description": "open | received | cancelled"}, {"name": "reference", "in": "query", "required": false, "schema": {"type": "string"}, "description": "Your reference / 你的参考号"}, {"name": "warehouse_id", "in": "query", "required": false, "schema": {"type": "integer"}, "description": "Contracted warehouse id / 签约仓库 ID"}, {"name": "updated_since", "in": "query", "required": false, "schema": {"type": "string"}, "description": "ISO 8601 date-time: only records changed since / 只返回此时间之后更新的记录"}, {"name": "page", "in": "query", "required": false, "schema": {"type": "integer"}, "description": "Page number, starting at 1 / 页码，从 1 开始"}, {"name": "page_size", "in": "query", "required": false, "schema": {"type": "integer"}, "description": "Items per page (default 50, max 200) / 每页条数（默认 50，最多 200）"}], "responses": {"200": {"description": "OK", "content": {"application/json": {"schema": {"type": "object", "properties": {"data": {"type": "array", "items": {"$ref": "#/components/schemas/Inbound"}}, "pagination": {"$ref": "#/components/schemas/Pagination"}}}}}}, "400": {"description": "Invalid JSON or header / 请求格式错误", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Error"}}}}, "401": {"description": "Missing, invalid, expired or revoked API key; invalid, expired or replayed signature; appkey mismatch / 密钥或签名无效", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Error"}}}}, "403": {"description": "Insufficient scope, warehouse not contracted or IP not allowed / 权限不足、仓库未签约或 IP 不在白名单", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Error"}}}}, "404": {"description": "Not found (also for records of other sellers) / 不存在", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Error"}}}}, "409": {"description": "Conflict (duplicate order, already shipped, ...) / 冲突", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Error"}}}}, "422": {"description": "Validation error / 校验失败", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Error"}}}}, "429": {"description": "Rate limited, see Retry-After / 请求过于频繁", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Error"}}}}}}}, "/api/v1/inbound/{id}": {"get": {"operationId": "api_inbound_get", "tags": ["Inbound"], "summary": "Inbound notice status and received quantities", "description": "Scope (any of): `inbound`", "parameters": [{"name": "id", "in": "path", "required": true, "schema": {"type": "integer"}}], "responses": {"200": {"description": "OK", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Inbound"}}}}, "400": {"description": "Invalid JSON or header / 请求格式错误", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Error"}}}}, "401": {"description": "Missing, invalid, expired or revoked API key; invalid, expired or replayed signature; appkey mismatch / 密钥或签名无效", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Error"}}}}, "403": {"description": "Insufficient scope, warehouse not contracted or IP not allowed / 权限不足、仓库未签约或 IP 不在白名单", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Error"}}}}, "404": {"description": "Not found (also for records of other sellers) / 不存在", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Error"}}}}, "409": {"description": "Conflict (duplicate order, already shipped, ...) / 冲突", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Error"}}}}, "422": {"description": "Validation error / 校验失败", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Error"}}}}, "429": {"description": "Rate limited, see Retry-After / 请求过于频繁", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Error"}}}}}}}, "/api/v1/inventory": {"get": {"operationId": "api_inventory", "tags": ["Inventory"], "summary": "Stock by warehouse / SKU / batch", "description": "Scope (any of): `stock`", "parameters": [{"name": "warehouse_id", "in": "query", "required": false, "schema": {"type": "integer"}, "description": "Contracted warehouse id / 签约仓库 ID"}, {"name": "sku", "in": "query", "required": false, "schema": {"type": "string"}, "description": "Exact SKU code / SKU 编码"}, {"name": "page", "in": "query", "required": false, "schema": {"type": "integer"}, "description": "Page number, starting at 1 / 页码，从 1 开始"}, {"name": "page_size", "in": "query", "required": false, "schema": {"type": "integer"}, "description": "Items per page (default 50, max 200) / 每页条数（默认 50，最多 200）"}], "responses": {"200": {"description": "OK", "content": {"application/json": {"schema": {"type": "object", "properties": {"data": {"type": "array", "items": {"$ref": "#/components/schemas/InventoryRow"}}, "pagination": {"$ref": "#/components/schemas/Pagination"}}}}}}, "400": {"description": "Invalid JSON or header / 请求格式错误", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Error"}}}}, "401": {"description": "Missing, invalid, expired or revoked API key; invalid, expired or replayed signature; appkey mismatch / 密钥或签名无效", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Error"}}}}, "403": {"description": "Insufficient scope, warehouse not contracted or IP not allowed / 权限不足、仓库未签约或 IP 不在白名单", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Error"}}}}, "404": {"description": "Not found (also for records of other sellers) / 不存在", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Error"}}}}, "409": {"description": "Conflict (duplicate order, already shipped, ...) / 冲突", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Error"}}}}, "422": {"description": "Validation error / 校验失败", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Error"}}}}, "429": {"description": "Rate limited, see Retry-After / 请求过于频繁", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Error"}}}}}}}, "/api/v1/returns": {"post": {"operationId": "api_returns_create", "tags": ["Returns"], "summary": "Announce a return", "description": "Scope (any of): `returns`", "parameters": [{"name": "Idempotency-Key", "in": "header", "required": false, "schema": {"type": "string"}, "description": "Same key + same body within 7 days returns the stored response instead of creating again / 相同的幂等键 7 天内重复提交返回首次结果"}], "responses": {"201": {"description": "OK", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Return"}}}}, "400": {"description": "Invalid JSON or header / 请求格式错误", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Error"}}}}, "401": {"description": "Missing, invalid, expired or revoked API key; invalid, expired or replayed signature; appkey mismatch / 密钥或签名无效", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Error"}}}}, "403": {"description": "Insufficient scope, warehouse not contracted or IP not allowed / 权限不足、仓库未签约或 IP 不在白名单", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Error"}}}}, "404": {"description": "Not found (also for records of other sellers) / 不存在", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Error"}}}}, "409": {"description": "Conflict (duplicate order, already shipped, ...) / 冲突", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Error"}}}}, "422": {"description": "Validation error / 校验失败", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Error"}}}}, "429": {"description": "Rate limited, see Retry-After / 请求过于频繁", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Error"}}}}}, "requestBody": {"required": true, "content": {"application/json": {"schema": {"$ref": "#/components/schemas/ReturnInput"}}}}}, "get": {"operationId": "api_returns_list", "tags": ["Returns"], "summary": "List returns", "description": "Scope (any of): `returns`", "parameters": [{"name": "state", "in": "query", "required": false, "schema": {"type": "string"}, "description": "announced | received | inspected | awaiting_instruction | processing | held | done | cancelled"}, {"name": "tracking_number", "in": "query", "required": false, "schema": {"type": "string"}, "description": "Return tracking number / 退件运单号"}, {"name": "warehouse_id", "in": "query", "required": false, "schema": {"type": "integer"}, "description": "Contracted warehouse id / 签约仓库 ID"}, {"name": "updated_since", "in": "query", "required": false, "schema": {"type": "string"}, "description": "ISO 8601 date-time: only records changed since / 只返回此时间之后更新的记录"}, {"name": "page", "in": "query", "required": false, "schema": {"type": "integer"}, "description": "Page number, starting at 1 / 页码，从 1 开始"}, {"name": "page_size", "in": "query", "required": false, "schema": {"type": "integer"}, "description": "Items per page (default 50, max 200) / 每页条数（默认 50，最多 200）"}], "responses": {"200": {"description": "OK", "content": {"application/json": {"schema": {"type": "object", "properties": {"data": {"type": "array", "items": {"$ref": "#/components/schemas/Return"}}, "pagination": {"$ref": "#/components/schemas/Pagination"}}}}}}, "400": {"description": "Invalid JSON or header / 请求格式错误", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Error"}}}}, "401": {"description": "Missing, invalid, expired or revoked API key; invalid, expired or replayed signature; appkey mismatch / 密钥或签名无效", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Error"}}}}, "403": {"description": "Insufficient scope, warehouse not contracted or IP not allowed / 权限不足、仓库未签约或 IP 不在白名单", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Error"}}}}, "404": {"description": "Not found (also for records of other sellers) / 不存在", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Error"}}}}, "409": {"description": "Conflict (duplicate order, already shipped, ...) / 冲突", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Error"}}}}, "422": {"description": "Validation error / 校验失败", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Error"}}}}, "429": {"description": "Rate limited, see Retry-After / 请求过于频繁", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Error"}}}}}}}, "/api/v1/returns/{id}": {"get": {"operationId": "api_returns_get", "tags": ["Returns"], "summary": "Get a return", "description": "Scope (any of): `returns`", "parameters": [{"name": "id", "in": "path", "required": true, "schema": {"type": "integer"}}], "responses": {"200": {"description": "OK", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Return"}}}}, "400": {"description": "Invalid JSON or header / 请求格式错误", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Error"}}}}, "401": {"description": "Missing, invalid, expired or revoked API key; invalid, expired or replayed signature; appkey mismatch / 密钥或签名无效", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Error"}}}}, "403": {"description": "Insufficient scope, warehouse not contracted or IP not allowed / 权限不足、仓库未签约或 IP 不在白名单", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Error"}}}}, "404": {"description": "Not found (also for records of other sellers) / 不存在", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Error"}}}}, "409": {"description": "Conflict (duplicate order, already shipped, ...) / 冲突", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Error"}}}}, "422": {"description": "Validation error / 校验失败", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Error"}}}}, "429": {"description": "Rate limited, see Retry-After / 请求过于频繁", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Error"}}}}}}}, "/api/v1/returns/{id}/instruction": {"post": {"operationId": "api_returns_instruction", "tags": ["Returns"], "summary": "Give the instruction for an inspected return", "description": "Scope (any of): `returns`", "parameters": [{"name": "id", "in": "path", "required": true, "schema": {"type": "integer"}}, {"name": "Idempotency-Key", "in": "header", "required": false, "schema": {"type": "string"}, "description": "Same key + same body within 7 days returns the stored response instead of creating again / 相同的幂等键 7 天内重复提交返回首次结果"}], "responses": {"200": {"description": "OK", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Return"}}}}, "400": {"description": "Invalid JSON or header / 请求格式错误", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Error"}}}}, "401": {"description": "Missing, invalid, expired or revoked API key; invalid, expired or replayed signature; appkey mismatch / 密钥或签名无效", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Error"}}}}, "403": {"description": "Insufficient scope, warehouse not contracted or IP not allowed / 权限不足、仓库未签约或 IP 不在白名单", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Error"}}}}, "404": {"description": "Not found (also for records of other sellers) / 不存在", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Error"}}}}, "409": {"description": "Conflict (duplicate order, already shipped, ...) / 冲突", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Error"}}}}, "422": {"description": "Validation error / 校验失败", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Error"}}}}, "429": {"description": "Rate limited, see Retry-After / 请求过于频繁", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Error"}}}}}, "requestBody": {"required": true, "content": {"application/json": {"schema": {"$ref": "#/components/schemas/InstructionInput"}}}}}}, "/api/v1/vas/services": {"get": {"operationId": "api_vas_services", "tags": ["Value-added services"], "summary": "Services that can be requested", "description": "Scope (any of): `vas`", "parameters": [], "responses": {"200": {"description": "OK", "content": {"application/json": {"schema": {"type": "object", "properties": {"data": {"type": "array", "items": {"$ref": "#/components/schemas/VasService"}}, "pagination": {"$ref": "#/components/schemas/Pagination"}}}}}}, "400": {"description": "Invalid JSON or header / 请求格式错误", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Error"}}}}, "401": {"description": "Missing, invalid, expired or revoked API key; invalid, expired or replayed signature; appkey mismatch / 密钥或签名无效", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Error"}}}}, "403": {"description": "Insufficient scope, warehouse not contracted or IP not allowed / 权限不足、仓库未签约或 IP 不在白名单", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Error"}}}}, "404": {"description": "Not found (also for records of other sellers) / 不存在", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Error"}}}}, "409": {"description": "Conflict (duplicate order, already shipped, ...) / 冲突", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Error"}}}}, "422": {"description": "Validation error / 校验失败", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Error"}}}}, "429": {"description": "Rate limited, see Retry-After / 请求过于频繁", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Error"}}}}}}}, "/api/v1/vas": {"post": {"operationId": "api_vas_create", "tags": ["Value-added services"], "summary": "Request a value-added service", "description": "Scope (any of): `vas`", "parameters": [{"name": "Idempotency-Key", "in": "header", "required": false, "schema": {"type": "string"}, "description": "Same key + same body within 7 days returns the stored response instead of creating again / 相同的幂等键 7 天内重复提交返回首次结果"}], "responses": {"201": {"description": "OK", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Vas"}}}}, "400": {"description": "Invalid JSON or header / 请求格式错误", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Error"}}}}, "401": {"description": "Missing, invalid, expired or revoked API key; invalid, expired or replayed signature; appkey mismatch / 密钥或签名无效", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Error"}}}}, "403": {"description": "Insufficient scope, warehouse not contracted or IP not allowed / 权限不足、仓库未签约或 IP 不在白名单", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Error"}}}}, "404": {"description": "Not found (also for records of other sellers) / 不存在", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Error"}}}}, "409": {"description": "Conflict (duplicate order, already shipped, ...) / 冲突", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Error"}}}}, "422": {"description": "Validation error / 校验失败", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Error"}}}}, "429": {"description": "Rate limited, see Retry-After / 请求过于频繁", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Error"}}}}}, "requestBody": {"required": true, "content": {"application/json": {"schema": {"$ref": "#/components/schemas/VasInput"}}}}}, "get": {"operationId": "api_vas_list", "tags": ["Value-added services"], "summary": "List value-added service requests", "description": "Scope (any of): `vas`", "parameters": [{"name": "state", "in": "query", "required": false, "schema": {"type": "string"}, "description": "draft | submitted | quoted | in_progress | to_confirm | done | cancelled"}, {"name": "warehouse_id", "in": "query", "required": false, "schema": {"type": "integer"}, "description": "Contracted warehouse id / 签约仓库 ID"}, {"name": "updated_since", "in": "query", "required": false, "schema": {"type": "string"}, "description": "ISO 8601 date-time: only records changed since / 只返回此时间之后更新的记录"}, {"name": "page", "in": "query", "required": false, "schema": {"type": "integer"}, "description": "Page number, starting at 1 / 页码，从 1 开始"}, {"name": "page_size", "in": "query", "required": false, "schema": {"type": "integer"}, "description": "Items per page (default 50, max 200) / 每页条数（默认 50，最多 200）"}], "responses": {"200": {"description": "OK", "content": {"application/json": {"schema": {"type": "object", "properties": {"data": {"type": "array", "items": {"$ref": "#/components/schemas/Vas"}}, "pagination": {"$ref": "#/components/schemas/Pagination"}}}}}}, "400": {"description": "Invalid JSON or header / 请求格式错误", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Error"}}}}, "401": {"description": "Missing, invalid, expired or revoked API key; invalid, expired or replayed signature; appkey mismatch / 密钥或签名无效", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Error"}}}}, "403": {"description": "Insufficient scope, warehouse not contracted or IP not allowed / 权限不足、仓库未签约或 IP 不在白名单", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Error"}}}}, "404": {"description": "Not found (also for records of other sellers) / 不存在", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Error"}}}}, "409": {"description": "Conflict (duplicate order, already shipped, ...) / 冲突", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Error"}}}}, "422": {"description": "Validation error / 校验失败", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Error"}}}}, "429": {"description": "Rate limited, see Retry-After / 请求过于频繁", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Error"}}}}}}}, "/api/v1/vas/{id}": {"get": {"operationId": "api_vas_get", "tags": ["Value-added services"], "summary": "Get a value-added service request", "description": "Scope (any of): `vas`", "parameters": [{"name": "id", "in": "path", "required": true, "schema": {"type": "integer"}}], "responses": {"200": {"description": "OK", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Vas"}}}}, "400": {"description": "Invalid JSON or header / 请求格式错误", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Error"}}}}, "401": {"description": "Missing, invalid, expired or revoked API key; invalid, expired or replayed signature; appkey mismatch / 密钥或签名无效", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Error"}}}}, "403": {"description": "Insufficient scope, warehouse not contracted or IP not allowed / 权限不足、仓库未签约或 IP 不在白名单", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Error"}}}}, "404": {"description": "Not found (also for records of other sellers) / 不存在", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Error"}}}}, "409": {"description": "Conflict (duplicate order, already shipped, ...) / 冲突", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Error"}}}}, "422": {"description": "Validation error / 校验失败", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Error"}}}}, "429": {"description": "Rate limited, see Retry-After / 请求过于频繁", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Error"}}}}}}}, "/api/v1/transfers": {"post": {"operationId": "api_transfers_create", "tags": ["FBA / transfers"], "summary": "Create an FBA / transfer order (box labels as base64 PDF)", "description": "Scope (any of): `orders`", "parameters": [{"name": "Idempotency-Key", "in": "header", "required": false, "schema": {"type": "string"}, "description": "Same key + same body within 7 days returns the stored response instead of creating again / 相同的幂等键 7 天内重复提交返回首次结果"}], "responses": {"201": {"description": "OK", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Transfer"}}}}, "400": {"description": "Invalid JSON or header / 请求格式错误", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Error"}}}}, "401": {"description": "Missing, invalid, expired or revoked API key; invalid, expired or replayed signature; appkey mismatch / 密钥或签名无效", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Error"}}}}, "403": {"description": "Insufficient scope, warehouse not contracted or IP not allowed / 权限不足、仓库未签约或 IP 不在白名单", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Error"}}}}, "404": {"description": "Not found (also for records of other sellers) / 不存在", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Error"}}}}, "409": {"description": "Conflict (duplicate order, already shipped, ...) / 冲突", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Error"}}}}, "422": {"description": "Validation error / 校验失败", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Error"}}}}, "429": {"description": "Rate limited, see Retry-After / 请求过于频繁", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Error"}}}}}, "requestBody": {"required": true, "content": {"application/json": {"schema": {"$ref": "#/components/schemas/TransferInput"}}}}}, "get": {"operationId": "api_transfers_list", "tags": ["FBA / transfers"], "summary": "List FBA / transfer orders", "description": "Scope (any of): `orders`", "parameters": [{"name": "status", "in": "query", "required": false, "schema": {"type": "string"}, "description": "pending | processing | on_hold | shipped | cancelled"}, {"name": "shipment_id", "in": "query", "required": false, "schema": {"type": "string"}, "description": "FBA shipment ID"}, {"name": "warehouse_id", "in": "query", "required": false, "schema": {"type": "integer"}, "description": "Contracted warehouse id / 签约仓库 ID"}, {"name": "updated_since", "in": "query", "required": false, "schema": {"type": "string"}, "description": "ISO 8601 date-time: only records changed since / 只返回此时间之后更新的记录"}, {"name": "page", "in": "query", "required": false, "schema": {"type": "integer"}, "description": "Page number, starting at 1 / 页码，从 1 开始"}, {"name": "page_size", "in": "query", "required": false, "schema": {"type": "integer"}, "description": "Items per page (default 50, max 200) / 每页条数（默认 50，最多 200）"}], "responses": {"200": {"description": "OK", "content": {"application/json": {"schema": {"type": "object", "properties": {"data": {"type": "array", "items": {"$ref": "#/components/schemas/Transfer"}}, "pagination": {"$ref": "#/components/schemas/Pagination"}}}}}}, "400": {"description": "Invalid JSON or header / 请求格式错误", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Error"}}}}, "401": {"description": "Missing, invalid, expired or revoked API key; invalid, expired or replayed signature; appkey mismatch / 密钥或签名无效", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Error"}}}}, "403": {"description": "Insufficient scope, warehouse not contracted or IP not allowed / 权限不足、仓库未签约或 IP 不在白名单", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Error"}}}}, "404": {"description": "Not found (also for records of other sellers) / 不存在", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Error"}}}}, "409": {"description": "Conflict (duplicate order, already shipped, ...) / 冲突", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Error"}}}}, "422": {"description": "Validation error / 校验失败", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Error"}}}}, "429": {"description": "Rate limited, see Retry-After / 请求过于频繁", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Error"}}}}}}}, "/api/v1/transfers/{id}": {"get": {"operationId": "api_transfers_get", "tags": ["FBA / transfers"], "summary": "Get an FBA / transfer order", "description": "Scope (any of): `orders`", "parameters": [{"name": "id", "in": "path", "required": true, "schema": {"type": "integer"}}], "responses": {"200": {"description": "OK", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Transfer"}}}}, "400": {"description": "Invalid JSON or header / 请求格式错误", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Error"}}}}, "401": {"description": "Missing, invalid, expired or revoked API key; invalid, expired or replayed signature; appkey mismatch / 密钥或签名无效", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Error"}}}}, "403": {"description": "Insufficient scope, warehouse not contracted or IP not allowed / 权限不足、仓库未签约或 IP 不在白名单", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Error"}}}}, "404": {"description": "Not found (also for records of other sellers) / 不存在", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Error"}}}}, "409": {"description": "Conflict (duplicate order, already shipped, ...) / 冲突", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Error"}}}}, "422": {"description": "Validation error / 校验失败", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Error"}}}}, "429": {"description": "Rate limited, see Retry-After / 请求过于频繁", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Error"}}}}}}}, "/api/v1/wallets": {"get": {"operationId": "api_wallets", "tags": ["Billing"], "summary": "Prepaid balance per warehouse company", "description": "Scope (any of): `billing:read`", "parameters": [], "responses": {"200": {"description": "OK", "content": {"application/json": {"schema": {"type": "object", "properties": {"data": {"type": "array", "items": {"$ref": "#/components/schemas/Wallet"}}, "pagination": {"$ref": "#/components/schemas/Pagination"}}}}}}, "400": {"description": "Invalid JSON or header / 请求格式错误", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Error"}}}}, "401": {"description": "Missing, invalid, expired or revoked API key; invalid, expired or replayed signature; appkey mismatch / 密钥或签名无效", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Error"}}}}, "403": {"description": "Insufficient scope, warehouse not contracted or IP not allowed / 权限不足、仓库未签约或 IP 不在白名单", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Error"}}}}, "404": {"description": "Not found (also for records of other sellers) / 不存在", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Error"}}}}, "409": {"description": "Conflict (duplicate order, already shipped, ...) / 冲突", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Error"}}}}, "422": {"description": "Validation error / 校验失败", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Error"}}}}, "429": {"description": "Rate limited, see Retry-After / 请求过于频繁", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Error"}}}}}}}, "/api/v1/wallets/{id}/transactions": {"get": {"operationId": "api_wallet_transactions", "tags": ["Billing"], "summary": "Prepaid balance transactions", "description": "Scope (any of): `billing:read`", "parameters": [{"name": "id", "in": "path", "required": true, "schema": {"type": "integer"}}, {"name": "date_from", "in": "query", "required": false, "schema": {"type": "string"}, "description": "ISO date-time / 开始时间"}, {"name": "date_to", "in": "query", "required": false, "schema": {"type": "string"}, "description": "ISO date-time / 结束时间"}, {"name": "page", "in": "query", "required": false, "schema": {"type": "integer"}, "description": "Page number, starting at 1 / 页码，从 1 开始"}, {"name": "page_size", "in": "query", "required": false, "schema": {"type": "integer"}, "description": "Items per page (default 50, max 200) / 每页条数（默认 50，最多 200）"}], "responses": {"200": {"description": "OK", "content": {"application/json": {"schema": {"type": "object", "properties": {"data": {"type": "array", "items": {"$ref": "#/components/schemas/WalletTransaction"}}, "pagination": {"$ref": "#/components/schemas/Pagination"}}}}}}, "400": {"description": "Invalid JSON or header / 请求格式错误", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Error"}}}}, "401": {"description": "Missing, invalid, expired or revoked API key; invalid, expired or replayed signature; appkey mismatch / 密钥或签名无效", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Error"}}}}, "403": {"description": "Insufficient scope, warehouse not contracted or IP not allowed / 权限不足、仓库未签约或 IP 不在白名单", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Error"}}}}, "404": {"description": "Not found (also for records of other sellers) / 不存在", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Error"}}}}, "409": {"description": "Conflict (duplicate order, already shipped, ...) / 冲突", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Error"}}}}, "422": {"description": "Validation error / 校验失败", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Error"}}}}, "429": {"description": "Rate limited, see Retry-After / 请求过于频繁", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Error"}}}}}}}, "/api/v1/charges": {"get": {"operationId": "api_charges", "tags": ["Billing"], "summary": "Charges (billable events)", "description": "Scope (any of): `billing:read`", "parameters": [{"name": "date_from", "in": "query", "required": false, "schema": {"type": "string"}, "description": "ISO date-time / 开始时间"}, {"name": "date_to", "in": "query", "required": false, "schema": {"type": "string"}, "description": "ISO date-time / 结束时间"}, {"name": "charge_type", "in": "query", "required": false, "schema": {"type": "string"}, "description": "e.g. outbound, inbound, storage / 费用类型"}, {"name": "state", "in": "query", "required": false, "schema": {"type": "string"}, "description": "pending | rated | error | void"}, {"name": "warehouse_id", "in": "query", "required": false, "schema": {"type": "integer"}, "description": "Contracted warehouse id / 签约仓库 ID"}, {"name": "page", "in": "query", "required": false, "schema": {"type": "integer"}, "description": "Page number, starting at 1 / 页码，从 1 开始"}, {"name": "page_size", "in": "query", "required": false, "schema": {"type": "integer"}, "description": "Items per page (default 50, max 200) / 每页条数（默认 50，最多 200）"}], "responses": {"200": {"description": "OK", "content": {"application/json": {"schema": {"type": "object", "properties": {"data": {"type": "array", "items": {"$ref": "#/components/schemas/Charge"}}, "pagination": {"$ref": "#/components/schemas/Pagination"}}}}}}, "400": {"description": "Invalid JSON or header / 请求格式错误", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Error"}}}}, "401": {"description": "Missing, invalid, expired or revoked API key; invalid, expired or replayed signature; appkey mismatch / 密钥或签名无效", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Error"}}}}, "403": {"description": "Insufficient scope, warehouse not contracted or IP not allowed / 权限不足、仓库未签约或 IP 不在白名单", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Error"}}}}, "404": {"description": "Not found (also for records of other sellers) / 不存在", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Error"}}}}, "409": {"description": "Conflict (duplicate order, already shipped, ...) / 冲突", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Error"}}}}, "422": {"description": "Validation error / 校验失败", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Error"}}}}, "429": {"description": "Rate limited, see Retry-After / 请求过于频繁", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Error"}}}}}}}}, "webhooks": {"order.label_created": {"post": {"summary": "A shipping label was bought: first tracking number, before the order leaves the warehouse", "parameters": [{"name": "X-WMS-Event", "in": "header", "schema": {"type": "string"}}, {"name": "X-WMS-Event-Id", "in": "header", "schema": {"type": "string"}}, {"name": "X-WMS-Timestamp", "in": "header", "schema": {"type": "string"}, "description": "Unix time (seconds)"}, {"name": "X-WMS-Signature", "in": "header", "schema": {"type": "string"}, "description": "sha256=hex(HMAC-SHA256(secret, timestamp + '.' + raw body))"}], "requestBody": {"content": {"application/json": {"schema": {"$ref": "#/components/schemas/WebhookEvent"}}}}, "responses": {"200": {"description": "Any 2xx acknowledges; anything else is retried with back-off (1 min ... 24 h)"}}}}, "order.shipped": {"post": {"summary": "An order or transfer left the warehouse (tracking numbers included)", "parameters": [{"name": "X-WMS-Event", "in": "header", "schema": {"type": "string"}}, {"name": "X-WMS-Event-Id", "in": "header", "schema": {"type": "string"}}, {"name": "X-WMS-Timestamp", "in": "header", "schema": {"type": "string"}, "description": "Unix time (seconds)"}, {"name": "X-WMS-Signature", "in": "header", "schema": {"type": "string"}, "description": "sha256=hex(HMAC-SHA256(secret, timestamp + '.' + raw body))"}], "requestBody": {"content": {"application/json": {"schema": {"$ref": "#/components/schemas/WebhookEvent"}}}}, "responses": {"200": {"description": "Any 2xx acknowledges; anything else is retried with back-off (1 min ... 24 h)"}}}}, "order.held": {"post": {"summary": "An order was put on hold", "parameters": [{"name": "X-WMS-Event", "in": "header", "schema": {"type": "string"}}, {"name": "X-WMS-Event-Id", "in": "header", "schema": {"type": "string"}}, {"name": "X-WMS-Timestamp", "in": "header", "schema": {"type": "string"}, "description": "Unix time (seconds)"}, {"name": "X-WMS-Signature", "in": "header", "schema": {"type": "string"}, "description": "sha256=hex(HMAC-SHA256(secret, timestamp + '.' + raw body))"}], "requestBody": {"content": {"application/json": {"schema": {"$ref": "#/components/schemas/WebhookEvent"}}}}, "responses": {"200": {"description": "Any 2xx acknowledges; anything else is retried with back-off (1 min ... 24 h)"}}}}, "inbound.received": {"post": {"summary": "Goods of an inbound notice were received", "parameters": [{"name": "X-WMS-Event", "in": "header", "schema": {"type": "string"}}, {"name": "X-WMS-Event-Id", "in": "header", "schema": {"type": "string"}}, {"name": "X-WMS-Timestamp", "in": "header", "schema": {"type": "string"}, "description": "Unix time (seconds)"}, {"name": "X-WMS-Signature", "in": "header", "schema": {"type": "string"}, "description": "sha256=hex(HMAC-SHA256(secret, timestamp + '.' + raw body))"}], "requestBody": {"content": {"application/json": {"schema": {"$ref": "#/components/schemas/WebhookEvent"}}}}, "responses": {"200": {"description": "Any 2xx acknowledges; anything else is retried with back-off (1 min ... 24 h)"}}}}, "return.awaiting_instruction": {"post": {"summary": "An inspected return waits for your instruction", "parameters": [{"name": "X-WMS-Event", "in": "header", "schema": {"type": "string"}}, {"name": "X-WMS-Event-Id", "in": "header", "schema": {"type": "string"}}, {"name": "X-WMS-Timestamp", "in": "header", "schema": {"type": "string"}, "description": "Unix time (seconds)"}, {"name": "X-WMS-Signature", "in": "header", "schema": {"type": "string"}, "description": "sha256=hex(HMAC-SHA256(secret, timestamp + '.' + raw body))"}], "requestBody": {"content": {"application/json": {"schema": {"$ref": "#/components/schemas/WebhookEvent"}}}}, "responses": {"200": {"description": "Any 2xx acknowledges; anything else is retried with back-off (1 min ... 24 h)"}}}}, "wallet.low_balance": {"post": {"summary": "A prepaid balance fell below its low-balance threshold", "parameters": [{"name": "X-WMS-Event", "in": "header", "schema": {"type": "string"}}, {"name": "X-WMS-Event-Id", "in": "header", "schema": {"type": "string"}}, {"name": "X-WMS-Timestamp", "in": "header", "schema": {"type": "string"}, "description": "Unix time (seconds)"}, {"name": "X-WMS-Signature", "in": "header", "schema": {"type": "string"}, "description": "sha256=hex(HMAC-SHA256(secret, timestamp + '.' + raw body))"}], "requestBody": {"content": {"application/json": {"schema": {"$ref": "#/components/schemas/WebhookEvent"}}}}, "responses": {"200": {"description": "Any 2xx acknowledges; anything else is retried with back-off (1 min ... 24 h)"}}}}}, "components": {"securitySchemes": {"bearerAuth": {"type": "http", "scheme": "bearer", "description": "Scopes: orders (Outbound orders and FBA / transfer orders), inbound (Inbound notices (ASN) and SKU master data), stock (Inventory and SKU read access), returns (Return announcements and instructions), vas (Value-added service requests), billing:read (Prepaid balance, transactions and charges (read only))"}, "apiKeyHeader": {"type": "apiKey", "in": "header", "name": "X-API-Key"}, "hmacKey": {"type": "apiKey", "in": "header", "name": "X-WMS-Key", "description": "Optional HMAC request signing (the key itself is not sent): headers `X-WMS-Key` (appkey = seller code, or the key prefix), `X-WMS-Timestamp` (Unix seconds, within 300 s), `X-WMS-Nonce` (8-64 characters [A-Za-z0-9_-], single use) and `X-WMS-Signature: sha256=<hex>` where hex = HMAC-SHA256(key = sha256_hex(appSecret), message = METHOD \\n PATH \\n QUERY \\n TIMESTAMP \\n NONCE \\n sha256_hex(raw body)), lines joined with \\n. appSecret = the API key."}, "hmacTimestamp": {"type": "apiKey", "in": "header", "name": "X-WMS-Timestamp"}, "hmacNonce": {"type": "apiKey", "in": "header", "name": "X-WMS-Nonce"}, "hmacSignature": {"type": "apiKey", "in": "header", "name": "X-WMS-Signature"}}, "schemas": {"Error": {"type": "object", "properties": {"error": {"type": "object", "properties": {"code": {"type": "string", "description": "Machine readable code, e.g. not_found, insufficient_scope, warehouse_not_contracted, validation_error, duplicate_order, rate_limited"}, "message": {"type": "string"}, "details": {"type": "object"}}, "required": ["code", "message"]}}, "required": ["error"]}, "Pagination": {"type": "object", "properties": {"page": {"type": "integer"}, "page_size": {"type": "integer"}, "total": {"type": "integer"}, "has_more": {"type": "boolean"}}}, "Me": {"type": "object", "properties": {"seller": {"type": "object", "properties": {"id": {"type": "integer"}, "code": {"type": ["string", "null"]}, "name": {"type": "string"}}}, "user": {"type": "object", "properties": {"id": {"type": "integer"}, "name": {"type": "string"}, "login": {"type": "string"}}}, "key": {"type": "object", "properties": {"id": {"type": "integer"}, "name": {"type": "string"}, "prefix": {"type": "string"}, "scopes": {"type": "array", "items": {"type": "string"}}, "rate_limit_per_minute": {"type": "integer"}, "expires_at": {"type": ["string", "null"], "description": "ISO 8601 UTC date-time", "format": "date-time"}, "appkey": {"type": ["string", "null"], "description": "Your appkey (= seller code), for X-WMS-Key"}, "signing_available": {"type": "boolean", "description": "HMAC request signing can be used"}, "signature_required": {"type": "boolean"}, "ip_allowlist": {"type": "array", "items": {"type": "string"}}}}}}, "Warehouse": {"type": "object", "properties": {"id": {"type": "integer"}, "public_code": {"type": "string", "description": "Platform-unique warehouse code (WS-<company>-<warehouse>), never changes; accepted as warehouse_code / 全平台唯一的仓库代码，生成后不变"}, "code": {"type": "string", "description": "Warehouse short name, unique per warehouse company only"}, "name": {"type": "string"}, "company": {"type": "string"}, "mode": {"type": "string", "enum": ["light", "standard", "pro"]}, "timezone": {"type": ["string", "null"]}, "address": {"type": "object", "properties": {"name": {"type": ["string", "null"]}, "street": {"type": ["string", "null"]}, "street2": {"type": ["string", "null"]}, "city": {"type": ["string", "null"]}, "state": {"type": ["string", "null"]}, "zip": {"type": ["string", "null"]}, "country": {"type": ["string", "null"]}, "phone": {"type": ["string", "null"]}}}}}, "Sku": {"type": "object", "properties": {"id": {"type": "integer"}, "sku": {"type": "string"}, "name": {"type": "string"}, "barcode": {"type": ["string", "null"]}, "fnsku": {"type": ["string", "null"]}, "length_cm": {"type": "number"}, "width_cm": {"type": "number"}, "height_cm": {"type": "number"}, "weight_kg": {"type": "number"}, "volume_cbm": {"type": "number"}, "active": {"type": "boolean"}, "created_at": {"type": ["string", "null"], "description": "ISO 8601 UTC date-time", "format": "date-time"}, "updated_at": {"type": ["string", "null"], "description": "ISO 8601 UTC date-time", "format": "date-time"}}}, "SkuInput": {"type": "object", "properties": {"sku": {"type": "string", "description": "SKU code, unique per seller (required on create)"}, "name": {"type": "string", "description": "Product name (required on create)"}, "barcode": {"type": "string"}, "fnsku": {"type": "string"}, "length_cm": {"type": "number"}, "width_cm": {"type": "number"}, "height_cm": {"type": "number"}, "weight_kg": {"type": "number"}}}, "Recipient": {"type": "object", "properties": {"name": {"type": "string"}, "street": {"type": "string"}, "street2": {"type": "string"}, "city": {"type": "string"}, "state": {"type": "string", "description": "State code or name (required for US)"}, "zip": {"type": "string"}, "country": {"type": "string", "description": "ISO country code, default US"}, "phone": {"type": "string"}, "email": {"type": "string"}}, "required": ["name", "street", "city", "zip"]}, "OrderLineInput": {"type": "object", "properties": {"sku": {"type": "string", "description": "Warehouse SKU code, barcode or a mapped channel SKU"}, "quantity": {"type": "number"}, "external_item_id": {"type": "string", "description": "Your order line id (e.g. Amazon order-item-id)"}, "product_name": {"type": "string"}}, "required": ["sku", "quantity"]}, "OrderInput": {"type": "object", "properties": {"warehouse_id": {"type": "integer", "description": "Contracted warehouse id (or use warehouse_code)"}, "warehouse_code": {"type": "string", "description": "Warehouse public_code (recommended) or short code"}, "external_id": {"type": "string", "description": "Your order number - unique per seller (duplicates get 409)"}, "channel": {"type": "string", "description": "e.g. amazon, walmart, shopify"}, "store": {"type": "string"}, "order_date": {"type": "string", "format": "date-time"}, "ship_by_date": {"type": "string", "format": "date-time"}, "ship_service_level": {"type": "string"}, "buyer_email": {"type": "string"}, "recipient": {"$ref": "#/components/schemas/Recipient"}, "lines": {"type": "array", "items": {"$ref": "#/components/schemas/OrderLineInput"}}}, "required": ["external_id", "recipient", "lines"]}, "OrderLine": {"type": "object", "properties": {"sku": {"type": ["string", "null"]}, "name": {"type": "string"}, "quantity": {"type": "number"}, "shipped_quantity": {"type": "number"}, "external_item_id": {"type": ["string", "null"]}}}, "Order": {"type": "object", "properties": {"id": {"type": "integer"}, "name": {"type": "string"}, "kind": {"type": "string", "enum": ["order", "transfer"]}, "external_id": {"type": ["string", "null"]}, "reference": {"type": ["string", "null"]}, "source": {"type": ["string", "null"]}, "channel": {"type": ["string", "null"]}, "store": {"type": ["string", "null"]}, "warehouse": {"type": "object", "properties": {"id": {"type": "integer"}, "public_code": {"type": "string", "description": "Platform-unique warehouse code (WS-<company>-<warehouse>), never changes; accepted as warehouse_code / 全平台唯一的仓库代码，生成后不变"}, "code": {"type": "string"}, "name": {"type": "string"}}}, "status": {"type": "string", "enum": ["pending", "processing", "on_hold", "shipped", "cancelled"]}, "state": {"type": "string", "description": "Detailed warehouse processing state (draft, waiting, confirmed, assigned, done, cancel); use status for your integration"}, "stage": {"type": ["string", "null"]}, "hold_reason": {"type": ["string", "null"]}, "ship_by": {"type": ["string", "null"], "description": "ISO 8601 UTC date-time", "format": "date-time"}, "scheduled_at": {"type": ["string", "null"], "description": "ISO 8601 UTC date-time", "format": "date-time"}, "created_at": {"type": ["string", "null"], "description": "ISO 8601 UTC date-time", "format": "date-time"}, "updated_at": {"type": ["string", "null"], "description": "ISO 8601 UTC date-time", "format": "date-time"}, "shipped_at": {"type": ["string", "null"], "description": "ISO 8601 UTC date-time", "format": "date-time"}, "service_level": {"type": ["string", "null"]}, "carrier": {"type": ["string", "null"]}, "tracking_numbers": {"type": "array", "items": {"type": "string"}}, "tracking_url": {"type": ["string", "null"]}, "recipient": {"type": "object", "properties": {"name": {"type": ["string", "null"]}, "city": {"type": ["string", "null"]}, "state": {"type": ["string", "null"]}, "zip": {"type": ["string", "null"]}, "country": {"type": ["string", "null"]}}}, "lines": {"type": "array", "items": {"$ref": "#/components/schemas/OrderLine"}}}}, "ReasonInput": {"type": "object", "properties": {"reason": {"type": "string", "description": "Required for hold, optional for cancel"}}}, "SandboxShipInput": {"type": "object", "properties": {"tracking_number": {"type": "string", "description": "Optional; default: a generated SANDBOX... number"}, "carrier": {"type": "string", "description": "Optional; default SANDBOX"}}}, "InboundInput": {"type": "object", "properties": {"warehouse_id": {"type": "integer"}, "warehouse_code": {"type": "string"}, "inbound_type": {"type": "string", "enum": ["parcel", "container", "pallet"], "default": "parcel"}, "container_type": {"type": "string", "enum": ["20gp", "40gp", "40hq", "45hq", "53ft"]}, "container_no": {"type": "string"}, "eta": {"type": "string", "format": "date"}, "carton_count": {"type": "integer", "description": "Required for parcel"}, "pallet_count": {"type": "integer", "description": "Required for pallet"}, "tracking": {"type": "string"}, "reference": {"type": "string", "description": "Your PO / shipment reference"}, "note": {"type": "string"}, "lines": {"type": "array", "items": {"type": "object", "properties": {"sku": {"type": "string"}, "sku_id": {"type": "integer"}, "quantity": {"type": "number"}}, "required": ["quantity"]}}}, "required": ["lines"]}, "Inbound": {"type": "object", "properties": {"id": {"type": "integer"}, "name": {"type": "string"}, "warehouse": {"type": "object", "properties": {"id": {"type": "integer"}, "public_code": {"type": "string", "description": "Platform-unique warehouse code (WS-<company>-<warehouse>), never changes; accepted as warehouse_code / 全平台唯一的仓库代码，生成后不变"}, "code": {"type": "string"}, "name": {"type": "string"}}}, "reference": {"type": ["string", "null"]}, "status": {"type": "string", "enum": ["announced", "arrived", "receiving", "partially_received", "received", "cancelled"]}, "state": {"type": "string"}, "stage": {"type": ["string", "null"]}, "inbound_type": {"type": ["string", "null"]}, "container_type": {"type": ["string", "null"]}, "container_no": {"type": ["string", "null"]}, "tracking": {"type": ["string", "null"]}, "eta": {"type": ["string", "null"], "description": "ISO 8601 UTC date-time", "format": "date-time"}, "carton_count": {"type": "integer"}, "pallet_count": {"type": "integer"}, "created_at": {"type": ["string", "null"], "description": "ISO 8601 UTC date-time", "format": "date-time"}, "updated_at": {"type": ["string", "null"], "description": "ISO 8601 UTC date-time", "format": "date-time"}, "received_at": {"type": ["string", "null"], "description": "ISO 8601 UTC date-time", "format": "date-time"}, "backorder_ids": {"type": "array", "items": {"type": "integer"}}, "lines": {"type": "array", "items": {"type": "object", "properties": {"sku": {"type": ["string", "null"]}, "name": {"type": "string"}, "expected": {"type": "number"}, "received": {"type": "number"}, "open": {"type": "number"}, "difference": {"type": "number"}}}}}}, "InventoryRow": {"type": "object", "properties": {"warehouse": {"type": "object", "properties": {"id": {"type": "integer"}, "public_code": {"type": "string", "description": "Platform-unique warehouse code (WS-<company>-<warehouse>), never changes; accepted as warehouse_code / 全平台唯一的仓库代码，生成后不变"}, "code": {"type": "string"}, "name": {"type": "string"}}}, "sku_id": {"type": "integer"}, "sku": {"type": ["string", "null"]}, "name": {"type": "string"}, "on_hand": {"type": "number"}, "reserved": {"type": "number"}, "available": {"type": "number"}, "batches": {"type": "array", "items": {"type": "object", "properties": {"batch": {"type": ["string", "null"]}, "putaway_date": {"type": ["string", "null"], "description": "ISO 8601 UTC date-time", "format": "date-time"}, "age_days": {"type": "integer"}, "on_hand": {"type": "number"}, "reserved": {"type": "number"}, "available": {"type": "number"}}}}}}, "ReturnInput": {"type": "object", "properties": {"warehouse_id": {"type": "integer"}, "warehouse_code": {"type": "string"}, "tracking_number": {"type": "string"}, "rma_reference": {"type": "string"}, "origin_order": {"type": "string"}, "lines": {"type": "array", "items": {"type": "object", "properties": {"sku": {"type": "string"}, "sku_id": {"type": "integer"}, "description": {"type": "string"}, "quantity": {"type": "number"}}}}, "instruction": {"type": "string", "description": "Optional pre-set instruction", "enum": ["restock", "relabel_transfer", "destroy", "hold"]}, "instruction_note": {"type": "string"}}, "description": "Give at least one of tracking_number, rma_reference, origin_order."}, "InstructionInput": {"type": "object", "properties": {"instruction": {"type": "string", "enum": ["restock", "relabel_transfer", "destroy", "hold"]}, "note": {"type": "string"}}, "required": ["instruction"]}, "Return": {"type": "object", "properties": {"id": {"type": "integer"}, "name": {"type": "string"}, "warehouse": {"type": "object", "properties": {"id": {"type": "integer"}, "public_code": {"type": "string", "description": "Platform-unique warehouse code (WS-<company>-<warehouse>), never changes; accepted as warehouse_code / 全平台唯一的仓库代码，生成后不变"}, "code": {"type": "string"}, "name": {"type": "string"}}}, "state": {"type": "string"}, "tracking_number": {"type": ["string", "null"]}, "rma_reference": {"type": ["string", "null"]}, "origin_order": {"type": ["string", "null"]}, "instruction": {"type": ["string", "null"]}, "instruction_note": {"type": ["string", "null"]}, "instruction_deadline": {"type": ["string", "null"], "description": "ISO 8601 UTC date-time", "format": "date-time"}, "is_abnormal": {"type": "boolean"}, "abnormal_reason": {"type": ["string", "null"]}, "photo_count": {"type": "integer"}, "announced_at": {"type": ["string", "null"], "description": "ISO 8601 UTC date-time", "format": "date-time"}, "received_at": {"type": ["string", "null"], "description": "ISO 8601 UTC date-time", "format": "date-time"}, "inspected_at": {"type": ["string", "null"], "description": "ISO 8601 UTC date-time", "format": "date-time"}, "done_at": {"type": ["string", "null"], "description": "ISO 8601 UTC date-time", "format": "date-time"}, "updated_at": {"type": ["string", "null"], "description": "ISO 8601 UTC date-time", "format": "date-time"}, "lines": {"type": "array", "items": {"type": "object", "properties": {"sku": {"type": ["string", "null"]}, "description": {"type": ["string", "null"]}, "quantity": {"type": "number"}, "condition": {"type": ["string", "null"], "enum": ["new", "repackable", "unsellable", null]}}}}}}, "VasService": {"type": "object", "properties": {"code": {"type": "string"}, "name": {"type": "string"}, "description": {"type": ["string", "null"]}, "charge_uom": {"type": "string"}, "requires_quote": {"type": "boolean"}, "conditional_recheck": {"type": "boolean"}, "requires_photo": {"type": "boolean"}}}, "VasInput": {"type": "object", "properties": {"warehouse_id": {"type": "integer"}, "warehouse_code": {"type": "string"}, "instructions": {"type": "string"}, "deadline": {"type": "string", "format": "date"}, "order_id": {"type": "integer", "description": "One of your orders / inbound notices this work is for"}, "sku": {"type": "string"}, "submit": {"type": "boolean", "description": "Submit to the warehouse right away (default true)"}, "lines": {"type": "array", "items": {"type": "object", "properties": {"service_code": {"type": "string", "description": "See GET /vas/services"}, "sku": {"type": "string"}, "quantity": {"type": "number"}, "note": {"type": "string"}, "conditional": {"type": "boolean"}, "previous_result": {"type": "string"}}, "required": ["service_code"]}}}, "required": ["lines"]}, "Vas": {"type": "object", "properties": {"id": {"type": "integer"}, "name": {"type": "string"}, "warehouse": {"type": "object", "properties": {"id": {"type": "integer"}, "public_code": {"type": "string", "description": "Platform-unique warehouse code (WS-<company>-<warehouse>), never changes; accepted as warehouse_code / 全平台唯一的仓库代码，生成后不变"}, "code": {"type": "string"}, "name": {"type": "string"}}}, "state": {"type": "string"}, "instructions": {"type": ["string", "null"]}, "deadline": {"type": ["string", "null"], "description": "ISO 8601 UTC date-time", "format": "date-time"}, "order_id": {"type": ["integer", "null"]}, "sku": {"type": ["string", "null"]}, "needs_quote": {"type": "boolean"}, "quote_amount": {"type": "number"}, "quote_approved": {"type": "boolean"}, "currency": {"type": ["string", "null"]}, "created_at": {"type": ["string", "null"], "description": "ISO 8601 UTC date-time", "format": "date-time"}, "submitted_at": {"type": ["string", "null"], "description": "ISO 8601 UTC date-time", "format": "date-time"}, "done_at": {"type": ["string", "null"], "description": "ISO 8601 UTC date-time", "format": "date-time"}, "updated_at": {"type": ["string", "null"], "description": "ISO 8601 UTC date-time", "format": "date-time"}, "lines": {"type": "array", "items": {"type": "object", "properties": {"service_code": {"type": "string"}, "service": {"type": "string"}, "sku": {"type": ["string", "null"]}, "quantity": {"type": "number"}, "qty_done": {"type": "number"}, "note": {"type": ["string", "null"]}}}}}}, "TransferInput": {"type": "object", "properties": {"warehouse_id": {"type": "integer"}, "warehouse_code": {"type": "string"}, "transfer_type": {"type": "string", "enum": ["amazon_fba", "walmart_wfs", "other_warehouse", "pickup"], "default": "amazon_fba"}, "ship_mode": {"type": "string", "enum": ["spd", "ltl", "pickup"], "default": "spd"}, "shipment_id": {"type": "string", "description": "FBA shipment ID (required for amazon_fba)"}, "reference_id": {"type": "string"}, "fc_code": {"type": "string", "description": "Destination FC, e.g. ONT8"}, "destination": {"type": "object", "properties": {"name": {"type": "string"}, "street": {"type": "string"}, "street2": {"type": "string"}, "city": {"type": "string"}, "zip": {"type": "string"}, "state_code": {"type": "string"}, "country_code": {"type": "string"}, "phone": {"type": "string"}, "email": {"type": "string"}}}, "appointment": {"type": "string", "format": "date-time"}, "relabel_required": {"type": "boolean"}, "fnsku_label_count": {"type": "integer"}, "pallet_count": {"type": "integer"}, "carton_count": {"type": "integer"}, "pickup_uom": {"type": "string", "enum": ["pallet", "carton"]}, "reference": {"type": "string"}, "note": {"type": "string"}, "lines": {"type": "array", "items": {"type": "object", "properties": {"sku": {"type": "string"}, "sku_id": {"type": "integer"}, "quantity": {"type": "number"}}, "required": ["quantity"]}}, "box_labels_pdf": {"type": "string", "description": "FBA box labels PDF, base64 (required for amazon_fba): one label per carton", "contentEncoding": "base64"}, "box_labels_filename": {"type": "string"}, "fnsku_labels_pdf": {"type": "string", "description": "FNSKU labels PDF, base64", "contentEncoding": "base64"}, "fnsku_labels_filename": {"type": "string"}}, "required": ["lines"]}, "Transfer": {"allOf": [{"$ref": "#/components/schemas/Order"}, {"type": "object", "properties": {"transfer_type": {"type": ["string", "null"]}, "ship_mode": {"type": ["string", "null"]}, "shipment_id": {"type": ["string", "null"]}, "reference_id": {"type": ["string", "null"]}, "fc_code": {"type": ["string", "null"]}, "appointment": {"type": ["string", "null"], "description": "ISO 8601 UTC date-time", "format": "date-time"}, "relabel_required": {"type": "boolean"}, "carton_count": {"type": "integer"}, "box_label_count": {"type": "integer"}, "pallet_count": {"type": "integer"}}}]}, "Wallet": {"type": "object", "properties": {"id": {"type": "integer"}, "company": {"type": "string"}, "currency": {"type": "string"}, "balance": {"type": "number"}, "low_balance_threshold": {"type": "number"}, "credit_limit": {"type": "number"}, "is_low": {"type": "boolean"}, "warehouses": {"type": "array", "items": {"type": "object", "properties": {"id": {"type": "integer"}, "public_code": {"type": "string", "description": "Platform-unique warehouse code (WS-<company>-<warehouse>), never changes; accepted as warehouse_code / 全平台唯一的仓库代码，生成后不变"}, "code": {"type": "string"}, "name": {"type": "string"}}}}}}, "WalletTransaction": {"type": "object", "properties": {"id": {"type": "integer"}, "date": {"type": ["string", "null"], "description": "ISO 8601 UTC date-time", "format": "date-time"}, "type": {"type": "string", "enum": ["topup", "charge", "refund", "adjust"]}, "amount": {"type": "number"}, "balance_after": {"type": "number"}, "currency": {"type": "string"}, "reference": {"type": ["string", "null"]}, "charge_type": {"type": ["string", "null"]}}}, "Charge": {"type": "object", "properties": {"id": {"type": "integer"}, "date": {"type": ["string", "null"], "description": "ISO 8601 UTC date-time", "format": "date-time"}, "charge_type": {"type": "string"}, "quantity": {"type": "number"}, "uom": {"type": "string"}, "amount": {"type": "number"}, "currency": {"type": ["string", "null"]}, "state": {"type": "string", "enum": ["pending", "rated", "error", "void"]}, "reference": {"type": ["string", "null"]}, "warehouse": {"type": "object", "properties": {"id": {"type": "integer"}, "public_code": {"type": "string", "description": "Platform-unique warehouse code (WS-<company>-<warehouse>), never changes; accepted as warehouse_code / 全平台唯一的仓库代码，生成后不变"}, "code": {"type": "string"}, "name": {"type": "string"}}}}}, "WebhookEvent": {"type": "object", "properties": {"id": {"type": "string", "description": "Event id (evt_...), use it to ignore duplicates"}, "type": {"type": "string", "enum": ["order.label_created", "order.shipped", "order.held", "inbound.received", "return.awaiting_instruction", "wallet.low_balance"]}, "created_at": {"type": ["string", "null"], "description": "ISO 8601 UTC date-time", "format": "date-time"}, "seller": {"type": "object", "properties": {"id": {"type": "integer"}, "code": {"type": ["string", "null"]}}}, "data": {"type": "object", "description": "order.label_created / order.shipped / order.held: {order: Order}; inbound.received: {inbound: Inbound, receipt: {...}}; return.awaiting_instruction: {return: Return}; wallet.low_balance: {wallet: Wallet}"}}}}}}