API接口文档

一、接口概览

看店通 API 采用 RESTful 设计风格，遵循 HTTP 语义：GET 查询、POST 创建、PUT 全量更新、PATCH 局部更新、DELETE 删除。接口按业务模块划分，路径均以 /v1 开头。

• 商品接口：商品列表、详情、分类、SKU、库存、批量操作、上下架
• 订单接口：订单创建、查询、状态变更、退款、物流、批量导出
• 会员接口：会员信息、等级、积分、优惠券、地址、标签
• 支付接口：预支付、支付结果查询、退款、对账单下载
• 营销接口：优惠券、活动、拼团、秒杀、满减
• 分销接口：分销员、佣金、提现记录

二、常用接口清单

方法	路径	说明	所需 scope
POST	/v1/oauth/token	用 AppId 与 AppSecret 换取访问令牌	—
GET	/v1/orders	订单列表查询，支持时间范围与状态筛选	order:read
GET	/v1/orders/{order_no}	订单详情查询	order:read
POST	/v1/orders/{order_no}/ship	发货回写，提交物流公司与运单号	order:write
GET	/v1/products	商品列表查询	product:read
PATCH	/v1/products/{product_id}	商品局部更新，如改价、上下架	product:write
POST	/v1/inventory/sync	库存批量同步，单次最多 500 个 SKU	inventory:write
GET	/v1/members/{member_id}	会员详情查询，手机号默认脱敏	member:read
POST	/v1/refunds	发起退款，需附加签名	refund:write
POST	/v1/exports	创建异步导出任务	对应数据集的只读 scope

路径参数中的 {order_no}、{product_id} 需做 URL 编码。写接口建议统一带上 Idempotency-Key 请求头，重试时复用同一个 key 即可避免重复下单或重复发货。

三、认证方式

业务请求在请求头携带令牌即可：

Authorization: Bearer {access_token}

令牌如何换取、有效期、敏感写接口的 HMAC-SHA256 签名、密钥轮换与错误码对照表，一律以API 鉴权说明为准，本页不重复定义。请在服务端换取和保存令牌，AppSecret 不得出现在小程序或 H5 前端代码中。

四、请求规范

字段命名、时间、金额、分页与幂等约定与OpenAPI 总览第二节相同，此处只列调用本页接口时最常用的几项：

• Base URL：https://api.kandiantong.com/v1（仅 HTTPS）
• 请求 / 响应：UTF-8 JSON，Content-Type: application/json
• 字段命名：snake_case，订单号统一为 order_no
• 金额：整数「分」，字段以 _fen 结尾
• 分页：page 从 1 开始，page_size 默认 20、最大 100

所有接口返回统一的响应结构，包含 code、message、request_id、data 四个顶层字段。code 为 0 表示成功，非 0 为业务错误码。

五、响应示例

成功响应：

{
  "code": 0,
  "message": "success",
  "request_id": "req_7f3c9a12b4e5",
  "data": {
    "order_no": "KDT202609290001",
    "status": "paid",
    "pay_amount_fen": 19900,
    "paid_at": "2026-09-29T20:30:00+08:00"
  }
}

错误响应（40001 表示签名校验失败，参数类错误请对照鉴权文档中的 HTTP 400 / 业务码）：

{
  "code": 40002,
  "message": "invalid sku",
  "request_id": "req_9d8c7b6a5e4f",
  "details": {
    "field": "sku_id",
    "reason": "not_found"
  }
}

分页响应中 data 为对象，包含 list 数组、total 总数以及回显的 page 与 page_size。

六、错误码说明

HTTP 状态码表示传输与权限层结果：400 参数错误、401 未认证或令牌过期、403 权限不足（scope 未开通）、404 资源不存在、429 请求过于频繁、500 服务端异常。响应体中的 code 表示业务结果，两者不一致时以 code 为准。4xx 需修正请求后再发，重试无意义；429 请读取 Retry-After 后指数退避；5xx 可有限次重试。完整错误码对照表见API 鉴权说明第七节。

七、限流与频率

限流按 AppId 维度统计：读接口 600 次/分钟，写接口 120 次/分钟，超出返回 HTTP 429 并携带 Retry-After 响应头。批量场景请优先使用批量接口而不是循环调用单条接口，例如库存同步用 /v1/inventory/sync 一次提交 500 个 SKU，比循环 500 次快两个数量级，也不会撞限流。超过 10 万行的数据拉取请改用异步导出。

八、SDK 与调试工具

看店通提供 Java、PHP、Node.js、Python 多语言服务端 SDK，封装了令牌缓存、签名计算、重试退避与错误映射，接入方式见SDK 接入指南。同时提供 Postman 集合与在线接口调试工具，可在开发者中心下载。调试时建议先用沙箱凭证跑通只读接口，再逐步接入写接口。

九、联调排查思路

联调阶段遇到问题，建议按「从外到内」的顺序排查，可以避免把时间浪费在错误的方向上。第一步先确认网络可达：用 curl 直接请求令牌接口，能拿到令牌说明域名解析、证书、出口防火墙都没问题。第二步确认认证：把令牌接口返回的 access_token 手动拼进一个只读接口的请求头再发一次，通了说明凭证与权限没问题，接下来的问题就都在业务参数上了。

第三步才是看业务参数。这里最常见的三类错误是：时间参数没带时区，服务端按 UTC 解析导致查出来的数据差 8 小时；金额单位搞错，把「元」直接当「分」传，金额差了 100 倍；分页参数超限，page_size 传了 500 而上限是 100，被静默截断后误以为数据丢失。这三类问题在响应里都不会报错，只会给出看似正常但不对的结果，所以要主动核对。

排查过程中请始终保留每次调用的 request_id 并记录在案。提交工单时附上它、调用时间、完整的请求路径与实际/期望结果，技术支持可以直接定位到那一次调用的服务端日志，通常当天就能给出结论；只描述「接口有问题」而没有 request_id，往往要来回沟通好几轮才能开始查。

十、延伸阅读

异步通知机制见事件回调 Webhook；ERP 与 WMS 的字段映射与对账口径见ERP 对接指南；服务端加固要求见安全规范。