启明智联文档中心

主题

API 使用指南 ​

本页介绍调用平台后端 API 服务（cloud.qimingidc.cn）的通用约定：Base URL、认证方式、响应结构与分页。接口清单见 API 参考。官网（www.qimingidc.cn）的用户操作说明见用户指引。

Base URL ​

所有接口的 Base URL 为：

https://cloud.qimingidc.cn

接口文档中的「接口地址」均为相对路径，实际请求时拼接在 Base URL 之后。例如登录接口文档地址为 /console/v1/login，则完整请求地址为：

https://cloud.qimingidc.cn/console/v1/login

认证方式 ​

JWT（会话令牌） ​

通过登录接口（或注册、验证码接口）成功后，响应中会返回 jwt 字段。后续请求将其放入请求头 Authorization，格式为 Bearer + 空格 + JWT：

Authorization: Bearer eyJ0eX.test.ste

API 密钥（长期调用） ​

适合服务端长期调用：在会员中心的 API 管理中创建 API 密钥后，会获得 token（以及私钥与调用地址）。调用时同样通过 Authorization 请求头携带令牌。建议同时开启 IP 白名单，仅允许指定服务器 IP 调用。详见 API管理。

WARNING

令牌等同于账户凭证，请妥善保管，切勿在前端页面或公开仓库中泄露。

通用响应结构 ​

接口返回 JSON，常见结构为：

json
{
  "status": 200,
  "msg": "成功",
  "data": { }
}
  • status：状态码，200 表示成功，4xx/5xx 表示失败；
  • msg：提示信息；
  • data：业务数据，无数据时可能为空。

具体字段以各接口文档的「响应参数」表为准。

分页与列表 ​

列表类接口通常支持以下分页参数：

参数类型说明
pageint页码，默认 1
limitint每页条数，默认 10
orderbystring排序字段
sortstring排序方向，asc / desc

响应中一般包含 list（当前页数据）与 count（总条数）。

无需登录的接口 ​

部分公共接口（如商品列表、注册配置、验证码等）无需携带令牌即可访问，详见 公共接口。

请求方式约定 ​

  • GET：查询类接口，参数通过 Query String 传递；
  • POST / PUT / DELETE：写入类接口，参数建议以 JSON body 提交（Content-Type: application/json）；
  • 路径中以 : 开头的部分（如 /console/v1/product/:id/...）为路径参数，调用时替换为实际值。

错误排查建议 ​

  1. 确认请求头 Authorization 格式正确（Bearer 与令牌之间有一个空格）；
  2. 确认令牌未过期、API 密钥未被删除且调用 IP 在白名单内；
  3. 确认使用了正确的 Base URL 与完整路径（含版本号 /console/v1/）；
  4. 查看 msg 字段中的错误提示；操作类问题可在操作日志中核对。