站点开放接口 · API v1

开放平台

用站点管理端生成的一对凭证，把站点里的商品与订单数据接入你自有的系统。统一鉴权、统一返回结构：先换 token，再带三个值调用业务接口。

# 1) 用站点凭证换取 access_token
curl -X POST https://你的站点域名/open/v1/auth/token \
  -H "Content-Type: application/json" \
  -d '{"appId": "nm1a2b3c4d5e6f7a8b", "appSecret": "9f8e7d6c..."}'

# 2) 携带三值调用业务接口
curl https://你的站点域名/open/v1/site \
  -H "X-Site-Id: 3" \
  -H "X-App-Id: nm1a2b3c4d5e6f7a8b" \
  -H "X-App-Secret: 9f8e7d6c..."

接入准备

三步完成接入

凭证由站点管理端生成，第三方只需持有这一对值即可开始对接，无需再申请独立账号。

生成凭证

在站点管理端「系统管理 → 开放平台」点击「生成凭证」，得到该站点唯一的 appId 与 appSecret。

换取 token

调用 POST /open/v1/auth/token，用 appId + appSecret 换取 access_token，并记下响应中的 siteId、appId、appSecret。

调用业务接口

调用其余接口时携带 siteId、appId、appSecret 三个值——三者必须同属一个站点。

凭证按站点隔离：每个站点各自生成、互不通用；重置后旧凭证立即失效，请及时同步给已接入的第三方。

鉴权

获取 token

用站点凭证换取访问令牌。该接口是本页唯一不需要携带三值的接口。

POST/open/v1/auth/token无需公共参数

请求参数

参数	类型	必填	说明
`appId`	string	是	站点管理端生成的应用 ID
`appSecret`	string	是	站点管理端生成的应用密钥

请求示例

curl -X POST https://你的站点域名/open/v1/auth/token \
  -H "Content-Type: application/json" \
  -d '{
    "appId": "nm1a2b3c4d5e6f7a8b",
    "appSecret": "9f8e7d6c5b4a39281706f5e4d3c2b1a0..."
  }'

返回示例

{
  "code": 0,
  "message": "ok",
  "data": {
    "access_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
    "token_type": "Bearer",
    "expires_in": 7200,
    "siteId": "3",
    "appId": "nm1a2b3c4d5e6f7a8b",
    "appSecret": "9f8e7d6c5b4a39281706f5e4d3c2b1a0..."
  },
  "request_id": "..."
}

access_token 用于标识本次会话；调用业务接口时（见「接口清单」），除 token 外仍须携带 siteId、appId、appSecret 三个值。

公共参数

每个接口都必须带上这三个值

除「获取 token」外，所有开放接口都要求传入 siteId、appId、appSecret。三个值可放在请求头（推荐）或查询参数中，任一缺失返回 30001，与站点不匹配返回 30002。

值	请求头（推荐）	查询参数	说明
`siteId`	`X-Site-Id`	`siteId`	站点 ID
`appId`	`X-App-Id`	`appId`	应用 ID
`appSecret`	`X-App-Secret`	`appSecret`	应用密钥

建议同时携带 Authorization: Bearer {access_token}，便于日志追踪与服务端会话校验。

错误码

常见返回码

所有接口均返回统一结构 { code, message, data, request_id }，code = 0 表示成功。

code	说明
`0`	成功
`10001`	参数错误
`10005`	系统繁忙
`20001`	站点不存在
`20002`	站点已过期
`20004`	站点已停用
`30001`	应用凭证缺失（未传全 siteId / appId / appSecret）
`30002`	应用凭证无效（三个值与站点不匹配）