zoe/ttx-project-doc
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
76ed80829c2a06e43dc5e76cdb42c94135404ec7
ttx-project-doc/Shopee_Automation_Vendor_接入协议手册_出库模块映射WES字段_V1.2.md
T

195 KiB
Raw Blame History

Shopee Automation Vendor 接入协议手册出库模块映射 WES 字段 V1.2

来源：C:\Users\zoe\Downloads\Shopee Automation Vendor 接入协议手册出库模块映射WES字段V1.2.docx

说明：本文档由 Word 接入协议手册转换生成，保留原始章节、接口字段表、响应字段表和返回码表，便于在仓库 docs/ 中维护和检索。

Shopee Automation Vendor 接入协议手册

文档版本信息

版本号 发布日期 发布人 版本说明
V1.0.0 2026-01-04 Shopee WMS 初稿
V1.0.1 2026-02-09 Shopee WMS 销售出库业务类型枚举统一
V1.0.2 2026-02-10 Shopee WMS vendor错误码更新
V1.0.3 2026-02-10 Shopee WMS 3.3.1 需求池模式新增demand_mode字段
V1.0.4 2026-02-11 Shopee WMS 3.4.1 接口增加属性key说明
4.1接口字段urgent_flag变更到attr_list中
4.3状态码更新
4.7 接口字段urgent_flag future_order_qty future_sku_qty oos_order_qty 四个字段变更到attr_list中
V1.0.5 2026-02-12 Shopee WMS 新增3.2.11对账接口
V1.0.6 2026-02-25 Shopee WMS 2.1 接口返回putaway_qty字段说明
2.5 接口返回task_list说明
2.7 接口请求total_qty、putaway_qty、submit_qty字段说明
2.8 接口请求sku_list说明
V1.0.7 2026-02-25 Shopee WMS 出库模块新增固定属性枚举说明(紫色标记)3.1.3 更新urgent flag批量接口新增批量返回参数
v1.0.8 2026-02-26 Shopee WMS 4.1AttrList新增oos_order_qty字段
4.1和4.7AttrItem新增urgent_flag字段说明(红色标记)
出库模块 新增拣货明细id说明(橙色标记)
v1.0.9 2026-02-27 Shopee WMS 出库属性列表新增attr_value_type
3pl 属性key重命名为channel_id
v1.1.0 2026-02-28 Shopee WMS 入库2.7接口新增错误码-10001016
v1.1.1 2026-03-03 Shopee WMS 基础资料5.4 请求体新增reconciliation_date字段
v1.1.2 2026-03-03 Shopee WMS 入库2.1 请求报文、2.5响应报文批次信息 BatchInfo新增purchase_type
v1.1.3 2026-03-04 Shopee WMS 库内4.5api路径改动 tovendor改为toshopee (已标记红色)
v1.1.4 2026-03-04 Shopee WMS 入库2.4接口增加了关于反拣的search_key说明。
v1.1.5 2026-03-04 Shopee WMS 库内4.3接口 remark增加传参说明
v1.1.6 2026-03-05 Shopee WMS 出库(黄底标记)
3.1.7增加校验说明、参数返回说明
3.3.9 入参、出参与销售出库统一
3.4.7 出参与销售出库统一
3.1.11 增加参数说明
v1.1.7 2026-03-05 Shopee WMS 3.1.1, 3.2.1, 3.3.1 3.4.1 新增下发参数ticket_type
3.2.2 删除不可能返回的错误码
v1.1.8 2026-03-05 Shopee WMS 2.6接口新增uid录入说明
v1.1.9 2026-03-06 Shopee WMS 4.1接口新增ticket_type
ticket_type枚举统一
v1.2.0 2026-03-06 Shopee WMS 5.2，5.3，5.4接口block_type字段统一
v1.2.1 2026-03-06 Shopee WMS 出库错误码补充
v1.2.2 2026-03-09 Shopee WMS 废弃入库2.1、2.3、2.4、2.5、2.7、2.8接口sheet_id字段
v1.2.3 2026-03-09 Shopee WMS 出库接口调用说明补充
v1.2.4 2026-03-10 Shopee WMS 入库2.1、2.4接口BatchInfo新增sku_id
v1.2.5 2026-03-12 Shopee WMS 基础资料新增接口5.8；
基础资料接口5.3 去除响应体BatchInventory 中的uid_list字段；
v1.2.6 2026-03-16 Shopee WMS 4.1接口新增sku_quality参数 (好坏品 0代表好品 1代表坏品)
v1.2.7 2026-03-17 Shopee WMS 需求池返回值增加非必填说明（3.3.6、3.3.8、3.3.10、3.3.11）
3.3.3 res_list增加最大长度说明
3.1.7 过账相关接口的拣货id增加长度说明
batch_no、pickup_id类型为int64
3.3.1 补充ctime字段
v1.2.8 2026-03-19 Shopee WMS 附录A.1 新增-10000005错误码
v1.2.9 2026-03-19 Shopee WMS 新增接口失败重试策略说明
v1.3.0 2026-03-30 Shopee WMS 4.2的device_id字段 4.3的new_device_id字段增加备注(不可二次使用)
v1.3.1 2026-04-01 Shopee WMS 更新operator说明
v1.3.2 2026-04-03 Shopee WMS 5.3修复sku business type枚举值说明
v1.3.3 2026-04-07 Shopee WMS 5.7查询robot状态接口可选参数agv_id_list统一改为robot_id_list
v1.3.4 2026-04-08 Shopee WMS 4.7增加更新失败的单据id列表
4.5 接口增加一个需要重试的状态码

目录

概述

本文档定义了Shopee Automation系统的完整接入协议规范。Vendor系统通过标准的HTTP/HTTPS接口与Shopee WMS Automation系统进行数据交互，实现自动化仓储作业。

适用范围

所有接入Shopee Automation系统的第三方Vendor

术语定义

Vendor: 第三方自动化设备/系统提供商

Automation: Shopee WMS自动化服务

北向请求: Vendor主动发起的请求

南向请求: Automation主动发起的请求

请求方式

请求方式旨在说明 Vendor和Shopee是如何进行交互的，按请求方向分为北向请求和南向请求

1.1 Vendor请求Automation（北向请求）

请求协议
协议项 值 类型 是否必须 说明
请求协议 Https - - -
请求方式 POST - 是 -
请求Host https://wms-automation.ssc.{env}.shopee.{cid} - 是 {env}: test, uat, staging（生产环境无需填写）
{cid}: ID: "co.id", MY: "com.my", PH: "ph", SG: "sg", TH: "co.th", TW: "tw", VN: "vn", BR: "com.br", CN: "cn"
请求路径 /api/v2/automation/toshopee/{module}/{sub_module}/{interface_name} - 是 module: inbound, outbound, inventory, basic
具体路径在接口协议中给定
请求头 Content-Type string 是 用于指定数据格式
值固定为：application/json
Authorization string 是 用于鉴权(有效期5分钟)
值为：
Bearer
其中，Bearer + 空格为固定部分，JWT token生成参考author
X-Request-Id string 是 请求唯一ID
使用UUID V4生成，长度为36个字符串，如：a1444101-b3a9-47b6-9967-dc0a77c2e8b2
X-Machine-Id string 否 自动化设备ID，和设备有关的操作需要加
X-Operator string 否 操作员邮箱,和人有关要加(因某些异常而系统触发且无实际操作员则传vendor@shopee.com，如:30分钟系统缺货0捡回传，没有上墙的0捡回传等), 具体接口body里传的operator同逻辑。
和人无关或批量提交可不加
响应头 Content-Type string 是 application/json
Trace_id string 是 请求追踪trace id
Request-Timestamp-Ms int 是 接收到请求时的毫秒级时间，如：1767853211916
Response-Timestamp-Ms int 是 返回请求时的毫秒级时间，如：1767853218097
X-Response-Et int 是 响应耗时(单位毫秒)，如：6181
AuthorizationJWT Token加密规范

Authorization的它是一组字符串，可以通过”.”切分成三个为Base64编码部分，格式为：xxxxx.yyyyy.zzzzz，三个部分分别对应header, payload以及signature

算法: HS256 // 用于签名时的算法，固定值

Secret: // Shopee提供，用于签名时的密钥，密钥区分环境

Header: // 头部，包含生成的算法以及Token类型

{

"alg": "HS256",

"typ": "JWT",

}

Payload: // 载荷，实际内容

{

"timestamp": 1765965498, // 请求时的秒级时间戳，有效期5分钟

"account": "xxx" // 账号，Shopee提供

}

Signature: // 签名

HMACSHA256(base64UrlEncode(header) + "." + base64UrlEncode(payload), secret)

生成示例:

下面提供一个GO语言的生成示例参考 (网页在线生成可参考：jwt.io):

func getSignToken(token, secret string) (string, *wmserror.WMSError) {

// header部分

headers := map[string]interface{}{

"typ": “JWT”,

"alg": "HS256",

}

bHeaders, err := json.Marshal(headers)

if err != nil {

return "", wmserror.NewError(constant.ErrHttpJwtEncodeFail, "jwt header to json fail:%v", err.Error())

}

// payload部分

payload := map[string]interface{}{

"timestamp": time.Now().Unix(),

"account": token,

}

bPayload, err := json.Marshal(payload)

if err != nil {

return "", wmserror.NewError(constant.ErrJsonEncodeFail, "header and body to json fail:%v", err.Error())

}

segments := []string{

jwt.EncodeSegment(bHeaders),

jwt.EncodeSegment(bPayload),

}

signingInput := strings.Join(segments, ".")

// signature部分是使用secret对前两部分的签名

signature, err := jwt.SigningMethodHS256.Sign(signingInput, []byte(secret))

if err != nil {

return "", wmserror.NewError(constant.ErrHttpJwtEncodeFail, "jwt encode fail:%v", err.Error())

}

// 返回三部分拼接的结果

return strings.Join([]string{signingInput, signature}, "."), nil

}

请求体格式

{

"xxx": "yyy"// 具体请求业务数据，由各接口定义(请求字段部分)

}

响应体格式

{

"retcode": 0, // 固定字段

"message": "success", // 固定字段

"data": { // 固定字段

// 内部响应数据，由各接口定义(响应字段部分)

}

}

请求和响应示例(以5.1接口为例)

请求体为：

{

"whs_id": "SGL",

"user_id": 123456

}

响应体为：

{

"retcode": 0,

"message": "success",

"data": {

"user_id":123456,

"email": "aaa@shopee.com"

}

}

1.2 Automation请求Vendor（南向请求）

请求协议
协议项 值 类型 是否必须 说明
请求协议 Http
请求方式 POST - 是 -
请求Host http://robot-{whs_id}.wms.{env}.ssc.shopee.{cid} - 是 whs_id小写
请求路径 /api/v2/automation/tovendor/{module}/{sub_module}/{interface_name} - 是 module: inbound, outbound, inventory, basic
具体路径在接口协议中给定
请求头 Content-Type string 是 用于指定数据格式
值固定为：application/json
Authorization string 是 用于鉴权(有效期5分钟)值为：
Bearer
其中，Bearer + 空格为固定部分，JWT token生成参考Authorization Jwt Token加密规范
X-Request-Id string 是 请求唯一ID
使用UUID V4生成，长度为36个字符串，如：a1444101-b3a9-47b6-9967-dc0a77c2e8b2
响应头 Content-Type string 是 application/json
Trace_id string 是 请求追踪trace id
Request-Timestamp-Ms int 是 接收到请求时的毫秒级时间，如：1767853211916
Response-Timestamp-Ms int 是 返回请求时的毫秒级时间，如：1767853218097
X-Response-Et int 是 响应耗时(单位毫秒)，如：6181
AuthorizationJWT Token校验

Authorization的token加密规范见1.1，vendor需要对shopee的请求做token鉴权校验

下面提供一个GO语言的校验的参考示例(账号和密钥shopee提供)

func VerifyAuthorizationToken(r *http.Request, account, secret string, tokenExpireSecond int64) error {

// 1. 从 Header 中提取 Bearer Token

authHeader := r.Header.Get("Authorization")

if authHeader == "" {

return fmt.Errorf("Authorization header is required")

}

parts := strings.SplitN(authHeader, " ", 2)

if len(parts) != 2 || parts[0] != "Bearer" {

return fmt.Errorf("Authorization header format must be: Bearer ")

}

tokenString := parts[1]

// 2. 解析并校验 JWT Token

token, err := jwt.Parse(tokenString, func(token *jwt.Token) (interface{}, error) {

// 2a. 校验签名算法必须是 HS256

if signingMethod, ok := token.Method.(*jwt.SigningMethodHMAC); !ok || signingMethod != jwt.SigningMethodHS256 {

return nil, fmt.Errorf("unexpected signing method: %v", token.Header["alg"])

}

// 2b. 从 payload 中取出 account

claims, ok := token.Claims.(jwt.MapClaims)

if !ok {

return nil, fmt.Errorf("invalid token claims")

}

accountVal, ok := claims["account"]

if !ok {

return nil, fmt.Errorf("account is required in token payload")

}

// 2c. 校验account

parsedAccount, ok := accountVal.(string)

if !ok {

return nil, fmt.Errorf("account must be a string")

}

if parsedAccount != account {

return nil, fmt.Errorf("account is invalid")

}

// 2d. 校验 timestamp分钟有效期

timestampVal, ok := claims["timestamp"]

if !ok {

return nil, fmt.Errorf("timestamp is required in token payload")

}

timestamp, ok := timestampVal.(float64)

if !ok {

return nil, fmt.Errorf("timestamp must be a number")

}

now := time.Now().Unix()

if int64(math.Abs(float64(now-int64(timestamp)))) > tokenExpireSecond {

return nil, fmt.Errorf("token expired: timestamp diff exceeds %d seconds", tokenExpireSecond)

}

// 返回该 account 对应的密钥，jwt 库会用它验证签名

return []byte(secret), nil

})

if err != nil {

return fmt.Errorf("token verify failed: %w", err)

}

if !token.Valid {

return fmt.Errorf("invalid token")

}

return nil

}

请求体格式

{

"xxx": "yyy"// 具体请求业务数据，由各接口定义(请求字段部分)

}

响应体格式

{

"retcode": 0, // 固定字段

"message": "success", // 固定字段

"data": { // 固定字段

// 内部响应数据，由各接口定义(响应字段部分)

}

}

请求和响应示例(以5.3接口为例)

请求体为：

{

"whs_id":"SGL",

"page_no":1,

"page_size":10,

"sku_id_list":["123", "456"]

}

响应体为：

{

"retcode": 0,

"message": "success",

"data": {

"page_no": 1,

"page_size": 10,

"list":[

{

"sku_id": "123",

"batch_no":123,

"block_type":0,

"quantity":10,

"uid_list":[

{

"unit_id": "123"

}

]

},

{

"sku_id": "456",

"batch_no":456,

"block_type":0,

"quantity":10,

"uid_list":[

{

"unit_id": "456"

}

]

}

]

}

}

接口失败重试策略

这里的用户指的是作业用户，即拣货员

Vendor请求Automation失败场景

请求失败分为http失败和retcode错误码

若http响应码不为200，视为接口没调通，需按接口请求方式触发重试

若为用户触发的同步请求，则需阻塞用户操作，由用户触发重试

若为系统触发的同步请求，则由系统触发重试

若为系统触发的异步请求，则由系统触发重试

若http响应码为200，且retcode为-10000005(超时)，需按接口请求方式触发重试

若为用户触发的同步请求，则需阻塞用户操作，由用户触发重试

若为系统触发的同步请求，则由系统触发重试

若为系统触发的异步请求，则由系统触发重试

其余retcode场景，参考具体错误码说明

若写明了错误码不需要重试，则不进行重试

若需要重试

用户触发的同步请求由用户触发重试

系统触发的请求由系统触发重试

其余场景，原则上有错误码则需要重试

重试方法

采用梯度重试策略，第一次重试间隔1秒，第二次重试间隔3秒，第三次重试间隔7秒...

当前系统触发的重试次数定为3次，用户触发的重试由用户决定。

入库模块接口协议

入库模块主要处理商品入库相关的自动化作业，包括收货确认、上架任务分配、货位管理等。

入库单据枚举值定义

Field Value Name【前端展示】
task_type 1 PurchaseInbound
2 ReturnInbound
3 MoveTransferInbound
4 RackTransfer
5 Replenishment
6 ReversPicking
枚举类型 枚举值
入库单据类型 type WhsInboundOrderType = int64
const (
WhsInboundOrderTypeePoInbound WhsInboundOrderType = 1 //采购入库上架
WhsInboundOrderTypeReturnInbound WhsInboundOrderType = 2 //退货入库上架
WhsInboundOrderTypeMoveTransferInbound WhsInboundOrderType = 3 //调拨入库上架
WhsInboundOrderTypeRackTransfer WhsInboundOrderType = 4 //移库上架
WhsInboundOrderTypeReplenishment WhsInboundOrderType = 5 //补货上架
WhsInboundOrderTypeReversPicking WhsInboundOrderType = 6 //反拣上架
)
入库单据状态 type WhsInboundOrderStatus = int64 //PutawayTaskStatus
const (
WhsInboundOrderStatusPending WhsInboundOrderStatus = 10
WhsInboundOrderStatusAssigned WhsInboundOrderStatus = 100
WhsInboundOrderStatusOngoing WhsInboundOrderStatus = 20
WhsInboundOrderStatusDone WhsInboundOrderStatus = 80
WhsInboundOrderStatusCancel WhsInboundOrderStatus = 90
)
入库错误码 // vendor调用shopee公共错误码，格式为-1000xxxx
// 0000-0999为公共错误，1000-1999为入库业务错误，2000-2999为出库业务错误，3000-3999为库内业务错误，4000-4999为基础资料业务错误
const (
ErrVendorAuthFailed = -10000000 // 鉴权失败，内容/格式错误，检查请求account/时间戳/Authorization，不需要自动重试
ErrVendorParamsInvalid = -10000001 // 请求参数错误，参数不对，检查请求参数，不需要自动重试
ErrVendorSystemError = -10000002 // 系统错误，系统内部异常，需要自动重试
)
// vendor 调用shopee inbound 错误码 格式为 -10001xxx
const (
ErrWhsIbShopeeInternalErr = -10001000
ErrWhsInboundOrderNotExist = -10001001 //入库单不存在
ErrWhsInboundOrderHasDone = -10001002 //入库单已经完结
ErrWhsInboundOrderStatusWrong = -10001003 //入库单状态不对
ErrWhsIbNotAllowVendorPutaway = -10001004 //入库单不在vendor作业
ErrWhsIbSkuQtyExceedLeftQty = -10001010 //sku提交数量超出待上架数量 - wms总数比vendor少
ErrWhsIbSkuUidQtyNotMatch = -10001011 //sku提交数量和uid数量不匹配-uid管理
ErrWhsIbSkuUidEmpty = -10001012 //uid管理sku没传uid_list
ErrWhsIbSkuUidInvalid = -10001013 //uid不合法
ErrWhsIbSkuQtyExceedWMSLeftQty = -10001014 //sku提交数量超出待上架数量 - wms总数跟vendor一样，putawayqty比vendor多
ErrWhsIbRequestSkuQtyMd5NotMatch = -10001015 //相同request id的请求，与上次的sku详情不一致
ErrWhsIbSkuPutawayQtyNotMatch = -10001020 //sku上架数量和wms不一致-需要人工介入
)

2.1 入库单据下发到Vendor

接口URL 接口描述 调用方 业务要求
/api/v2/automation/tovendor/inbound/order/create_inbound_order WMS生成上架任务之后同步给Vendor shopee 上架任务创建后，目标逻辑区是自动化区的上架任务，主动同步给vendor
接口系统要求
Avg RT Timeout 幂等字段 降级方案
200ms 10s task_info.task_id 无
请求字段
字段名 类型 是否必须 最大长度 说明 示例
whs_id string 是 16 仓库id
task_info InboundTaskInfo 是 单据信息 {}
batch_info_list List 是 本任务的批次详情信息【批次号幂等】 []

InboundTaskInfo

字段名 类型 是否必须 最大长度 说明 示例
task_id string 是 32 入库单号，上架任务单或者反拣单 "PASGC0002601060003"
唯一的
device_id string 是 32 设备id 【反拣没有？】 "IBBSK03082"
source_no string 否 64 关联单据id，只有反拣有，需要支持进入作业
task_type int 是 任务类型，详情见入库类型枚举 1
task_status int 是 单据状态，
wms会更新这个字段。		 10
task_version int 是 版本号，只能增加
wms会更新这个字段,只有在调用2.2接口主动更新时才会增加，2.5接口查询时不会变更这个字段。		 1，
task_priority int 是 任务优先级 2
is_urgent int 是 是否紧急，越大优先级越高
wms会更新这个字段		 1，
WES需要页面展示
specify_uid int 是 是否指定uid，如果没指定，录入uid需要wms校验 1
on_hold int 是 是否需要禁止上架，如果有异常该字段为1，vendor需要禁止作业，包含主动完结操作。
wms会更新这个字段		 0
ctime int 是 创建时间戳，
wms会按照这个时间进行范围查询		 1767582974(秒)
ongoing_time int 是 任务Ongoing时间 1767582974
done_time int 是 任务完结时间 1767582974
sku_info_list List 是 任务sku明细,会扣除掉在wms上架掉部分，所以如果任务全部在wms上架了，这部分为空

