认证
一个 Bearer 令牌，对应一家店铺
密钥按店铺签发，并带有明确的权限范围。一个密钥可以读取商品却无权发起退款，这就是对接库存数据与把整个生意拱手交出之间的区别。
- 在 Authorization 请求头中携带 Bearer 令牌
- 按资源设置权限，读写分开
- 可随时在控制台吊销密钥
- 每次调用都会记入店铺的审计日志
http
POST /v1/orders/{id}/fulfilments
Authorization: Bearer sk_live_…
Content-Type: application/json
{
"outletId": "out_3f9",
"lines": [{ "orderLineId": "ol_88", "quantity": 2 }],
"deliveryMethod": "RIDER"
}参考
可调用的接口
目前可用的资源组。完整的请求与响应结构将随公开参考文档一同发布。
| 资源 | 路径 | 操作 |
|---|---|---|
| 商品 | /v1/products | 查询 · 创建 · 更新 · 删除 |
| 规格 | /v1/products/{id}/variants | 查询 · 创建 · 更新 |
| 商品集合 | /v1/collections | 查询 · 创建 · 更新 |
| 库存 | /v1/inventory/levels | 查询 · 调整 · 调拨 |
| 订单 | /v1/orders | 查询 · 创建 · 更新 · 取消 |
| 履约 | /v1/orders/{id}/fulfilments | 查询 · 创建 |
| 退货 | /v1/returns | 查询 · 创建 · 审批 |
| 客户 | /v1/customers | 查询 · 创建 · 更新 |
| 付款 | /v1/payments | 查询 · 退款 |
| 发票 | /v1/invoices | 查询 · 创建 · 发送 |
| 门店 | /v1/outlets | list |
| Webhook | /v1/webhooks | 查询 · 创建 · 删除 |
限制与行为
调用时的预期行为
限流
按密钥限流，每次响应都会返回剩余额度。超限请求会返回 429 并附带重试提示，而不是静默失败。
分页
列表接口采用游标分页。请使用上一次响应中的游标翻页，而不是逐条获取记录。
幂等性
写请求支持幂等键，因此超时后重试不会生成第二笔订单或第二笔退款。
错误
失败时除了可读消息外，还会返回稳定的机器可读错误码，便于您的集成按错误码而非文字进行判断。
版本管理
版本号包含在路径中。不兼容的变更会以新版本发布；新增功能直接在当前版本上线，并会提前公告。
Webhook 推送
推送内容均带签名，失败后按退避策略重试。每次推送及其响应都可查看，便于排查出错的接口。