快速开始

API 中心创建的 Client ID 即兼容协议的 api_key，API Secret 仅显示一次。生产密钥建议强制出口 IP 白名单。

开放 API V2 认证

所有请求在 Query 传入 api_key、timestamp、nonce、signature。时间戳容差 5 分钟，nonce 为 8–32 位且只能使用一次。

{HTTP_METHOD}\n{timestamp}\n{nonce}\n{request_path}\n{sorted_business_params}

Method 大写，Path 不含 Query；业务参数按键名排序后使用 PHP http_build_query 默认编码（空格编码为 +），再用 API Secret 计算 HMAC-SHA256。成功响应使用 code=1，顶层字段为 message 和 timestamp。

商品、分类与余额

GET /api/v2/categories
GET /api/v2/products?lang=zh-cn&cate_id=1&keyword=facebook
GET /api/v2/products/sku?sku_id=1001&lang=zh-cn
GET /api/v2/account/balance

对外只返回本地公开商品 ID、合作方售价、本地可售库存与本地钱包。不返回上游商品 ID、成本、上游库存或上游余额。

创建订单

POST /api/v2/order/create

sku_id=1001&quantity=1&request_no=PARTNER-20260714-001&response_mode=strict&notify_url=https%3A%2F%2Fpartner.example.com%2Fwebhook

request_no 在 V2 中可选但强烈建议填写：最长 64，仅字母、数字、下划线和短横线，并应保证每笔业务订单唯一。同一账户重复提交相同 request_no 只返回原订单，不重复冻结、采购或发卡。

notify_url 可选，但必须与 API 合作中心中该密钥已启用的公网 HTTPS Webhook 地址完全一致。回调仅在对方返回 HTTP 200 时视为成功；正文只通知已发货状态，不包含卡密，请再调用查单/取卡接口拉取。

下单后钱包金额先进入冻结；成功发卡后转为消费，明确失败后解冻。供应商响应不确定时保留冻结并只查单，不重新创建。

查单取卡

GET /api/v2/order/query

request_no=PARTNER-20260714-001

优先使用 request_no，仅无 request_no 时使用本地 order_no。已交付返回 status=shipped、delivery_content、secret和 delivery_count。卡密为完整字符串，请加密存储，禁止写入普通日志。

原 Header/JSON V1（保留）

原协议路径为 /openapi/v1/*，使用 X-Client-Id、X-Timestamp、X-Nonce、X-Signature 请求头和 JSON Body。原协议仍可用，新接入建议直接使用上述开放 API V2。

GET  /openapi/v1/products
POST /openapi/v1/orders
GET  /openapi/v1/orders/{order_no}
GET  /openapi/v1/orders/{order_no}/delivery
GET  /openapi/v1/account/balance

兼容 V1 创建订单

POST /api/v1/order/create
sku_id=1001&quantity=1&remark=partner-order

兼容 V1 协议未定义 request_no，因此该请求可不传。服务端只允许在有效期内对完全相同的已签名下单请求进行安全重放并返回原订单；若客户端重新生成 timestamp、nonce 和 signature，V1 协议无法证明它仍是同一业务单。对网络不确定场景要求强幂等时，请使用 V2 并显式传唯一 request_no。

错误码

1：成功
1100：参数错误
1200：认证、Nonce、IP 或 Scope 错误
1203：签名验证失败
1300：库存不足
1301：钱包余额不足
1303/1304：SKU 不存在/已下架
1305/1306/1307：版本或规格错误
1400：请求频率过高
1500：系统异常

请保留请求时间、路径和业务 request_no 以便排查，不要提供 API Secret、完整签名或卡密。

跨境无忧开放 API