InboundSkuInfo

字段名 类型 是否必须 最大长度 说明 示例
sku_id string 是 64 Sku id "43376943579_395240042371"
batch_id string 是 128 明细行唯一键，需要在2.7接口回传给wms进行库存分配。 行号
"PA81868"
sheet_id string 是 64 关联单据id
batch_no string 是 64 批次号,相同批次号可能有多行明细 "2026010600001134"
total_qty int 是 sku当前批次总数【=已经上架+待上架】
wms会更新这个字段		 100
putaway_qty int 否 sku 上架的数量 ，主要用于对账两边上架数量，不做数量更新 10
uid_list List 否 sku是uid管理才会有值
1、生成任务时指定Uid会传全部uid，包含上架和未上架的
生产任务时没指定uid时只会传已经上架的部分
wms会更新这个字段【扣减掉wms上架的部分】,vendor侧需要保证这一行的uid_list进行全量更新，但是要保留vendor侧自身的上架状态

InboundUidInfo

字段名 类型 是否必须 最大长度 说明 示例
unit_id string 是 64 Unit id "SGF9YP69HW1"
stock_status int 是 Uid状态- 不包含wms系统的上架
0:未上架
1:已上架
这个状态是shopee侧记录的vendor上架的状态，只用于对账，vendor侧应该以自己系统记录的状态为准，vendor不应该用于更新自己系统的状态。		 0

BatchInfo

字段名 类型 是否必须 最大长度 说明 示例
sku_id string 是 64 sku id "2302990075_2019666499"
batch_no string 是 64 批次号，全局唯一 "2026021772289588"
inbound_id string 是 64 入库单号 "IBBSK03082"
inbound_date int 是 入库时间戳 1766534400
sku_quality int 是 sku质量:
0: Good
1: Damage		 0
origin_whs_id string 是 16 仓库id "SGC"
supplier_id string 是 64 供应商id "SSG1595335573586010113"
supplier_name string 是 64 供应商name "SPH2028670238723198977"
purchase_type string 是 64 Consignment 或者 Outright Consignment
production_date int 否 生产日期 1681603200
expiration_date int 否 过期日期 1807747200
block_type int 是 冻结类型:
0: Normal
1: Expiring
3: Expired		 0
mbn string 否 64 药品标识 "IBBSK03082"
ctime int 是 创建时间 1767683440
响应字段
字段名 类型 是否必须 最大长度 说明 示例
无
返回码
返回码 描述 说明 是否需要自动重试
-10011001 参数非法 比如参数是否必填、类型不符、长度不正确、非法字符、主键重复等 否
-10011010 单据类型未配置 单据类型未配置 否
-10011023 SKU不存在 SKU不存在 否
-10011049 仓库不存在 未配置仓库 否
-10011098 其他非法操作 上述未枚举时兜底使用 否
-10011099 系统错误 如限流、数据库错误、内部错误等等 是

2.2 WMS给Vendor下发单据变更接口

接口URL 接口描述 调用方 业务要求
/api/v2/automation/tovendor/inbound/order/update_inbound_order WMS上架任务变更之后同步给Vendor shopee 1、WMS 上架完成或者改变任务优先级或者提报了异常，会同步给vendor。
2、如果wms执行了上架，不会实时同步给vendor，需要vendor定时或者节点触发主动从wms获取最新的任务状态和明细
接口系统要求
Avg RT Timeout 幂等字段 降级方案
200ms 10s 无 无
请求字段
字段名 类型 是否必须 最大长度 说明 示例
whs_id string 是 16 仓库id
new_version int64 是 变更版本 2，
版本号WES需要存储最新的
update_type int 是 变更类型：bit位标识类型
0:wms作业
task_info InboundTaskUpdateInfo 否 任务信息,vendor需要根据最新的值做处理更新任务,主要包含任务状态、任务明细、优先级的更新，如vendor不存在这个任务，直接返回成功即可。 哪些字段需要更新？

InboundTaskUpdateInfo

字段名 类型 是否必须 最大长度 说明 示例
task_id string 是 32 入库单号，上架任务单或者反拣单 "PASGC0002601060003"
唯一的
task_status int 是 单据状态，
wms会更新这个字段。		 10
task_version int 是 版本号，只能增加
wms会更新这个字段		 1，
task_priority int 是 任务优先级 2
is_urgent int 是 是否紧急，越大优先级越高
wms会更新这个字段		 1，
WES需要页面展示
on_hold int 是 是否需要禁止上架，如果有异常该字段为1，vendor需要禁止作业，包含主动完结操作。
wms会更新这个字段		 0
done_time int 是 任务完结时间 1767582974
sku_info_list List 是 任务明细，如果任务中某个明细全部在wms非自动化区上架了，更新时给vendor的明细中不包含这条记录了，vendor需要把多出的记录删除。

InboundSkuUpdateInfo

字段名 类型 是否必须 最大长度 说明 示例
sku_id string 是 64 Sku id "43376943579_395240042371"
batch_id string 是 128 明细行唯一键 行号
total_qty int 是 sku当前批次总数【=已经上架+待上架】
wms会更新这个字段		 100
uid_list List 否 uid 管理且前置环节已经录入
uid list, 包含已经上架和未上架的
响应字段
字段名 类型 是否必须 最大长度 说明 示例
无
返回码
返回码 描述 说明 是否需要自动重试
-10011001 参数非法 比如参数是否必填、类型不符、长度不正确、非法字符、主键重复等 否
-10011050 需求数量不能小于上架数量 修改入库单据信息时校验 否
-10011098 其他非法操作 上述未枚举时兜底使用 否
-10011099 系统错误 如限流、数据库错误、内部错误等等 是

2.3 WMS向Vendor下发单据查询接口

接口URL 接口描述 调用方 业务要求
/api/v2/automation/tovendor/inbound/order/search_inbound_order_list WMS查询vendor入库单据信息 shopee wms 定期查询vendor入库单据进行对账
接口系统要求
Avg RT Timeout 幂等字段 降级方案
1000ms 30s 无 无
请求字段
字段名 类型 是否必须 最大长度 说明 示例
whs_id string 是 16 仓库id
start_time int 否 创建开始时间，包含此时间（下发时间的起始值） 1767261430
end_time int 否 创建结束时间，包含此时间
（下发时间的结束值）		 1767693430
task_id_list List 否 入库单据list ["PASGC0002601060003"]
page_size int 否 页大小，默认50 50
page_no int 否 页码，默认1 1
响应字段
字段名 类型 是否必须 最大长度 说明 示例
total int 是 总任务单据 10
task_list List 是 任务明细（需要包含任务和任务的明细） [{}]
返回码
返回码 描述 说明 是否需要自动重试
-10011001 参数非法 比如参数是否必填、类型不符、长度不正确、非法字符、主键重复等 否
-10011099 系统错误 如限流、数据库错误、内部错误等等 是

2.4 Vendor向WMS请求入库任务接口

接口URL 接口描述 调用方 业务要求
/api/v2/automation/toshopee/inbound/order/get_inbound_order Vendor通过容器或者单据获取未完结的入库任务 vendor 1、Vendor本地找不到单据可以通过此接口请求wms获取进行中的单据。
2、通过此接口获取的任务wms会进行打标已经同步到了vendor，后续任务变更会通知到vendor
接口系统要求
Avg RT Timeout 幂等字段 降级方案
200ms 10s 无 无
请求字段
字段名 类型 是否必须 最大长度 说明 示例
whs_id string 是 16 仓库id
search_key string 是 用户扫描内容，获取入库单据的标识码，支持device_id,或者order_no[反拣]/
针对反拣场景，支持进入作业的方式比较多，searck_key不一定在device_id或者source_no中，所以在多次进入作业由于扫描条形码不同且不在device_id和source_no中，vendor无法识别来请求wms，但其实对于的是同一个反拣任务，vendor需要用task_id做幂等。		 "IBBSK03082"
operator string 是 64 操作人邮箱 xxx@shopee.com
响应字段
字段名 类型 是否必须 最大长度 说明 示例
task_info InboundTaskInfo 是 单据信息 {}
batch_info_list List 是 本任务的批次详情信息【批次号幂等】 []
返回码
返回码 描述 说明 是否需要自动重试
0 返回成功 vendor正常处理业务
-10000001 请求参数错误 vendor参数错误
-10000002 wms系统错误 一些异常情况，可重试 是
-10001000 wms内部错误 需要wms进行错误检查修正
-10001001 入库单不存在 找不到单据
-10001002 入库单已经完结 单据已经完结
-10001003 入库单状态不对 此任务状态不能在vendor作业
-10001004 入库单不在vendor作业 此任务不在vendor作业

2.5 Vendor向WMS反查入库任务接口

接口URL 接口描述 调用方 业务要求
/api/v2/automation/toshopee/inbound/order/search_inbound_order_list Vendor 反查wms入库单据信息 vendor vendor通过此接口批量获取最新的入库单据状态，用于本地任务更新。wms不会实时通知vendor任务的变更。
接口系统要求
Avg RT Timeout 幂等字段 降级方案
1000ms 20s 无 无
请求字段
字段名 类型 是否必须 最大长度 说明 示例
whs_id string 是 16 仓库id
start_time int 否 创建开始时间
对于已完成任务，完成时间超过1个月不在支持查询（查询不到，不会报错）。		 1767261430
end_time int 否 创建结束时间
end_time-start_time间隔，不能超过7天
end_time、start_time必须同时指定。
[start_time,end_time]为闭区间，start_time <=X<=end_time。		 1767693430
task_id_list List 否 入库单据list，长度不能超过2000
1. task_id_list和<start_time
,end_time>两个参数必须传其中一个。
对于已完成任务，完成时间超过1个月不在支持查询（查询不到，不会报错）。		 ["PASGC0002601060003"]
page_size int 否 页大小，未传默认50
最大不能超过200		 50
page_no int 否 页码，未传默认1 1
响应字段
字段名 类型 是否必须 最大长度 说明 示例
total int 是 总任务单据 10
task_list List 是 任务明细，会变更的字段参考2.2接口
如果某个SKU全部在WMS上架，将不返回这条SKU明细。
如果整个任务的全部SKU都在WMS上架，将返回任务，但SKU列表是空的。
如果任务的sku明细没返回，Vendor需要把这条sku记录清空。		 [{}]
返回码
返回码 描述 说明 是否需要自动重试
0 返回成功 vendor正常处理业务
-10000001 请求参数错误 vendor参数错误
-10000002 wms系统错误 一些异常情况，可重试 是
-10001000 wms内部错误 需要wms进行错误检查修正

2.6 Vendor向WMS校验uid接口

接口URL 接口描述 调用方 业务要求
/api/v2/automation/toshopee/inbound/order/check_uid Vendor 录入uid时如果选择实时校验，通过此接口进行uid合法性校验 vendor Vendor侧开关控制流程，默认不通过此接口进行校验，在过账接口批量校验。打开开关才走这个接口校验

Uid录入说明,2.1接口如果specify_uid=0,最开始uid_list为空

接口系统要求
Avg RT Timeout 幂等字段 降级方案
200ms 10s 无 无
请求字段
字段名 类型 是否必须 最大长度 说明 示例
whs_id string 是 16 仓库id
task_id string 是 入库单号，不传则返回所有待处理入库单 "PASGC0002601060003"
task_type int 是 入库单据类型 1
sku_id string 是 Sku id "43376943579_395240042371"
unit_id string 是 Unit it "SGF9YP69HW1"
operator string 是 64 操作人邮箱 xxx@shopee.com
响应字段
字段名 类型 是否必须 最大长度 说明 示例
无
返回码
返回码 描述 说明 是否需要自动重试
0 返回成功 vendor正常处理业务
-10000001 请求参数错误 vendor参数错误
-10000002 wms系统错误 一些异常情况，可重试 是
-10001000 wms内部错误 需要wms进行错误检查修正
-10001001 入库单不存在 找不到单据
-10001002 入库单已经完结 单据已经完结
-10001003 入库单状态不对 此任务状态不能在vendor作业
-10001004 入库单不在vendor作业 此任务不在vendor作业
-10001013 Uid不合法 需要业务重新录入uid

2.7 Vendor向WMS提交库存过账接口

接口URL 接口描述 调用方 业务要求
/api/v2/automation/toshopee/inbound/order/submit_putaway vendor提交上架明细，增加库存。 vendor Vendor需要保障库存一致性,如果是网络问题没等到响应，需要用完全相同的请求体重试三次。
接口系统要求
Avg RT Timeout 幂等字段 降级方案
200ms 10s request_id
【单据维度】		 无

库存一致性保障方式：

vendor 侧用户提交上架，vendor请求wms如果是网络问题，需要用同一个请求报文原地重试最少三次。

重试请求wms仍然超时，返回用户错误。用户重复点击了，需要判断请求意图，即是否是同一个请求【sku、location和qty都一样】，如果一样用同一个request_id请求到wms，如果不一样新生成一个request_id,再根据wms返回到结果进行处理。如果wms判断上一次成功，则会报错，vendor需要做库存补偿。

vendor 侧拿到wms结果之后且wms处理成功，本地增加库存失败，需要立即重试，如果还失败需要告警手动处理。

请求字段
字段名 类型 是否必须 最大长度 说明 示例
whs_id string 是 16 仓库id
task_id string 是 32 入库单号 "PASGC0002601060003"
task_type int 是 入库单据类型 1
request_id string 是 128 请求id，幂等字段,
整个单据维度幂等		 "1767693430000123"，
提交上架的明细是同一条的时候，requestid需要相同
putaway_type int 上架方式：
倒箱（收货）：11
离线支架（整箱上架）：12
在线循环（by sku）：13
输送线：14
sku_list List 是 上架明细，其中的putaway_qty是此次上架的数量，uid_list是此次上架的uid []
operator string 是 64 操作人邮箱 xxx@shopee.com

PutawaySkuInfo

字段名 类型 是否必须 最大长度 说明 示例
sku_id string 是 64 sku id "43376943579_395240042371"
batch_id string 是 128 当前明细唯一键
sheet_id string 是 64
batch_no string 是 64 批次号 "2026010600001134"
total_qty int 是 sku当前明细行总数，wms内部做对比，对不上时仅内部告警。 60，
明细的计划数量
putaway_qty int 是 sku当前明细行已经上架数量，总数减去次数量为剩余数量，wms内部做对比，对不上时仅内部告警。 10，
明细的已经上架的数量
submit_qty int 是 此次上架数量，不能超过剩余数量，超过时直接报错，整个请求都不成功。 20，
明细的本次上架的数量
uid_list List 否 上架uid
响应字段
字段名 类型 是否必须 最大长度 说明 示例
task_status int 是 任务状态，首次作业从Pending->Ongoing 100
err_list List<>ErrSkuInfo 否 错误明细 [见下表]

ErrSkuInfo

字段名 类型 是否必须 最大长度 说明 示例
sku_id string 是 64 Sku id "43376943579_395240042371"
batch_id string 是 128 当前明细唯一键
sheet_id string 是 64 关联单据id
batch_no string 是 批次号
total_qty int 是 sku当前明细行总数，可能跟request不同，vendor需要根据返回做调整。 0
putaway_qty int 是 wms记录的已经上架的数量，跟vendor对不上时vendor需要告警。 告警就行
exceed_qty int 是 当前请求超出的数量，为0表示没超出
err_uid_list List 否 不合法的uid，需要重新贴标录入
返回码
返回码 描述 说明 是否需要自动重试
0 返回成功 vendor正常处理业务
-10000001 请求参数错误 vendor参数错误
-10000002 wms系统错误 一些异常情况，可重试 是
-10001000 wms内部错误 需要wms进行错误检查修正
-10001001 入库单不存在 找不到单据
-10001002 入库单已经完结 单据已经完结
-10001003 入库单状态不对 此任务状态不能在vendor作业
-10001004 入库单不在vendor作业 此任务不在vendor作业
-10001010 sku提交数量超出待上架数量 可能是vendor侧没更新任务明细。可拉取最新单任务更新后重试。
-10001011 sku提交数量和uid数量不匹配-uid管理 检查参数
-10001012 uid管理sku没传uid_list 检查sku 是否uid管理
-10001013 Uid不合法 明细在err_uid_list中
-10001014 sku提交的数量+之前上架的数量比预期总数多。 预期数量一致，可能是之前wms上架成功，vendor失败了。这一条明细无法上架，需要人工处理。
-10001015 相同request id的请求，与上次的sku详情不一致 换一个requestid重试
-10001016 一次请求的batch_id过多 请求数据量太大，需要拆分

2.8 Vendor向WMS下发单据状态变更接口

接口URL 接口描述 调用方 业务要求
/api/v2/automation/toshopee/inbound/order/update_inbound_status Vendor完成作业之后，向wms下发单据完成 vendor 需要带上任务已经上架的明细进行库存对账，没有上架的部分wms会将其默认移动到AV区。
-此接口一定在过账接口提交完成之后异步调用，否则过账接口还没提交会导致库存对不齐。
接口系统要求
Avg RT Timeout 幂等字段 降级方案
200ms 10s 无 无
请求字段
字段名 类型 是否必须 最大长度 说明 示例
whs_id string 是 16 仓库id
task_id string 是 32 入库单号 "PASGC0002601060003"
task_type int 是 入库单据类型 1
task_status int 是 任务状态，完成传Done状态 80
sku_list List 是 上架明细，uid只用传上架的，total_qty不校验。putaway_qty不一致时会失败且告警。
operator string 是 64 操作人邮箱 xxx@shopee.com
响应字段
字段名 类型 是否必须 最大长度 说明 示例
无
返回码
返回码 描述 说明 是否需要自动重试
0 返回成功 vendor正常处理业务
-10000001 请求参数错误 vendor参数错误
-10000002 wms系统错误 一些异常情况，可重试 是
-10001000 wms内部错误 需要wms进行错误检查修正
-10001001 入库单不存在 找不到单据
-10001002 入库单已经完结 单据已经完结
-10001003 入库单状态不对 此任务状态不能在vendor作业
-10001004 入库单不在vendor作业 此任务不在vendor作业
-10001020 vendor侧sku上架数量和wms不一致 可稍后重试，多次不成功人工介入 是

2.9 Vendor向WMS批量校验uid接口

接口URL 接口描述 调用方 业务要求
/api/v2/automation/toshopee/inbound/order/check_uid_list Vendor 录入uid后批量校验uid合法性 vendor 批量校验，不合法的uid在返回体中，有任意一个不合法就会报错。
接口系统要求
Avg RT Timeout 幂等字段 降级方案
200ms 10s 无 无
请求字段
字段名 类型 是否必须 最大长度 说明 示例
whs_id string 是 16 仓库id
task_id string 是 入库单号，不传则返回所有待处理入库单 "PASGC0002601060003"
task_type int 是 入库单据类型 1
sku_id string 是 Sku id "43376943579_395240042371"
uid_list List 是 Uid List,不能重复 ["SGF9YP69HW1",
"SGF9YP69HW2"]
operator string 是 64 操作人邮箱 xxx@shopee.com
响应字段
字段名 类型 是否必须 最大长度 说明 示例
invalid_uid_list List 是 不合法的list，为空表面都合法 ["SGF9YP69HW1"]
返回码
返回码 描述 说明 是否需要自动重试
0 返回成功 vendor正常处理业务
-10000001 请求参数错误 vendor参数错误
-10000002 wms系统错误 一些异常情况，可重试 是
-10001000 wms内部错误 需要wms进行错误检查修正
-10001001 入库单不存在 找不到单据
-10001002 入库单已经完结 单据已经完结
-10001003 入库单状态不对 此任务状态不能在vendor作业
-10001004 入库单不在vendor作业 此任务不在vendor作业
-10001013 Uid不合法 需要业务重新录入uid

出库模块接口协议

出库模块主要处理订单出库相关的自动化作业，包括波次管理、拣货任务、复检包装等。

