开放平台接入指南

更新说明

20260901

第一版

前提条件

接入方需要准备以下信息：

注册账号：您需要下载饰饰牛APP进行注册账号。购买、求购等涉及扣款的接口，您需要预充值购买账户余额, 才能完成购买饰品的操作, 需要您自行通过接口进行余额查询, 以及进行充值, 保证账户余额充足, 以免影响使用。

开通 API：在 个人中心 - API 管理 申请开通。申请前需完成实名认证，并绑定 Steam 账号。

app-key / app-secret：开通后可在 API 管理中查看。app-key 是调用凭证，app-secret 仅用于签名，请妥善保管，不要泄露、不要写在前端。

IP 白名单（可选）：可在 API 管理中配置，多个 IP 用英文逗号分隔，最多 100 个。配置后仅白名单 IP 可调用；未配置则不限制。

回调地址（可选）：在 API 管理中填写。用于接收订单状态通知，详见《回调通知》。

限流说明

默认限流次数为 50 次/秒（50 QPS），按调用方 app-key + 接口路径独立计数。部分接口如有更严格限制，会在该接口文档中单独标注。

触发限流时 HTTP 状态码为 429，响应头包含：

响应头	说明
X-RateLimit-Limit	当前接口窗口内允许的最大次数
X-RateLimit-Remaining	剩余可调用次数
Retry-After	建议等待秒数

请求结构

调用开放平台接口，是指向服务地址按「路径 + 方法 + 公共头 + 业务参数」发请求。构造不正确将无法调用成功。

查询买家订单列表示例如下：

发布求购单示例如下：

请将 {openapi-host} 替换为实际接入域名。

服务地址

服务地域	域名	备注
国内外	`https://openapi.shishiniu.com`	开放平台路径前缀为 `/api/openapi`

通信协议

生产环境通过 HTTPS 通信。Content-Type：

GET：无需 Body，业务参数放 Query

POST：application/json，业务参数放 JSON Body

请求方式

按各接口文档使用 GET 或 POST。POST 统一接收 JSON，未知字段会被拒绝。

请求参数

请求包含两类参数：

公共请求参数（每个接口都要带，放在 Header）：

参数名	位置	必填	说明
app-key	Header	是	应用 Key，在个人中心 - API 管理获取
timestamp	Header	是	请求时间戳，支持秒或毫秒；与服务器时差不能超过 5 分钟
sign	Header	是	签名串，生成规则见下方「签名机制」

业务参数：各接口特有，GET 放 Query，POST 放 JSON Body，见各接口文档。

字符编码

请求与返回均使用 UTF-8。

签名机制

与回调通知使用同一套加签规则。app-secret 只参与运算，不要放在请求里。

加签步骤

取出全部业务参数（GET 为 Query，POST 为 JSON 一层字段），按请求方的实际传参参与签名。

将 Header 中的 timestamp 一并加入参数列表。app-key、sign 不参与签名。

按参数名 ASCII 从小到大排序，用 & 拼成 key=value 字符串。

在末尾追加 &sign={app_secret}。

对整串做 MD5，得到 32 位大写 字符串，作为 Header sign。

示例

假设：

timestamp = 1718265222

app_secret = your-app-secret

业务参数：page=1、pageSize=20、status=1

待签名字符串：

page=1&pageSize=20&status=1&timestamp=1718265222&sign=your-app-secret

sign = upper(MD5(待签名字符串))

无业务参数的接口（例如部分 POST 仅有公共头）时，待签名字符串为：

timestamp=1718265222&sign=your-app-secret

返回结果

业务结果统一为 JSON。HTTP 200 时请先看 code：0 为成功，非 0 为失败。

调用成功：

{
  "code": 0,
  "msg": "成功",
  "data": {}
}

调用失败：

{
  "code": 1,
  "msg": "余额不足",
  "data": null
}

