跳转到内容
Xcotton Xcotton Developer Docs
Ctrl K

认证、签名与通用规则

1. 签名

Section titled “1. 签名”
项目说明
算法HMAC-SHA256
待签名内容请求体 JSON 字符串（原始报文，不做任何格式化）
密钥 (Secret)signKey（共享签名密钥），测试环境联系 Support 获取，生产环境单独分配
签名计算Signature = Base64(HMAC-SHA256(signKey, requestBody))
传递方式放入 HTTP 请求头 Signature
开关默认开启，可按店铺独立关闭。如需变更店铺配置，请联系 Support。创建店铺接口是例外，始终校验签名

POST /OpenApiV2/applyToken 不校验 Signature（见 申请令牌）。

2. 接口通用规则

Section titled “2. 接口通用规则”

2.1 请求头

Section titled “2.1 请求头”

商户业务接口（除申请令牌外）标准请求头：

Header值说明
Content-Typeapplication/json必填
AuthorizationBearer {token}Token 鉴权。申请令牌接口不要带此头
Signature{signature}HMAC-SHA256 签名。店铺开启签名校验时必填；关闭时不校验。申请令牌接口不要带此头

创建店铺接口 OpenApiCreateUserAndShopV2 使用平台 SaaS App（appType=1）申请的 token，不能用店铺 token；该 token 也不能调其它商户业务接口。该接口不读取店铺签名开关，Signature 始终必填。见 创建店铺。

2.2 通用约定

Section titled “2.2 通用约定”
项目规则
请求方式POST（未特别说明时）
Content-Typeapplication/json
字段命名小驼峰为主；个别字段为历史兼容（如 ItemPicInfoMain、Properties、CancelError）
金额类型string，单位为币种主单位（如币种 USD 即美元金额）；小数位数以各字段 schema 为准（存在 4 位小数字段，如延保报价 price），不要统一按 2 位截断
时间格式RFC 3339，例：2023-09-05T21:21:22+00:00

2.3 环境域名

Section titled “2.3 环境域名”
环境请求地址
测试 (beta)https://betaxcottons.xmhhulu.com
生产 (美国)https://openapi.xcottons.com

生产域名解析至 52.86.202.15、34.192.81.36 两个公网入口 IP。如需全球加速访问，联系 Support（加速域名无固定 IP）。

3. 防重放

Section titled “3. 防重放”

3.1 说明

Section titled “3.1 说明”
项目说明
能力与开关接口支持防重放；是否启用按店铺配置，部分店铺可关闭。自20260824开始，接入OPENAPI默认接入防重放功能。
配置方式联系 Support 修改店铺配置

3.2 请求头（开启后必传）

Section titled “3.2 请求头（开启后必传）”
Header格式示例
Timestamp毫秒级时间戳1765952712000
NonceUUID 随机字符串d8193360-8ae1-4297-a092-13c0c8f4b7fe

Timestamp 与 Xcotton 服务器时间的差值需在 300 秒以内，否则接口报错。

Timestamp 与 Nonce 是条件必填：店铺开启防重放时两者必须同时传入，任意一个缺失都会校验失败；店铺关闭防重放时不要求传入，也不参与签名。

3.3 签名规则变化（开启后）

Section titled “3.3 签名规则变化（开启后）”
项目说明
公式Signature = Base64(HMAC-SHA256(signKey, newBody))
新报文内容newBody = 原始请求体 JSON 字符串逐字节原样拼接字面后缀 &Timestamp={timestamp}&Nonce={nonce}（&、= 为字面字符，无空格）
字节口径拼接前不要重新序列化、转义或格式化请求体；对拼接后的完整字符串按 UTF-8 字节计算 HMAC
示例{"testkey":{"testkey1":"testvalue"}}&Timestamp=1765952712000&Nonce=d8193360-8ae1-4297-a092-13c0c8f4b7fe

3.4 完整请求头（开启后）

Section titled “3.4 完整请求头（开启后）”
Header值
Content-Typeapplication/json
AuthorizationBearer {token}
Signature{signature}
Timestamp{timestamp}
Nonce{nonce}

4. 回调接口（入站：Xcotton → 商户）

Section titled “4. 回调接口（入站：Xcotton → 商户）”

回调 URL 由商户在店铺接入时配置（openapiConfig.callEndpoints），由 Support 协助开通。报文结构与店铺无关，只有 URL 按店配置。当前六类已上线回调和两类预设计回调的 payload 均写在 OpenAPI webhooks 中，可在 API 接口文档 查看字段；那不是出站接口，不要对着 OpenAPI 域名点 Send。邮包险开通审核回调使用配置键 openApiSpSwitchCallback，其中 secret 是敏感凭据，禁止记录到日志或前端页面。

4.1 请求方式

Section titled “4.1 请求方式”
项目说明
请求方式POST
Content-Typeapplication/json
验签头xmh-hmc-signature（见 §4.2）

4.2 签名规则

Section titled “4.2 签名规则”
项目说明
算法HMAC-SHA256
待签名内容请求体 JSON 字符串（原始报文）
密钥 (Secret)signKey（共享签名密钥）
签名计算sign = Base64(HMAC-SHA256(signKey, requestBody))
传递方式放入 HTTP 请求头 xmh-hmc-signature

4.3 成功条件（与出站不同）

Section titled “4.3 成功条件（与出站不同）”

平台只认 HTTP 状态码 200。不解析商户响应 body 中的 errCode。非 200 视为失败并定时重试。

5. 性能

Section titled “5. 性能”
项目说明
单机 QPS50
扩容方式横向扩容
生产实例数高频接口服务 20+ 实例

6. 出站 OpenAPI 成功标准与重试

Section titled “6. 出站 OpenAPI 成功标准与重试”

本节只给出站（商户 → Xcotton）接口。回调见 §4.3。

6.1 成功标准

Section titled “6.1 成功标准”

只有同时满足以下条件才视为成功：

条件值
HTTP 状态码200（业务失败时 HTTP 仍为 200，看 errCode）
业务状态码errCode = 0

6.2 成功响应示例

Section titled “6.2 成功响应示例”
{
  "errCode": 0,
  "errMsg": "success",
  "data": {}
}

6.3 重试规则

Section titled “6.3 重试规则”
项目说明
可重试错误码附录 中 920xxx 一类（超时、限流、临时故障）
不要盲目重试参数错误、鉴权失败、业务拒绝等非 920xxx 码，重复调用通常无意义
幂等退保等写接口请带业务幂等键（如 cancelId）；不要假设所有接口都可随意重试