枚举key 枚举值
3.1.1 销售出库下发task max_order_size const (
SkuSizeTypeExtraSmall SkuSizeType = 1
SkuSizeTypeSmall SkuSizeType = 2
SkuSizeTypeMedium SkuSizeType = 0
SkuSizeTypeLarge SkuSizeType = 8
SkuSizeTypeSuperLarge SkuSizeType = 16
SkuSizeTypeBulky SkuSizeType = 10
SkuSizeTypeExtraBulky SkuSizeType = 20
SkuSizeTypeDefault SkuSizeType = 99
SkuSizeTypeNone SkuSizeType = -2
)
var SkuSizePriorityMap = map[SkuSizeType]int64{
SkuSizeTypeExtraSmall: 1,
SkuSizeTypeSmall: 2,
SkuSizeTypeMedium: 3,
SkuSizeTypeLarge: 4,
SkuSizeTypeSuperLarge: 5,
SkuSizeTypeBulky: 6,
SkuSizeTypeExtraBulky: 7,
}
3.2.1 销售出库下发order order_structure const (
SalesOrderSkuQtyTypeSingleSkuSingleQty SalesOrderSkuQtyType = 1
SalesOrderSkuQtyTypeSingleSkuMultiQty SalesOrderSkuQtyType = 2
SalesOrderSkuQtyTypeMultiSku SalesOrderSkuQtyType = 3
SalesOrderSkuQtyTypeUndefined SalesOrderSkuQtyType = 10
)
var SalesOrderSkuQtyType2NameMap = map[SalesOrderSkuQtyType]string{
SalesOrderSkuQtyTypeSingleSkuSingleQty: "SSSQ",
SalesOrderSkuQtyTypeSingleSkuMultiQty: "SSAQ",
SalesOrderSkuQtyTypeMultiSku: "MSAQ",
}
3.2.1 销售出库下发order order_size const (
SkuSizeTypeExtraSmall SkuSizeType = 1
SkuSizeTypeSmall SkuSizeType = 2
SkuSizeTypeMedium SkuSizeType = 0
SkuSizeTypeLarge SkuSizeType = 8
SkuSizeTypeSuperLarge SkuSizeType = 16
SkuSizeTypeBulky SkuSizeType = 10
SkuSizeTypeExtraBulky SkuSizeType = 20
SkuSizeTypeDefault SkuSizeType = 99
SkuSizeTypeNone SkuSizeType = -2
)
var SkuSizePriorityMap = map[SkuSizeType]int64{
SkuSizeTypeExtraSmall: 1,
SkuSizeTypeSmall: 2,
SkuSizeTypeMedium: 3,
SkuSizeTypeLarge: 4,
SkuSizeTypeSuperLarge: 5,
SkuSizeTypeBulky: 6,
SkuSizeTypeExtraBulky: 7,
}
销售出库 inner_packaging
、
outer_packaging的type枚举		 const (
ConsumableSpecialTypeNoneSuggested = -1
ConsumableTypePackingBox ConsumableType = 1
ConsumableTypePouch ConsumableType = 2
ConsumableTypeStationeries ConsumableType = 3
ConsumableTypeFillers ConsumableType = 4
ConsumableTypeStretchFilms ConsumableType = 5
ConsumableTypeOthers ConsumableType = 6
ConsumableTypeSticker ConsumableType = 7
ConsumableTypeBubbleWrap ConsumableType = 8
ConsumableTypePEWrap ConsumableType = 9
ConsumableTypeGift ConsumableType = 10
ConsumableTypeBubbleWrapOuter ConsumableType = 11
)
var ConsumableTypeValueToName = map[int64]string{
ConsumableTypePackingBox: "PackingBox",
ConsumableTypePouch: "Pouch",
ConsumableTypeStationeries: "Stationeries",
ConsumableTypeFillers: "Fillers",
ConsumableTypeStretchFilms: "StretchFilms",
ConsumableTypeOthers: "Others",
ConsumableTypeSticker: "Sticker",
ConsumableTypeBubbleWrap: "BubbleWrap",
ConsumableTypePEWrap: "PEWrap",
ConsumableTypeGift: "Gift",
ConsumableTypeBubbleWrapOuter: "BubbleWrapOuter",
}
3.3.1 RTS/MTO下发需求 order_source
（MTO)		 const (
mtoCreateChannelWMS MTOCreateChannel = 0
mtoCreateChannelPMS MTOCreateChannel = 1
mtoCreateChannelFBS MTOCreateChannel = 2
)
3.3.1 RTS/MTO下发需求 transported_by const (
MTOTransportedByOthers MTOTransportedBy = 0
MTOTransportedBySpx MTOTransportedBy = 1
)
3.3.1 RTS/MTO下发需求 biz_type const (
SkuBusinessTypeUndefined SkuBusinessType = 0
SkuBusinessTypeFRS SkuBusinessType = 1
SkuBusinessTypeFBS SkuBusinessType = 2
SkuBusinessTypeNormalRetail SkuBusinessType = 3
SkuBusinessTypeSCS SkuBusinessType = 4
)
3.3.1 RTS/MTO下发需求 delivery_method const (
RTSPickUpBySuppliers RTSDeliveryMethod = 1
RTSPickUpBySupplierDuringInbound RTSDeliveryMethod = 2
RTSShopeeSendsBack RTSDeliveryMethod = 3
RTSThrowAway RTSDeliveryMethod = 4
)
var DeliveryMethodDescMap = map[RTSDeliveryMethod]string{
RTSPickUpBySuppliers: "Pick Up By Suppliers",
RTSPickUpBySupplierDuringInbound: "Pick Up By Supplier During Inbound",
RTSShopeeSendsBack: "Shopee Sends Back",
RTSThrowAway: "Throw Away",
}
3.3.1 RTS/MTO下发需求 rts_reason const (
RealRTSReasonSupplierRequest RTSReason = "R1"
RealRTSReasonAgingProduct RTSReason = "R2"
RealRTSReasonManufacturingDefective RTSReason = "R3"
RealRTSReasonExpired RTSReason = "R4"
RealRTSReasonBuyerReturn RTSReason = "R5"
RealRTSReasonOther RTSReason = "R6"
RealRTSReasonExpiring RTSReason = "R7"
RealRTSSellerRequest RTSReason = "R8"
RealRTSDamagedAndExpiry RTSReason = "R9"
// deprecated
RealRTSReasonInboundRTS RTSReason = "R10"
// Resell Phase II 新增 reason
RealRTSReasonReSellFailInsurance RTSReason = "R11"
RealRTSReasonReSellFailNonInsurance RTSReason = "R12"
RealRTSReasonShopExitInsurance RTSReason = "R13"
RealRTSReasonShopExitNonInsurance RTSReason = "R14"
VirtualRTSReasonSkuIdSwap RTSReason = "VR-IB1"
VirtualRTSReasonSkusBundling RTSReason = "VR-IB2"
VirtualRTSReasonOthers RTSReason = "VR-IB3"
ReplacementRTSReasonDamaged RTSReason = "RP1"
)
var WmsReturnReasonToIscReturnReasonMap = map[string]pb.RtsReason{
"R1": pb.RtsReason_RtsReasonSupplierRequest,
"R2": pb.RtsReason_RtsReasonAgingProduct,
"R3": pb.RtsReason_RtsReasonManufacturingDefectiveOrExpired,
"R4": pb.RtsReason_RtsReasonExpired,
"R5": pb.RtsReason_RtsReasonBuyerReturn,
"R6": pb.RtsReason_RtsReasonOthers,
"R7": pb.RtsReason_RtsReasonExpiring,
"R8": pb.RtsReason_RtsReasonSellerRequest,
"R9": pb.RtsReason_RtsReasonDamagedAndExpiry,
"R10": pb.RtsReason_RtsReasonInboundRts,
"VR-IB1": pb.RtsReason_RtsReasonSkuIdSwap,
"VR-IB2": pb.RtsReason_RtsReasonSkuBundling,
"VR-IB3": pb.RtsReason_RtsReasonOthers,
"RP1": pb.RtsReason_RtsReasonDamagedItems,
}
3.3.1 RTS/MTO下发需求 order_source
（RTS）		 const (
RTSCreateChannelWMS RTSCreateChannel = 0
RTSCreateChannelPMS RTSCreateChannel = 1
)
错误码汇总
销售出库 const (
ErrOutboundVendorCopierFail = -10002000 // 参数拷贝失败
ErrOutboundVendorParam = -10002001 // 参数错误
ErrOutboundVendorFailOrder = -10002002 // 订单加入波次失败
ErrOutboundVendorCreatePickingTask = -10002003 // 创建波次失败
ErrOutboundVendorTaskEmpty = -10002004 // 波次为空
ErrOutboundVendorTaskStatus = -10002005 // 波次状态不对
ErrOutboundVendorTaskSource = -10002006 // 波次来源不对
ErrOutboundVendorRespEmpty = -10002007 // 外部响应为空
ErrOutboundVendorCompleteInterOrder = -10002008 // complete接口 订单列表交集错误
ErrOutboundVendorPickupIDUsed = -10002009 // 波次ID已被使用
ErrOutboundVendorChangeInterOrder = -10002010 // 换箱接口 订单列表交集错误
ErrOutboundVendorDeviceError = -10002011 // device 错误
ErrOutboundVendorRetCode = -10002012 // 调用vendor封装错误码
ErrOutboundVendorUnitError = -10002013 // 拣货明细校验错误
ErrOutboundVendorOthers = -10002014 // 其他业务类错误码
)
RTS const (
ErrRtsVendorParam = -10002501
ErrRtsVendorSystemError = -10002502
ErrRtsVendorRequireNotFound = -10002503
ErrRtsVendorRequireNotToVendor = -10002504
ErrRtsVendorSubRequireAlreadyDone = -10002505
ErrRtsVendorRequireStatusNotAssigned = -10002506
ErrRtsVendorFlowModeMismatch = -10002507
ErrRtsDeviceNotAllow = -10002508
)
MTO const (
ErrMtoVendorParams = -10002801
ErrMtoVendorStartPickingTask = -10002802
ErrMtoVendorBindDevice = -10002803
ErrMtoVendorSyncPickingDetail = -10002804
ErrMtoVendorCompletePickingTask = -10002805
)

3.1 销售出库自动化SubPickingTask

3.1.1 WMS给Vendor下发拣货任务
接口URL 接口描述 调用方 业务要求
/api/v2/automation/tovendor/outbound/salesorder/create_sub_picking_task WMS给Vendor下发拣货任务 shopee 占用库存要求：
批次属性必须是：好品+normal
该任务不可混合其他任务一起拣货，不可追加明细
若30分钟还没占用库存，则调用完成接口【0拣】
接口系统要求
Avg RT Timeout 幂等字段 降级方案
300ms 10s sub_pickup_id+whs_id 无，
请求字段
字段名 类型 是否必须 最大长度 说明 示例 WES表字段
whs_id string 是 16 仓库id SGL shipment_header.warehouseCode
sub_pickup_id string 是 32 拣货任务id，幂等hik的单据 202104220002_0，波次id shipment_header.erpOrderCode
shipment_header.shopeeWave-新增字段，shopee波次号
同步接到两个字段中
urgent_flag int 是 0~99 越大越紧急 1 shipment_header.priority
cut_off_time int 是 任务截止时间，秒级时间戳，越小越优先出库 1767837541 shipment_header.cutOffTime-新增字段，截止时间
ship_by_date int 是 Ship by Date（Task中order最早的sbd），秒级 1767837541 shipment_header.scheduledShipDate
purchase_time int 是 Purchase Time（Task中order最早的pt），秒级 1767837541 shipment_header.purchaseTime-新增字段，购买时间
order_time int 是 Create Time（Task中order最早的create time），秒级 1767837541 shipment_header.orderTime-新增字段，订单创建时间
ctime int 是 创建时间，WMS创建的时间戳，秒级 1767751167 shipment_header.ctime-新增字段，shopee wms创建时间
can_group_picking int 是 0: 不可混拣 0 shipment_header.canGroupPicking
新增字段，是否混拣
group_key string 是 128 特征值，若可混拣，则有值 xxx_xx_xx_xx shipment_header.groupKey
新增字段，混拣特征值
sku_info_list List 是 期望拣货数量 明细取值见下文
single_attr_list List 是 属性列表（单属性）
当前有：
process_guide
spx_single_store
spx_store_group_template
spx_store_group_id
max_order_size		 max_order_size接到shipment_header.orderSize-新增字段
multi_attr_list List 是 属性列表（多属性）
当前attr_key有：
channel_id、fulfillment_chain_id		 channel_id接到shipment_header.channelId-新增字段
fulfillment_chain_id接到shipment_header.fulfillmentChainId-新增字段
ticket_type int 是 单据类型：
1: 销售出库下发task 2:销售出库下发order 3:rts需求池需求 4: mto需求池需求 5: mto下发任务 6: RT		 1 shipment_header.ticketType-新增字段
shipment_header.shipmentType
默认：XSCK

SkuInfo字段详情

字段名 类型 是否必须 最大长度 说明 示例 WES表字段
sku_id string 是 64 sku_id 1767751294820_08379 shipment_detail.itemCode
qty int 是 期望拣货数量 10 shipment_detail.requestQty
block_type int 是 销售出库传的是0 normal
指定冻结类型（Normal/临期/过期）
SKUBlockTypeNoNeed SKUBlockType = 0
SKUBlockTypeEXPIRING SKUBlockType = 1
SKUBlockTypeEXPIRED SKUBlockType = 3		 0 shipment_detail.shelfLifeSts
效期状态
quality int 是 0 好品
指定好/坏品
SkuQualityTypeGood SkuQualityType = 0
SkuQualityTypeDamage SkuQualityType = 1		 0 shipment_detail.inventorySts
库存状态

SingleAttr字段详情（WES需要展示吗？）

字段名 类型 是否必须 最大长度 说明 示例 WES表字段（需同步插入数据字典，shopee_field_dictionary,attr_key插入组类型，attr_value_id插入标识，attr_value_name插入名称，attr_value_type插入value1）接口下发时判断数据字典如果没有该组类型的标识需要插入数据字典
attr_key string 是 64 属性key max_order_size config_detail.groupType
attr_value_id string 是 128 属性value id(没有id的场景我们id和name传的是相同的值) 1 config_detail.identifier
attr_value_type string 否 128 属性 type的枚举
（有些属性需要支持类型筛选）		 1 config_detail.value1
attr_value_name string 是 128 属性value 可读 large config_detail.description

MultiAttr字段详情（WES需要展示吗？）

字段名 类型 是否必须 最大长度 说明 示例 WES表字段（需同步插入数据字典，shopee_field_dictionary, attr_key插入组类型，attr_value_id插入标识，attr_value_name插入名称，attr_value_type插入value1）接口下发时判断数据字典如果没有该组类型的标识需要插入数据字典
attr_key string 是 64 属性key 3pl config_detail.groupType
attr_value_list List 是 属性value列表 [
{
"attr_value_id":"30005",
"attr_value_name":"SPX"
},
{
"attr_value_id":"30006",
"attr_value_name":"SPD"
}
]

Attr字段详情

字段名 类型 是否必须 最大长度 说明 示例
attr_value_id string 是 属性value "30005" config_detail.identifier
attr_value_type string 否 128 属性 type的枚举
（有些属性需要支持类型筛选）		 1 config_detail.description
attr_value_name string 是 属性value 可读 "SPX"
响应字段（和vendor对一下能提供什么字段给WMS）
字段名 类型 是否必须 最大长度 说明 示例
无
返回码
返回码 描述 说明 是否需要自动重试
-10012001 参数非法 比如参数是否必填、类型不符、长度不正确、非法字符、主键重复等 否
-10012010 单据类型未配置 单据类型未配置 否
-10012023 SKU不存在 SKU不存在 否
-10012049 仓库不存在 未配置仓库 否
-10012098 其他非法操作 上述未枚举时兜底使用 否
-10012099 系统错误 如限流、数据库错误、内部错误等等 是
3.1.2 WMS取消拣货任务
接口URL 接口描述 调用方 业务要求
/api/v2/automation/tovendor/outbound/salesorder/cancel_sub_picking_task WMS取消拣货任务 shopee WMS支持从Pending/Ongoing取消掉，若是Ongoing → 取消的case，Vendor好像会报错，WMS收到不能取消时，会阻塞取消请求（Vendor考虑如果只绑了device也支持取消）
注意：WMS会释放库存、释放device，需要Vendor也考虑
接口系统要求
Avg RT Timeout 幂等字段 降级方案
300ms 10s sub_pickup_id+whs_id 无
请求字段
字段名 类型 是否必须 最大长度 说明 示例 WES表字段（取消WES走base标记cancel，标记的单子集波不抓）
whs_id string 是 16 仓库id SGL shipment_header.warehouseCode
sub_pickup_id string 是 32 拣货任务id，幂等 202104220002_0 shipment_header.erpOrderCode
响应字段
字段名 类型 是否必须 最大长度 说明 示例
无
返回码
返回码 描述 说明 是否需要自动重试
-10012001 参数非法 比如参数是否必填、类型不符、长度不正确、非法字符、主键重复等 否
-10012051 单据不存在 单据不存在 否
-10012052 单据已拣货，不能取消 单据已拣货，不能取消 否
-10012098 其他非法操作 上述未枚举时兜底使用 否
-10012099 系统错误 如限流、数据库错误、内部错误等等 是
3.1.3 WMS向Vendor更新订单/task的urgent flag
接口URL 接口描述 调用方 业务要求
/api/v2/automation/tovendor/outbound/salesorder/update_task_flag wms向vendor更新订单/task的urgent flag shopee 定时任务，会捞取未完结的pickingTask看是否满足urgent条件，若满足urgent条件则更新Vendor的urgent标。
注意：urgent有可能会更新为non-urgent。
接口系统要求
Avg RT Timeout 幂等字段 降级方案
300ms 10s 无 无
请求字段
字段名 类型 是否必须 最大长度 说明 示例 WES表字段
whs_id string 是 16 仓库id SGL shipment_header.warehouseCode
biz_type int 是 1 - 销售出库 2 - RTS 3 - MTO 1 shipment_header.shipmentType
ticket_type int 是 单据类型：
单据类型：
1: 销售出库下发task 2: 销售出库下发order 3:rts需求池需求 4: mto 需求池需求 5: mto下发任务 6: RT		 1 shipment_header.ticketType
ticket_number_list List 是 32 单据列表 ["202104220002_0"] shipment_header.erpOrderCode
urgent_flag int 是 0~99 越大越紧急 0 shipment_header.priority
更新该字段
响应字段
字段名 类型 是否必须 最大长度 说明 示例
success_list List 是 200
fail_list List 是 200
not_exist_list List 是 200 不存在列表
返回码
返回码 描述 说明 是否需要自动重试
-10012001 参数非法 比如参数是否必填、类型不符、长度不正确、非法字符、主键重复等 否
-10012098 其他非法操作 上述未枚举时兜底使用 否
-10012099 系统错误 如限流、数据库错误、内部错误等等 是
3.1.4 Vendor绑定/解绑device(空占)【复用basic接口】废弃
3.1.5 Vendor开始拣货任务
接口URL 接口描述 调用方 业务要求
/api/v2/automation/toshopee/outbound/salesorder/start_picking_task Vendor开始拣货任务 vendor 同步调用，需要重试，接口未成功阻塞该波次的后续作业流程
必须WMS成功再Vendor成功
接口系统要求
Avg RT Timeout 幂等字段 降级方案
1s 10s whs_id+sub_pickup_id + status 无
请求字段
字段名 类型 是否必须 最大长度 说明 示例 WES表字段
whs_id string 是 16 仓库id SGL shipment_header.warehouseCode
sub_pickup_id string 是 32 拣货任务id 202104220002_0 shipment_header.shopeeWave
station_type int 是 工作站类型
单据分播流程、分播出库流程
1：vendor pick to order
2：vendor batch picking		 1 按照工作站选的类型取值
pick_type int 是 1: pick to order(wave_type=0)对应vendor pick to order
2: pick to wave(wave_type=1\2\3\4\5) 对应vendor dynamic wave
3: flow pick(wave_type=1/5)		 1 如果工作站类型选的1：vendor pick to order则传1
如果waveType=1或5则传3
否则传2
wave_type int 是 1: SingleSkuSingleQtyWave
2: SameSkuSameQtyWave3: MixWave 4: SingleSkuAndAnyQtyWave
5: MixSkuSingleQtyWave		 waveType
operator string 是 64 operator邮箱
有场景没有（自动开班）		 xxx@shopee.com 取工作站登录用户表的邮箱
响应字段
字段名 类型 是否必须 最大长度 说明 示例
无
返回码
返回码 描述 说明 是否需要自动重试
-10002000 参数拷贝失败 内部参数拷贝失败 是
-10002001 参数错误 参数错误 是
-10002004 拣货任务不存在 ���务不存在 是
-10002006 拣货任务来源不正确 任务来源不正确 是
-10002005 拣货任务状态不正确 任务状态不正确 是
-10002014 其他业务类错误 其他业务类错误 是
3.1.6 Vendor实绑拣货任务

0121上午对齐：流程变成了两步（后绑device流程）

