Agent API 文档

概览

Base URL 为站点根路径。所有 Agent 接口位于 /api/v1/agent/*。仅 status=APPROVED 且开启「向 Agent 供货」的商品可见；价格为代理价（固定价或折扣），下单数量单笔 1–5。

• 需要已批准的 Agent 身份与 API Key
• 支付目前支持 USDT：TRC20（默认）或 BEP20
• 下单后返回收款地址与金额，到账后订单进入履约
• 发货内容通过 deliveryUrl 拉取（需同一 Agent 身份）

将 https://YOUR_HOST 换成实际站点（本地示例 http://127.0.0.1:43321）

认证

在请求头携带 API Key（二选一）。Key 在 Agent 申请通过后由平台发放；服务端只保存 SHA-256 哈希，明文仅展示一次。

Authorization: Bearer <api_key>

x-api-key: <api_key>

未带 Key、Key 无效或 Agent 未批准 → HTTP 401，body: {"error":"unauthorized"}。

接口

{
  "products": [
    {
      "id": "prod_xxx",
      "slug": "x-account-sms",
      "title": { "zh": "…", "en": "…", "ko": "…" },
      "listPrice": "3.00",
      "agentPrice": "2.40",
      "stock": 73,
      "deliveryType": "AUTO",
      "category": "accounts"
    }
  ]
}

{
  "productId": "prod_xxx",
  "quantity": 1,
  "network": "TRC20"
}

{
  "checkoutId": "chk_xxx",
  "orderNumber": "XN123456",
  "paymentId": "pay_xxx",
  "amount": "2.40",
  "address": "T…",
  "payPath": "/pay/pay_xxx"
}

{
  "number": "XN123456",
  "status": "FULFILLED",
  "deliveryType": "AUTO",
  "quantity": 1,
  "total": "2.40",
  "hasDelivery": true,
  "deliveryUrl": "/api/orders/XN123456/delivery",
  "paymentStatus": "CONFIRMED"
}

错误码

• 401 unauthorized — 缺少或无效 API Key
• 404 unavailable — 商品不存在、未批准或不向 Agent 供货
• 404 not_found — 订单不存在或不属于当前 Agent
• 400 — 业务错误（如库存不足等），error 为小写原因字符串

代理价与供货

商品需勾选 supplyToAgents。定价模式：

• FIXED：使用 agentPrice 作为单价
• DISCOUNT：listPrice × (1 − agentDiscountPct) − agentDiscountAmt（不低于 0）
• 未配置模式时回退为 listPrice

列表接口只返回 stock > 0 的在售商品；下单时也会校验供货标记与库存。