旺店通企业版对接指南:签名与订单查询

接口形态

旺店通企业版的开放接口统一为 openapi2 风格:

POST https://api.wangdian.cn/openapi2/{接口服务名}.php

例如订单查询是 sales_order_query.php,出库单查询是 stockout_order_query.php。鉴权参数(sid、appkey、timestamp、sign)放在 URL query,业务参数打包后放在 body。

鉴权四要素

timestamp 是最容易被忽视的坑:它不是 Unix 时间戳(差 8 小时基准),计算时务必以 Asia/Shanghai 时区为基准。

签名算法

旺店通企业版签名的步骤:

1. 把 URL query 中除 sign 外的所有参数,按参数名升序排列;
2. 拼成 key1value1key2value2... 的字符串;
3. 首尾拼接 appsecret:appsecret + 拼接串 + appsecret;
4. MD5 后转十六进制字符串。

注意:业务 body 不参与签名;参与签名的参数值不要先做 URL 编码;如果 body 为空,部分接口要求 body 传 {} 占位。

请求体:gzip + base64

openapi2 的 body 不是裸 JSON:业务 JSON 先 gzip 压缩,再 base64 编码,作为请求体发送。响应同样可能是压缩的,客户端要按响应头判断解压。这一层建议封装在统一客户端里,业务代码只面对 JSON。

订单查询实战

sales_order_query.php 的核心业务参数:起止时间(支持按最后修改时间增量)、订单状态、分页(page_no / page_size)。实践建议:

1. 增量按修改时间,窗口与调度频率匹配并重叠数分钟,按订单编号去重;
2. 分页上限:page_size 有上限(以官方文档为准),超页要循环翻页直到返回不足一页;
3. 状态过滤在服务端做:只拉需要的订单状态(如已审核/已发货),减少传输与解析量;
4. 原始单号 = 幂等键:平台原始单号字段是后续写入 ERP 时的查重依据,务必保留。

常见问题

• 签名错误 100xx:九成是 timestamp 基准错(用了 Unix 时间戳)或参数没按名排序;
• 时间误差超限:服务器时钟与北京时间偏差超过 5 分钟,先校时钟再排查签名;
• body 解析失败:忘了 gzip 压缩,或 base64 带了换行符;
• 限流:旺店通对 sid 维度有调用频率限制,高频轮询前先确认额度,超限返回错误码要退避重试。