接口URL 接口描述 调用方 业务要求
/api/v2/automation/toshopee/outbound/salesorder/bind_picking_task Vendor开始拣货任务 vendor 作业接口，拣货员同步调用
必须WMS成功再Vendor成功
销售出库自动化SubPickingTask和自动化order共用
同步调用，需要重试，接口未成功阻塞该波次的后续作业流程
接口系统要求
Avg RT Timeout 幂等字段 降级方案
1s 10s whs_id+sub_pickup_id+device_id 无
请求字段
字段名 类型 是否必须 最大长度 说明 示例 WES表字段
whs_id string 是 16 仓库id SGL shipment_header.warehouseCode
sub_pickup_id string 是 32 拣货任务id 202104220002_0 shipment_header.shopeeWave
device_id string 是 32 拣货设备id OPBSK11873 wcs_sorting_wall_cell.containerCode
分拣墙格口绑定的目标容器号
station_type int 是 工作站类型
单据分播流程、分播出库流程
1：vendor pick to order
2：vendor batch picking		 1 按照工作站选的类型取值
grid_no string 是 格口号 Hik-A-1-1,
唯一码		 wcs_sorting_wall_cell.cellCode
分拣墙格口号
operator string 是 64 operator邮箱 xxx@shopee.com 取工作站登录用户表的邮箱
响应字段
字段名 类型 是否必须 最大长度 说明 示例
无
返回码
返回码 描述 说明 是否需要用户重试
-10002000 参数拷贝失败 内部参数拷贝失败 是
-10002001 参数错误 参数错误 是
-10002004 拣货任务不存在 任务不存在 是
-10002006 拣货任务来源不正确 任务来源不正确 是
-10002005 拣货任务状态不正确 任务状态不正确 是
-10002011 device 不合法 device不存在或者不能使用 是，由用户发起重试
-10002014 其他业务类错误 其他业务类错误 是
3.1.7 Vendor增量拣货明细
接口URL 接口描述 调用方 业务要求
/api/v2/automation/toshopee/outbound/salesorder/sync_picking_detail Vendor增量拣货明细 vendor 每次同步一批任务的明细，增量同步
业务侧延时1分钟一次，聚合调用
销售出库自动化SubPickingTask和自动化order共用
异步调用，接口失败需要重试
接口系统要求
Avg RT Timeout 幂等字段 降级方案
1s 10s sub_pickup_id + id 无
请求字段
字段名 类型 是否必须 最大长度 说明 示例 WES表字段（涉及客户化）
whs_id string 是 16 仓库id SGL shipment_header.warehouseCode
sub_picking_task_list List 是 100 拣货任务列表
每次调用最外层的sub_pickup_id不允许重复		 [
]		 shipment_header.shopeeWave

SubPickingTaskInfo字段详情

字段名 类型 是否必须 最大长度 说明 示例 WES表字段
sub_pickup_id string 是 32 拣货任务id 202104220002_0 shipment_header.shopeeWave
picked_info_list List 是 拣货明细列表 详见下表

picked_info_list字段详情

字段名 类型 是否必须 最大长度 说明 示例 WES表字段
id string 是 64 vendor拣货id，待vendor提供
幂等用		 task_detail.taskCode
device_id string 是 16 拣货设备id OPBSK11873 wcs_sorting_wall_cell.containerCode
分拣墙格口绑定的目标容器号
sku_id string 是 32 sku_id 1767751294820_08379 task_detail.itemCode
code string 否 32 operator扫描的upc码，若是UID则体现在UID列表 177777 扫描的UPC需要记录在任务明细task_detail.barcode-新增字段，回传时取该字段
batch_no int64 是 批次号 2026010600001134 task_detail.batch
unit_list List 否 NA uid
qty int 是 数量, >0 1 task_detail.itemCode
ctime int 是 拣货时间戳 task_detail.confirmedAt
operator string 是 64 operator邮箱 xxx@shopee.com 取工作站登录用户表的邮箱

UnitItem

字段名 类型 是否必须 最大长度 说明 示例 WES表字段
unit_id string 是 32 unit_id编码 [“8u118”,”111] 序列号
根据拣货完成的明细lpn匹配序列号表lpn去查询序列号
scan_time int 是 20 扫描时间 序列号表最后更新时间serial_number.lastUpdated
响应字段
字段名 类型 是否必须 最大长度 说明 示例
success_list List 是 sub_pickup_id维度
failed_list List<string 是 sub_pickup_id维度
返回码
返回码 描述 说明 是否需要自动重试
-10002000 参数拷贝失败 内部参数拷贝失败 是
-10002001 参数错误 参数错误 是
-10002014 其他业务类错误 其他业务类错误 是
3.1.8 Vendor发起换箱（不产生新任务）（用户点换箱有2种场景，第1如果没调通接口比如返回网络连接失败等情况则不允许继续拣货到老料箱-界面锁住，第2如果调通了返回正常的失败码则允许继续往老料箱集波，第2调通了返回成功码则只能往新箱中拣货）
接口URL 接口描述 调用方 业务要求
/api/v2/automation/toshopee/outbound/salesorder/change_picking_device Vendor发起换箱 vendor 作业接口，拣货员同步调用
必须WMS成功再Vendor成功
Vendor可以使用dynamic方式跑自动化SubPickingTask，支持发起换箱
和校验device接口不同的是，这里WMS会有逻辑处理
换箱成功后，WMS的旧箱不可再新增拣货明细
同步调用，需要重试，接口未成功阻塞该波次的后续作业流程
接口系统要求
Avg RT Timeout 幂等字段 降级方案
1s 10s 无 无
请求字段
字段名 类型 是否必须 最大长度 说明 示例 WES表字段
whs_id string 是 16 仓库id SGL shipment_header.warehouseCode
sub_pickup_id string 是 32 拣货任务id 202104220002_0 shipment_header.shopeeWave
from_device_id string 是 老的设备id OPBSK11873 wcs_sorting_wall_cell.previousContainerCode-新增字段，拣货换箱时需将原箱号更新到该字段
to_device_id string 是 新的设备id OPBSK11874 wcs_sorting_wall_cell.containerCode
分拣墙格口绑定的目标容器号-换箱后的
station_type int 是 工作站类型
单据分播流程、分播出库流程
1：vendor pick to order
2：vendor batch picking		 1 按照工作站选的类型取值
operator string 是 64 operator邮箱 xxx@shopee.com 取工作站登录用户表的邮箱
picked_info_list List 是 旧箱拣货明细列表
注意：如果有多次换箱，那么这个列表是所有旧箱的拣货明细数据
(增量拣货明细有可能会丢请求)		 详见下表 task_detail.targetContainer-新增字段，拣货实际拣到槽口绑定的料箱时需要将目标料箱号更新到任务明细targetContainer字段

picked_info_list字段详情

字段名 类型 是否必须 最大长度 说明 示例 WES表字段
id string 是 64 vendor拣货id，待vendor提供
增量拣货明细有可能会丢请求，幂等用		 task_detail.taskCode
device_id string 是 16 拣货设备id OPBSK11873 task_detail.targetContainer
sku_id string 是 32 sku_id 1767751294820_08379 task_detail.itemCode
code string 否 32 operator扫描的upc码，若是UID则体现在UID列表 177777 扫描的UPC需要记录在任务明细task_detail.barcode-新增字段，回传时取该字段
batch_no int64 是 批次号 2026010600001134 task_detail.batch
unit_list List 否 NA uid
qty int 是 数量>0 1 task_detail.totalQty
ctime int 是 拣货时间戳 task_detail.confirmedAt
operator string 是 64 operator邮箱 xxx@shopee.com task_detail.confirmedBy的邮箱

UnitItem

字段名 类型 是否必须 最大长度 说明 示例 WES表字段
unit_id string 是 32 unit_id编码 [“8u118”,”111] 序列号
根据拣货完成的明细lpn匹配序列号表lpn去查询序列号
scan_time int 是 20 扫描时间 序列号表最后更新时间serial_number.lastUpdated
响应字段
字段名 类型 是否必须 最大长度 说明 示例
无
返回码
返回码 描述 说明 是否需要用户重试
-10002000 参数拷贝失败 内部参数拷贝失败 是
-10002001 参数错误 参数错误 是
-10002004 拣货任务不存在 任务不存在 是
-10002006 拣货任务来源不正确 任务来源不正确 是
-10002005 拣货任务状态不正确 任务状态不正确 是
-10002013 拣货明细校验错误 拣货明细校验错误 是
-10002011 device 不合法 device不存在或者不能使用 是，由用户发起重试
-10002014 其他业务类错误 其他业务类错误 是
3.1.9 Vendor完成拣货任务

可以缺量完成拣货任务【0拣vendor会释放device】

接口URL 接口描述 调用方 业务要求
/api/v2/automation/toshopee/outbound/salesorder/complete_picking_task Vendor完成拣货任务 vendor 接口失败了需要弹窗提示失败原因
要求失败重试，重试时需保证每次重试的报文一致
每次增量明细库存应该是完成时明细库存的子集，即批次维度库存>=sum(增量明细库存)，如果出现异常判断为Vendor有bug需要排查修复
注意vn模式集货任务需要扫MergeLane，业务侧SOP保证对接vendor的任务不会出现。
异步调用，接口失败需要重试
接口系统要求
Avg RT Timeout 幂等字段 降级方案
1s 10s 无 无
请求字段
字段名 类型 是否必须 最大长度 说明 示例 WES表字段
whs_id string 是 16 仓库id SGL shipment_header.warehouseCode
sub_pickup_id string 是 32 拣货任务id 202104220002_0 shipment_header.shopeeWave
operator string 是 64 operator邮箱 xxx@shopee.com 取工作站登录用户表的邮箱
picked_info_list List 是 拣货明细列表
注意：这个列表是本波次所有的拣货明细数据
(增量拣货明细有可能会丢请求)		 详见下表

picked_info_list字段详情

字段名 类型 是否必须 最大长度 说明 示例 WES表字段
id string 是 64 vendor拣货id，待vendor提供
增量拣货明细有可能会丢请求，幂等用		 task_detail.taskCode
device_id string 是 16 拣货设备id OPBSK11873 task_detail.targetContainer
sku_id string 是 32 sku_id 1767751294820_08379 task_detail.itemCode
code string 否 32 operator扫描的upc码，若是UID则体现在UID列表 177777 扫描的UPC需要记录在任务明细task_detail.barcode-新增字段，回传时取该字段
batch_no int64 是 批次号 2026010600001134 task_detail.batch
unit_list List 否 NA uid
qty int 是 数量>0 1 task_detail.totalQty
ctime int 是 拣货时间戳 task_detail.confirmedAt
operator string 是 64 operator邮箱 xxx@shopee.com task_detail.confirmedBy的邮箱

UnitItem

字段名 类型 是否必须 最大长度 说明 示例 WES表字段
unit_id string 是 32 unit_id编码 [“8u118”,”111] 序列号
根据拣货完成的明细lpn匹配序列号表lpn去查询序列号
scan_time int 是 20 扫描时间 序列号表最后更新时间serial_number.lastUpdated
响应字段
字段名 类型 是否必须 最大长度 说明 示例
无
返回码
返回码 描述 说明 是否需要自动重试
-10002000 参数拷贝失败 内部参数拷贝失败 是
-10002001 参数错误 参数错误 是
-10002004 拣货任务不存在 任务不存在 是
-10002013 拣货明细校验错误 拣货明细校验错误 是
-10002006 拣货任务来源不正确 任务来源不正确 是
-10002014 其他业务类错误 其他业务类错误 是
3.1.10 Vendor请求流程指引
接口URL 接口描述 调用方 业务要求
/api/v2/automation/toshopee/outbound/salesorder/search_picking_process_guide Vendor请求流程指引 vendor 此接口不一定是在任务结束的时候拉取，可以作业过程中提前异步拉取，需确保WMS任务创建/开始后再来调用，需要Vendor考虑是否缓存
接口系统要求
Avg RT Timeout 幂等字段 降级方案
300ms 10s 无 无
请求字段
字段名 类型 是否必须 最大长度 说明 示例 WES表字段
whs_id string 是 16 仓库id SGL shipment_header.warehouseCode
sub_pickup_id string 是 32 拣货任务id 202104220002_0 shipment_header.shopeeWave
响应字段
字段名 类型 是否必须 最大长度 说明 示例
custom_message string 是 512 若返回的是空字符串需要使用vendor默认提示语 请将容器放置复核区
返回码
返回码 描述 说明 是否需要自动重试
-10002000 参数拷贝失败 内部参数拷贝失败 是
-10002001 参数错误 参数错误 是
3.1.11 查询Vendor拣货任务列表【出库所有订单类型通用对账查询vendor接口】
接口URL 接口描述 调用方 业务要求
/api/v2/automation/tovendor/outbound/salesorder/query_picking_detail 查询Vendor拣货任务列表 shopee 批量查询接口，支持查询vendor创建的任务和shopee创建的任务
接口系统要求
Avg RT Timeout 幂等字段 降级方案
300ms 10s 无 无
请求字段
字段名 类型 是否必须 最大长度 说明 示例 WES表字段
whs_id string 是 16 仓库id SGL shipment_header.warehouseCode
task_id_list List 是 32 任务id ["202104220002_0"] shipment_header.erpOrderCode
task_type int 是 1:销售出库、2:RTS、3:MTO shipment_header.shipmentType
响应字段
字段名 类型 是否必须 最大长度 说明 示例
task_info_list List 是 任务列表 详见下表

TaskInfo（整波没完成3个list不需要传值）

字段名 类型 是否必须 最大长度 说明 示例 WES表字段
task_id string 是 任务id shipment_header.erpOrderCode
status int 是 是否终态任务状态
0: pending
1: done		 shipment_header.trailingSts尾状态小于400则传0，否则传1
vendor_status int 是 vendor状态，vendor提供给WMS shipment_header.leadingSts
picked_info_list List 是 拣货明细列表（若该任务换箱产生新任务，则不含换到新箱的订单/需求）
注意：根据任务类型判断，
若是销售出库下发的sub_picking_task，赋值与3.1.9保持一致
若是销售出库下发的order，赋值与3.2.10保持一致（但明细字段名为sheet_number）
若是需求池模式，赋值与3.3.10一致（但明细字段名为sheet_number）
若是mto下发picking_task，赋值与3.4.8一致		 详见下表
shortage_info_list List 是 缺拣明细列表（若该任务换箱产生新任务，则不含换到新箱的订单/需求）
注意：根据任务类型判断，
若是销售出库下发的sub_picking_task，赋值与3.1.9保持一致
若是销售出库下发的order，赋值与3.2.10保持一致（但明细字段名为sheet_number）
若是需求池模式，赋值与3.3.10一致（但明细字段名为sheet_number）
若是mto下发picking_task，赋值与3.4.8一致		 详见下表
zero_info_list List 是 0拣订单/需求列表（若该任务换箱产生新任务，则不含换到新箱的订单/需求）
注意：根据任务类型判断，
若是销售出库下发的sub_picking_task，赋值与3.1.9保持一致
若是销售出库下发的order，赋值与3.2.10保持一致（但明细字段名为sheet_number）
若是需求池模式，赋值与3.3.10一致（但明细字段名为sheet_number）
若是mto下发picking_task，赋值与3.4.8一致		 ["OBCNG000260101081110","OBCNG000260101081112"]

picked_info_list字段详情

字段名 类型 是否必须 最大长度 说明 示例 WES表字段
id string 是 64 vendor拣货id，待vendor提供
增量拣货明细有可能会丢请求，幂等用		 task_detail.taskCode
device_id string 是 16 拣货设备id OPBSK11873 task_detail.targetContainer
sku_id string 是 32 sku_id 1767751294820_08379 task_detail.itemCode
code string 否 32 operator扫描的upc码，若是UID则体现在UID列表 177777 扫描的UPC需要记录在任务明细task_detail.barcode-新增字段，回传时取该字段
batch_no int64 是 批次号 2026010600001134 task_detail.batch
unit_list List 否 NA uid
qty int 是 数量 1 task_detail.totalQty
ctime int 是 拣货时间戳 task_detail.confirmedAt
operator string 是 64 operator邮箱 xxx@shopee.com task_detail.confirmedBy的邮箱
sheet_number string 是 64 vendor创建的任务会有该字段，订单号，RTS需求号，MTO需求号 OBCNG000260101081110
RORWMSSGD00026010600003		 shipment_header.erpOrderCode

UnitItem

字段名 类型 是否必须 最大长度 说明 示例 WES表字段
unit_id string 是 32 unit_id编码 [“8u118”,”111] 序列号
根据拣货完成的明细lpn匹配序列号表lpn去查询序列号
scan_time int 是 20 扫描时间 序列号表最后更新时间serial_number.lastUpdated
返回码
返回码 描述 说明 是否需要自动重试
-10012001 参数非法 比如参数是否必填、类型不符、长度不正确、非法字符、主键重复等 否
-10012099 系统错误 如限流、数据库错误、内部错误等等 是

3.2 销售出库自动化Order

3.2.1 WMS给Vendor下单

【拓展性字段】

展示和filter类 - 需要支持拓展

订单优先级等，影响订单出库时效的 - 可以不支持拓展

跑波分组类，影响跑波策略的 - 可以不支持拓展

接口URL 接口描述 调用方 业务要求
/api/v2/automation/tovendor/outbound/salesorder/create_order WMS给Vendor订单 shopee 占用库存要求：批次属性必须是：好品+normal
下单失败wms侧需要擦除预命中结果
30分钟未占用库存调用取消接口
接口系统要求
Avg RT Timeout 幂等字段 降级方案
200ms 10s order_number + status
有可能重复下单，进行中的订单只有一个		 无
请求字段
字段名 类型 是否必须 最大长度 说明 示例 WES表字段
whs_id string 是 16 仓库id SGL shipment_header.warehouseCode
order_number string 是 32 订单号，幂等 OBCNG000260101081110 shipment_header.erpOrderCode
can_group_picking int 是 1: 可混拣 1 shipment_header. canGroupPicking
新增字段，是否混拣
group_key string 是 128 特征值，若可混拣，则有值 xxx_xx_xx_xx，
相同group_key可以混拣		 shipment_header.groupKey
新增字段，混拣特征值
urgent_flag int 是 0~99 越大越紧急 99 shipment_header.priority
cut_off_time int 是 任务截止时间，秒级时间戳，越小越优先出库 1767837541 shipment_header.cutOffTime-新增字段
截止时间
ctime int 是 创建时间，WMS创建的时间戳 1767751167 shipment_header.ctime-新增字段，shopee wms创建时间
ship_by_date int 是 截运时间 1767751167 shipment_header.scheduledShipDate
purchase_time int 是 购买时间 1767751167 shipment_header.purchaseTime-新增字段，购买时间
single_attr_list List 是 属性列表（单属性）
当前有：service_code、channel_id、fulfillment_chain_id、order_structure、order_size、shop_group、store_id、parcel_id、lm_tracking_no、pickup_region、delivery_region、sls_tracking_no、actual_weight(单位：g)、lane_code、handover、zone_code_id、outer_packaging		 插入数据字典逻辑与3.1.1同理
service_code接到shipment_header.serviceCode-新增字段
fulfillment_chain_id接到shipment_header.orderStructure-新增字段
order_size 接到shipment_header.orderSize-新增字段
shop_group接到shipment_header.shopGroup-新增字段
store_id接到
shipment_header.storeId-新增字段
delivery_region接到shipment_header.deliveryRegion-新增字段
lane_code接到shipment_header.laneCode-新增字段
outer_packaging接到shipment_header.outerPackaging-新增字段
multi_attr_list List 是 属性列表（多属性）
shop_id、shopee_order_sn、inner_packaging		 插入数据字典逻辑与3.1.1同理
shop_id接到shipment_header.shopId-新增字段
sku_info_list List 是 Sku信息 明细取值见下文
ticket_type int 是 单据类型：
单据类型：
1: 销售出库下发task 2:销售出库下发order 3:rts需求池需求 4: mto需求池需求 5: mto下发任务 6: RT		 2 shipment_header.ticketType-新增字段
shipment_header.shipmentType默认：XSCK

SkuInfo字段详情

字段名 类型 是否必须 最大长度 说明 示例 WES表字段
sku_id string 是 64 sku_id 1767751294820_08379 shipment_detail.itemCode
qty int 是 期望拣货数量 10 shipment_detail.requestQty
block_type int 是 销售出库传的是0 normal
指定冻结类型（Normal/临期/过期）
SKUBlockTypeNoNeed SKUBlockType = 0
SKUBlockTypeEXPIRING SKUBlockType = 1
SKUBlockTypeEXPIRED SKUBlockType = 3		 0 shipment_detail.shelfLifeSts
效期状态
quality int 是 0 好品
指定好/坏品
SkuQualityTypeGood SkuQualityType = 0
SkuQualityTypeDamage SkuQualityType = 1		 0 shipment_detail.inventorySts
库存状态
响应字段
字段名 类型 是否必须 最大长度 说明 示例
无
返回码
返回码 描述 说明 是否需要自动重试
-10012001 参数非法 比如参数是否必填、类型不符、长度不正确、非法字符、主键重复等 否
-10012010 单据类型未配置 单据类型未配置 否
-10012023 SKU不存在 SKU不存在 否
-10012049 仓库不存在 未配置仓库 否
-10012098 其他非法操作 上述未枚举时兜底使用 否
-10012099 系统错误 如限流、数据库错误、内部错误等等 是
3.2.2 WMS向Vendor捞单
接口URL 接口描述 调用方 业务要求
/api/v2/automation/tovendor/outbound/salesorder/cancel_order WMS向Vendor撤回订单 shopee 捞成功才可在wms侧进行拣货操作
接口系统要求
Avg RT Timeout 幂等字段 降级方案
300ms 10s order_number 无
请求字段
字段名 类型 是否必须 最大长度 说明 示例 WES表字段（取消WES走base标记cancel，标记的单子集波不抓）
whs_id string 是 16 仓库id SGL shipment_header.warehouseCode
order_number_list List 是 200 订单号列表 [“OBCNG000260101081110”,”OBCNG000260101081112”] shipment_header.erpOrderCode
响应字段
字段名 类型 是否必须 最大长度 说明 示例
success_list List 是 200 取消成功列表
fail_list List 是 200 取消失败列表
not_exist_list List 是 200 订单不存在列表
返回码
返回码 描述 说明 是否需要自动重试
-10012001 参数非法 比如参数是否必填、类型不符、长度不正确、非法字符、主键重复等 否
-10012098 其他非法操作 上述未枚举时兜底使用 否
-10012099 系统错误 如限流、数据库错误、内部错误等等 是
3.2.3 Vendor向WMS撤单

