OpenAPI 总览

看店通 OpenAPI 面向服务端集成，覆盖商品、订单、会员、营销、库存等域。本文是开放能力的地图与导航页：告诉你有哪些接口域、通用调用约定是什么、按什么顺序接入，以及遇到问题该去哪一篇细分文档。认证细节、回调细节、SDK 用法分别由专门的文档承载，本文不重复展开。

一、接口域划分

二、通用约定

下列约定对所有接口域生效，与API 鉴权说明中的定义保持一致：

• Base URL：https://api.kandiantong.com/v1，仅支持 HTTPS（TLS 1.2 及以上）。
• 编码与格式：请求与响应均为 UTF-8 编码的 JSON，Content-Type: application/json。
• 字段命名：统一 snake_case，例如 order_no、page_size、request_id；不使用驼峰写法。
• 时间格式：业务时间字段一律为 ISO 8601 带时区偏移，如 2026-09-29T20:30:00+08:00；Unix 秒级时间戳只用于签名头 X-Kdt-Timestamp。
• 金额：一律使用整数「分」，字段名以 _fen 结尾，避免浮点误差。
• 幂等：写接口支持 Idempotency-Key 请求头，同一 key 在 24 小时内重复提交返回首次结果。
• 版本：主版本号在 URL 路径中体现（/v1），次版本通过新增可选字段的方式向下兼容演进。

三、统一响应结构

无论成功失败，响应体结构都是固定的四个顶层字段，业务数据只放在 data 中：

{
  "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"
  }
}

列表类接口的 data 固定包含 list 数组与 total 总数，便于客户端统一处理：

{
  "code": 0,
  "message": "success",
  "request_id": "req_a1b2c3d4e5f6",
  "data": {
    "list": [],
    "total": 0,
    "page": 1,
    "page_size": 20
  }
}

四、分页与查询

普通列表接口使用 page（从 1 开始）与 page_size（默认 20，最大 100）。当结果集超过 1 万行时，翻页到后段会明显变慢，此时应改用游标分页：传入上一页返回的 next_cursor 与 limit，服务端按主键有序推进，耗时与页码无关。

超过 10 万行的场景不要用任何一种分页硬拉，请改走异步导出任务，否则大概率在扫库阶段拖慢实时交易。常用筛选条件包括创建时间范围、订单状态、门店 ID、更新时间范围；做增量同步时请以 updated_at 而非 created_at 为游标，否则会漏掉历史单的状态变更。

五、限流

限流按 AppId 维度统计：读接口 600 次/分钟，写接口 120 次/分钟。超限时返回 HTTP 429，响应头 Retry-After 给出建议等待秒数。批量同步建议安排在夜间窗口，用消息队列匀速消费而不是并发打满；重试务必采用指数退避，固定间隔重试只会让限流窗口持续无法恢复。

六、错误码结构

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

HTTP 状态码表示传输与权限层结果，code 表示业务结果，两者不一致时以 code 为准。4xx 需要修正请求后再发，盲目重试没有意义；5xx 可以有限次重试。每条日志都请保留 request_id，这是提工单时定位单次调用的唯一依据。完整的错误码对照表见API 鉴权说明第七节。

七、推荐接入路径

1. 在商户后台创建应用，取得沙箱环境的 AppId 与 AppSecret，按API 鉴权说明跑通令牌获取。
2. 调通一个只读接口（建议订单查询），确认网络、证书、字段解析都没问题。
3. 按业务优先级接入写接口，先商品与库存，再订单与发货，最后是退款等敏感操作。
4. 配置事件回调，把轮询改造成事件驱动，并完成幂等设计。
5. 压测与对账：用沙箱数据跑一轮全流程，核对订单数、金额、库存三项是否闭环。
6. 申请生产凭证，双环境并行观察一周后切流。

已有 ERP 或 WMS 的项目，可直接参考ERP 对接指南中的字段映射表；使用官方 SDK 可以省去签名与重试的自研成本，见SDK 接入指南。

八、变更与兼容

我们对「向下兼容」的定义是：新增可选请求参数、新增响应字段、新增枚举值、放宽校验，这些都属于兼容变更，随时可能发布，不单独通知。删除字段、修改字段类型、收紧校验、调整错误码语义属于不兼容变更，会提前至少 30 天公告并升主版本号，旧版本保留 6 个月过渡期。

因此客户端必须做到两点：一是忽略未知 JSON 字段，不要用严格模式反序列化；二是对枚举值做兜底分支，遇到没见过的状态值降级处理而不是抛异常。版本发布记录见更新日志，建议同时在后台订阅变更邮件。