妙手ERP开放接口：单据回传自建系统

2026 年 2 月 27 日，妙手ERP 升级开放接口：订单、库存、采购、发货四类单据同时支持回调推送与增量拉取，提供独立沙箱环境与请求签名校验。接入的自建系统平均对接周期从三周缩短到 5 天，回调触达率为 99.7%。

做得越久的团队，越可能有一套自建系统：有人用它做 BI，有人用它对接工厂，也有人只是想把数据存进自己的库。妙手ERP 在 2025 年 10 月的客户访谈中发现，使用开放接口的团队里有 54% 曾因为字段变更导致对接中断，平均恢复时间 2.6 天。“接口的稳定性，比接口的数量更重要。”妙手ERP 平台生态负责人郑柏川说。

四类单据，两种取数方式

订单接口提供增量拉取与回调推送两条通道，增量拉取按更新时间游标分页，回调推送在状态变化时立即触发。库存接口提供快照查询与变动流水，采购与发货接口以单据为单位推送，四类接口共用同一套签名与重试规则。

两种方式可以混用：核心的订单与库存走回调，报表类的采购与发货走定时拉取，减少无效请求。接口文档里标注了每个字段的变更历史，字段新增不会影响旧版本调用，字段下线会提前 90 天公告并保留兼容期。

沙箱与签名：先在测试环境跑通

沙箱环境提供独立的测试店铺与模拟订单，可以构造异常场景：地址缺失、库存不足、平台限流、回调失败。接入方在沙箱里跑通四种场景后才申请生产密钥，生产密钥与沙箱密钥分离，避免误用。

签名采用时间戳加请求体摘要的方式，时间戳偏差超过 5 分钟即拒绝，防止重放。回调失败按 1 分钟、5 分钟、30 分钟三次重试，仍失败则进入死信队列，可在控制台手动重放。2026 年 1 月的统计显示，死信队列的平均积压量为 37 条，全部在当天处理。

限流与配额：别把接口当数据库

接口按店铺维度限流，默认每分钟 300 次，突发允许 600 次，超出返回明确的限流错误码与建议等待时间。配额可按合同调整，调整后即时生效，不需要重启。系统会统计接入方的调用分布，异常高的调用会触发提醒，避免用轮询代替回调。

实测数据：一家自建 BI 的团队把轮询改为回调加每小时快照后，日调用量从 82 万次降到 6.4 万次，接口错误率从 2.1% 降到 0.2%，对方服务器的负载也随之下降。团队负责人反馈，改造只用了两天，主要是把分页逻辑换成事件处理。

对接方的三种典型场景

第一种是自建 BI，只需要读；第二种是工厂协同，需要写采购单与到货数量；第三种是自研小程序，需要读订单并回写客服备注。三类场景对权限的要求不同，系统提供只读、读写、指定单据三类密钥，权限范围在控制台可查可撤。

广州服饰卖家供应链主管周乐言说：“我们把采购单推给工厂的小程序，工厂确认后回写到系统，跟单员少打了一半电话。”接入的 46 个团队中，读写类密钥占 38%，只读类占 57%，指定单据类占 5%，没有出现越权访问记录。截至 2026 年 2 月，已有 218 个自建系统接入开放接口，日均调用 4.2 万次，P95 响应 320 毫秒。调用量最大的不是订单，而是库存增量拉取，占 46%，多数是自建 WMS 在做分钟级同步。失败请求里 61% 是签名过期，22% 是超出配额，剩下的是参数缺失。接口按版本并存，旧版本至少保留 12 个月，升级前会提前 90 天在控制台公告。对接方普遍反馈，先跑通沙箱再谈业务逻辑，比边写边调省时间。下一步计划开放物流轨迹与售后工单两类事件订阅，目前已在沙箱完成验证。配额提醒会从 80% 提前到 60%，给对接方留出扩容时间。对接方最常问的两个问题，历史数据能否补拉、字段变更如何通知，答案分别是支持 90 天回溯、提前 60 天公告。团队也在评估把签名算法升级到更长的密钥，旧密钥并行保留一年，避免对接方被迫紧急改造。沙箱环境的调用不计入正式配额，对接方可以放心压测。

开放接口已向团队版用户开放，进阶版可申请只读密钥。接入前建议先在沙箱跑通四类异常场景，再申请生产密钥；接口文档与示例代码在下载中心的开发者页签提供，遇到字段问题可通过工单获取支持。