错误码及幂等计算

接口URL 接口描述 调用方 业务要求
/api/v2/automation/toshopee/outbound/salesorder/cancel_order Vendor向WMS撤回订单 Vendor 捞成功才可在wms侧进行拣货操作
如果是wms侧取消订单场景
vendor侧返回成功走现有正常订单取消流程 vendor侧返回失败走现有正常订单取消流程(所有订单取消场景不能取消picking task)
必须WMS成功再Vendor成功
同步调用，接口失败需要重试
接口系统要求
Avg RT Timeout 幂等字段 降级方案
300ms 10s 无
请求字段
字段名 类型 是否必须 最大长度 说明 示例 WES表字段
whs_id string 是 16 仓库id SGL shipment_header.warehouseCode
order_number_list List 是 200 订单号列表 [“OBCNG000260101081110”,”OBCNG000260101081112”] shipment_header.erpOrderCode
reason string 是 可能的取消原因（需要传英文）：
缺货取消
创建任务被踢出导致的取消
其他.....		 跑波次缺货取消的传1
拿波次号和订单请求上游集波验证失败踢单的也需要请求该接口传2
除以上两种情况外是3（是备用无逻辑走3）
响应字段
字段名 类型 是否必须 最大长度 说明 示例
success_list List 是 200 取消成功列表
fail_list List 是 200 取消失败列表
not_exist_list List 是 200 订单不存在列表
返回码
返回码 描述 说明 是否需要自动重试
-10002000 参数拷贝失败 内部参数拷贝失败 是
-10002001 参数错误 参数错误 是
-10002014 其他业务类错误 其他业务类错误 是
3.2.4 Wms向Vendor下发锁单/解锁请求
接口URL 接口描述 调用方 业务要求
/api/v2/automation/tovendor/outbound/salesorder/lock_unlock_order 锁单/解锁 Shopee 以vendor结果为准
接口系统要求
Avg RT Timeout 幂等字段 降级方案
300ms 10s order_number_list 无
请求字段
字段名 类型 是否必须 最大长度 说明 示例 WES表字段
whs_id string 是 16 仓库id SGL shipment_header.warehouseCode
order_number_list List 是 200一批 订单列表 [“OBCNG000260101081110”,”OBCNG000260101081112”] shipment_header.erpOrderCode
request_type int 是 1:上锁/0:解锁 1，
不允许取消则不允许上锁		 传1则WES走base标记挂起，标记的单子集波不抓
传0则将挂起标记的恢复正常
响应字段
字段名 类型 是否必须 最大长度 说明 示例
success_list List 是 200
fail_list List 是 200
not_exist_list List 是 200 订单不存在列表
返回码
返回码 描述 说明 是否需要自动重试
-10012001 参数非法 比如参数是否必填、类型不符、长度不正确、非法字符、主键重复等 否
-10012052 单据已拣货，不能锁单 失败的单号单独返回，该逻辑走不到 否
-10012098 其他非法操作 上述未枚举时兜底使用 否
-10012099 系统错误 如限流、数据库错误、内部错误等等 是
3.2.5 vendor向wms获取号段缓存（该接口需要定时任务触发抓取，判断如果shopee_wave.waveType类型的未用的波次总数低于系统参数wave_number_threshold设置的数量则调用该接口请求上游再获取一批号段）
接口URL 接口描述 调用方 业务要求
/api/v2/automation/toshopee/outbound/salesorder/cache_task_number 号段缓存 Vendor 建议当天使用当天的号段
失败重试
接口系统要求
Avg RT Timeout 幂等字段 降级方案
200ms 10s - 无
请求字段
字段名 类型 是否必须 最大长度 说明 示例 WES表字段
whs_id string 是 16 仓库id SGL shopee_wave.warehouseCode
count int 是 数量，最大100 100 100
biz_type int 是 1 - 销售出库2 - RTS3 - MTO 1 3种类型每天取100个，当天集波用当天的波次
响应字段
字段名 类型 是否必须 最大长度 说明 示例
task_id_list List 是 号段列表 [“202104220002_0”,”202104220003_0”]
获取waveid，每天都获取一次，不能用前一天的号段
返回码
返回码 描述 说明 是否需要自动重试
-10002000 参数拷贝失败 内部参数拷贝失败 是
-10002001 参数错误 参数错误 是
-10002014 其他业务类错误 其他业务类错误 是
3.2.6 Vendor绑定解绑设备【复用basic接口】废弃
3.2.7Vendor向WMS创建picking task（创建时如果wms返回失败的列表需要重新拿成功的列表再次请求上游直到返回全部成功为止）
接口URL 接口描述 调用方 业务要求
/api/v2/automation/toshopee/outbound/salesorder/create_picking_task 创建task Vendor 涉及wms库存分配, 组装task属性, 订单状态变更等场景 失败需要支持重试, 增加告警
必须WMS成功再Vendor成功
同步调用，需要重试，接口未成功阻塞该波次的后续作业流程
接口系统要求
Avg RT Timeout 幂等字段 降级方案
1s 10s sub_pickup_id 无
请求字段
字段名 类型 是否必须 最大长度 说明 示例 WES表字段
whs_id string 是 16 仓库id SGL shipment_header.warehouseCode
sub_pickup_id string 是 32 拣货任务id 202104220002_0 根据订单类型取得shopee_wave中的状态为100的波次号，取完就要更新状态为使用中，注意并发
station_type int 是 工作站类型
单据分播流程、分播出库流程
1：vendor pick to order
2：vendor batch picking		 1 按照工作站选的类型取值
pick_type int 是 1: pick to order(wave_type=0)对应vendor pick to order
2: pick to wave(wave_type=1\2\3\4\5) 对应vendor dynamic wave
3: flow pick(wave_type=1/5)		 1 如果工作站类型选的1：vendor pick to order则传1
如果waveType=1或5则传3
否则传2
wave_type int 是 1: SingleSkuSingleQtyWave
2: SameSkuSameQtyWave3: MixWave 4: SingleSkuAndAnyQtyWave
5: MixSkuSingleQtyWave		 waveType
order_number_list List 是 订单号列表 [“OBCNG000260101081110”,”OBCNG000260101081112”] shipment_header.erpOrderCode
operator string 是 64 operator邮箱 xxx@shopee.com 取工作站登录用户表的邮箱
响应字段
字段名 类型 是否必须 最大长度 说明 示例
task_attr_info TaskAttrInfo 是 task属性 wms返回 vendor需要更新
fail_order_list List 是 返回码为失败的情况下可能会有该字段（参考错误码），表示WMS的这些订单不支持进入波次，vendor需要把这些订单从波次中移除并触发捞单。

TaskAttrInfo字段详情

字段名 类型 是否必须 最大长度 说明 示例 WES字段
sub_pickup_id string 是 任务id shipment_header.shopeeWave
urgent_flag int 是 0~99 越大越紧急 1 shipment_header.priority
cut_off_time int 是 任务截止时间，秒级时间戳，越小越优先出库 1767837541 shipment_header.cutOffTime-新增字段，截止时间
ctime int 是 创建时间，WMS创建的时间戳，秒级 1767751167 shipment_header.ctime-新增字段，shopee wms创建时间
single_attr_list List 是 属性列表（单属性）
同3.1.1的属性说明
multi_attr_list List 是 属性列表（多属性）
同3.1.1的属性说明
返回码
返回码 描述 说明 是否需要自动重试
-10002000 参数拷贝失败 内部参数拷贝失败 是
-10002001 参数错误 参数错误 是
-10002009 波次ID已被使用 波次ID已被使用 是，换一个波次ID进行重试
-10002002 订单不支持进入波次 订单不支持进入波次
订单进入了其他波次
订单占用库存失败		 否，踢单，捞单
-10002003 创建波次失败 创建波次失败 是
-10002014 其他业务类错误 其他业务类错误 是
3.2.8 Vendor向WMS追加明细
接口URL 接口描述 调用方 业务要求
/api/v2/automation/toshopee/outbound/salesorder/append_order 追加 Vendor 只做追加动作
只要创建任务成功了，随时有可能调用追加接口
逻辑说明
如果创建订单1，2成功，追加时追加订单1，2不会报错 => 相当于没有追加任何订单
如果创建订单1，2成功，追加时追加订单1，2，3可以成功 => 表现为追加了一个单
如果创建订单1，2失败，追加时追加订单1，2会报错 => 因为都没有任务
同步调用，需要重试，接口未成功阻塞该波次的后续作业流程
接口系统要求
Avg RT Timeout 幂等字段 降级方案
500ms 10s sub_pickup_id+orderlist 无
请求字段
字段名 类型 是否必须 最大长度 说明 示例 WES表字段
whs_id string 是 16 仓库id SGL shipment_header.warehouseCode
sub_pickup_id string 是 32 拣货任务id 202104220002_0 追加到shopee的波次号
new_order_number_list List 是 追加的订单列表 [“OBCNG000260101081110”,”OBCNG000260101081112”] shipment_header.erpOrderCode
响应字段
字段名 类型 是否必须 最大长度 说明 示例
task_attr_info TaskAttrInfo 是 task属性 wms返回 vendor需要更新
fail_order_list List 是 返回码为失败的情况下会有该字段，表示WMS的这些订单不支持进入波次，vendor需要把这些订单从波次中移除并触发捞单。

TaskAttrInfo字段详情

字段名 类型 是否必须 最大长度 说明 示例 WES表字段
sub_pickup_id string 是 任务id shipment_header.shopeeWave
urgent_flag int 是 0~99 越大越紧急 1 shipment_header.priority
cut_off_time int 是 任务截止时间，秒级时间戳，越小越优先出库 1767837541 shipment_header.cutOffTime-新增字段，截止时间
ctime int 是 创建时间，WMS创建的时间戳，秒级 1767751167 shipment_header.ctime-新增字段，shopee wms创建时间
single_attr_list List 是 属性列表（单属性）
同3.1.1的属性说明
multi_attr_list List 是 属性列表（多属性）
同3.1.1的属性说明
返回码
返回码 描述 说明 是否需要自动重试
-10002000 参数拷贝失败 内部参数拷贝失败 是
-10002001 参数错误 参数错误 是
-10002005 波次状态不对 波次状态不对 否，退出这个波次的追加流程
-10002009 波次ID已被使用 波次ID已被使用 是，换一个波次ID进行重试
-10002002 订单不支持进入波次 订单不支持进入波次
订单进入了其他波次
订单占用库存失败		 否，踢单，捞单
-10002003 创建波次失败 创建波次失败 是
-10002014 其他业务类错误 其他业务类错误 是
3.2.9 flow pick换箱
接口URL 接口描述 调用方 业务要求
/api/v2/automation/toshopee/outbound/salesorder/change_device 完成 Vendor 这种换箱是生成新的picking task
作业接口，必须WMS成功再Vendor成功
同步调用，需要重试，接口未成功阻塞该波次的后续作业流程
接口系统要求
Avg RT Timeout 幂等字段 降级方案
1s 10s sub_pickup_id 无
请求字段
字段名 类型 是否必须 最大长度 说明 示例 WES表字段
whs_id string 是 16 仓库id SGL shipment_header.warehouseCode
sub_pickup_id string 是 32 拣货任务id 202104220002_0 原shopee波次号
from_device_id string 是 32 原拣货设备id OPBSK11873 wcs_sorting_wall_cell.previousContainerCode-新增字段，拣货换箱时需将原箱号更新到该字段
to_device_id string 是 32 新拣货设备id OPBSK11874 wcs_sorting_wall_cell.containerCode分拣墙格口绑定的目标容器号-换箱后的
new_pickup_id string 是 32 新拣货任务id 202104220003_0 取新的shopee波次号段
picked_order_number_list List 是 满拣订单sku列表 整单全拣货的单据
明细见下文
zero_order_info_list List 是 0拣订单列表；
注意0拣时，订单在vendor终态了		 [“OBCNG000260101081110”,”OBCNG000260101081112”] 整单未拣货的单据
明细见下文
new_order_number_list List 是 新task订单列表
长度必须>0		 [“OBCNG000260101081113”,”OBCNG000260101081114”] 未拣货的订单
即组到新波次的订单
operator string 是 64 operator邮箱 xxx@shopee.com 取工作站登录用户表的邮箱

PickedOrderInfo字段详情

字段名 类型 是否必须 最大长度 说明 示例 WES表字段
id string 是 64 vendor拣货id，待vendor提供
增量拣货明细有可能会丢请求，幂等用		 task_detail.taskCode
order_number string 是 32 订单号 OBCNG000260101081110 shipment_header.erpOrderCode
device_id string 是 32 设备id OPBSK11873 task_detail.targetContainer
sku_id string 是 32 sku_id 1767751294820_08379 task_detail.itemCode
code string 否 32 operator扫描的upc码，若是UID则体现在UID列表 177777 扫描的UPC需要记录在任务明细task_detail.barcode-新增字段，回传时取该字段
batch_no int64 是 批次号 2026010600001134 task_detail.batch
unit_list List 是 Unit id列表
qty int 是 数量 >0 1 task_detail.totalQty
operator string 是 64 operator邮箱 xxx@shopee.com task_detail.confirmedBy的邮箱
ctime int 是 拣货时间戳 task_detail.confirmedAt
响应字段
字段名 类型 是否必须 最大长度 说明 示例
task_attr_info_list List 是 新老task属性 wms返回 vendor需要更新

TaskAttrInfo字段详情

字段名 类型 是否必须 最大长度 说明 示例 WES表字段
sub_pickup_id string 是 任务id shipment_header.shopeeWave
urgent_flag int 是 0~99 越大越紧急 1 shipment_header.priority
cut_off_time int 是 任务截止时间，秒级时间戳，越小越优先出库 1767837541 shipment_header.cutOffTime-新增字段,截止时间
ctime int 是 创建时间，WMS创建的时间戳，秒级 1767751167 shipment_header.ctime-新增字段，shopee wms创建时间
single_attr_list List 是 属性列表（单属性）
同3.1.1的属性说明
multi_attr_list List 是 属性列表（多属性）
同3.1.1的属性说明
返回码
返回码 描述 说明 是否需要用户重试
-10002000 参数拷贝失败 内部参数拷贝失败 是
-10002001 参数错误 参数错误 是
-10002005 波次状态不对 波次状态不对 否，退出这个波次的追加流程
-10002013 拣货明细校验错误 拣货明细校验错误 是
-10002010 订单列表交集错误 订单列表交集错误 是
-10002009 波次ID已被使用 波次ID已被使用 是，换一个波次ID进行重试
-10002003 创建波次失败 创建波次失败 是
-10002014 其他业务类错误 其他业务类错误 是
3.2.10 Vendor完成task

【确认一下vendor 0拣、新箱0拣如何处理device的】： vendor释放掉

波次对应订单全部取消，vendor关闭波次，确认一下是否释放device

接口URL 接口描述 调用方 业务要求
/api/v2/automation/toshopee/outbound/salesorder/vendor_complete_task 完成 Vendor 零拣的单Vendor需要取消掉，WMS回滚至created
异步调用，接口失败需要重试
接口系统要求
Avg RT Timeout 幂等字段 降级方案
1s 10s sub_pickup_id 无
请求字段
字段名 类型 是否必须 最大长度 说明 示例 WES表字段
whs_id string 是 16 仓库id SGL shipment_header.warehouseCode
sub_pickup_id string 是 32 拣货任务id 202104220002_0 shipment_header.shopeeWave
picked_order_number_list List 是 满拣订单sku列表 整单全拣货的单据
明细见下文
shortage_order_info_list List 是 缺拣订单sku列表 整单部分拣货的单据
明细见下文
zero_order_info_list List 是 0拣订单列表；
注意0拣时，订单在vendor终态了		 [“OBCNG000260101081110”,”OBCNG000260101081112”] 整单未拣货的订单
operator string 是 operator邮箱 xxx@shopee.com 取工作站登录用户表的邮箱

PickedOrderInfo字段详情

字段名 类型 是否必须 最大长度 说明 示例 WES表字段
id string 是 64 vendor拣货id，待vendor提供
增量拣货明细有可能会丢请求，幂等用		 task_detail.taskCode
order_number string 是 订单号 shipment_header.erpOrderCode
device_id string 是 16 拣货设备id OPBSK11873 task_detail.targetContainer
sku_id string 是 32 sku_id 1767751294820_08379 task_detail.itemCode
code string 否 32 operator扫描的upc码，若是UID则体现在UID列表 177777 扫描的UPC需要记录在任务明细task_detail.barcode-新增字段，回传时取该字段
batch_no int64 是 批次号 2026010600001134 task_detail.batch
unit_list List 否 NA uid
qty int 是 数量>0 1 task_detail.totalQty
ctime int 是 拣货时间戳 task_detail.confirmedAt
operator string 是 64 operator邮箱 xxx@shopee.com task_detail.confirmedBy的邮箱

UnitItem

字段名 类型 是否必须 最大长度 说明 示例 WES表字段
unit_id string 是 32 unit_id编码 [“8u118”,”111] 序列号
根据拣货完成的明细lpn匹配序列号表lpn去查询序列号
scan_time int 是 20 扫描时间 序列号表最后更新时间serial_number.lastUpdated
响应字段
字段名 类型 是否必须 最大长度 说明 示例
task_attr_info TaskAttrInfo 是 task属性 wms返回 vendor需要更新

TaskAttrInfo字段详情-不处理

字段名 类型 是否必须 最大长度 说明 示例
sub_pickup_id string 是 任务id
urgent_flag int 是 0~99 越大越紧急 1
cut_off_time int 是 任务截止时间，秒级时间戳，越小越优先出库 1767837541
ctime int 是 创建时间，WMS创建的时间戳，秒级 1767751167
single_attr_list List 是 属性列表（单属性）
同3.1.1的属性说明
multi_attr_list List 是 属性列表（多属性）
同3.1.1的属性说明
返回码
返回码 描述 说明 是否需要自动重试
-10002000 参数拷贝失败 内部参数拷贝失败 是
-10002001 参数错误 参数错误 是
-10002004 拣货任务不存在 任务不存在 是
-10002013 拣货明细校验错误 拣货明细校验错误 是
-10002006 拣货任务来源不正确 任务来源不正确 是
-10002008 订单列表交集错误 订单列表交集错误，有重复订单 是
-10002014 其他业务类错误 其他业务类错误 是
3.2.11 Wms向Vendor查询冻结状态订单列表(对账)
接口URL 接口描述 调用方 业务要求
/api/v2/automation/tovendor/outbound/salesorder/search_lock_order_list 查询锁单列表 Shopee
接口系统要求
Avg RT Timeout 幂等字段 降级方案
300ms 10s order_number_list 无
请求字段
字段名 类型 是否必须 最大长度 说明 示例 WES表字段
whs_id string 是 16 仓库id SGL shipment_header.warehouseCode
响应字段
字段名 类型 是否必须 最大长度 说明 示例 WES表字段（返回上锁订单待定即标记为挂起的订单）
order_number_list List 是 shipment_header.erpOrderCode
返回码
返回码 描述 说明 是否需要自动重试
3.2.12 复用接口列表

3.1.6 Vendor实绑拣货任务

3.1.7 Vendor增量拣货明细

3.1.8 Vendor发起换箱（不产生新任务）

3.1.11 查询Vendor拣货任务列表【出库通用对账查询vendor接口】

3.3 RTS & MTO 需求池

3.3.1 WMS给Vendor下发需求
接口URL 接口描述 调用方 业务要求
/api/v2/automation/tovendor/outbound/rtsmto/create_require WMS给Vendor下发需求 shopee 涉及 RTS / MTO 类型的需求下发，包含该需求指定要拣货的 Device 类型
接口系统要求
Avg RT Timeout 幂等字段 降级方案
200ms 10s order_number, res_number 无
请求字段
字段名 类型 是否必须 最大长度 说明 示例 WES表字段（按明细行拆单）
whs_id string 是 16 仓库id SGL shipment_header.warehouseCode
order_number string 是 32 订单号，幂等 RTSWMSSGL00026010700001 shipment_header.sourceOrderCode
biz_type int 是 16 任务类型：1 - 销售出库
2 - RTS
3 - MTO		 2 shipment_header.shipmentType
res_list List 是 需求列表
Mar 9: 当前res list长度最大1000		 详见下表
single_attr_list List 是 属性列表（单属性）
当前有：
to_whs
expected_ob_date
order_source
transported_by
biz_type
order_tag
supplier_id
delivery_method
return_date
rts_reason
order_source
04-14 新增: rts_type （20 - Real 30 - Virtual）
04-21 新增： sku_biz_type		 0509补充RTS、MTO属性keysRTS：
to_whs
expected_ob_date
order_source
supplier_id
delivery_method
return_date
rts_reason
rts_type
biz_type
MTO：
from_whs
to_whs
biz_type
sku_biz_type
order_flag
urgent_flag
create_time
expected_ob_date
order_source
transfer_type
注意:两者order_source枚举RTS和MTO不一样
multi_attr_list List 是 属性列表（多属性）
当前attr_key有：
ticket_type int 是 单据类型：
单据类型：
1: 销售出库下发task 2: 销售出库下发order 3:rts需求池需求 4: mto 需求池需求 5: mto下发任务 6: RT		 3或者4 shipment_header.ticketType

