把超鑫选品接入
你的商城与系统

快速开始

1. 让超鑫选品管理员在 ERP「合作方 API」中创建合作方。
2. 安全保存只显示一次的 API Key、API Secret 和 Webhook Secret。
3. 先调用测试环境，确认签名、商品与订单结构。
4. 切换到正式环境并保留相同签名方式。

鉴权签名

所有 API 请求必须携带以下请求头。时间戳与服务器时间相差不能超过 5 分钟；Nonce 不能重复。

签名原文为五行：时间戳、Nonce、HTTP 方法、完整路径与查询参数、请求体 SHA-256。

const apiKey = process.env.CHAOXIN_API_KEY;
const apiSecret = process.env.CHAOXIN_API_SECRET;
const method = "GET";
const path = "/api/open/sandbox/v1/products?page=1&page_size=20";
const body = "";
const timestamp = Math.floor(Date.now() / 1000).toString();
const nonce = crypto.randomUUID().replaceAll("-", "");
const bodyHash = await sha256(body);
const canonical = [timestamp, nonce, method, path, bodyHash].join("\n");
const signature = await hmacSha256Hex(canonical, apiSecret);

const response = await fetch("https://chaoxinerp.com" + path, {
  headers: {
    "X-CX-API-Key": apiKey,
    "X-CX-Timestamp": timestamp,
    "X-CX-Nonce": nonce,
    "X-CX-Signature": signature
  }
});

商品与实时库存

返回有库存的商品仓库记录。支持 page、page_size、q、category、warehouse 和 sku。

传入商品接口返回的 sku 时同时返回套图、详情、属性、尺寸和证书下载地址。图片和证书通过超鑫接口读取，并使用相同的签名鉴权。

实时物流报价

根据收件国家、邮编、商品数量、发货仓、实际重量与材积重返回可用物流渠道和美元运费。当前自动报价仅支持美国境内地址。

{
  "country": "US",
  "postal_code": "91761",
  "items": [
    { "sku": "cxsku_由商品接口返回", "quantity": 1 }
  ]
}

返回结果按脱敏仓库代码分组，每个渠道包含 shipping_service_id、名称、时效备注、Zone、重量、材积重、箱数和费用。商品标价不含运费。

创建和查询订单

external_order_id 同时作为幂等键；重复提交同一合作方订单号不会重复创建。

{
  "external_order_id": "SHOP-20261023-0001",
  "shipping": {
    "name": "收件人",
    "phone": "13100000000",
    "address": "完整收货地址"
  },
  "items": [
    { "sku": "cxsku_由商品接口返回", "quantity": 1 }
  ],
  "note": "选填备注"
}

不传外部订单号时返回最近 50 个订单。正式订单进入 ERP「销售订单」，管理员确认发货后扣减库存。

测试环境订单仅用于验证签名、参数与返回结构：不会扣减正式库存、不会扣除账户余额、不会创建真实仓库履约，也不会产生真实物流。

订单状态 Webhook

管理员确认发货或取消 API 订单时，系统向合作方配置的 HTTPS 地址发送 JSON。

{
  "event": "order.updated",
  "created_at": "2026-10-23T08:00:00.000Z",
  "data": {
    "id": "超鑫订单 ID",
    "external_order_id": "合作方订单 ID",
    "status": "shipped",
    "updated_at": "2026-10-23T08:00:00.000Z"
  }
}

使用 X-CX-Webhook-Timestamp 与原始请求体验证 X-CX-Webhook-Signature：

HMAC-SHA256(WebhookSecret, timestamp + "." + rawBody)

错误与限制

• 默认每个合作方每分钟 60 次，可在 ERP 中设置为 1–600 次。
• 浏览器跨域调用只允许 ERP 白名单中的完整 HTTPS 来源。
• 错误响应包含 error.code、error.message 和 request_id。
• 正式订单最多 50 种商品，每个 SKU 数量为 1–999。
• 订单价格与库存以服务器接收请求时的数据为准。