Openapi For Warehouse FAQ – OneWarehouse

问题1：各接口的含义是什么？哪些是必要串接的接口？

答：为了确保OneWarehouse (OW) 与贵司WMS 系统能顺畅协作，API 分为「推送（Push）」与「查询（Query）」两大类。带有⭐️ 符号的为强烈建议必接的核心接口。

A. 业务推送与回传接口

业务场景	API 介面名称	传递方向	触发与应用情境描述
商品	⭐️ 商品同步	OW ➔ WMS	OW 新增或更新商品档案时，推送资料给WMS 建档。
入库	⭐️ 采购入库单下单	OW ➔ WMS	OW 建立「采购入库单」后，推送单据给WMS 准备收货。
	⭐️ 退货入库单下单	OW ➔ WMS	OW 执行「退货入库单」后，推送退货资讯给WMS。
	⭐️ 入库单取消	OW ➔ WMS	OW 发起入库单（含采购/退货）作废时，推送取消请求。
	⭐️ 入库单回传(Callback)	WMS ➔ OW	WMS 实际完成收货入库后，回传「入库状态与实际明细」给OW。
出库	⭐️ 出库单下单	OW ➔ WMS	OW 执行出货时，推送「出库订单」给WMS 安排拣货包装。
	⭐️ 出库单取消	OW ➔ WMS	OW 发起拦截出货时，推送取消出货请求给WMS。
	⭐️ 出库单回传(Callback)	WMS ➔ OW	WMS 完成包装出库后，回传「出库状态、包裹与出库明细」给OW。
	⭐️ 仓库取消出货	WMS ➔ OW	当WMS 发现异常（如缺货/破损）需主动中断出货时，推送取消请求给OW。

B. 查询与辅助接口

业务场景	API 介面名称	传递方向	触发与应用情境描述
出库	⭐️ 获取运单(面单)	WMS ➔ OW	WMS 查询出库订单的物流运单图档（回传PDF 格式之下载连结）。
	获取自画运单参数	WMS ➔ OW	若WMS 不直接取图档，可获取运单底层参数，由WMS 系统自行绘制渲染运单。
	⭐️申请拆包介面	WMS ➔ OW	当仓库发现一笔订单过大需拆分为多个包裹时，呼叫此介面申请新的子运单号。
基础	获取商家资讯	WMS ➔ OW	WMS 查询货主（Merchant）的公司名称等基本资料。

问题2： API 的系统触发节点

答：以下为OW 系统触发呼叫的具体操作节点：

接口名称	业务类型	触发节点与执行动作	操作路径(OW 后台)
商品同步	商品	1.新商品：点选采购入库单的【保存】按钮。 2.旧商品(已入库)：点选编辑商品页的【保存】按钮。	1. 采购入库> 建立入库单 2. 商品管理> 编辑
采购入库单下单	入库	点选采购入库单的【保存】按钮。	采购入库> 建立入库单
退货入库单下单	入库	点选退货单(待处理) 的【执行退货】按钮。	退货管理
入库单取消	入库	点选入库单(待入库) 的【作废】按钮。	采购入库
出库单下单	出库	点选订单(待处理) 的【执行出货】按钮。	订单管理
出库单取消	出库	点选订单(待出库) 的【拦截出货】按钮。	订单管理
查询库存	库存	由OW 内部排程配置的定时触发。	(系统后台执行)

问题3：回调Key 和下发Key 的对应用途为何？以什么为基准去检查Webhook Request？

答：这两组密钥在系统交互中扮演身分验证的关键角色：

【回调Key (Callback Key)】

用途：WMS 在入库/出库操作成功后，回调OW 系统时的「身分验证」。确保请求来源合法，防止未经授权的访问。
检查基准：
1. 密钥一致性：检查请求中的密钥与OW 系统中储存的回调Key 是否完全一致。
2. 来源验证：确认请求确实来自WMS 系统。
3. 时间戳与签名(如适用)：结合时间戳和签名进行验证，确保即时性与数据完整性。

【下发Key (Push Key)】

用途：OW 系统呼叫WMS 系统时的「身分验证」。 OW 会将包含sign(签名)、timestamp(时间戳) 等栏位的请求发给WMS。
检查基准：
1. 加密结果一致性：WMS 需使用下发Key 及指定加密方式对请求参数进行加密，结果必须与请求中的sign完全一致。
2. 参数验证：验证timestamp等参数，确保请求没有过期。
3. 安全性：确保使用的加密算法安全，无已知漏洞。

问题5：是否需要设置IP 白名单限制？

答：视WMS系统的安全需求而定，OW端不设IP限制。

WMS端限制（可选配置）：如果贵司WMS系统有访问来源的安全限制需求，我们提供了OneWarehouse系统的固定出口IP 。请在贵司的防火墙/网关中将以下IP加入白名单，以便顺利接收OW的推送请求。
OW端限制（无需配置）：当WMS系统回调OneWarehouse网关时，OW系统不会进行IP白名单限制，贵司无需提供出口IP予我们。

OneWarehouse系统固定出口IP地址列表（供WMS设定白名单使用）：

121.11.221.130
121.11.221.131
52.77.143.211
122.248.196.11
46.51.219.5
13.214.244.173
18.143.33.165
13.215.123.123
120.78.70.56
120.78.69.89
120.78.67.40
120.78.71.91