ResInfo字段详情

字段名 类型 是否必须 最大长度 说明 示例 WES表字段
res_number string 是 64 RTS需求号 RORWMSSGD00026010600003 shipment_header.erpOrderCode
根据该字段进行拆分单据
sku_id string 是 64 sku_id 1767751294820_08379 shipment_detail.itemCode
qty int 是 期望拣货数量 1 shipment_detail.requestQty
block_type int 是 指定冻结类型（Normal/临期/过期）
SKUBlockTypeNoNeed SKUBlockType = 0
SKUBlockTypeEXPIRING SKUBlockType = 1
SKUBlockTypeEXPIRED SKUBlockType = 3		 0 shipment_detail.shelfLifeSts
效期状态
quality int 是 0 好品
指定好/坏品
SkuQualityTypeGood SkuQualityType = 0
SkuQualityTypeDamage SkuQualityType = 1		 0 shipment_detail.inventorySts
库存状态
group_key string 是 特征值（包含 delivery_method， supplier .. 决定是否能混拣） shipment_header. groupKey新增字段，混拣特征值
can_group_picking int 是 是否能和其他不一样特征值的需求混拣
0 - 不能混拣
1 - 可以混拣		 默认0 shipment_header. canGroupPicking
新增字段，是否混拣
urgent_flag int 是 0~99 越大越紧急 99 shipment_header.priority
demand_mode int 是 2 : single 模式
1 : mix 模式
展示用		 1 shipment_header.demandMode
ctime int 是 需求创建时间 1767751167 shipment_header.ctime-新增字段，shopee wms创建时间
响应字段
字段名 类型 是否必须 最大长度 说明 示例
无
返回码
返回码 描述 说明 是否需要自动重试
-10012001 参数非法 比如参数是否必填、类型不符、长度不正确、非法字符、主键重复等 否
-10012010 单据类型未配置 单据类型未配置 否
-10012023 SKU不存在 SKU不存在 否
-10012049 仓库不存在 未配置仓库 否
-10012098 其他非法操作 上述未枚举时兜底使用 否
-10012099 系统错误 如限流、数据库错误、内部错误等等 是
3.3.2 WMS向Vendor取消需求
接口URL 接口描述 调用方 业务要求
/api/v2/automation/tovendor/outbound/rtsmto/cancel_require WMS向Vendor取消需求 shopee 批量取消下发的需求
接口系统要求
Avg RT Timeout 幂等字段 降级方案
200ms 10s order_number, res_number 无
请求字段
字段名 类型 是否必须 最大长度 说明 示例 WES表字段（取消WES走base标记cancel，标记的单子集波不抓）
whs_id string 是 16 仓库id SGL shipment_header.warehouseCode
biz_type int 是 4 任务类型：1 - 销售出库
2 - RTS
3 - MTO		 2 shipment_header.shipmentType
res_number_list List 是 64 RTS需求号列表 / MTO 需求号列表 [RORWMSSGD00026010600003] shipment_header.erpOrderCode
响应字段
字段名 类型 是否必须 最大长度 说明 示例
success_list List 取消成功的需求列表
fail_list List 取消失败的需求列表
not_exist_list List 不存在的的需求列表
返回码
返回码 描述 说明 是否需要自动重试
-10012001 参数非法 比如参数是否必填、类型不符、长度不正确、非法字符、主键重复等 否
-10012098 其他非法操作 上述未枚举时兜底使用 否
-10012099 系统错误 如限流、数据库错误、内部错误等等 是
3.3.3 Vendor 向 WMS 同步占用信息
接口URL 接口描述 调用方 业务要求
/api/v2/automation/toshopee/outbound/rtsmto/sync_occupied_require Vendor 向 WMS 同步占用信息 vendor 销售出库占用0库存时，触发的是捞单接口，而RTSMTO触发的是此接口
【注意此时没有波次ID】
同步调用，接口失败需要重试
要么一起成功要么一起失败
接口系统要求
Avg RT Timeout 幂等字段 降级方案
1s 10s order_number, res_number 无
请求字段
字段名 类型 是否必须 最大长度 说明 示例 WES表字段
whs_id string 是 16 仓库id SGL shipment_header.warehouseCode
biz_type int 是 4 任务类型：1 - 销售出库
2 - RTS
3 - MTO		 2 shipment_header.shipmentType
res_list List 是 需求列表，长度<2000 详见下表

ResInfo字段详情

字段名 类型 是否必须 最大长度 说明 示例 WES表字段
res_number string 是 64 RTS需求号 RORWMSSGD00026010600003 shipment_header.erpOrderCode
allocated_qty int 是 分配的数量 0 拣的则传 0 汇总该单明细请求数量-短分配量
shipment_detail
requestQty -shortAllocQty
响应字段
字段名 类型 是否必须 最大长度 说明 示例
无
返回码
返回码 描述 说明 是否需要自动重试
-10002501 参数错误 参数错误 是
-10002503 需求不存在 需求不存在 是
-10002504 需求来源不正确 需求来源不正确 是
-10002506 需求状态不正确 需求状态不正确 是
-10002502 其他业务错误码 其他业务类错误码 是
3.3.4 Vendor绑定/解绑device【废弃】
3.3.5 Vendor向wms获取号段缓存【复用】

3.2.5 vendor向wms获取号段缓存

3.3.6 Vendor向WMS创建picking task（创建时如果wms返回失败的列表需要重新拿成功的列表再次请求上游直到返回全部成功为止）
接口URL 接口描述 调用方 业务要求
/api/v2/automation/toshopee/outbound/rtsmto/create_picking_task 创建task Vendor 必须WMS成功再Vendor成功
涉及组装task属性, 订单状态变更等场景 失败需要支持重试, 增加告警
同步调用，需要重试，接口未成功阻塞该波次的后续作业流程
接口系统要求
Avg RT Timeout 幂等字段 降级方案
1s 10s pickup_id 无
请求字段
字段名 类型 是否必须 最大长度 说明 示例 WES表字段
whs_id string 是 16 仓库id SGL shipment_header.warehouseCode
pickup_id int64 是 64 拣货任务id 202104220002 根据订单类型取得shopee_wave中的状态为100的波次号，取完就要更新状态为使用中，注意并发
biz_type int 是 4 任务类型：1 - 销售出库
2 - RTS
3 - MTO		 2 shipment_header.shipmentType
station_type int 是 工作站类型
单据分播流程、分播出库流程
1：vendor pick to order
2：vendor batch picking		 1 按照工作站选的类型取值
res_number_list List 是 需求号列表 [“OBCNG000260101081110”,”OBCNG000260101081112”] shipment_header.erpOrderCode
operator string 是 64 operator邮箱 xxx@shopee.com 取工作站登录用户表的邮箱
响应字段
字段名 类型 是否必须 最大长度 说明 示例
fail_res_list List 是 返回码为失败的情况下会有该字段，表示WMS的这些订单不支持进入波次，vendor需要把这些订单从波次中移除并触发捞单。
task_attr_info ResTaskAttrInfo 否 RTS当前没有urgent_flag且其余字段都下发过vendor能计算出来，属非必填字段

ResTaskAttrInfo

字段名 类型 是否必须 最大长度 说明 示例
pickup_id int64 是 任务id
urgent_flag int 是 0~99 越大越紧急 1
ctime int 是 创建时间，WMS创建的时间戳，秒级 1767751167
single_attr_list List 是 属性列表（单属性）
当前待确认放single还是放multi：
to_whs
expected_ob_date
order_source
transported_by
biz_type
order_tag
supplier_id
delivery_method
return_date
rts_reason
order_source
multi_attr_list List 是 属性列表（多属性）
当前attr_key有：
返回码
返回码 描述 说明 是否需要自动重试
-10002501 参数错误 参数错误 是
-10002503 需求不存在 需求不存在 是
-10002504 需求来源不正确 需求来源不正确 是
-10002506 需求状态不正确 需求状态不正确 是
-10002507 需求分组key不正确 需求分组key不正确 是
-10002512 需求已跑入了其他波次 需求已跑入了其他波次 是，踢单后重试
-10002502 其他业务错误码 其他业务类错误码 是
3.3.7 Vendor实绑拣货任务
接口URL 接口描述 调用方 业务要求
/api/v2/automation/toshopee/outbound/rtsmto/bind_picking_task Vendor实际绑定拣货任务容器 vendor 作业接口，必须WMS成功再Vendor成功
同步调用，需要重试，接口未成功阻塞该波次的后续作业流程
接口系统要求
Avg RT Timeout 幂等字段 降级方案
1s 10s 无 无
请求字段
字段名 类型 是否必须 最大长度 说明 示例 WES表字段
whs_id string 是 16 仓库id SGL shipment_header.warehouseCode
pickup_id int64 是 64 拣货任务id 202104220002 shipment_header.shopeeWave
device_id string 是 32 拣货设备id OPBSK11873 wcs_sorting_wall_cell.containerCode分拣墙格口绑定的目标容器号
biz_type int 是 4 任务类型：1 - 销售出库
2 - RTS
3 - MTO		 2 shipment_header.shipmentType
operator string 是 64 operator邮箱 xxx@shopee.com 取工作站登录用户表的邮箱
响应字段
字段名 类型 是否必须 最大长度 说明 示例
无
返回码
返回码 描述 说明 是否需要用户重试
-10002501 参数错误 参数错误 是
-10002509 device不可用 device不可用 是，由用户重试
3.3.8 Vendor向WMS追加明细
接口URL 接口描述 调用方 业务要求
/api/v2/automation/toshopee/outbound/rtsmto/append_order 追加 Vendor 必须WMS成功再Vendor成功
只做追加动作
同步调用，需要重试，接口未成功阻塞该波次的后续作业流程
接口系统要求
Avg RT Timeout 幂等字段 降级方案
1s 10s pickup_id 无
请求字段
字段名 类型 是否必须 最大长度 说明 示例 WES表字段
whs_id string 是 16 仓库id SGL shipment_header.warehouseCode
pickup_id int64 是 64 拣货任务id 202104220002 追加到shopee的波次号
biz_type int 是 4 任务类型：1 - 销售出库
2 - RTS
3 - MTO		 2 shipment_header.shipmentType
res_number_list List 是 追加的需求列表，增量 [“OBCNG000260101081110”,”OBCNG000260101081112”] shipment_header.erpOrderCode
响应字段
字段名 类型 是否必须 最大长度 说明 示例
fail_res_list List 是 返回码为失败的情况下会有该字段，表示WMS的这些订单不支持进入波次，vendor需要把这些订单从波次中移除并触发捞单。
task_attr_info ResTaskAttrInfo 否 RTS当前没有urgent_flag且其余字段都下发过vendor能计算出来，属非必填字段
返回码
返回码 描述 说明 是否需要自动重试
-10002501 参数错误 参数错误 是
-10002510 拣货任务不存在 拣货任务不存在 是
-10002511 拣货任务状态不合法 拣货任务状态不合法 是
-10002504 需求来源不正确 需求来源不正确 是
-10002506 需求状态不正确 需求状态不正确 是
-10002512 需求已跑入了其他波次 需求已跑入了其他波次 是，踢单后重试
3.3.9 Vendor增量同步拣货明细
接口URL 接口描述 调用方 业务要求
/api/v2/automation/toshopee/outbound/rtsmto/sync_picking_detail Vendor增量拣货明细 vendor 实际拣货下架的明细增量同步
每次调用最外层的pickup_id不允许重复
异步调用，接口失败需要重试
接口系统要求
Avg RT Timeout 幂等字段 降级方案
300ms 10s 无 无
请求字段
字段名 类型 是否必须 最大长度 说明 示例 WES表字段
whs_id string 是 16 仓库id SGL shipment_header.warehouseCode
biz_type int 是 4 任务类型：1 - 销售出库
2 - RTS
3 - MTO		 2 shipment_header.shipmentType
picking_task_list List 是 100 拣货任务列表 详见下表

PickingTaskList字段详情

字段名 类型 是否必须 最大长度 说明 示例 WES表字段
pickup_id int64 是 64 拣货任务id 202104220002 shipment_header.shopeeWave
picked_info_list List 是 拣货明细列表 详见下表

PickedInfo字段详情

字段名 类型 是否必须 最大长度 说明 示例 WES表字段
id string 是 64 vendor拣货id，待vendor提供
幂等用		 shipment_header.erpOrderCode
device_id string 是 16 拣货设备id OPBSK11873 wcs_sorting_wall_cell.containerCode分拣墙格口绑定的目标容器号
sku_id string 是 32 sku_id 1767751294820_08379 task_detail.itemCode
res_number string 是 64 RTS需求号 RORWMSSGD00026010600003 shipment_header.erpOrderCode
code string 否 32 operator扫描的upc码，若是UID则体现在UID列表 177777 扫描的UPC需要记录在任务明细task_detail.barcode-新增字段，回传时取该字段
batch_no int64 是 批次号 2026010600001134 task_detail.batch
unit_list List 否 NA uid
qty int 是 数量>0 1 task_detail.totalQty
ctime int 是 拣货时间戳 task_detail.confirmedAt
operator string 是 64 operator邮箱 xxx@shopee.com task_detail.confirmedBy的邮箱

UnitItem

字段名 类型 是否必须 最大长度 说明 示例 WES表字段
unit_id string 是 32 unit_id编码 [“8u118”,”111] 根据拣货完成的明细lpn匹配序列号表lpn去查询序列号
scan_time int 是 20 扫描时间 序列号表最后更新时间serial_number.lastUpdated
响应字段
字段名 类型 是否必须 最大长度 说明 示例
success_list List 是 pickup_id维度
failed_list List 是 pickup_id维度
返回码
返回码 描述 说明 是否需要自动重试
-10002501 参数错误 参数错误 是
-10002510 拣货任务不存在 拣货任务不存在 是
-10002511 拣货任务状态不合法 拣货任务状态不合法 是
-10002504 需求来源不正确 需求来源不正确 是
-10002506 需求状态不正确 需求状态不正确 是
-10002507 需求分组key不正确 需求分组key不正确 是
-10002508 库存扣减失败 库存扣减失败 是
3.3.10 Vendor完成task
接口URL 接口描述 调用方 业务要求
/api/v2/automation/toshopee/outbound/rtsmto/complete_task 完成 Vendor 完成波次时通知
异步调用，接口失败需要重试
接口系统要求
Avg RT Timeout 幂等字段 降级方案
1s 10s pickup_id 无
请求字段
字段名 类型 是否必须 最大长度 说明 示例 WES表字段
whs_id string 是 16 仓库id SGL shipment_header.warehouseCode
pickup_id int64 是 64 拣货任务id 202104220002 shipment_header.shopeeWave
biz_type int 是 4 任务类型：1 - 销售出库
2 - RTS
3 - MTO		 1 shipment_header.shipmentType
operator string 是 64 operator邮箱 xxx@shopee.com 取工作站登录用户表的邮箱
picked_order_number_list List 是 满拣需求sku列表 整单全拣货的单据
明细见下文
shortage_order_info_list List 是 缺拣需求sku列表 缺拣（未拣满或者因为缺货零拣） 整单部分拣货的单据
明细见下文
zero_order_info_list List 是 0拣需求列表 未拣货需求列表 整单未拣货的单据

PickedOrderInfo字段详情

字段名 类型 是否必须 最大长度 说明 示例 WES表字段
id string 是 64 vendor拣货id，待vendor提供
增量拣货明细有可能会丢请求，幂等用		 task_detail.taskCode
res_number string 是 32 需求号 OBCNG000260101081110 shipment_header.erpOrderCode
device_id string 是 32 设备id OPBSK11873 task_detail.targetContainer
sku_id string 是 32 sku_id 1767751294820_08379 task_detail.itemCode
code string 否 32 operator扫描的upc码，若是UID则体现在UID列表 177777 扫描的UPC需要记录在任务明细task_detail.barcode-新增字段，回传时取该字段
batch_no int64 是 批次号 2026010600001134 task_detail.batch
unit_list List 否 NA uid
qty int 是 数量>0 1 task_detail.totalQty
ctime int 是 拣货时间戳 task_detail.confirmedAt
operator string 是 64 operator邮箱 xxx@shopee.com task_detail.confirmedBy的邮箱

UnitItem

字段名 类型 是否必须 最大长度 说明 示例 WES表字段
unit_id string 是 32 unit_id编码 [“8u118”,”111] 根据拣货完成的明细lpn匹配序列号表lpn去查询序列号
scan_time int 是 20 扫描时间 序列号表最后更新时间serial_number.lastUpdated
响应字段
字段名 类型 是否必须 最大长度 说明 示例
task_attr_info ResTaskAttrInfo 否 RTS当前没有urgent_flag且其余字段都下发过vendor能计算出来，属非必填字段
返回码
返回码 描述 说明 是否需要自动重试
-10002501 参数错误 参数错误 是
-10002510 拣货任务不存在 拣货任务不存在 是
-10002511 拣货任务状态不合法 拣货任务状态不合法 是
-10002504 需求来源不正确 需求来源不正确 是
-10002506 需求状态不正确 需求状态不正确 是
-10002508 库存扣减失败 库存扣减失败 是
3.3.11 Vendor换箱接口（用户点换箱有2种场景，第1如果没调通接口比如返回网络连接失败等情况则不允许继续拣货到老料箱-界面锁住，第2如果调通了返回正常的失败码则允许继续往老料箱集波，第2调通了返回成功码则只能往新箱中拣货）
接口URL 接口描述 调用方 业务要求
/api/v2/automation/toshopee/outbound/rtsmto/ change_picking_device 完成 Vendor 同flow picking 换箱
作业接口，必须WMS成功再Vendor成功
同步调用，需要重试，接口未成功阻塞该波次的后续作业流程
接口系统要求
Avg RT Timeout 幂等字段 降级方案
1s 10s pickup_id 无
请求字段
字段名 类型 是否必须 最大长度 说明 示例 WES表字段
whs_id string 是 16 仓库id SGL shipment_header.warehouseCode
pickup_id int64 是 64 拣货任务id 202104220002 shipment_header.shopeeWave换箱前的上游波次号
new_pickup_id int64 是 64 新的拣货任务id 202104220002 取上游新的波次号段（也是rts和mto订单都是flow pick形式）
new_device_id string 是 32 设备id OPBSK11873 wcs_sorting_wall_cell.containerCode分拣墙格口绑定的目标容器号-换箱后的
biz_type int 是 4 任务类型：1 - 销售出库
2 - RTS
3 - MTO		 2 shipment_header.shipmentType
station_type int 是 工作站类型
单据分播流程、分播出库流程
1：vendor pick to order
2：vendor batch picking
注意：如果是BatchPicking，需求池模式只能走FLowPicking产生新任务的换箱模式		 1 按照工作站选的类型取值
operator string 是 64 operator邮箱 xxx@shopee.com 取工作站登录用户表的邮箱
picked_order_number_list List 是 满拣需求sku列表 整单全拣货的单据
明细见下文
zero_order_info_list List 是 0拣需求列表；
注意0拣时，订单在vendor终态了		 [“RORWMSSGD00026010600003”,”RORWMSSGD00026010600003”] 整单未拣货的订单
new_order_number_list List 否 新task需求列表
长度必须>0		 [“RORWMSSGD00026010600003”,”RORWMSSGD00026010600003”] shipment_header.erpOrderCode

PickedOrderInfo字段详情

字段名 类型 是否必须 最大长度 说明 示例 WES表字段
id string 是 64 vendor拣货id，待vendor提供
增量拣货明细有可能会丢请求，幂等用		 task_detail.taskCode
res_number string 是 32 需求号 OBCNG000260101081110 shipment_header.erpOrderCode
sku_id string 是 32 sku_id 1767751294820_08379 task_detail.itemCode
code string 否 32 operator扫描的upc码，若是UID则体现在UID列表 177777 扫描的UPC需要记录在任务明细task_detail.barcode-新增字段，回传时取该字段
batch_no int64 是 批次号 2026010600001134 task_detail.batch
unit_list List 否 NA uid
qty int 是 数量> 0 1 task_detail.totalQty
ctime int 是 拣货时间戳 task_detail.confirmedAt
operator string 是 64 operator邮箱 xxx@shopee.com task_detail.confirmedBy的邮箱

UnitItem

字段名 类型 是否必须 最大长度 说明 示例 WES表字段
unit_id string 是 32 unit_id编码 [“8u118”,”111] 根据拣货完成的明细lpn匹配序列号表lpn去查询序列号
scan_time int 是 20 扫描时间 序列号表最后更新时间serial_number.lastUpdated
响应字段
字段名 类型 是否必须 最大长度 说明 示例
task_attr_info_list List 否 RTS当前没有urgent_flag且其余字段都下发过vendor能计算出来，属非必填字段
返回码
返回码 描述 说明 是否需要用户重试
-10002501 参数错误 参数错误 是
-10002510 拣货任务不存在 拣货任务不存在 是
-10002511 拣货任务状态不合法 拣货任务状态不合法 是
-10002504 需求来源不正确 需求来源不正确 是
-10002506 需求状态不正确 需求状态不正确 是
-10002508 库存扣减失败 库存扣减失败 是
3.3.12 查询Vendor拣货任务列表【复用】

