开发文档

这里是看店通的开发者中心，面向对接我们系统的后端工程师、集成实施顾问与前端定制开发者。全部文档分为四条线：开放接口（怎么调我们）、系统集成（怎么和你已有的 ERP、WMS、CRM 打通）、定制开发（怎么改小程序和扩展后台功能）、部署与安全（怎么把系统稳当地跑起来）。

如果你是第一次接入，建议按这个顺序读：先看 OpenAPI 总览 建立全局印象，了解有哪些接口域、通用约定是什么；再看 API 鉴权说明 跑通令牌获取，这是所有接口调用的前提；然后用 API 接口文档 查具体路径与参数，开始写第一个只读接口的调用；跑通之后接入 事件回调，把轮询改造成事件驱动。这四步做完，基本的数据打通就完成了。

有两点需要提前说明。第一，认证相关的表述以「API 鉴权说明」为准。令牌有效期、签名算法、密钥轮换流程、错误码含义都在那一篇里定义，其他文档只引用不重复；如果你在不同页面上看到了不一致的描述，请以那一篇为准并告诉我们，我们会修正。第二，全站接口遵循同一套调用约定：字段命名统一 snake_case，订单号一律是 order_no；业务时间字段统一 ISO 8601 带时区格式；金额统一用整数「分」；分页参数是 page 与 page_size；限流按 AppId 统计，读接口 600 次/分钟、写接口 120 次/分钟。这些约定不会因接口域不同而变化。

实施类项目请重点看 ERP 对接指南，里面的字段映射表、库存超卖三层防御与三条对账线是从真实项目里沉淀出来的，能省掉方案设计阶段的大量返工。需要换系统或做数据归档的，看 数据导出与迁移；自己维护服务器的，看 私有化部署 和 安全规范，后者的「上线前安全自检」清单建议每次大版本发布都过一遍。

常见问题速查

调用接口一直返回 401 怎么办？先确认令牌是否已过期（有效期 7200 秒），再确认用的 AppId 与环境是否匹配——把沙箱凭证发到生产域名是最常见的原因。如果是多实例部署，还要检查各实例是否在互相挤兑令牌，解决办法是把令牌缓存换成共享存储。

签名总是校验失败？九成是对解析后的请求体重新序列化再签名导致的。签名必须基于原始字节，请把签名逻辑放在所有会改写请求体的中间件之后。其次检查服务器时钟，偏差超过 5 分钟会直接被时间窗拒绝。

Webhook 收不到推送？按三步排查：先在后台「事件订阅 → 投递记录」看有没有推送记录，没有说明事件没触发或没订阅；有记录但响应非 2xx，看返回内容定位你自己的处理逻辑；有记录但显示超时，说明处理耗时超过 5 秒，需要改成先落库再异步处理。

要拉全量历史数据，用列表接口翻页行不行？不行。超过 10 万行请用异步导出任务，列表接口深分页既慢又会挤占实时交易资源，还容易触发限流。做增量同步时请以 updated_at 为游标，用 created_at 会漏掉历史订单的状态变更。

找不到答案时，请带上 request_id、发生时间与复现步骤提交工单，或扫描页面右下角二维码联系技术支持。涉及定制交付的项目，项目群中会提供与本站文档对应的补充说明。