通用接入指南

1. 鉴权

所有接口通过 HTTP 请求头鉴权。请在 BuyEasy 开放平台控制台创建应用后获取 App Key 与 App Secret，并在每个请求中携带。

鉴权支持两种传法，任选其一即可（推荐同时使用头，系统会按优先级读取）：

curl "https://open.buyeasysaas.com/api/open/taobao/items/detail?item_url=..." \
  -H "x-api-key: YOUR_APP_KEY" \
  -H "Authorization: Bearer YOUR_APP_SECRET"

2. 统一响应结构

所有接口返回统一 JSON 结构。成功时 success 为 true，失败时 success 为 false 并返回 code 与 message。

// 成功
{
  "success": true,
  "code": 0,
  "message": "success",
  "data": { },
  "billing": { "charged": 0.027, "unitPrice": 0.027, "multiplier": 1, "risk": null, "product": "淘宝商品详情", "callId": 1024 }
}

// 失败
{
  "success": false,
  "code": "insufficient_balance",
  "message": "余额不足，请先充值"
}

3. 错误码

常见错误码与排查方向如下；具体 message 以接口实时返回为准。

4. 计费与余额

淘宝、1688、微店的商品查询类接口统一按 ¥0.027/次计费；订单采购与 AI 接口仍按各自产品配置计费。调用失败不扣费。

商品详情防刷只识别同一 App Key 以高度固定间隔连续抓取不同商品的自动化序列：第 100 次起 10 倍、第 500 次起 50 倍、第 1000 次起 100 倍。普通不规则访问不触发。

billing 字段包含实扣金额（charged）、基础单价（unitPrice）、倍率（multiplier）、风险说明（risk）、接口产品名（product）与调用记录 ID（callId），可用于对账。

查询当前余额：GET /api/open/account/balance。

curl "https://open.buyeasysaas.com/api/open/account/balance" \
  -H "x-api-key: YOUR_APP_KEY" \
  -H "Authorization: Bearer YOUR_APP_SECRET"

5. 限流与每日配额

每个应用有每日调用配额（daily_limit）。超过配额返回 429 daily_limit_exceeded。

建议：在控制台为生产应用配置充足配额；客户端对 429 做指数退避重试。

6. 幂等键

创建订单、支付等写操作支持幂等键 Idempotency-Key（请求头）。相同 key 的重复请求会返回首次结果的缓存，不会产生重复扣费或重复下单。

建议：每次业务单号生成唯一的 Idempotency-Key；若需重新下单，必须使用新的业务单号与新的 Idempotency-Key。

curl -X POST "https://open.buyeasysaas.com/api/open/taobao/orders/create" \
  -H "x-api-key: YOUR_APP_KEY" \
  -H "Authorization: Bearer YOUR_APP_SECRET" \
  -H "Idempotency-Key: order-20260726-0001" \
  -d '{ "out_order_id": "order-20260726-0001", "items": [] }'

7. Webhook 回调

可在控制台为应用配置 Webhook URL。当采购订单状态发生变更（如已创建 / 已付款 / 已取消 / 已发货）时，BuyEasy 会向该地址推送 JSON 通知，便于你异步同步订单状态。

请对回调来源做签名校验，并对重复推送做幂等处理。

{
  "event": "purchase_order.status_changed",
  "platform": "taobao",
  "purchase_order_id": "po_001",
  "external_order_id": "TB123",
  "status": "paid",
  "occurred_at": "2026-07-26T05:00:00Z"
}

8. 最佳实践

接入前先调用 GET /api/open/health 确认服务可用。

推荐链路：先 resolve-link 解析商品链接 → items/detail 取详情 → orders/preview 预览 → orders/create 创建 → orders/pay 支付 → orders/detail 查询。

对所有失败做统一异常处理，优先依据 code 做分支；对 429 做退避重试。

记录 billing.callId 用于财务对账与工单排查。