字段	类型	是否一定返回	说明
code	int	是	业务状态码。`0` 成功；`1` 业务失败；`500` 服务异常；`1001` Steam 会话失效；`1002` 购买账户余额不足
msg	string	是	提示信息。成功为「成功」，失败为错误原因
data	object / array / number / string / null	是	成功时的业务数据，结构见各接口；失败时多为 `null` 或空字符串

HTTP 状态码	说明
200	已到达业务处理（再根据 code 判断成败）

响应头加签说明

开放平台业务接口在返回 JSON Body 的同时，会在响应 Header 中返回签名，用于确认响应未被篡改。

响应头	说明
X-Timestamp	服务端生成签名时的 Unix 秒级时间戳
X-Sign	响应签名，32 位大写 MD5

加签规则

取本次响应的 Body 原始 JSON 字符串（即 HTTP 响应体原文，不要美化、不要重新 JSON.stringify / json.Marshal）。

取响应头 X-Timestamp。

拼接待签名字符串：

{响应体原文}&{X-Timestamp}&{app_secret}

对整串做 MD5，再转成 32 位大写，即为 X-Sign。

公式：

X-Sign = upper(MD5(body + "&" + X-Timestamp + "&" + app_secret))

验签步骤（客户端）

读取响应头 X-Timestamp、X-Sign。

校验 X-Timestamp 与本地时间差不超过 5 分钟（超时可视为无效响应）。

用收到的 响应体原始字节（转成字符串，不得重新序列化）按上述公式本地计算签名。

与 X-Sign 比对（建议忽略大小写）；一致则验签通过。

示例

假设：

响应体原文：{"code":0,"msg":"成功","data":{"orderId":10001}}

X-Timestamp = 1718265222

app_secret = your-app-secret

待签名字符串：

{"code":0,"msg":"成功","data":{"orderId":10001}}&1718265222&your-app-secret

X-Sign = upper(MD5(待签名字符串))

注意事项

必须用原始响应体验签。重新格式化 JSON（增减空格、字段顺序变化、Unicode 转义差异等）都会导致签名不一致。

请求签名（Header sign）与响应签名（Header X-Sign）规则不同：请求是参数字典序拼接；响应是 body&timestamp&app_secret。

app_secret 只参与本地计算，不会出现在响应中。

重要安全提示

强烈建议严格按照响应头验签。 若未按规则验签，导致响应体被篡改并造成财产损失的，平台概不负责。

名词解释

名字	解释
服务域名	开放平台接入域名，路径前缀 `/api/openapi`
app-key	调用凭证，代表您在本平台的身份，泄露后他人可代为操作
app-secret	签名密钥，仅保存在服务端，用于生成/校验请求签名、响应签名、回调签名
timestamp	请求时间戳，秒或毫秒，有效窗口 ±5 分钟
sign	请求或回调的签名，32 位大写 MD5
X-Timestamp	响应加签时间戳（秒），有效窗口建议按 ±5 分钟校验
X-Sign	响应签名，对「响应体原文 & X-Timestamp & app_secret」做 MD5 大写

订单状态

status	说明
0	待付款
1	待发货
2	结算中
3	已完成
4	已取消
5	已退款

求购单状态

status	说明
0	待支付
1	求购中
2	暂停中
3	已完成
4	已取消
5	已删除

如何调试

如何使用接口文档提供的调试功能

选择任意开放平台接口，点击调试按钮

第一次调试需要先设置全局变量，配置 app-key

填写您的 app-key 等公共请求头

设置之后点击发送即可获得响应参数

更新说明#

20260901#

前提条件#

限流说明#

请求结构#

服务地址#

通信协议#

请求方式#

请求参数#

字符编码#

签名机制#

加签步骤#

示例#

返回结果#

响应头加签说明#

加签规则#

验签步骤（客户端）#

示例#

注意事项#

名词解释#

订单状态#

求购单状态#

如何调试#

更新说明

20260901

前提条件

限流说明

请求结构

服务地址

通信协议

请求方式

请求参数

字符编码

签名机制

加签步骤

示例

返回结果

响应头加签说明

加签规则

验签步骤（客户端）

示例

注意事项

名词解释

订单状态

求购单状态

如何调试