API Docs
YMS API
External WMS Integration Guide

YMS 外部 WMS 对接指南

概述

YMS 系统支持通过 HTTP 回调方式与外部 WMS 系统集成。当 YMS 中发生任务操作（创建、更新、取消）时，系统会同步调用外部 WMS 提供的回调接口，将任务信息推送给外部 WMS。

核心流程：YMS 负责生成 taskId，通过回调接口通知外部 WMS，外部 WMS 可返回操作人信息。

1. 配置说明

对接前需要在 YMS 系统中配置以下两个参数（由 YMS 运维人员在后台配置）：

参数编号参数名称类型说明示例
SP-53External WMS Callback URLSTRING外部 WMS 回调地址https://your-wms.com/api/yms/task
SP-54External WMS Request HeadersDICTIONARY自定义请求头（JSON 格式）{"X-API-Key": "sk-xxx"}
  • 配置了 SP-53 回调地址后，该租户的任务操作将自动推送到外部 WMS
  • SP-54 中配置的请求头会附加到每次回调请求中，可用于鉴权

2. 回调接口规范

2.1 接口信息

  • 请求方式：POST
  • 请求地址：由 SP-53 配置的回调 URL（CREATE / UPDATE / CANCEL 共用同一地址）
  • Content-Type：application/json

2.2 请求头

每次回调请求会携带以下请求头：

Header说明来源
Content-Type固定为 application/json系统自动
AuthorizationYMS 当前用户的认证 Token系统自动
X-Tenant-Id租户 ID系统自动
X-Yard-Id园区 ID系统自动
Item-Time-Zone当前时区系统自动
自定义 HeaderSP-54 中配置的自定义请求头用户配置

注意：如果 SP-54 中配置了 Authorization，系统自动生成的 Authorization 不会覆盖用户配置的值。

2.3 请求体（Request Body）

{
  "taskId": "TASK-20260403-0001",
  "entryId": "ENT-20260403-0001",
  "taskType": "OFFLOAD",
  "receiptIds": ["REC-001", "REC-002"],
  "loadIds": ["LOAD-001"],
  "operate": "CREATE",
  "dockId": "LOC-DOCK-01",
  "equipmentNo": "CNTR1234567",
  "equipmentType": "CONTAINER",
  "loadMode": "LIVE_LOAD",
  "assigneeUserId": "user-001"
}

字段说明：

字段类型必填说明
taskIdString是任务 ID，由 YMS 系统生成，全局唯一
entryIdString否入场记录 ID
taskTypeString是任务类型，见下方枚举
receiptIdsList<String>否关联的收货单 ID 列表
loadIdsList<String>否关联的装货单 ID 列表
operateString是操作类型：CREATE / UPDATE / CANCEL
dockIdString否分配的 Dock（库门）位置 ID
equipmentNoString否设备编号（如集装箱号、拖车号）
equipmentTypeString否设备类型，见下方枚举
loadModeString否装载模式，见下方枚举
assigneeUserIdString否分配的操作人 ID

taskType 枚举值：

值说明
OFFLOAD卸货任务
LOAD装货任务
SHUTTLE移车任务

equipmentType 枚举值：

值说明
CONTAINER集装箱
TRAILER拖车
CHASSIS底盘车

loadMode 枚举值：

值说明
LIVE_LOAD现场装货
PRE_LOAD预装货

2.4 响应体（Response Body）

外部WMS需返回以下格式的 JSON 响应, 以下参数仅在创建task时可选返回，若返回则task使用外部返回的 assignee作为task的操作人员：

{
  "code": 200,
  "success": true,
  "msg": "OK",
  "data": {
    "assigneeUserId": "wms-user-001",
    "assigneeUserName": "张三"
  }
}

字段说明：

字段类型必填说明
codeInteger否业务状态码
successBoolean是操作是否成功，YMS 以此判断回调结果
msgString否错误信息（失败时返回）
dataObject否业务数据
data.assigneeUserIdString否WMS 分配的操作人 ID
data.assigneeUserNameString否WMS 分配的操作人姓名

重要：success 字段为 false 或响应为空时，YMS 会认为回调失败并阻塞当前业务操作（任务创建/更新/取消将失败）。

3. 操作类型说明

3.1 CREATE — 任务创建

触发时机：司机在 YMS 系统完成登记（Check-In）后，系统自动创建任务时触发。

业务场景：

  • 卸货任务（OFFLOAD）：司机到达园区，需要卸货
  • 装货任务（LOAD）：司机到达园区，需要装货 外部 WMS 处理建议：
  • 接收 YMS 生成的 taskId，在 WMS 侧建立关联
  • 可返回 assigneeUserId 和 assigneeUserName，YMS 会将其作为任务的操作人

3.2 UPDATE — 任务更新

触发时机：任务信息发生变更时触发，例如：

  • 重新分配 Dock 位置
  • 变更操作人
  • 更新关联的收货单/装货单

外部 WMS 处理建议：

  • 根据 taskId 找到对应任务，更新相关信息

3.3 CANCEL — 任务取消

触发时机：任务被取消时触发。

外部 WMS 处理建议：

  • 根据 taskId 找到对应任务，执行取消操作
  • 释放相关资源（如 Dock 占用、操作人分配等）

4. 错误处理

场景YMS 行为
外部 WMS 返回 success: false阻塞当前操作，向用户提示错误信息（msg 字段内容）
网络超时或连接失败阻塞当前操作，向用户提示网络异常
外部 WMS 返回空响应阻塞当前操作，提示 "Empty response"

建议外部 WMS 在处理失败时，在 msg 字段中返回有意义的错误描述，便于排查问题。

5. 对接流程

  1. 外部 WMS 实现回调接口：按照上述规范实现一个 POST 接口
  2. 提供回调地址和鉴权信息：将接口 URL 和所需的鉴权 Header 提供给 YMS 运维
  3. YMS 配置参数：运维在 YMS 后台配置 SP-53（回调 URL）和 SP-54（自定义 Header）
  4. 联调测试：在测试环境进行 CREATE / UPDATE / CANCEL 全流程验证

6. 请求示例

CREATE 请求示例

curl -X POST 'https://your-wms.com/api/yms/task' \
  -H 'Content-Type: application/json' \
  -H 'Authorization: Bearer xxx' \
  -H 'X-Tenant-Id: tenant-001' \
  -H 'X-Yard-Id: yard-001' \
  -H 'X-Facility-Id: yard-001' \
  -H 'X-API-Key: sk-xxx' \
  -d '{
    "taskId": "TASK-20260403-0001",
    "entryId": "ENT-20260403-0001",
    "taskType": "OFFLOAD",
    "receiptIds": ["REC-001"],
    "operate": "CREATE",
    "dockId": "LOC-DOCK-01",
    "equipmentNo": "CNTR1234567",
    "equipmentType": "CONTAINER",
    "loadMode": "LIVE_OFFLOAD"
  }'

成功响应示例

{
  "code": 200,
  "success": true,
  "msg": "OK",
  "data": {
    "taskId": "TASK-20260403-0001",
    "assigneeUserId": "wms-user-001",
    "assigneeUserName": "张三"
  }
}

失败响应示例

{
  "code": 500,
  "success": false,
  "msg": "Dock LOC-DOCK-01 is not available",
  "data": null
}
Get AuthorizationPOST Create Customer