开放 API 文档

01接口总览

接口地址（正式）：https://api.xcx181.top/api/v1

请求与响应均为 application/json; charset=utf-8。所有请求需携带签名头（见 02 节），时间戳与服务器偏差不得超过 300 秒。

公共响应结构

{
  "code": 0,              // 0 成功，非 0 见错误码表
  "message": "success",  // 结果描述
  "data": { ... },         // 业务数据，失败时为 null
  "trace_id": "t_8f2c1a9e" // 链路 ID，排查问题时提供
}

02签名算法

使用注册后分配的 AccessKey / Secret 做 HMAC-SHA256 签名。签名结果为 hex 小写字符串。

请求头

签名步骤

• 构造待签名串（每段以换行符 \n 连接）：
  sign_raw = access_key + "\n" + nonce + "\n" + timestamp + "\n" + body
  其中 body 为请求体原文（GET 请求为空字符串）。
• 计算签名：sign = HMAC-SHA256(secret, sign_raw).hex()
• 将 sign 放入 X-Sign 请求头。

$ak = 'ak_xxxxxxxxxxxx';
$sk = 'sk_xxxxxxxxxxxx';
$body = json_encode(['product_id' => '1001', 'order_no' => 'ORD001', 'qty' => 1], JSON_UNESCAPED_UNICODE);
$nonce = bin2hex(random_bytes(4));
$ts   = (string) time();

$signRaw = $ak . "\n" . $nonce . "\n" . $ts . "\n" . $body;
$sign = hash_hmac('sha256', $signRaw, $sk);   // hex 小写

$ch = curl_init('https://api.xcx181.top/api/v1/order/create');
curl_setopt_array($ch, [
  CURLOPT_POST           => true,
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_HTTPHEADER     => [
    'Content-Type: application/json',
    "X-Access-Key: {$ak}",
    "X-Nonce: {$nonce}",
    "X-Timestamp: {$ts}",
    "X-Sign: {$sign}",
  ],
  CURLOPT_POSTFIELDS     => $body,
]);
echo curl_exec($ch);

03统一下单

请求参数（body）

成功响应 data

04订单查询

返回字段与下单 data 一致，另含 create_time、finish_time、supplier_msg（供应商返回信息）。

05商品列表

每个商品返回 channels[]：渠道编码、渠道名称、当前报价、可用库存、渠道状态，便于你展示「多渠道比价」结果。

06渠道状态

状态取值：active 正常 / degraded 熔断降级 / maintaining 维护中 / disabled 已停用。可配合告警系统监控渠道健康度。

07回调通知

订单状态变更（成功 / 失败）时，中转服务以 POST 表单或 JSON 向你的 notify_url 发送通知，最多重试 5 次（间隔 0s / 15s / 60s / 300s / 900s）。

回调参数

回调应答

你的服务端处理成功后请返回纯文本 success（或 HTTP 200 且 body 为 success）；返回其他内容均视为失败并触发重试。请以订单号做幂等处理，避免重试导致重复入账。

08错误码

09在线调试（签名生成器）

填写你的密钥与请求体，生成带真实 HMAC-SHA256 签名的 cURL 命令，可直接粘贴到终端试调（密钥仅在浏览器本地计算，不会上传）。

// 点击上方「生成签名请求」，这里输出带签名的 cURL 命令