本文适用于需要将仓库管理系统（WMS）与 OneWarehouse（OW）进行系统对接的仓库合作伙伴。通过 OpenAPI 对接后，OneWarehouse 可将商品、入库单、退货入库单、出库单及取消指令推送至仓库 WMS；仓库也可依据实际作业结果，通过回调接口将入库、出库、取消、异常等处理结果同步回 OneWarehouse。
如需查看完整字段、请求示例与错误码，请参阅 OneWarehouse OpenAPI 文档。：OneWarehouse OpenAPI 文档。
一、整体对接流程
OpenAPI For Warehouse 的接入流程分为四个阶段：
- 接入准备
确认双方系统职责、业务场景与需要对接的 API 范围。 - 接口配置
仓库方提供 WMS 接收端点，OneWarehouse 配置 Webhook 推送地址；同时确认仓库回调 OneWarehouse 的方式与鉴权信息。 - 沙盒联调
使用 OneWarehouse 沙盒环境建立商品、入库单、退货单、出库单等测试资料，验证双方资料流是否正确。 - 正式上线
完成所有必要 API 测试后，切换至正式环境，并完成线上首单验证。
二、系统资料流说明
OneWarehouse 与仓库 WMS 的资料流分为两个方向：
1. OneWarehouse 推送至仓库 WMS
此方向由 OneWarehouse 主动发送请求至仓库方提供的 API URL。主要用于建立或更新商品、入库单、出库单及取消指令。
示例场景：
- 商家在 OneWarehouse 建立采购入库单后，OW 将入库单资料推送至 WMS。
- 商家在 OneWarehouse 执行出库后，OW 将出库单、收件人、商品明细、物流方式等资料推送至 WMS。
- 商家在 OneWarehouse 发起拦截出货或取消入库时，OW 将取消请求推送至 WMS。
2. 仓库 WMS 回调 OneWarehouse
此方向由仓库 WMS 在作业状态变更后，将处理结果同步回 OneWarehouse。
示例场景：
- 仓库完成入库验收后，回传实收数量及入库状态。
- 仓库完成出库后，回传出库完成状态、物流单号、包裹信息或面单信息。
- 仓库拒绝取消、取消失败或发生异常时，回传对应的处理结果与原因。
具体回调接口、请求字段与状态码，请以 OpenAPI 文档中的最新规范为准。
三、仓库方需提供的 API 接收端点
在建立沙盒环境前，请仓库方先提供以下 API 接收端点。OneWarehouse 会根据业务触发节点，将 JSON 格式资料推送至对应 URL。
| API 类型 | 功能说明 | 逻辑说明 |
|---|---|---|
| 商品同步 API | 同步商品基本档案 | 当商品首次建立或商品资料更新时，OneWarehouse 将商品资料推送至 WMS。若 sku_id 已存在，WMS 应执行更新；若不存在，WMS 应执行新增。 |
| 采购入库单 API | 建立采购入库任务 | 用于 OneWarehouse 将采购入库单资料推送至 WMS，仓库可依此建立入库作业任务。 |
| 退货入库单 API | 建立退货入库任务 | 当商家处理退货并执行入库时，OneWarehouse 会将退货入库资料推送至 WMS。 |
| 入库单取消 API | 取消未完成入库单 | 当商家发起入库取消或拦截时，WMS 需根据目前作业状态回传是否允许取消。 |
| 出库单下单 API | 建立出库发货订单 | 用于 OneWarehouse 将出库订单、收件人信息、商品明细、物流商信息等资料推送至 WMS。 |
| 出库单取消 API | 取消未出库订单 | 当商家发起拦截出货时，WMS 需根据目前出库进度回传是否拦截成功。 |
⚠️ 注意：上述 API URL 是建立沙盒测试环境的必要前置资料。若尚未提供，OneWarehouse 无法完成 Webhook 配置，也无法提供完整的沙盒联调环境。
四、 沙盒环境准备
在正式上线前，请先于 OneWarehouse 沙盒环境完成开发与测试。
1. 仓库方需提供
请提供以下信息给 OneWarehouse 对接团队：
- 商品同步 API URL
- 采购入库单 API URL
- 退货入库单 API URL
- 入库单取消 API URL
- 出库单下单 API URL
- 出库单取消 API URL
- 测试用仓库代码
- 技术对接人及联系方式
2. OneWarehouse 将提供
OneWarehouse 对接团队会在完成配置后提供：
- 沙盒客户端入口
- 沙盒测试账号
- 测试用 AppSecret 或其他鉴权资料
- 技术对接群组
基于安全考量，AppSecret 等敏感信息建议通过对接群组或指定方式单独提供。
五、 联调与测试流程
步骤 1：登录沙盒客户端触发测试
仓库方可通过 OneWarehouse 沙盒客户端执行以下操作，触发对应 API 推送。
| 测试项目 | 触发方式 |
| 商品同步 API |
首次商品同步通常会在建立采购入库单并保存时触发； 既有商品更新则可通过编辑商品并保存触发。 |
| 采购入库单 API | 建立并保存采购入库单时触发。 |
| 退货入库单 API | 针对待处理退货单，执行入库处理时触发。 |
| 入库单取消 API | 针对待入库单，执行作废、取消或拦截入库时触发。 |
| 出库单下单 API | 针对待处理订单，执行出库时触发。 |
| 出库单取消 API | 针对待出库订单，执行拦截出货或取消出库时触发。 |
步骤 2：检查 WMS 接收结果
仓库方需确认 WMS 是否正确收到 OneWarehouse 推送资料，并检查以下项目：
- API 是否有收到请求
- Request Body 是否完整
- 字段格式是否符合预期
- WMS 是否成功建立对应单据
- WMS 是否正确回传 Response
- OneWarehouse 是否正确显示推送结果
步骤 3：测试 WMS 回调 OneWarehouse
若对接范围包含仓库回调，仓库方需根据 OpenAPI 文档完成回调测试，包含但不限于：
- 入库完成回调
- 出库完成回调
- 出库物流信息回调
- 取消结果回调
- 异常状态回调
回调测试时，请确认 OneWarehouse 是否能正确更新单据状态与物流信息。
步骤 4：异常排查
测试期间若出现资料未同步、状态不一致、字段错误或接口报错，请在对接群组中提供以下信息：
- OneWarehouse 单号
- 错误截图
- WMS 系统日志
OneWarehouse 技术团队会根据日志协助排查。
六、测试验收标准
完成沙盒联调前，建议至少通过以下测试项目：
| 测试项目 | 验收标准 |
| 商品同步 | 商品可从 OneWarehouse 成功推送至 WMS，且新增、更新逻辑正确。 |
| 采购入库 | 采购入库单可成功建立至 WMS，商品明细与数量正确。 |
| 退货入库 | 退货入库单可成功建立至 WMS，退货商品与数量正确。 |
| 入库取消 | WMS 可依照实际作业状态回传取消成功或取消失败。 |
| 出库下单 | 出库单可成功建立至 WMS，收件人、商品、物流方式等资料正确。 |
| 出库取消 | WMS 可依照出库进度回传拦截成功或拦截失败。 |
| 仓库回调 | WMS 可将作业结果成功同步回 OneWarehouse。 |
| 异常处理 | 当资料错误或业务状态不允许时，WMS 可回传明确错误信息。 |
七、正式上线流程
- 上线申请：当所需对接的所有API通过联调测试，且双方确认数据流转准确无误后，即可向我方申请切换至生产环境。
-
参数切换：我方将正式提供生产环境专用的
AppSecret以及正式版的客户端链接。 - 正式发布：请将贵司 WMS 的接收地址切换为生产域名，配合完成最后的线上首单验证后，即可正式上线运行。
如有任何技术疑问，请随时联系 OneWarehouse 技术对接团队。
评论
0 条评论
请登录写评论。