聚水潭奇门对接指南:订单与库存下行

奇门是什么

奇门是阿里体系为电商仓储/ERP 场景定义的一套网关协议:请求通过统一的 HTTP 网关进出,业务参数以 XML(或 JSON)报文放在 body,系统参数(method、app_key、session、timestamp、sign 等)放在 URL query。聚水潭以"奇门自定义接口"的方式向三方开放订单、库存等数据。

公共参数与签名

每个请求的 URL 携带系统参数:

签名规则(奇门标准):把除 sign 外的所有参数按参数名 ASCII 升序排列,拼成 secretkey1value1key2value2...secret 形式(首尾各拼一次 appSecret),做 MD5 后转大写。要点:

• 参与签名的是 URL query 参数,body 报文不参与签名;
• 参数值中有特殊字符时注意编码时机:先签名再 URL 编码;
• timestamp 与服务器偏差过大直接验签失败。

商家路由:target_app_key 与 customer_id

聚水潭是多租户 SaaS,同一个奇门接口服务多个商家。除了系统参数里的 target_app_key(按聚水潭开放平台文档给定),报文内还要带 customer_id(或 owner 相关字段),具体取值在商家授权时向聚水潭获取。多商家对接时,这两者的组合就是路由键,错一个就会查到别家或报权限错误。

订单下行(查询)

以奇门自定义的订单查询接口为例,报文核心字段:查询时间区间(按修改时间增量)、分页参数(页码/页大小)。落地建议:

1. 增量窗口重叠 5-10 分钟:订单状态流转变更时间可能跳变,重叠拉取 + 按订单号去重,比精确窗口可靠;
2. 页大小保守:奇门网关有超时限制,页太大容易超时,宁多翻页;
3. 字段取最小集:只声明需要的字段,报文小、解析快;
4. 状态映射先行:聚水潭的订单状态与本系统状态枚举要先建映射表。

库存下行

库存场景一般是把 WMS/ERP 的可用库存同步给聚水潭,或反向查询聚水潭的库存流水。要点:

• 库存是全量覆盖语义还是增量调整语义,要先与聚水潭侧确认口径,两套语义混用是库存差异的最大来源;
• 批量库存报文注意单包条数上限,超出要拆包;
• 大促前建议人工核对一次全量,大促期间只走增量。

联调清单

1. 签名算法用官方示例报文离线验证通过再发真实请求;
2. 单商家先跑通订单查询全链路,再扩展多商家;
3. 把每次请求/响应原文(脱敏)落库,奇门问题排查全靠报文;
4. 与聚水潭确认限流阈值,调度频率留出余量。