3.1.11 查询Vendor拣货任务列表【出库通用对账查询vendor接口】

3.3.13 更新需求的urgent_flag【复用】

3.1.3 WMS向Vendor更新订单/task的urgent flag

3.4 非需求池MTO

3.4.1 WMS给Vendor下发拣货任务
接口URL 接口描述 调用方 业务要求
/api/v2/automation/tovendor/outbound/mto/create_picking_task WMS给Vendor下发拣货任务 shopee 多个拣货任务不可混拣，支持缺拣和零拣
接口系统要求
Avg RT Timeout 幂等字段 降级方案
300ms 10s pickup_id 无
请求字段
字段名 类型 是否必须 最大长度 说明 示例 WES表字段
whs_id string 是 16 仓库id SGL shipment_header.warehouseCode
pickup_id int64 是 64 拣货任务id，幂等 202104220002 shipment_header.erpOrderCode
shipment_header.shopeeWave-新增字段，shopee波次号
同步接到两个字段中
urgent_flag int 是 0~99 越大越紧急 99 shipment_header.priority
ctime int 是 创建时间，WMS创建的时间戳 1767751167 shipment_header.ctime-新增字段，shopee wms创建时间
can_group_picking int 是 0: 不可混拣 0 shipment_header. canGroupPicking
新增字段，是否混拣
group_key string 是 128 特征值，若可混拣，则有值 xxx_xx_xx_xx shipment_header.groupKey
新增字段，混拣特征值
sku_info_list List 是 期望拣货数量
single_attr_list List 是 属性列表（单属性）
当前有：
to_whs
expected_ob_date
order_source
transported_by
multi_attr_list List 是 属性列表（多属性）
当前attr_key有
ticket_type int 是 单据类型：
1: 销售出库下发task 2: 销售出库下发order 3:rts需求池需求 4: mto 需求池需求 5: mto下发任务 6: RT		 5 shipment_header.ticketType
shipment_header.shipmentType默认为MTO

SkuInfo字段详情

字段名 类型 是否必须 最大长度 说明 示例 WES表字段
sku_id string 是 64 sku_id 1767751294820_08379 shipment_detail.itemCode
qty int 是 期望拣货数量 10 shipment_detail.requestQty
block_type int 是 销售出库传的是0 normal
指定冻结类型（Normal/临期/过期）
SKUBlockTypeNoNeed SKUBlockType = 0
SKUBlockTypeEXPIRING SKUBlockType = 1
SKUBlockTypeEXPIRED SKUBlockType = 3		 0 shipment_detail.shelfLifeSts
效期状态
quality int 是 0 好品
指定好/坏品
SkuQualityTypeGood SkuQualityType = 0
SkuQualityTypeDamage SkuQualityType = 1		 0 shipment_detail.inventorySts
库存状态

SingleAttr字段详情【同销售出库】

MultiAttr字段详情【同销售出库】

响应字段
字段名 类型 是否必须 最大长度 说明 示例
无
返回码
返回码 描述 说明 是否需要自动重试
-10012001 参数非法 比如参数是否必填、类型不符、长度不正确、非法字符、主键重复等 否
-10012010 单据类型未配置 单据类型未配置 否
-10012023 SKU不存在 SKU不存在 否
-10012049 仓库不存在 未配置仓库 否
-10012098 其他非法操作 上述未枚举时兜底使用 否
-10012099 系统错误 如限流、数据库错误、内部错误等等 是
3.4.2 WMS取消拣货任务
接口URL 接口描述 调用方 业务要求
/api/v2/automation/tovendor/outbound/mto/cancel_picking_task WMS取消拣货任务 shopee WMS支持从Pending（Vendor考虑如果只绑了device也支持取消）
注意：WMS会释放库存、释放device，需要Vendor也考虑
接口系统要求
Avg RT Timeout 幂等字段 降级方案
300ms 10s pickup_id 无
请求字段
字段名 类型 是否必须 最大长度 说明 示例 WES表字段（取消WES走base标记cancel，标记的单子集波不抓）
whs_id string 是 16 仓库id SGL shipment_header.warehouseCode
pickup_id int64 是 64 拣货任务id，幂等 202104220002 shipment_header.erpOrderCode
响应字段
字段名 类型 是否必须 最大长度 说明 示例
返回码
返回码 描述 说明 是否需要自动重试
-10012001 参数非法 比如参数是否必填、类型不符、长度不正确、非法字符、主键重复等 否
-10012051 单据不存在 单据不存在，取消失败的单号单独返回，该逻辑走不到 否
-10012052 单据已拣货，不能取消 如果批量取消，取消失败的单号单独返回，该逻辑走不到 否
-10012098 其他非法操作 上述未枚举时兜底使用 否
-10012099 系统错误 如限流、数据库错误、内部错误等等 是
3.4.3 WMS向Vendor更新task的urgent flag【复用3.1.3】
3.4.4 Vendor绑定/解绑device【复用basic接口】废弃
3.4.5 Vendor开始拣货任务
接口URL 接口描述 调用方 业务要求
/api/v2/automation/toshopee/outbound/mto/start_picking_task Vendor开始拣货任务 vendor 必须WMS成功再Vendor成功
同步调用，需要重试，接口未成功阻塞该波次的后续作业流程
接口系统要求
Avg RT Timeout 幂等字段 降级方案
1s 10s 无 无
请求字段
字段名 类型 是否必须 最大长度 说明 示例 WES表字段
whs_id string 是 16 仓库id SGL shipment_header.warehouseCode
pickup_id int64 是 64 拣货任务id，幂等 202104220002 shipment_header.erpOrderCode
station_type int 是 工作站类型
单据分播流程、分播出库流程
1：vendor pick to order
2：vendor batch picking		 1 按照工作站选的类型取值
operator string 是 64 operator邮箱 xxx@shopee.com 取工作站登录用户表的邮箱
响应字段
字段名 类型 是否必须 最大长度 说明 示例
无
返回码
返回码 描述 说明 是否需要自动重试
-10002801 参数错误 参数错误 是
-10002802 开始拣货任务失败 开始拣货任务失败 是
3.4.6 Vendor真实绑定拣货任务
接口URL 接口描述 调用方 业务要求
/api/v2/automation/toshopee/outbound/mto/bind_picking_task Vendor开始拣货任务 vendor 作业接口，必须WMS成功再Vendor成功
同步调用，需要重试，接口未成功阻塞该波次的后续作业流程
接口系统要求
Avg RT Timeout 幂等字段 降级方案
1s 10s 无 无
请求字段
字段名 类型 是否必须 最大长度 说明 示例 WES表字段
whs_id string 是 16 仓库id SGL shipment_header.warehouseCode
pickup_id int64 是 64 拣货任务id，幂等 202104220002 shipment_header.shopeeWave
device_id string 是 32 拣货设备id OPBSK11873 wcs_sorting_wall_cell.containerCode
operator string 是 64 operator邮箱 xxx@shopee.com 取工作站登录用户表的邮箱
响应字段
字段名 类型 是否必须 最大长度 说明 示例
无
返回码
返回码 描述 说明 是否需要用户重试
-10002801 参数错误 参数错误 是
-10002803 绑定device失败 绑定device失败 是
3.4.7 Vendor增量拣货明细
接口URL 接口描述 调用方 业务要求
/api/v2/automation/toshopee/outbound/mto/sync_picking_detail Vendor增量拣货明细 vendor 每次调用最外层的pickup_id不允许重复
异步调用，接口失败需要重试
接口系统要求
Avg RT Timeout 幂等字段 降级方案
300ms 10s 无 无
请求字段
字段名 类型 是否必须 最大长度 说明 示例 WES表字段
whs_id string 是 16 仓库id SGL shipment_header.warehouseCode
picking_task_list List 是 100 拣货任务列表 [
]

PickingTaskInfo字段详情

字段名 类型 是否必须 最大长度 说明 示例 WES表字段
pickup_id int64 是 64 拣货任务id，幂等 202104220002 shipment_header.shopeeWave
picked_info_list List 是 拣货明细列表 详见下表

picked_info_list字段详情

字段名 类型 是否必须 最大长度 说明 示例 WES表字段
id string 是 64 vendor拣货id，待vendor提供
幂等用		 task_detail.taskCode
device_id string 是 16 拣货设备id OPBSK11873 task_detail.targetContainer
sku_id string 是 32 sku_id 1767751294820_08379 task_detail.itemCode
code string 否 32 operator扫描的upc码，若是UID则体现在UID列表 177777 扫描的UPC需要记录在任务明细task_detail.barcode-新增字段，回传时取该字段
batch_no int64 是 批次号 2026010600001134 task_detail.batch
unit_list List 否 NA uid
qty int 是 数量> 0 1 task_detail.totalQty
ctime int 是 拣货时间戳 task_detail.confirmedAt
operator string 是 64 operator邮箱 xxx@shopee.com task_detail.confirmedBy的邮箱
响应字段
字段名 类型 是否必须 最大长度 说明 示例
success_list List 是 pickup_id维度
failed_list List 是 pickup_id维度
返回码
返回码 描述 说明 是否需要自动重试
-10002801 参数错误 参数错误 是
-10002804 拣货明细失败 拣货明细失败 是
3.4.8 Vendor完成拣货任务

可以缺量完成拣货任务

接口URL 接口描述 调用方 业务要求
/api/v2/automation/toshopee/outbound/mto/complete_picking_task Vendor完成拣货任务 vendor 异步调用，接口失败需要重试
接口系统要求
Avg RT Timeout 幂等字段 降级方案
300ms 10s 无 无
请求字段
字段名 类型 是否必须 最大长度 说明 示例 WES表字段
whs_id string 是 16 仓库id SGL shipment_header.warehouseCode
pickup_id int64 是 64 拣货任务id，幂等 202104220002 shipment_header.shopeeWave
operator string 是 64 operator邮箱 xxx@shopee.com 取工作站登录用户表的邮箱
picked_info_list List 是 拣货明细列表 详见下表

picked_info_list字段详情

字段名 类型 是否必须 最大长度 说明 示例 WES表字段
id string 是 64 vendor拣货id，待vendor提供
增量拣货明细有可能会丢请求，幂等用		 task_detail.taskCode
device_id string 是 16 拣货设备id OPBSK11873 task_detail.targetContainer
sku_id string 是 32 sku_id 1767751294820_08379 task_detail.itemCode
code string 否 32 operator扫描的upc码，若是UID则体现在UID列表 177777 扫描的UPC需要记录在任务明细task_detail.barcode-新增字段，回传时取该字段
batch_no int64 是 批次号 2026010600001134 task_detail.batch
unit_list List 否 NA uid
qty int 是 数量> 0 1 task_detail.totalQty
ctime int 是 拣货时间戳 task_detail.confirmedAt
operator string 是 64 operator邮箱 xxx@shopee.com task_detail.confirmedBy的邮箱
响应字段
字段名 类型 是否必须 最大长度 说明 示例
无
返回码
返回码 描述 说明 是否需要自动重试
-10002801 参数错误 参数错误 是
-10002805 完成拣货任务失败 完成拣货任务失败 是
3.4.9 查询Vendor拣货任务列表【复用】

3.1.11 查询Vendor拣货任务列表【出库通用对账查询vendor接口】

库内模块接口协议

库内管理模块主要处理仓库内部的库存管理和维护作业，包括库存查询、移位、盘点等。

4.1 库内移库同步占用库存给Vendor接口

接口URL 接口描述 调用方 业务要求
/api/v2/automation/tovendor/inventory/racktransfer/create_rt_order WMS给Vendor同步移库占用的库存 shopee
接口系统要求
Avg RT Timeout 幂等字段 降级方案
300ms 20s whs_id+rt_order_id sku_info_list: 500条数据量以内的要求平均响应时间300ms ;数据量2000条要求平均响应时间1000ms
请求字段
字段名 类型 是否必须 最大长度 说明 示例
whs_id string 是 16 仓库id SGL
rt_order_id string 是 32 移库单号(RT开头) RTSGL00020250102001
attr_list List 是 100 单据属性字段放到这里方便扩展
目前会有urgent_flag
2.26新增oos_order_qty
ctime int 是 20 移库单创建时间
operator string 是 128 下发操作人邮箱 xxx@shopee.com
ticket_type int 是 NA 枚举(复用出库枚举VendorUrgentTicketType) 移库固定为6 (Rack Transfer) 6
sku_info_list List 是 NA 长度应该不会太长 相同sku+block_type会合并 {}

AttrItem(urgent_flag 值范围0-99 非枚举)

字段名 类型 是否必须 最大长度 说明 示例
attr_key string 是 32 入库单号，不传则返回所有待处理入库单 urgent_flag
attr_value_id string 是 32 属性具体值 1
attr_value_name string 是 128 值对应的名称用于界面展示

SkuInfo

字段名 类型 是否必须 最大长度 说明 示例
sku_id string 是 64 入库单号，不传则返回所有待处理入库单 "18377383_9999"
block_type int 是 NA 冻结类型(0 正常 1 临期 3过期) 0
qty int 是 占用数量 2
sku_quality int 是 NA 好坏品 0是好品 1是坏品 0
响应字段
字段名 类型 是否必须 最大长度 说明 示例
无
返回码
返回码 描述 说明 是否需要自动重试
-10013001 参数非法 比如参数是否必填、类型不符、长度不正确、非法字符、主键重复等 否
-10013023 SKU不存在 SKU不存在 否
-10013049 仓库不存在 未配置仓库 否
-10013098 其他非法操作 上述未枚举时兜底使用 否
-10013099 系统错误 如限流、数据库错误、内部错误等等 是

4.2 库内移库Vendor占用PickingDevice接口

接口URL 接口描述 调用方 业务要求
/api/v2/automation/toshopee/inventory/racktransfer/occupy_device vendor占用device(换箱不用这个接口 用关箱那个接口) vendor
接口系统要求
Avg RT Timeout 幂等字段 降级方案
300ms 5s whs_id+rt_order_id 无
请求字段
字段名 类型 是否必须 最大长度 说明 示例
whs_id string 是 16 仓库id SGL
relation_id string 是 传shopee创建的移库单号(RT开头)，Vendor侧创建的话要传Vendor侧唯一的单据号(要与后续关箱时传的source_id一致) RTSGL00020250102001
grid_no string 是 分拨墙的格口号 同3.1.6接口
device_id string 是 设备号; 单据用过的device不允许上架完后二次使用 B00013
request_type int 是 1单据占用 2释放 1
响应字段
字段名 类型 是否必须 最大长度 说明 示例
无
返回码
返回码 描述 说明 是否需要自动重试
-10003000 device不合法 没传或者传的不存在 否
-10003001 已关箱 已经被占用并关箱 否
-10003002 device类型不符合移库 否
-10003003 被其他单据占用 否

4.3 库内Vendor发起Picking明细整箱同步到WMS(WMS/Vendor创建)

接口URL 接口描述 调用方 业务要求
/api/v2/automation/toshopee/inventory/racktransfer/submit_picking_sku_list vendor拣货后同步拣货明细到wms vendor
接口系统要求
Avg RT Timeout 幂等字段 降级方案
300ms 5s whs_id+device_id+rt_order_id/source_id
请求字段
字段名 类型 是否必须 最大长度 说明 示例
whs_id string 是 16 仓库id SGL
rt_order_id string 否 32 移库单号(RT开头) WMS生成的
和source_id必传一个		 RTSGL00020250102001
source_id string 否 32 Vendor生成的，source_id和rt_order_id必传一个
remark string 否 128 Vendor生成的必传remark
要做场景区分：
Expiring/expired rack transfer
Damage rack transfer
Normal rack transfer
device_id string 否 16 设备号(一个source_id/rt_order_id对应多个device_id 一次请求只给一个device) 0拣可不传 B00013
new_device_id string 否 16 新占用箱子，关箱时可以传一个新占用的箱子(对应系统页面是一次操作 但不允许关空箱)单据用过的device不允许上架完二次使用
grid_no string 是 分拨墙的格口号 new_device_id有传的话必传 同3.1.6接口
sku_info_list List 否 NA 缺拣时不传 关箱的时候传所有明细
另外WMS创建需要实时传明细(Vendor创建的可以只在关箱传一次)
picking_flag int 是 1 1:整单完成 2:仅关箱(传所有明细) 3:换箱(传旧箱所有明细及new_device_id) 1

SkuInfo

字段名 类型 是否必须 最大长度 说明 示例
id string 是 20 标识明细的唯一id
sku_id string 是 64 sku_id 1322222_09911
qty int 是 20 数量 1
batch_no int64 是 20 批次号 20190311000045104
unit_list List 是 NA
picking_time int 是 20 拣货时间 秒
operator string 是 64 拣货操作人(一个移库单可能不同人拣货) 邮箱 xxx@shopee.com
block_type int 是 0代表非冻结库存 1代表临期库存 3代表过期库存

UnitItem

字段名 类型 是否必须 最大长度 说明 示例
unit_id string 是 32 unit_id编码 [“8u118”,”111]
scan_time int 是 20 扫描时间 秒级
响应字段
字段名 类型 是否必须 最大长度 说明 示例
无
返回码
返回码 描述 说明 是否需要自动重试
-10000002 系统错误/并发提交 数据库错误/并发导致的错误 是
-10003000 device不合法 没传或者传的不存在 否
-10003001 已关箱 已经被占用并关箱 否
-10003002 device类型不符合移库 否
-10003003 被其他单据占用 否

4.4 库内Vendor发起Picking明细定时回传到WMS(只针对WMS创建)

接口URL 接口描述 调用方 业务要求
/api/v2/automation/toshopee/inventory/racktransfer/sync_picking_sku_list vendor拣货后同步拣货明细到wms(一分钟同步一次) vendor
接口系统要求
Avg RT Timeout 幂等字段 降级方案
500ms 5s
请求字段
字段名 类型 是否必须 最大长度 说明 示例
whs_id string 是 16 仓库id SGL
rt_picking_list List 是 NA 移库单号(RT开头) 每一行代表一个移库单的拣货数据

RTOrderInfo

字段名 类型 是否必须 最大长度 说明 示例
rt_order_id string 否 32 shopee来源的必须传
source_id string vendor来源的必须传
device_list List 是 NA

DeviceItem

字段名 类型 是否必须 最大长度 说明 示例
sku_info_list List 是 NA
device_id string 是 16

SkuInfo

字段名 类型 是否必须 最大长度 说明 示例
id string 是 20 标识明细的唯一id
sku_id string 是 64 sku_id 1322222_09911
qty int 是 20 数量 1
batch_no int64 是 20 批次号 20190311000045104
unit_list List 是 NA uid列表
picking_time int 是 20 拣货时间 秒级
operator string 是 64 拣货操作人(一个移库单可能不同人拣货) 邮箱号

UnitItem

字段名 类型 是否必须 最大长度 说明 示例
unit_id string 是 32 unit_id编码 [“8u118”,”111]
scan_time int 是 20 扫描时间 秒级
响应字段
字段名 类型 是否必须 最大长度 说明 示例
无
返回码
返回码 描述 说明 是否需要自动重试
重复提交

4.5 库内Vendor发起盘点差异调减同步给WMS

接口URL 接口描述 调用方 业务要求
/api/v2/automation/toshopee/inventory/racktransfer/handle_diff_stock vendor差异处理同步到WMS vendor
接口系统要求
Avg RT Timeout 幂等字段 降级方案
300ms 5s whs_id+source_id 失败重试
请求字段
字段名 类型 是否必须 最大长度 说明 示例
whs_id string 是 16 仓库id SGL
source_id string 是 32 Vendor保证这个字段是唯一的 可以重试
sku_info_list List 是 200 要移库到AV区的库存数据列表 为保证性能传200条以内

SkuInfo

字段名 类型 是否必须 最大长度 说明 示例
id string 是 20 标识明细的唯一id
sku_id string 是 64 sku_id 1322222_09911
qty int 是 数量 1
batch_no int64 是 20 批次号 20190311000045104
unit_id_list List 是 NA [“8u118”,”111]
picking_time int 否 20 时间 秒级
operator string 否 64 操作人邮箱 xxx@shopee.com
响应字段
字段名 类型 是否必须 最大长度 说明 示例
rt_order_id string 是 32 在wms侧是唯一的 Vendor暂时无需关注 RTSGL00020250102001
返回码
返回码 描述 说明 是否需要自动重试
-10003004 库存移动失败 是

4.6 库内发起Vendor查询拣货接口(用于对账)

接口URL 接口描述 调用方 业务要求
/api/v2/automation/tovendor/inventory/racktransfer/query_picking_list WMS调用Vendor接口查询移库拣货用于对账(用source_id对账移库拣货明细) shopee
接口系统要求
Avg RT Timeout 幂等字段 降级方案
500ms 10s 无
请求字段
字段名 类型 是否必须 最大长度 说明 示例
whs_id string 是 16 仓库id SGL
source_id_list List 否 50 Vendor传的单号(rt_order_list必传一个)
rt_order_id_list List 否 50 Source_id_list 和 rt_order_list必传一个
wave_flag int 否 不传和传0一个逻辑
传1 是DamageRackTransfer(不通过跑波拣货的 虚拟拣货)
start_time int 否 仅在wave_type=1时必传(这个时候不传source_id_list和rt_order_id_list) 通过时间查这段时间虚拟拣货数据来和Shopee数据比对补偿
end_time int 否 仅在wave_type=1时必传(这个时候不传source_id_list和rt_order_id_list)通过时间查这段时间虚拟拣货数据来和Shopee数据比对补偿
exclude_source_id_list List 否 仅在wave_type=1时必传 剔除掉这个时间范围的单号 避免返回太多没必要处理的数据
响应字段
字段名 类型 是否必须 最大长度 说明 示例
whs_id string 是
rt_order_info_list List 是 控制传入的rt_order_list/source_id_list长度即可

RTOrderInfo

字段名 类型 是否必须 最大长度 说明 示例
rt_order_id string 否 32 rt_order_id
source_id string 否 32
is_complete bool 是
device_list List 是 NA

DeviceItem

字段名 类型 是否必须 最大长度 说明 示例
sku_info_list List 是 NA
device_id string 是 16
is_close bool 是 1 是否关箱

SkuInfo

字段名 类型 是否必须 最大长度 说明 示例
id string 是 20
sku_id string 是 64 sku_id "18377383_9999"
batch_no int64 是 20 冻结类型(0 正常 1 临期 3过期) 20250101000000
qty int 是 20 占用数量 2
unit_list List 否 NA uid
picking_time int 是 20 拣货时间 秒级
operator string 是 64 操作人邮箱 xxx@shopee.com

UnitItem

字段名 类型 是否必须 最大长度 说明 示例
unit_id string 是 32 unit_id编码 “8u118”
scan_time int 是 20 扫描时间
返回码
返回码 描述 说明 是否需要自动重试
-10013001 参数非法 比如参数是否必填、类型不符、长度不正确、非法字符、主键重复等 否
-10013099 系统错误 如限流、数据库错误、内部错误等等 是

4.7 库内更新(移库)单据(WMS创建的)

接口URL 接口描述 调用方 业务要求
/api/v2/automation/tovendor/inventory/racktransfer/update_rt_order WMS调用Vendor接口更新优先级/状态(取消) shopee Vendor侧保证占用device前(且WMS来源的移库单)可以取消 取消成功后WMS再取消
WMS调用失败会重试
接口系统要求
Avg RT Timeout 幂等字段 降级方案
300ms 5s
请求字段
字段名 类型 是否必须 最大长度 说明 示例
whs_id string 是 16 仓库id SGL
rt_order_list List 是 1000 传的列表用于批量更新(最少传一个)
update_event int 是 NA 取消单据(取消只处理status) 1其他单据信息更新2

RTOrderItem

字段名 类型 是否必须 最大长度 说明 示例
rt_order_id string 是 32 WMS侧的移库单号 RTSGL00020250102001
status int 否 status和其他单据字段至少传一个目前只有6 代表取消
attr_list List 否 update_event=2时必传
目前单据属性(后面新增不改协议)
urgent_flag(值范围0-99)
future_order_qty(整数 >= 0)
future_sku_qty(整数 >= 0)
oos_order_qty(整数 >= 0)
字段不一定都传(可能只传一个)

AttrItem(urgent_flag 值范围0-99 非枚举)

字段名 类型 是否必须 最大长度 说明 示例
attr_key string 是 32 入库单号，不传则返回所有待处理入库单 urgent_flag
attr_value_id string 是 32 属性具体值 1
attr_value_name string 是 128 值对应的名称用于界面展示
响应字段
字段名 类型 是否必须 最大长度 说明 示例
fail_order_id_list List 否 更新失败的单据 ["order1", "order2"]
返回码
返回码 描述 说明 是否需要自动重试
-10013001 参数非法 比如参数是否必填、类型不符、长度不正确、非法字符、主键重复等 否
-10013051 单据不存在 单据不存在 否
-10013052 单据已拣货，不能取消 如果批量取消，取消失败的单号单独返回，该逻辑走不到 否
-10013098 其他非法操作 上述未枚举时兜底使用 否
-10013099 系统错误 如限流、数据库错误、内部错误等等 是

基础资料模块接口协议

基础资料模块主要处理系统基础数据的同步和管理，包括商品信息、供应商信息、仓库信息等。

5.1 vendor向WMS查询用户是否存在

接口URL 接口描述 调用方 业务要求
/api/v2/automation/toshopee/basic/user/query_user_exist Vendor向WMS查询用户是否存在 Vendor
接口系统要求
Avg RT Timeout 幂等字段 降级方案
200ms 10s user_id 无
请求字段
字段名 类型 是否必须 最大长度 说明 示例
whs_id string 是 仓库编号 SGL
user_id int64 是 shopee用户id 123456
响应字段
字段名 类型 是否必须 最大长度 说明 示例
user_id int64 是 shopee用户id 123456
email string 是 64 shopee用户邮箱 aaa@shopee.com
返回码
返回码 描述 说明 是否需要自动重试
-10000001 参数错误 否
-10004001 用户不存在 否
-10004002 用户状态异常 否

5.2 WMS向Vendor同步批次状态

接口URL 接口描述 调用方 业务要求
/api/v2/automation/tovendor/basic/inventory/batch_status_update WMS向Vendor同步批次状态 Shopee
接口系统要求
Avg RT Timeout 幂等字段 降级方案
500ms 10s 无
请求字段
字段名 类型 是否必须 最大长度 说明 示例
whs_id string 是 仓库编号 SGL
batch_list List 是 状态有变化的批次以及状态；最大1000个，超过1000个分多次调用。 [
{
batch_no:12345
batch_status: 1
}
]

BatchBlockType

字段名 类型 是否必须 最大长度 说明 示例
batch_no bigint 是 批次号 2025091757580761
block_type int 是 批次状态
（固定枚举值）		 0-Normal
1-Expiring
3-Expired
响应字段
字段名 类型 是否必须 最大长度 说明 示例
无
返回码
返回码 描述 说明 是否需要自动重试
-10014001 参数非法 比如参数是否必填、类型不符、长度不正确、非法字符、主键重复等
-10014098 其他非法操作 上述未枚举时兜底使用
-10014099 系统错误 如限流、数据库错误、内部错误等等

5.3 WMS向Vendor查询库存信息

接口URL 接口描述 调用方 业务要求
/api/v2/automation/tovendor/basic/inventory/query_sku_batch_inventory WMS向Vendor查询批次库存信息 Shopee
接口系统要求
Avg RT Timeout 幂等字段 降级方案
500ms 10s sku_id+batch_no 无
请求字段
字段名 类型 是否必须 最大长度 说明 示例
whs_id string 是 仓库编号 SGL
page_no int64 是 分页码，从1开始 1
page_size int64 是 分页大小，默认100，最大1000 20
sku_id_list List 否 Sku_id 列表，一次最多1000个 [
"123123",
"2332423423"
]
响应字段
字段名 类型 是否必须 最大长度 说明 示例
page_no int64 是 分页码，返回请求传的参数 1
page_size int64 是 分页大小，返回请求传的参数 20
list List 是 详细库存信息

BatchInventory

字段名 类型 是否必须 最大长度 说明 示例
sku_id string 是 64 sku id 101057873_10000551324
batch_no bigint 是 批次号 2025091757580761
block_type int 是 批次状态
（固定枚举值）		 0-Normal
1-Expiring
3-Expired
quantity int 是 数量 100
返回码
返回码 描述 说明 是否需要自动重试
-10014001 参数非法 比如参数是否必填、类型不符、长度不正确、非法字符、主键重复等
-10014099 系统错误 如限流、数据库错误、内部错误等等

5.4 WMS向Vendor同步对账结果

接口URL 接口描述 调用方 业务要求
/api/v2/automation/tovendor/basic/inventory/sync_reconciliation_result WMS向Vendo同步对账结果 WMS
接口系统要求
Avg RT Timeout 幂等字段 降级方案
500ms 20s whs_id+reconciliation_id 无
请求字段
字段名 类型 是否必须 最大长度 说明 示例
whs_id string 是 仓库编号 SGL
reconciliation_id string 是 64 对账唯一ID RC123
reconciliation_date int 是 对账时间 1772287200
list List 是

ReconciliationResult

字段名 类型 是否必须 最大长度 说明 示例
sku_id string 是 64 sku id 101057873_10000551324
batch_no bigint 是 批次号 2025091757580761
shopee_block_type int 是 wms批次状态
（固定枚举值）		 0-Normal
1-Expiring
3-Expired
vendor_block_type int 是 vendor批次状态
（固定枚举值）		 0-Normal
1-Expiring
3-Expired
shopee_quantity int 是 wms数量 100
vendor_quantity int 是 vendor数量 100
shopee_uid_list List 否 wms uid列表
vendor_uid_list List 否 vendor uid列表
响应字段
字段名 类型 是否必须 最大长度 说明 示例
返回码
返回码 描述 说明 是否需要自动重试
-10014001 参数非法 比如参数是否必填、类型不符、长度不正确、非法字符、主键重复等
-10014099 系统错误 如限流、数据库错误、内部错误等等

5.5 vendor向WMS查询sku信息

接口URL 接口描述 调用方 业务要求
/api/v2/automation/toshopee/basic/sku/query_sku_detail Vendor向WMS查询sku信息 Vendor
接口系统要求
Avg RT Timeout 幂等字段 降级方案
200ms 10s sku_id 无
请求字段
字段名 类型 是否必须 最大长度 说明 示例
whs_id string 是 仓库编号 SGL
sku_id_list List 是 1000 sku id、upc、uid列表 [“101057873_10000551324”, “101057873_10000551322”]
响应字段
字段名 类型 是否必须 最大长度 说明 示例
sku_list List 是 1000 sku 信息列表 [{
“sku_id”:”aaa”
},
{
“sku_id”:”bbb”
}]

SkuInfo

字段名 类型 是否必须 最大长度 说明 示例
sku_id string 是 64 sku id 101057873_10000551324
name string 是 1024 名称
（可变值）		 111
description string 否 64k 描述
（可变值）		 test
images List 是 20 图片链接，单个链接最大长度1024
（可变值）		 [“http://cf.shopee.sg/file/8ed755a36ef5374a0f56966da8969334”]
upc_list List 否 20 barcode
（可变值）		 [“u222”]
sku_height int 是 高度，最小单位mm 120
sku_width int 是 宽度，最小单位mm 110
sku_length int 是 长度，最小单位mm 100
gross_weight int 是 重量，最小单位g 20
volume int 是 体积，最小单位微升 10000
is_uid_sn_imei_mgt int 是 是否唯一码管理 0 - 不是
1- 是
is_danger int 是 是否危险品 0 - 不是
1- 是
is_liquid int 是 是否液体 0 - 不是
1- 是
is_fragile int 是 是否易碎品 0 - 不是
1- 是
with_battery int 是 是否带电池 0 - 不是
1- 是
is_high_value int 是 是否高价值 0 - 不是
1- 是
sku_tag_list List 否 sku 标签列表
is_key_batch_mgt int 是 是否关键批次管理 0 - 不是
1- 是
is_shelf_life int 是 是否效期品管理 0 - 不是
1- 是
category_level_1_id int 是 L1类别ID
（可变值）		 10001
category_level_1_name string 是 1024 L1类别名称
（可变值）		 Men Clothes
category_level_2_id int 否 L2类别ID
（可变值）		 10002
category_level_2_name string 1024 L2类别名称
（可变值）		 Men Clothes
category_level_3_id int 否 L3类别ID
（可变值）		 10003
category_level_3_name string 1024 L3类别名称
（可变值）		 Men Clothes
category_level_4_id int 否 L4类别ID
（可变值）		 10004
category_level_4_name string 1024 L4类别名称
（可变值）		 Men Clothes
category_level_5_id int 否 L5类别ID
（可变值）		 10005
category_level_5_name string 1024 L5类别名称
（可变值）		 Men Clothes
sell_type int 是 销售类型
（固定枚举值）		 0-invalid
1-Carton(箱)
2-Pcs(件)
3-Pack(排）
4-Unknow
sell_type_name string 是 16 销售类型名称
（固定枚举值）		 见sell_type
business_type int 是 sku类别
（固定枚举值）		 0 - Unknow
1- FRS
2- FBS
3-Normal Retail
4-SCS
business_type_name string 是 16 sku类别名称
（固定枚举值）		 见business_type
variation1 string 否 64 Listing 变体1
（可变值）		 Black
variation2 string 否 64 Listing 变体2
（可变值）		 45
shop_list List 否 sku所属店铺列表
sku_size_type_id string 是 64 sku size type 唯一ID
（可变值）		 S001
sku_size_type int 是 sku类型枚举
（固定枚举值）		 0-Medium
1-Extra Small
2-Small
8-Large
10-Bulky
16-Extra Large
20-Extra Bulky
sku_size_type_desc string 是 16 sku的类型描述
（固定枚举值）		 Medium
sku_size_type_name string 是 128 sku的类型名称
（可变值）		 0cm3-1000cm3
cb_option int 是 是否跨境 0-否
1-是
listing_seller_spu string 否 256 （可变值） 111
listing_seller_sku string 否 256 （可变值） 2222
outer_packaging int 是 外包材
（固定枚举值）		 0-unknow
1-Inherit
2-Pouch(manual)
3-Box(manual)
4-Pouch(inherit)
5-Box(inherit)
6-PE Wrap(manual)
7-PE Wrap(inherit)
8-Bubble Wrap Outer(manual)
9-Bubble Wrap Outer(inherit)
outer_packaging_name string 是 64 外包材名称
（固定枚举值）		 见outer_packaging
inner_packaging List 否

SkuTag

字段名 类型 是否必须 最大长度 说明 示例
sku_tag_id string 是 sku tag id号
（可变值）
sku_tag_name string 是 sku tag名称
（可变值）
sku_tag_type_id string 是 16 sku tag 类型
（可变值）		 Color
sku_tag_type_name string 是 64 sku tag 名称
（可变值）		 Yellow

Shop

字段名 类型 是否必须 最大长度 说明 示例
shop_id int 是 Shop id
（可变值）		 123
shop_name string 是 1024 shop 名称
（可变值）		 xx小店

Consumable

字段名 类型 是否必须 最大长度 说明 示例
consumable_id string 是 36 consumable id
（可变值）		 CS00015
consumable_name string 是 128 consumable 名称
（可变值）		 123qwe##
count int 是 数量
（可变值）		 2
返回码
返回码 描述 说明 是否需要自动重试
-10000001 参数错误 否
-10004003 sku不存在 否

5.6 WMS向Vendor同步sku信息

接口URL 接口描述 调用方 业务要求
/api/v2/automation/tovendor/basic/sku/sync_sku_info WMS向Vendor同步sku信息 Shopee
接口系统要求
Avg RT Timeout 幂等字段 降级方案
500ms 10s sku_id 无
请求字段
字段名 类型 是否必须 最大长度 说明 示例
whs_id string 是 仓库编号 SGL
sku_list List 是 与查询接口相同的结构体
响应字段
字段名 类型 是否必须 最大长度 说明 示例
无
返回码
返回码 描述 说明 是否需要自动重试
-10014001 参数非法 比如参数是否必填、类型不符、长度不正确、非法字符、主键重复等
-10014010 ABC未配置 本项目用不到
-10014011 SKU类型未配置 SKU类型未配置
-10014012 SKU组未配置 SKU组未配置
-10014098 其他非法操作 上述未枚举时兜底使用
-10014099 系统错误 如限流、数据库错误、内部错误等等

5.7 WMS向Vendor查询AGV设备信息

接口URL 接口描述 调用方 业务要求
/api/v2/automation/tovendor/basic/robot/query_agv_status WMS向Vendor查询AGV设备信息 Shopee
接口系统要求
Avg RT Timeout 幂等字段 降级方案
500ms 10s N/A 无
请求字段
字段名 类型 是否必须 最大长度 说明 示例
whs_id string 是 仓库编号 SGL
page_no int64 是 分页码，从1开始 1
page_size int64 是 分页大小，默认100，最大1000 20
robot_id_list List 否 robot id 列表，一次最多1000个 [
"1",
"2"
]
响应字段
字段名 类型 是否必须 最大长度 说明 示例
page_no int64 是 分页码，返回请求传的参数 1
page_size int64 是 分页大小，返回请求传的参数 20
list List 是 每台Agv状态信息

AgvStatus

字段名 类型 是否必须 最大长度 说明 示例
robot_id string 是 32 机器人唯一编码 00001
robot_type int 是 机器人类型 0-未知
1-拣货机器人
2-搬运机器人
3-拣货搬运一体机器人
root_ip string 是 64 机器人ip 192.168.1.2
battery int 是 机器人电量，0-100 100
status_list List 是 机器人状态列表，包括：连接状态、
行为状态、异常状态、在场状态
（vendor侧不确认的状态可与shopee沟通）
robot_direction int 否 机器人方向，0-360度 180
position_x int 否 机器人x坐标，毫米 100
position_y int 否 机器人y坐标，毫米 200
position_z int 否 机器人z坐标，毫米 300
speed int 否 机器人速度，mm/s 100

Status

字段名 类型 是否必须 最大长度 说明 示例
connection_status int 是 连接状态
（固定枚举值）		 0-未知
1-在线
2-离线
task_status int 是 行为状态
（固定枚举值）		 0-未知
1-空闲
2-充电
3-执行任务
4-暂停
5-异常
task_desc string 是 1024 行为描述 升举货架
移动中
exception_status int 是 异常状态
（固定枚举值）		 0-未知
1-正常
2-异常
exception_desc string 是 1024 异常描述 充电桩异常
onsite_status int 是 在场状态
（固定枚举值）		 0-未知
1-在场
2-离场
返回码
返回码 描述 说明 是否需要自动重试
-10014001 参数非法 比如参数是否必填、类型不符、长度不正确、非法字符、主键重复等

5.8 WMS向Vendor查询Unit 信息

接口URL 接口描述 调用方 业务要求
/api/v2/automation/tovendor/basic/inventory/query_vendor_unit_list WMS向Vendor查询Unit 信息 Shopee
接口系统要求
Avg RT Timeout 幂等字段 降级方案
500ms 10s N/A 无
请求字段
字段名 类型 是否必须 最大长度 说明 示例
whs_id string 是 仓库编号 SGL
page_no int64 是 分页码，从1开始 1
page_size int64 是 分页大小，默认100，最大1000 20
batch_no_list List 否 batch_no 列表，一次最多1000个 [
1,
2
]
响应字段
字段名 类型 是否必须 最大长度 说明 示例
page_no int64 是 分页码，返回请求传的参数 1
page_size int64 是 分页大小，返回请求传的参数 20
list List 是 每个 unit 的信息

UnitItem

字段名 类型 是否必须 最大长度 说明 示例
sku_id string 是 32 sku id 00001
batch_no int64 是 bigint 批次号 20250110111
unit_id string 是 64 unit id 123141341
返回码
返回码 描述 说明 是否需要自动重试
-10014001 参数非法 比如参数是否必填、类型不符、长度不正确、非法字符、主键重复等
-10014099 系统错误 如限流、数据库错误、内部错误等等

附录

A.1 返回码

返回码分为成功返回码和错误返回码，其中成功返回码为0，错误返回码为一个8位的负数。vendor调用shopee的返回错误码格式为-1000xxxx，shopee调用vendor的返回错误码格式为

-1001xxxx，后四位分成不同号段由不同模块使用。其中：0000-0999为公共错误，1000-1999

为入库业务错误，2000-2999为出库业务错误，3000-3999为库内业务错误，4000-4999为基础资料业务错误。

成功返回码

返回码 成功描述 说明
0 success 请求成功

vendor调用shopee公共错误码, 业务模块错误码详见各接口返回码说明

错误码 错误描述 说明 是否需要自动重试
-10000000 鉴权失败 内容/格式错误,检查请求account/时间戳/Authorization 否
-10000001 请求参数错误 参数不对，检查请求参数 否
-10000002 系统错误 系统内部异常 是
-10000003 请求IP不在白名单 IP不对 否
-10000004 请求量过大 限流错误 否
-10000005 请求超时 请求超时 是

shopee调用vendor公共错误码, 业务模块错误码详见各接口返回码说明

错误码 错误描述 说明 是否需要自动重试
-10010000 鉴权失败 内容/格式错误,检查请求account/时间戳/Authorization 否
-10010001 请求参数错误 参数不对，检查请求参数 否
-10010002 系统错误 系统内部异常 是

A.2 测试环境

测试域名

Test环境：https://wms-automation.ssc.test.shopee.{cid}

UAT环境：https://wms-automation.ssc.uat.shopee.{cid}

Staging环境：https://wms-automation.ssc.staging.shopee.{cid}

A.3 DB数据字符集说明

需要支持特殊字符：DEFAULT CHARSET=utf8mb4 COLLATE=utf8mb4_unicode_ci

文档维护说明:

文档维护说明:

本文档由Shopee WMS团队维护

建议反馈请联系：tao.fu@shopee.com

Reference in New Issue View Git Blame Copy Permalink