# 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说明<br>4.1接口字段urgent_flag变更到attr_list中<br>4.3状态码更新<br>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字段说明<br>2.5 接口返回task_list说明<br>2.7 接口请求total_qty、putaway_qty、submit_qty字段说明<br>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字段<br>4.1和4.7AttrItem新增urgent_flag字段说明(红色标记)<br>出库模块 新增拣货明细id说明(橙色标记) |
| v1.0.9 | 2026-02-27 | Shopee WMS | 出库属性列表新增attr_value_type<br>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 | 出库(黄底标记)<br>3.1.7增加校验说明、参数返回说明<br>3.3.9 入参、出参与销售出库统一<br>3.4.7 出参与销售出库统一<br>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<br>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<br>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；<br>基础资料接口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）<br>3.3.3 res_list增加最大长度说明<br>3.1.7 过账相关接口的拣货id增加长度说明<br>batch_no、pickup_id类型为int64<br>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列表<br>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（生产环境无需填写）<br>{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<br>具体路径在接口协议中给定 |
| 请求头 | Content-Type | string | 是 | 用于指定数据格式<br>值固定为：application/json |
|  | Authorization | string | 是 | 用于鉴权(有效期5分钟)<br>值为：<br>Bearer <JWT token><br>其中，Bearer + 空格为固定部分，JWT token生成参考author |
|  | X-Request-Id | string | 是 | 请求唯一ID<br>使用UUID V4生成，长度为36个字符串，如：a1444101-b3a9-47b6-9967-dc0a77c2e8b2 |
|  | X-Machine-Id | string | 否 | 自动化设备ID，和设备有关的操作需要加 |
|  | X-Operator | string | 否 | 操作员邮箱,和人有关要加(因某些异常而系统触发且无实际操作员则传vendor@shopee.com，如:30分钟系统缺货0捡回传，没有上墙的0捡回传等), 具体接口body里传的operator同逻辑。<br>和人无关或批量提交可不加 |
| 响应头 | 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的<JWT token>它是一组字符串，可以通过”.”切分成三个为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<br>具体路径在接口协议中给定 |
| 请求头 | Content-Type | string | 是 | 用于指定数据格式<br>值固定为：application/json |
|  | Authorization | string | 是 | 用于鉴权(有效期5分钟)值为：<br>Bearer <JWT token><br>其中，Bearer + 空格为固定部分，JWT token生成参考Authorization Jwt Token加密规范 |
|  | X-Request-Id | string | 是 | 请求唯一ID<br>使用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 <token>")

}

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


#### 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<BatchInfo> | 是 |  | 本任务的批次详情信息【批次号幂等】 | [] |

InboundTaskInfo


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

InboundSkuInfo


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

InboundUidInfo


| 字段名 | 类型 | 是否必须 | 最大长度 | 说明 | 示例 |
| --- | --- | --- | --- | --- | --- |
| unit_id | string | 是 | 64 | Unit id | "SGF9YP69HW1" |
| stock_status | int | 是 |  | Uid状态- 不包含wms系统的上架<br>0:未上架<br>1:已上架<br>这个状态是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质量:<br>0: Good<br>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 | 是 |  | 冻结类型:<br>0: Normal<br>1: Expiring<br>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。<br>2、如果wms执行了上架，不会实时同步给vendor，需要vendor定时或者节点触发主动从wms获取最新的任务状态和明细 |


| 接口系统要求 |  |  |  |
| --- | --- | --- | --- |
| Avg RT | Timeout | 幂等字段 | 降级方案 |
| 200ms | 10s | 无 | 无 |


##### 请求字段


| 字段名 | 类型 | 是否必须 | 最大长度 | 说明 | 示例 |
| --- | --- | --- | --- | --- | --- |
| whs_id | string | 是 | 16 | 仓库id |  |
| new_version | int64 | 是 |  | 变更版本 | 2，<br>版本号WES需要存储最新的 |
| update_type | int | 是 |  | 变更类型：bit位标识类型<br>0:wms作业 |  |
| task_info | InboundTaskUpdateInfo | 否 |  | 任务信息,vendor需要根据最新的值做处理更新任务,主要包含任务状态、任务明细、优先级的更新，如vendor不存在这个任务，直接返回成功即可。 | 哪些字段需要更新？ |

InboundTaskUpdateInfo


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

InboundSkuUpdateInfo


| 字段名 | 类型 | 是否必须 | 最大长度 | 说明 | 示例 |
| --- | --- | --- | --- | --- | --- |
| sku_id | string | 是 | 64 | Sku id | "43376943579_395240042371" |
| batch_id | string | 是 | 128 | 明细行唯一键 | 行号 |
| total_qty | int | 是 |  | sku当前批次总数【=已经上架+待上架】<br>wms会更新这个字段 | 100 |
| uid_list | List<String> | 否 |  | uid 管理且前置环节已经录入<br>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 | 否 |  | 创建结束时间，包含此时间<br>（下发时间的结束值） | 1767693430 |
| task_id_list | List<string> | 否 |  | 入库单据list | ["PASGC0002601060003"] |
| page_size | int | 否 |  | 页大小，默认50 | 50 |
| page_no | int | 否 |  | 页码，默认1 | 1 |


##### 响应字段


| 字段名 | 类型 | 是否必须 | 最大长度 | 说明 | 示例 |
| --- | --- | --- | --- | --- | --- |
| total | int | 是 |  | 总任务单据 | 10 |
| task_list | List<InboundTaskInfo> | 是 |  | 任务明细（需要包含任务和任务的明细） | [{}] |


##### 返回码


| 返回码 | 描述 | 说明 | 是否需要自动重试 |
| --- | --- | --- | --- |
| -10011001 | 参数非法 | 比如参数是否必填、类型不符、长度不正确、非法字符、主键重复等 | 否 |
| -10011099 | 系统错误 | 如限流、数据库错误、内部错误等等 | 是 |


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


| 接口URL | 接口描述 | 调用方 | 业务要求 |
| --- | --- | --- | --- |
|  |  |  |  |
| /api/v2/automation/toshopee/inbound/order/get_inbound_order | Vendor通过容器或者单据获取未完结的入库任务 | vendor | 1、Vendor本地找不到单据可以通过此接口请求wms获取进行中的单据。<br>2、通过此接口获取的任务wms会进行打标已经同步到了vendor，后续任务变更会通知到vendor |


| 接口系统要求 |  |  |  |
| --- | --- | --- | --- |
| Avg RT | Timeout | 幂等字段 | 降级方案 |
| 200ms | 10s | 无 | 无 |


##### 请求字段


| 字段名 | 类型 | 是否必须 | 最大长度 | 说明 | 示例 |
| --- | --- | --- | --- | --- | --- |
| whs_id | string | 是 | 16 | 仓库id |  |
| search_key | string | 是 |  | 用户扫描内容，获取入库单据的标识码，支持device_id,或者order_no[反拣]/<br>针对反拣场景，支持进入作业的方式比较多，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<BatchInfo> | 是 |  | 本任务的批次详情信息【批次号幂等】 | [] |


##### 返回码


| 返回码 | 描述 | 说明 | 是否需要自动重试 |
| --- | --- | --- | --- |
| 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 | 否 |  | 创建开始时间<br>对于已完成任务，完成时间超过1个月不在支持查询（查询不到，不会报错）。 | 1767261430 |
| end_time | int | 否 |  | 创建结束时间<br>end_time-start_time间隔，不能超过7天<br>end_time、start_time必须同时指定。<br>[start_time,end_time]为闭区间，start_time <=X<=end_time。 | 1767693430 |
| task_id_list | List<string> | 否 |  | 入库单据list，长度不能超过2000<br>1. task_id_list和<start_time<br>,end_time>两个参数必须传其中一个。<br>对于已完成任务，完成时间超过1个月不在支持查询（查询不到，不会报错）。 | ["PASGC0002601060003"] |
| page_size | int | 否 |  | 页大小，未传默认50<br>最大不能超过200 | 50 |
| page_no | int | 否 |  | 页码，未传默认1 | 1 |


##### 响应字段


| 字段名 | 类型 | 是否必须 | 最大长度 | 说明 | 示例 |
| --- | --- | --- | --- | --- | --- |
| total | int | 是 |  | 总任务单据 | 10 |
| task_list | List<InboundTaskInfo> | 是 |  | 任务明细，会变更的字段参考2.2接口<br>如果某个SKU全部在WMS上架，将不返回这条SKU明细。<br>如果整个任务的全部SKU都在WMS上架，将返回任务，但SKU列表是空的。<br>如果任务的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<br>【单据维度】 | 无 |

库存一致性保障方式：

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，幂等字段,<br>整个单据维度幂等 | "1767693430000123"，<br>提交上架的明细是同一条的时候，requestid需要相同 |
| putaway_type | int |  |  | 上架方式：<br>倒箱（收货）：11<br>离线支架（整箱上架）：12<br>在线循环（by sku）：13<br>输送线：14 |  |
| sku_list | List<PutawaySkuInfo> | 是 |  | 上架明细，其中的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，<br>明细的计划数量 |
| putaway_qty | int | 是 |  | sku当前明细行已经上架数量，总数减去次数量为剩余数量，wms内部做对比，对不上时仅内部告警。 | 10，<br>明细的已经上架的数量 |
| submit_qty | int | 是 |  | 此次上架数量，不能超过剩余数量，超过时直接报错，整个请求都不成功。 | 20，<br>明细的本次上架的数量 |
| uid_list | List<String> | 否 |  | 上架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<String> | 否 |  | 不合法的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区。<br>-此接口一定在过账接口提交完成之后异步调用，否则过账接口还没提交会导致库存对不齐。 |


| 接口系统要求 |  |  |  |
| --- | --- | --- | --- |
| 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<InboundSkuInfo> | 是 |  | 上架明细，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<String> | 是 |  | Uid List,不能重复 | ["SGF9YP69HW1",<br>"SGF9YP69HW2"] |
| operator | string | 是 | 64 | 操作人邮箱 | xxx@shopee.com |


##### 响应字段


| 字段名 | 类型 | 是否必须 | 最大长度 | 说明 | 示例 |
| --- | --- | --- | --- | --- | --- |
| invalid_uid_list | List<String> | 是 |  | 不合法的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 (<br>SkuSizeTypeExtraSmall SkuSizeType = 1<br>SkuSizeTypeSmall SkuSizeType = 2<br>SkuSizeTypeMedium SkuSizeType = 0<br>SkuSizeTypeLarge SkuSizeType = 8<br>SkuSizeTypeSuperLarge SkuSizeType = 16<br>SkuSizeTypeBulky SkuSizeType = 10<br>SkuSizeTypeExtraBulky SkuSizeType = 20<br>SkuSizeTypeDefault SkuSizeType = 99<br>SkuSizeTypeNone SkuSizeType = -2<br>)<br>var SkuSizePriorityMap = map[SkuSizeType]int64{<br>SkuSizeTypeExtraSmall: 1,<br>SkuSizeTypeSmall: 2,<br>SkuSizeTypeMedium: 3,<br>SkuSizeTypeLarge: 4,<br>SkuSizeTypeSuperLarge: 5,<br>SkuSizeTypeBulky: 6,<br>SkuSizeTypeExtraBulky: 7,<br>} |  |
| 3.2.1 销售出库下发order | order_structure | const (<br>SalesOrderSkuQtyTypeSingleSkuSingleQty SalesOrderSkuQtyType = 1<br>SalesOrderSkuQtyTypeSingleSkuMultiQty SalesOrderSkuQtyType = 2<br>SalesOrderSkuQtyTypeMultiSku SalesOrderSkuQtyType = 3<br>SalesOrderSkuQtyTypeUndefined SalesOrderSkuQtyType = 10<br>)<br>var SalesOrderSkuQtyType2NameMap = map[SalesOrderSkuQtyType]string{<br>SalesOrderSkuQtyTypeSingleSkuSingleQty: "SSSQ",<br>SalesOrderSkuQtyTypeSingleSkuMultiQty: "SSAQ",<br>SalesOrderSkuQtyTypeMultiSku: "MSAQ",<br>} |  |
| 3.2.1 销售出库下发order | order_size | const (<br>SkuSizeTypeExtraSmall SkuSizeType = 1<br>SkuSizeTypeSmall SkuSizeType = 2<br>SkuSizeTypeMedium SkuSizeType = 0<br>SkuSizeTypeLarge SkuSizeType = 8<br>SkuSizeTypeSuperLarge SkuSizeType = 16<br>SkuSizeTypeBulky SkuSizeType = 10<br>SkuSizeTypeExtraBulky SkuSizeType = 20<br>SkuSizeTypeDefault SkuSizeType = 99<br>SkuSizeTypeNone SkuSizeType = -2<br>)<br>var SkuSizePriorityMap = map[SkuSizeType]int64{<br>SkuSizeTypeExtraSmall: 1,<br>SkuSizeTypeSmall: 2,<br>SkuSizeTypeMedium: 3,<br>SkuSizeTypeLarge: 4,<br>SkuSizeTypeSuperLarge: 5,<br>SkuSizeTypeBulky: 6,<br>SkuSizeTypeExtraBulky: 7,<br>} |  |
| 销售出库 | inner_packaging<br>、<br>outer_packaging的type枚举 | const (<br>ConsumableSpecialTypeNoneSuggested = -1<br>ConsumableTypePackingBox ConsumableType = 1<br>ConsumableTypePouch ConsumableType = 2<br>ConsumableTypeStationeries ConsumableType = 3<br>ConsumableTypeFillers ConsumableType = 4<br>ConsumableTypeStretchFilms ConsumableType = 5<br>ConsumableTypeOthers ConsumableType = 6<br>ConsumableTypeSticker ConsumableType = 7<br>ConsumableTypeBubbleWrap ConsumableType = 8<br>ConsumableTypePEWrap ConsumableType = 9<br>ConsumableTypeGift ConsumableType = 10<br>ConsumableTypeBubbleWrapOuter ConsumableType = 11<br>)<br>var ConsumableTypeValueToName = map[int64]string{<br>ConsumableTypePackingBox: "PackingBox",<br>ConsumableTypePouch: "Pouch",<br>ConsumableTypeStationeries: "Stationeries",<br>ConsumableTypeFillers: "Fillers",<br>ConsumableTypeStretchFilms: "StretchFilms",<br>ConsumableTypeOthers: "Others",<br>ConsumableTypeSticker: "Sticker",<br>ConsumableTypeBubbleWrap: "BubbleWrap",<br>ConsumableTypePEWrap: "PEWrap",<br>ConsumableTypeGift: "Gift",<br>ConsumableTypeBubbleWrapOuter: "BubbleWrapOuter",<br>} |  |
| 3.3.1 RTS/MTO下发需求 | order_source<br>（MTO) | const (<br>mtoCreateChannelWMS MTOCreateChannel = 0<br>mtoCreateChannelPMS MTOCreateChannel = 1<br>mtoCreateChannelFBS MTOCreateChannel = 2<br>) |  |
| 3.3.1 RTS/MTO下发需求 | transported_by | const (<br>MTOTransportedByOthers MTOTransportedBy = 0<br>MTOTransportedBySpx MTOTransportedBy = 1<br>) |  |
| 3.3.1 RTS/MTO下发需求 | biz_type | const (<br>SkuBusinessTypeUndefined SkuBusinessType = 0<br>SkuBusinessTypeFRS SkuBusinessType = 1<br>SkuBusinessTypeFBS SkuBusinessType = 2<br>SkuBusinessTypeNormalRetail SkuBusinessType = 3<br>SkuBusinessTypeSCS SkuBusinessType = 4<br>) |  |
| 3.3.1 RTS/MTO下发需求 | delivery_method | const (<br>RTSPickUpBySuppliers RTSDeliveryMethod = 1<br>RTSPickUpBySupplierDuringInbound RTSDeliveryMethod = 2<br>RTSShopeeSendsBack RTSDeliveryMethod = 3<br>RTSThrowAway RTSDeliveryMethod = 4<br>)<br>var DeliveryMethodDescMap = map[RTSDeliveryMethod]string{<br>RTSPickUpBySuppliers: "Pick Up By Suppliers",<br>RTSPickUpBySupplierDuringInbound: "Pick Up By Supplier During Inbound",<br>RTSShopeeSendsBack: "Shopee Sends Back",<br>RTSThrowAway: "Throw Away",<br>} |  |
| 3.3.1 RTS/MTO下发需求 | rts_reason | const (<br>RealRTSReasonSupplierRequest RTSReason = "R1"<br>RealRTSReasonAgingProduct RTSReason = "R2"<br>RealRTSReasonManufacturingDefective RTSReason = "R3"<br>RealRTSReasonExpired RTSReason = "R4"<br>RealRTSReasonBuyerReturn RTSReason = "R5"<br>RealRTSReasonOther RTSReason = "R6"<br>RealRTSReasonExpiring RTSReason = "R7"<br>RealRTSSellerRequest RTSReason = "R8"<br>RealRTSDamagedAndExpiry RTSReason = "R9"<br>// deprecated<br>RealRTSReasonInboundRTS RTSReason = "R10"<br>// Resell Phase II 新增 reason<br>RealRTSReasonReSellFailInsurance RTSReason = "R11"<br>RealRTSReasonReSellFailNonInsurance RTSReason = "R12"<br>RealRTSReasonShopExitInsurance RTSReason = "R13"<br>RealRTSReasonShopExitNonInsurance RTSReason = "R14"<br>VirtualRTSReasonSkuIdSwap RTSReason = "VR-IB1"<br>VirtualRTSReasonSkusBundling RTSReason = "VR-IB2"<br>VirtualRTSReasonOthers RTSReason = "VR-IB3"<br>ReplacementRTSReasonDamaged RTSReason = "RP1"<br>)<br>var WmsReturnReasonToIscReturnReasonMap = map[string]pb.RtsReason{<br>"R1": pb.RtsReason_RtsReasonSupplierRequest,<br>"R2": pb.RtsReason_RtsReasonAgingProduct,<br>"R3": pb.RtsReason_RtsReasonManufacturingDefectiveOrExpired,<br>"R4": pb.RtsReason_RtsReasonExpired,<br>"R5": pb.RtsReason_RtsReasonBuyerReturn,<br>"R6": pb.RtsReason_RtsReasonOthers,<br>"R7": pb.RtsReason_RtsReasonExpiring,<br>"R8": pb.RtsReason_RtsReasonSellerRequest,<br>"R9": pb.RtsReason_RtsReasonDamagedAndExpiry,<br>"R10": pb.RtsReason_RtsReasonInboundRts,<br>"VR-IB1": pb.RtsReason_RtsReasonSkuIdSwap,<br>"VR-IB2": pb.RtsReason_RtsReasonSkuBundling,<br>"VR-IB3": pb.RtsReason_RtsReasonOthers,<br>"RP1": pb.RtsReason_RtsReasonDamagedItems,<br>} |  |
| 3.3.1 RTS/MTO下发需求 | order_source<br>（RTS） | const (<br>RTSCreateChannelWMS RTSCreateChannel = 0<br>RTSCreateChannelPMS RTSCreateChannel = 1<br>) |  |


|  | 错误码汇总 |
| --- | --- |
| 销售出库 | const (<br>ErrOutboundVendorCopierFail = -10002000 // 参数拷贝失败<br>ErrOutboundVendorParam = -10002001 // 参数错误<br>ErrOutboundVendorFailOrder = -10002002 // 订单加入波次失败<br>ErrOutboundVendorCreatePickingTask = -10002003 // 创建波次失败<br>ErrOutboundVendorTaskEmpty = -10002004 // 波次为空<br>ErrOutboundVendorTaskStatus = -10002005 // 波次状态不对<br>ErrOutboundVendorTaskSource = -10002006 // 波次来源不对<br>ErrOutboundVendorRespEmpty = -10002007 // 外部响应为空<br>ErrOutboundVendorCompleteInterOrder = -10002008 // complete接口 订单列表交集错误<br>ErrOutboundVendorPickupIDUsed = -10002009 // 波次ID已被使用<br>ErrOutboundVendorChangeInterOrder = -10002010 // 换箱接口 订单列表交集错误<br>ErrOutboundVendorDeviceError = -10002011 // device 错误<br>ErrOutboundVendorRetCode = -10002012 // 调用vendor封装错误码<br>ErrOutboundVendorUnitError = -10002013 // 拣货明细校验错误<br>ErrOutboundVendorOthers = -10002014 // 其他业务类错误码<br>) |
| RTS | const (<br>ErrRtsVendorParam = -10002501<br>ErrRtsVendorSystemError = -10002502<br>ErrRtsVendorRequireNotFound = -10002503<br>ErrRtsVendorRequireNotToVendor = -10002504<br>ErrRtsVendorSubRequireAlreadyDone = -10002505<br>ErrRtsVendorRequireStatusNotAssigned = -10002506<br>ErrRtsVendorFlowModeMismatch = -10002507<br>ErrRtsDeviceNotAllow = -10002508<br>) |
| MTO | const (<br>ErrMtoVendorParams = -10002801<br>ErrMtoVendorStartPickingTask = -10002802<br>ErrMtoVendorBindDevice = -10002803<br>ErrMtoVendorSyncPickingDetail = -10002804<br>ErrMtoVendorCompletePickingTask = -10002805<br>) |


#### 3.1 销售出库自动化SubPickingTask


##### 3.1.1 WMS给Vendor下发拣货任务


| 接口URL | 接口描述 | 调用方 | 业务要求 |
| --- | --- | --- | --- |
|  |  |  |  |
| /api/v2/automation/tovendor/outbound/salesorder/create_sub_picking_task | WMS给Vendor下发拣货任务 | shopee | 占用库存要求：<br>批次属性必须是：好品+normal<br>该任务不可混合其他任务一起拣货，不可追加明细<br>若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<br>shipment_header.shopeeWave-新增字段，shopee波次号<br>同步接到两个字段中 |
| 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<br>新增字段，是否混拣 |
| group_key | string | 是 | 128 | 特征值，若可混拣，则有值 | xxx_xx_xx_xx | shipment_header.groupKey<br>新增字段，混拣特征值 |
| sku_info_list | List<SkuInfo> | 是 |  | 期望拣货数量 |  | 明细取值见下文 |
| single_attr_list | List<SingleAttr> | 是 |  | 属性列表（单属性）<br>当前有：<br>process_guide<br>spx_single_store<br>spx_store_group_template<br>spx_store_group_id<br>max_order_size |  | max_order_size接到shipment_header.orderSize-新增字段 |
| multi_attr_list | List<MultiAttr> | 是 |  | 属性列表（多属性）<br>当前attr_key有：<br>channel_id、fulfillment_chain_id |  | channel_id接到shipment_header.channelId-新增字段<br>fulfillment_chain_id接到shipment_header.fulfillmentChainId-新增字段 |
| ticket_type | int | 是 |  | 单据类型：<br>1: 销售出库下发task 2:销售出库下发order 3:rts需求池需求 4: mto需求池需求 5: mto下发任务 6: RT | 1 | shipment_header.ticketType-新增字段 |
|  |  |  |  |  |  | shipment_header.shipmentType<br>默认：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<br>指定冻结类型（Normal/临期/过期）<br>SKUBlockTypeNoNeed SKUBlockType = 0<br>SKUBlockTypeEXPIRING SKUBlockType = 1<br>SKUBlockTypeEXPIRED SKUBlockType = 3 | 0 | shipment_detail.shelfLifeSts<br>效期状态 |
| quality | int | 是 |  | 0 好品<br>指定好/坏品<br>SkuQualityTypeGood SkuQualityType = 0<br>SkuQualityTypeDamage SkuQualityType = 1 | 0 | shipment_detail.inventorySts<br>库存状态 |

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的枚举<br>（有些属性需要支持类型筛选） | 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<Attr> | 是 |  | 属性value列表 | [<br>{<br>"attr_value_id":"30005",<br>"attr_value_name":"SPX"<br>},<br>{<br>"attr_value_id":"30006",<br>"attr_value_name":"SPD"<br>}<br>] |  |

Attr字段详情


| 字段名 | 类型 | 是否必须 | 最大长度 | 说明 | 示例 |  |
| --- | --- | --- | --- | --- | --- | --- |
| attr_value_id | string | 是 |  | 属性value | "30005" | config_detail.identifier |
| attr_value_type | string | 否 | 128 | 属性 type的枚举<br>（有些属性需要支持类型筛选） | 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也支持取消）<br>注意：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标。<br>注意：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 | 是 |  | 单据类型：<br>单据类型：<br>1: 销售出库下发task 2: 销售出库下发order 3:rts需求池需求 4: mto 需求池需求 5: mto下发任务 6: RT | 1 | shipment_header.ticketType |
| ticket_number_list | List<string> | 是 | 32 | 单据列表 | ["202104220002_0"] | shipment_header.erpOrderCode |
| urgent_flag | int | 是 |  | 0~99 越大越紧急 | 0 | shipment_header.priority<br>更新该字段 |


###### 响应字段


| 字段名 | 类型 | 是否必须 | 最大长度 | 说明 | 示例 |
| --- | --- | --- | --- | --- | --- |
| success_list | List<string> | 是 | 200 |  |  |
| fail_list | List<string> | 是 | 200 |  |  |
| not_exist_list | List<string> | 是 | 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 | 同步调用，需要重试，接口未成功阻塞该波次的后续作业流程<br>必须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 | 是 |  | 工作站类型<br>单据分播流程、分播出库流程<br>1：vendor pick to order<br>2：vendor batch picking | 1 | 按照工作站选的类型取值 |
| pick_type | int | 是 |  | 1: pick to order(wave_type=0)对应vendor pick to order<br>2: pick to wave(wave_type=1\2\3\4\5) 对应vendor dynamic wave<br>3: flow pick(wave_type=1/5) | 1 | 如果工作站类型选的1：vendor pick to order则传1<br>如果waveType=1或5则传3<br>否则传2 |
| wave_type | int | 是 |  | 1: SingleSkuSingleQtyWave<br>2: SameSkuSameQtyWave3: MixWave 4: SingleSkuAndAnyQtyWave<br>5: MixSkuSingleQtyWave |  | waveType |
| operator | string | 是 | 64 | operator邮箱<br>有场景没有（自动开班） | 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 | 作业接口，拣货员同步调用<br>必须WMS成功再Vendor成功<br>销售出库自动化SubPickingTask和自动化order共用<br>同步调用，需要重试，接口未成功阻塞该波次的后续作业流程 |


| 接口系统要求 |  |  |  |
| --- | --- | --- | --- |
| 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<br>分拣墙格口绑定的目标容器号 |
| station_type | int | 是 |  | 工作站类型<br>单据分播流程、分播出库流程<br>1：vendor pick to order<br>2：vendor batch picking | 1 | 按照工作站选的类型取值 |
| grid_no | string | 是 |  | 格口号 | Hik-A-1-1,<br>唯一码 | wcs_sorting_wall_cell.cellCode<br>分拣墙格口号 |
| 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 | 每次同步一批任务的明细，增量同步<br>业务侧延时1分钟一次，聚合调用<br>销售出库自动化SubPickingTask和自动化order共用<br>异步调用，接口失败需要重试 |


| 接口系统要求 |  |  |  |
| --- | --- | --- | --- |
| Avg RT | Timeout | 幂等字段 | 降级方案 |
| 1s | 10s | sub_pickup_id + id | 无 |


###### 请求字段


| 字段名 | 类型 | 是否必须 | 最大长度 | 说明 | 示例 | WES表字段（涉及客户化） |
| --- | --- | --- | --- | --- | --- | --- |
| whs_id | string | 是 | 16 | 仓库id | SGL | shipment_header.warehouseCode |
| sub_picking_task_list | List<SubPickingTaskInfo> | 是 | 100 | 拣货任务列表<br>每次调用最外层的sub_pickup_id不允许重复 | [<br>] | shipment_header.shopeeWave |

SubPickingTaskInfo字段详情


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

picked_info_list字段详情


| 字段名 | 类型 | 是否必须 | 最大长度 | 说明 | 示例 | WES表字段 |
| --- | --- | --- | --- | --- | --- | --- |
| id | string | 是 | 64 | vendor拣货id，待vendor提供<br>幂等用 |  | task_detail.taskCode |
| device_id | string | 是 | 16 | 拣货设备id | OPBSK11873 | wcs_sorting_wall_cell.containerCode<br>分拣墙格口绑定的目标容器号 |
| 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<UnitItem> | 否 | 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] | 序列号<br>根据拣货完成的明细lpn匹配序列号表lpn去查询序列号 |
| scan_time | int | 是 | 20 | 扫描时间 |  | 序列号表最后更新时间serial_number.lastUpdated |


###### 响应字段


| 字段名 | 类型 | 是否必须 | 最大长度 | 说明 | 示例 |
| --- | --- | --- | --- | --- | --- |
| success_list | List<string> | 是 |  | 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 | 作业接口，拣货员同步调用<br>必须WMS成功再Vendor成功<br>Vendor可以使用dynamic方式跑自动化SubPickingTask，支持发起换箱<br>和校验device接口不同的是，这里WMS会有逻辑处理<br>换箱成功后，WMS的旧箱不可再新增拣货明细<br>同步调用，需要重试，接口未成功阻塞该波次的后续作业流程 |


| 接口系统要求 |  |  |  |
| --- | --- | --- | --- |
| 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<br>分拣墙格口绑定的目标容器号-换箱后的 |
| station_type | int | 是 |  | 工作站类型<br>单据分播流程、分播出库流程<br>1：vendor pick to order<br>2：vendor batch picking | 1 | 按照工作站选的类型取值 |
| operator | string | 是 | 64 | operator邮箱 | xxx@shopee.com | 取工作站登录用户表的邮箱 |
| picked_info_list | List<SkuPickedInfo> | 是 |  | 旧箱拣货明细列表<br>注意：如果有多次换箱，那么这个列表是所有旧箱的拣货明细数据<br>(增量拣货明细有可能会丢请求) | 详见下表 | task_detail.targetContainer-新增字段，拣货实际拣到槽口绑定的料箱时需要将目标料箱号更新到任务明细targetContainer字段 |

picked_info_list字段详情


| 字段名 | 类型 | 是否必须 | 最大长度 | 说明 | 示例 | WES表字段 |
| --- | --- | --- | --- | --- | --- | --- |
| id | string | 是 | 64 | vendor拣货id，待vendor提供<br>增量拣货明细有可能会丢请求，幂等用 |  | 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<UnitItem> | 否 | 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] | 序列号<br>根据拣货完成的明细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 | 接口失败了需要弹窗提示失败原因<br>要求失败重试，重试时需保证每次重试的报文一致<br>每次增量明细库存应该是完成时明细库存的子集，即批次维度库存>=sum(增量明细库存)，如果出现异常判断为Vendor有bug需要排查修复<br>注意vn模式集货任务需要扫MergeLane，业务侧SOP保证对接vendor的任务不会出现。<br>异步调用，接口失败需要重试 |


| 接口系统要求 |  |  |  |
| --- | --- | --- | --- |
| 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<SkuPickedInfo> | 是 |  | 拣货明细列表<br>注意：这个列表是本波次所有的拣货明细数据<br>(增量拣货明细有可能会丢请求) | 详见下表 |  |

picked_info_list字段详情


| 字段名 | 类型 | 是否必须 | 最大长度 | 说明 | 示例 | WES表字段 |
| --- | --- | --- | --- | --- | --- | --- |
| id | string | 是 | 64 | vendor拣货id，待vendor提供<br>增量拣货明细有可能会丢请求，幂等用 |  | 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<UnitItem> | 否 | 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] | 序列号<br>根据拣货完成的明细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<string> | 是 | 32 | 任务id | ["202104220002_0"] | shipment_header.erpOrderCode |
| task_type | int | 是 |  | 1:销售出库、2:RTS、3:MTO |  | shipment_header.shipmentType |


###### 响应字段


| 字段名 | 类型 | 是否必须 | 最大长度 | 说明 | 示例 |
| --- | --- | --- | --- | --- | --- |
| task_info_list | List<TaskInfo> | 是 |  | 任务列表 | 详见下表 |

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


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

picked_info_list字段详情


| 字段名 | 类型 | 是否必须 | 最大长度 | 说明 | 示例 | WES表字段 |
| --- | --- | --- | --- | --- | --- | --- |
| id | string | 是 | 64 | vendor拣货id，待vendor提供<br>增量拣货明细有可能会丢请求，幂等用 |  | 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<UnitItem> | 否 | 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<br>RORWMSSGD00026010600003 | shipment_header.erpOrderCode |

UnitItem


| 字段名 | 类型 | 是否必须 | 最大长度 | 说明 | 示例 | WES表字段 |
| --- | --- | --- | --- | --- | --- | --- |
| unit_id | string | 是 | 32 | unit_id编码 | [“8u118”,”111] | 序列号<br>根据拣货完成的明细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<br>下单失败wms侧需要擦除预命中结果<br>30分钟未占用库存调用取消接口 |


| 接口系统要求 |  |  |  |
| --- | --- | --- | --- |
| Avg RT | Timeout | 幂等字段 | 降级方案 |
| 200ms | 10s | order_number + status<br>有可能重复下单，进行中的订单只有一个 | 无 |


###### 请求字段


| 字段名 | 类型 | 是否必须 | 最大长度 | 说明 | 示例 | 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<br>新增字段，是否混拣 |
| group_key | string | 是 | 128 | 特征值，若可混拣，则有值 | xxx_xx_xx_xx，<br>相同group_key可以混拣 | shipment_header.groupKey<br>新增字段，混拣特征值 |
| urgent_flag | int | 是 |  | 0~99 越大越紧急 | 99 | shipment_header.priority |
| cut_off_time | int | 是 |  | 任务截止时间，秒级时间戳，越小越优先出库 | 1767837541 | shipment_header.cutOffTime-新增字段<br>截止时间 |
| 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<SingleAttr> | 是 |  | 属性列表（单属性）<br>当前有：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同理<br>service_code接到shipment_header.serviceCode-新增字段<br>fulfillment_chain_id接到shipment_header.orderStructure-新增字段<br>order_size 接到shipment_header.orderSize-新增字段<br>shop_group接到shipment_header.shopGroup-新增字段<br>store_id接到<br>shipment_header.storeId-新增字段<br>delivery_region接到shipment_header.deliveryRegion-新增字段<br>lane_code接到shipment_header.laneCode-新增字段<br>outer_packaging接到shipment_header.outerPackaging-新增字段 |
| multi_attr_list | List<MultiAttr> | 是 |  | 属性列表（多属性）<br>shop_id、shopee_order_sn、inner_packaging |  | 插入数据字典逻辑与3.1.1同理<br>shop_id接到shipment_header.shopId-新增字段 |
| sku_info_list | List<SkuInfo> | 是 |  | Sku信息 |  | 明细取值见下文 |
| ticket_type | int | 是 |  | 单据类型：<br>单据类型：<br>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<br>指定冻结类型（Normal/临期/过期）<br>SKUBlockTypeNoNeed SKUBlockType = 0<br>SKUBlockTypeEXPIRING SKUBlockType = 1<br>SKUBlockTypeEXPIRED SKUBlockType = 3 | 0 | shipment_detail.shelfLifeSts<br>效期状态 |
| quality | int | 是 |  | 0 好品<br>指定好/坏品<br>SkuQualityTypeGood SkuQualityType = 0<br>SkuQualityTypeDamage SkuQualityType = 1 | 0 | shipment_detail.inventorySts<br>库存状态 |


###### 响应字段


| 字段名 | 类型 | 是否必须 | 最大长度 | 说明 | 示例 |
| --- | --- | --- | --- | --- | --- |
| 无 |  |  |  |  |  |


###### 返回码


| 返回码 | 描述 | 说明 | 是否需要自动重试 |
| --- | --- | --- | --- |
| -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<string> | 是 | 200 | 订单号列表 | [“OBCNG000260101081110”,”OBCNG000260101081112”] | shipment_header.erpOrderCode |


###### 响应字段


| 字段名 | 类型 | 是否必须 | 最大长度 | 说明 | 示例 |
| --- | --- | --- | --- | --- | --- |
| success_list | List<string> | 是 | 200 | 取消成功列表 |  |
| fail_list | List<string> | 是 | 200 | 取消失败列表 |  |
| not_exist_list | List<string> | 是 | 200 | 订单不存在列表 |  |


###### 返回码


| 返回码 | 描述 | 说明 | 是否需要自动重试 |
| --- | --- | --- | --- |
| -10012001 | 参数非法 | 比如参数是否必填、类型不符、长度不正确、非法字符、主键重复等 | 否 |
| -10012098 | 其他非法操作 | 上述未枚举时兜底使用 | 否 |
| -10012099 | 系统错误 | 如限流、数据库错误、内部错误等等 | 是 |


##### 3.2.3 Vendor向WMS撤单

错误码及幂等计算


| 接口URL | 接口描述 | 调用方 | 业务要求 |
| --- | --- | --- | --- |
|  |  |  |  |
| /api/v2/automation/toshopee/outbound/salesorder/cancel_order | Vendor向WMS撤回订单 | Vendor | 捞成功才可在wms侧进行拣货操作<br>如果是wms侧取消订单场景<br>vendor侧返回成功走现有正常订单取消流程 vendor侧返回失败走现有正常订单取消流程(所有订单取消场景不能取消picking task)<br>必须WMS成功再Vendor成功<br>同步调用，接口失败需要重试 |


| 接口系统要求 |  |  |  |
| --- | --- | --- | --- |
| Avg RT | Timeout | 幂等字段 | 降级方案 |
| 300ms | 10s |  | 无 |


###### 请求字段


| 字段名 | 类型 | 是否必须 | 最大长度 | 说明 | 示例 | WES表字段 |
| --- | --- | --- | --- | --- | --- | --- |
| whs_id | string | 是 | 16 | 仓库id | SGL | shipment_header.warehouseCode |
| order_number_list | List<string> | 是 | 200 | 订单号列表 | [“OBCNG000260101081110”,”OBCNG000260101081112”] | shipment_header.erpOrderCode |
| reason | string | 是 |  | 可能的取消原因（需要传英文）：<br>缺货取消<br>创建任务被踢出导致的取消<br>其他..... |  | 跑波次缺货取消的传1<br>拿波次号和订单请求上游集波验证失败踢单的也需要请求该接口传2<br>除以上两种情况外是3（是备用无逻辑走3） |


###### 响应字段


| 字段名 | 类型 | 是否必须 | 最大长度 | 说明 | 示例 |
| --- | --- | --- | --- | --- | --- |
| success_list | List<string> | 是 | 200 | 取消成功列表 |  |
| fail_list | List<string> | 是 | 200 | 取消失败列表 |  |
| not_exist_list | List<string> | 是 | 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<string> | 是 | 200一批 | 订单列表 | [“OBCNG000260101081110”,”OBCNG000260101081112”] | shipment_header.erpOrderCode |
| request_type | int | 是 |  | 1:上锁/0:解锁 | 1，<br>不允许取消则不允许上锁 | 传1则WES走base标记挂起，标记的单子集波不抓<br>传0则将挂起标记的恢复正常 |


###### 响应字段


| 字段名 | 类型 | 是否必须 | 最大长度 | 说明 | 示例 |
| --- | --- | --- | --- | --- | --- |
| success_list | List<string> | 是 | 200 |  |  |
| fail_list | List<string> | 是 | 200 |  |  |
| not_exist_list | List<string> | 是 | 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 | 建议当天使用当天的号段<br>失败重试 |


| 接口系统要求 |  |  |  |
| --- | --- | --- | --- |
| 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<string> | 是 |  | 号段列表 | [“202104220002_0”,”202104220003_0”]<br>获取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属性, 订单状态变更等场景 失败需要支持重试, 增加告警<br>必须WMS成功再Vendor成功<br>同步调用，需要重试，接口未成功阻塞该波次的后续作业流程 |


| 接口系统要求 |  |  |  |
| --- | --- | --- | --- |
| 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 | 是 |  | 工作站类型<br>单据分播流程、分播出库流程<br>1：vendor pick to order<br>2：vendor batch picking | 1 | 按照工作站选的类型取值 |
| pick_type | int | 是 |  | 1: pick to order(wave_type=0)对应vendor pick to order<br>2: pick to wave(wave_type=1\2\3\4\5) 对应vendor dynamic wave<br>3: flow pick(wave_type=1/5) | 1 | 如果工作站类型选的1：vendor pick to order则传1<br>如果waveType=1或5则传3<br>否则传2 |
| wave_type | int | 是 |  | 1: SingleSkuSingleQtyWave<br>2: SameSkuSameQtyWave3: MixWave 4: SingleSkuAndAnyQtyWave<br>5: MixSkuSingleQtyWave |  | waveType |
| order_number_list | List<string> | 是 |  | 订单号列表 | [“OBCNG000260101081110”,”OBCNG000260101081112”] | shipment_header.erpOrderCode |
| operator | string | 是 | 64 | operator邮箱 | xxx@shopee.com | 取工作站登录用户表的邮箱 |


###### 响应字段


| 字段名 | 类型 | 是否必须 | 最大长度 | 说明 | 示例 |
| --- | --- | --- | --- | --- | --- |
| task_attr_info | TaskAttrInfo | 是 |  | task属性 wms返回 vendor需要更新 |  |
| fail_order_list | List<string> | 是 |  | 返回码为失败的情况下可能会有该字段（参考错误码），表示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<SingleAttr> | 是 |  | 属性列表（单属性）<br>同3.1.1的属性说明 |  |  |
| multi_attr_list | List<MultiAttr> | 是 |  | 属性列表（多属性）<br>同3.1.1的属性说明 |  |  |
|  |  |  |  |  |  |  |


###### 返回码


| 返回码 | 描述 | 说明 | 是否需要自动重试 |
| --- | --- | --- | --- |
| -10002000 | 参数拷贝失败 | 内部参数拷贝失败 | 是 |
| -10002001 | 参数错误 | 参数错误 | 是 |
| -10002009 | 波次ID已被使用 | 波次ID已被使用 | 是，换一个波次ID进行重试 |
| -10002002 | 订单不支持进入波次 | 订单不支持进入波次<br>订单进入了其他波次<br>订单占用库存失败 | 否，踢单，捞单 |
| -10002003 | 创建波次失败 | 创建波次失败 | 是 |
| -10002014 | 其他业务类错误 | 其他业务类错误 | 是 |


##### 3.2.8 Vendor向WMS追加明细


| 接口URL | 接口描述 | 调用方 | 业务要求 |
| --- | --- | --- | --- |
|  |  |  |  |
| /api/v2/automation/toshopee/outbound/salesorder/append_order | 追加 | Vendor | 只做追加动作<br>只要创建任务成功了，随时有可能调用追加接口<br>逻辑说明<br>如果创建订单1，2成功，追加时追加订单1，2不会报错 => 相当于没有追加任何订单<br>如果创建订单1，2成功，追加时追加订单1，2，3可以成功 => 表现为追加了一个单<br>如果创建订单1，2失败，追加时追加订单1，2会报错 => 因为都没有任务<br>同步调用，需要重试，接口未成功阻塞该波次的后续作业流程 |


| 接口系统要求 |  |  |  |
| --- | --- | --- | --- |
| 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<string> | 是 |  | 追加的订单列表 | [“OBCNG000260101081110”,”OBCNG000260101081112”] | shipment_header.erpOrderCode |


###### 响应字段


| 字段名 | 类型 | 是否必须 | 最大长度 | 说明 | 示例 |
| --- | --- | --- | --- | --- | --- |
| task_attr_info | TaskAttrInfo | 是 |  | task属性 wms返回 vendor需要更新 |  |
| fail_order_list | List<string> | 是 |  | 返回码为失败的情况下会有该字段，表示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<SingleAttr> | 是 |  | 属性列表（单属性）<br>同3.1.1的属性说明 |  |  |
| multi_attr_list | List<MultiAttr> | 是 |  | 属性列表（多属性）<br>同3.1.1的属性说明 |  |  |


###### 返回码


| 返回码 | 描述 | 说明 | 是否需要自动重试 |
| --- | --- | --- | --- |
| -10002000 | 参数拷贝失败 | 内部参数拷贝失败 | 是 |
| -10002001 | 参数错误 | 参数错误 | 是 |
| -10002005 | 波次状态不对 | 波次状态不对 | 否，退出这个波次的追加流程 |
| -10002009 | 波次ID已被使用 | 波次ID已被使用 | 是，换一个波次ID进行重试 |
| -10002002 | 订单不支持进入波次 | 订单不支持进入波次<br>订单进入了其他波次<br>订单占用库存失败 | 否，踢单，捞单 |
| -10002003 | 创建波次失败 | 创建波次失败 | 是 |
| -10002014 | 其他业务类错误 | 其他业务类错误 | 是 |


##### 3.2.9 flow pick换箱


| 接口URL | 接口描述 | 调用方 | 业务要求 |
| --- | --- | --- | --- |
|  |  |  |  |
| /api/v2/automation/toshopee/outbound/salesorder/change_device | 完成 | Vendor | 这种换箱是生成新的picking task<br>作业接口，必须WMS成功再Vendor成功<br>同步调用，需要重试，接口未成功阻塞该波次的后续作业流程 |


| 接口系统要求 |  |  |  |
| --- | --- | --- | --- |
| 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<PickedOrderInfo> | 是 |  | 满拣订单sku列表 |  | 整单全拣货的单据<br>明细见下文 |
| zero_order_info_list | List<string> | 是 |  | 0拣订单列表；<br>注意0拣时，订单在vendor终态了 | [“OBCNG000260101081110”,”OBCNG000260101081112”] | 整单未拣货的单据<br>明细见下文 |
| new_order_number_list | List<string> | 是 |  | 新task订单列表<br>长度必须>0 | [“OBCNG000260101081113”,”OBCNG000260101081114”] | 未拣货的订单<br>即组到新波次的订单 |
| operator | string | 是 | 64 | operator邮箱 | xxx@shopee.com | 取工作站登录用户表的邮箱 |

PickedOrderInfo字段详情


| 字段名 | 类型 | 是否必须 | 最大长度 | 说明 | 示例 | WES表字段 |
| --- | --- | --- | --- | --- | --- | --- |
| id | string | 是 | 64 | vendor拣货id，待vendor提供<br>增量拣货明细有可能会丢请求，幂等用 |  | 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<UnitItem> | 是 |  | 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<TaskAttrInfo> | 是 |  | 新老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<SingleAttr> | 是 |  | 属性列表（单属性）<br>同3.1.1的属性说明 |  |  |
| multi_attr_list | List<MultiAttr> | 是 |  | 属性列表（多属性）<br>同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<br>异步调用，接口失败需要重试 |


| 接口系统要求 |  |  |  |
| --- | --- | --- | --- |
| 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<PickedOrderInfo> | 是 |  | 满拣订单sku列表 |  | 整单全拣货的单据<br>明细见下文 |
| shortage_order_info_list | List<PickedOrderInfo> | 是 |  | 缺拣订单sku列表 |  | 整单部分拣货的单据<br>明细见下文 |
| zero_order_info_list | List<string> | 是 |  | 0拣订单列表；<br>注意0拣时，订单在vendor终态了 | [“OBCNG000260101081110”,”OBCNG000260101081112”] | 整单未拣货的订单 |
| operator | string | 是 |  | operator邮箱 | xxx@shopee.com | 取工作站登录用户表的邮箱 |

PickedOrderInfo字段详情


| 字段名 | 类型 | 是否必须 | 最大长度 | 说明 | 示例 | WES表字段 |
| --- | --- | --- | --- | --- | --- | --- |
| id | string | 是 | 64 | vendor拣货id，待vendor提供<br>增量拣货明细有可能会丢请求，幂等用 |  | 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<UnitItem> | 否 | 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] | 序列号<br>根据拣货完成的明细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<SingleAttr> | 是 |  | 属性列表（单属性）<br>同3.1.1的属性说明 |  |
| multi_attr_list | List<MultiAttr> | 是 |  | 属性列表（多属性）<br>同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<string> | 是 |  |  |  | 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 - 销售出库<br>2 - RTS<br>3 - MTO | 2 | shipment_header.shipmentType |
| res_list | List<ResInfo> | 是 |  | 需求列表<br>Mar 9: 当前res list长度最大1000 | 详见下表 |  |
| single_attr_list | List<SingleAttr> | 是 |  | 属性列表（单属性）<br>当前有：<br>to_whs<br>expected_ob_date<br>order_source<br>transported_by<br>biz_type<br>order_tag<br>supplier_id<br>delivery_method<br>return_date<br>rts_reason<br>order_source<br>04-14 新增: rts_type （20 - Real 30 - Virtual）<br>04-21 新增： sku_biz_type | 0509补充RTS、MTO属性keysRTS：<br>to_whs<br>expected_ob_date<br>order_source<br>supplier_id<br>delivery_method<br>return_date<br>rts_reason<br>rts_type<br>biz_type<br>MTO：<br>from_whs<br>to_whs<br>biz_type<br>sku_biz_type<br>order_flag<br>urgent_flag<br>create_time<br>expected_ob_date<br>order_source<br>transfer_type<br>注意:两者order_source枚举RTS和MTO不一样 |  |
| multi_attr_list | List<MultiAttr> | 是 |  | 属性列表（多属性）<br>当前attr_key有： |  |  |
| ticket_type | int | 是 |  | 单据类型：<br>单据类型：<br>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<br>根据该字段进行拆分单据 |
| sku_id | string | 是 | 64 | sku_id | 1767751294820_08379 | shipment_detail.itemCode |
| qty | int | 是 |  | 期望拣货数量 | 1 | shipment_detail.requestQty |
| block_type | int | 是 |  | 指定冻结类型（Normal/临期/过期）<br>SKUBlockTypeNoNeed SKUBlockType = 0<br>SKUBlockTypeEXPIRING SKUBlockType = 1<br>SKUBlockTypeEXPIRED SKUBlockType = 3 | 0 | shipment_detail.shelfLifeSts<br>效期状态 |
| quality | int | 是 |  | 0 好品<br>指定好/坏品<br>SkuQualityTypeGood SkuQualityType = 0<br>SkuQualityTypeDamage SkuQualityType = 1 | 0 | shipment_detail.inventorySts<br>库存状态 |
| group_key | string | 是 |  | 特征值（包含 delivery_method， supplier .. 决定是否能混拣） |  | shipment_header. groupKey新增字段，混拣特征值 |
| can_group_picking | int | 是 |  | 是否能和其他不一样特征值的需求混拣<br>0 - 不能混拣<br>1 - 可以混拣 | 默认0 | shipment_header. canGroupPicking<br>新增字段，是否混拣 |
| urgent_flag | int | 是 |  | 0~99 越大越紧急 | 99 | shipment_header.priority |
| demand_mode | int | 是 |  | 2 : single 模式<br>1 : mix 模式<br>展示用 | 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 - 销售出库<br>2 - RTS<br>3 - MTO | 2 | shipment_header.shipmentType |
| res_number_list | List<string> | 是 | 64 | RTS需求号列表 / MTO 需求号列表 | [RORWMSSGD00026010600003] | shipment_header.erpOrderCode |


###### 响应字段


| 字段名 | 类型 | 是否必须 | 最大长度 | 说明 | 示例 |
| --- | --- | --- | --- | --- | --- |
| success_list | List<string> |  |  | 取消成功的需求列表 |  |
| fail_list | List<string> |  |  | 取消失败的需求列表 |  |
| not_exist_list | List<string> |  |  | 不存在的的需求列表 |  |


###### 返回码


| 返回码 | 描述 | 说明 | 是否需要自动重试 |
| --- | --- | --- | --- |
| -10012001 | 参数非法 | 比如参数是否必填、类型不符、长度不正确、非法字符、主键重复等 | 否 |
| -10012098 | 其他非法操作 | 上述未枚举时兜底使用 | 否 |
| -10012099 | 系统错误 | 如限流、数据库错误、内部错误等等 | 是 |


##### 3.3.3 Vendor 向 WMS 同步占用信息


| 接口URL | 接口描述 | 调用方 | 业务要求 |
| --- | --- | --- | --- |
|  |  |  |  |
| /api/v2/automation/toshopee/outbound/rtsmto/sync_occupied_require | Vendor 向 WMS 同步占用信息 | vendor | 销售出库占用0库存时，触发的是捞单接口，而RTSMTO触发的是此接口<br>【注意此时没有波次ID】<br>同步调用，接口失败需要重试<br>要么一起成功要么一起失败 |


| 接口系统要求 |  |  |  |
| --- | --- | --- | --- |
| Avg RT | Timeout | 幂等字段 | 降级方案 |
| 1s | 10s | order_number, res_number | 无 |


###### 请求字段


| 字段名 | 类型 | 是否必须 | 最大长度 | 说明 | 示例 | WES表字段 |
| --- | --- | --- | --- | --- | --- | --- |
| whs_id | string | 是 | 16 | 仓库id | SGL | shipment_header.warehouseCode |
| biz_type | int | 是 | 4 | 任务类型：1 - 销售出库<br>2 - RTS<br>3 - MTO | 2 | shipment_header.shipmentType |
| res_list | List<ResInfo> | 是 |  | 需求列表，长度<2000 | 详见下表 |  |

ResInfo字段详情


| 字段名 | 类型 | 是否必须 | 最大长度 | 说明 | 示例 | WES表字段 |
| --- | --- | --- | --- | --- | --- | --- |
| res_number | string | 是 | 64 | RTS需求号 | RORWMSSGD00026010600003 | shipment_header.erpOrderCode |
| allocated_qty | int | 是 |  | 分配的数量 | 0 拣的则传 0 | 汇总该单明细请求数量-短分配量<br>shipment_detail<br>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成功<br>涉及组装task属性, 订单状态变更等场景 失败需要支持重试, 增加告警<br>同步调用，需要重试，接口未成功阻塞该波次的后续作业流程 |


| 接口系统要求 |  |  |  |
| --- | --- | --- | --- |
| 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 - 销售出库<br>2 - RTS<br>3 - MTO | 2 | shipment_header.shipmentType |
| station_type | int | 是 |  | 工作站类型<br>单据分播流程、分播出库流程<br>1：vendor pick to order<br>2：vendor batch picking | 1 | 按照工作站选的类型取值 |
| res_number_list | List<string> | 是 |  | 需求号列表 | [“OBCNG000260101081110”,”OBCNG000260101081112”] | shipment_header.erpOrderCode |
| operator | string | 是 | 64 | operator邮箱 | xxx@shopee.com | 取工作站登录用户表的邮箱 |


###### 响应字段


| 字段名 | 类型 | 是否必须 | 最大长度 | 说明 | 示例 |
| --- | --- | --- | --- | --- | --- |
| fail_res_list | List<string> | 是 |  | 返回码为失败的情况下会有该字段，表示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<SingleAttr> | 是 |  | 属性列表（单属性）<br>当前待确认放single还是放multi：<br>to_whs<br>expected_ob_date<br>order_source<br>transported_by<br>biz_type<br>order_tag<br>supplier_id<br>delivery_method<br>return_date<br>rts_reason<br>order_source |  |
| multi_attr_list | List<MultiAttr> | 是 |  | 属性列表（多属性）<br>当前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成功<br>同步调用，需要重试，接口未成功阻塞该波次的后续作业流程 |


| 接口系统要求 |  |  |  |
| --- | --- | --- | --- |
| 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 - 销售出库<br>2 - RTS<br>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成功<br>只做追加动作<br>同步调用，需要重试，接口未成功阻塞该波次的后续作业流程 |


| 接口系统要求 |  |  |  |
| --- | --- | --- | --- |
| 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 - 销售出库<br>2 - RTS<br>3 - MTO | 2 | shipment_header.shipmentType |
| res_number_list | List<string> | 是 |  | 追加的需求列表，增量 | [“OBCNG000260101081110”,”OBCNG000260101081112”] | shipment_header.erpOrderCode |


###### 响应字段


| 字段名 | 类型 | 是否必须 | 最大长度 | 说明 | 示例 |
| --- | --- | --- | --- | --- | --- |
| fail_res_list | List<string> | 是 |  | 返回码为失败的情况下会有该字段，表示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 | 实际拣货下架的明细增量同步<br>每次调用最外层的pickup_id不允许重复<br>异步调用，接口失败需要重试 |


| 接口系统要求 |  |  |  |
| --- | --- | --- | --- |
| Avg RT | Timeout | 幂等字段 | 降级方案 |
| 300ms | 10s | 无 | 无 |


###### 请求字段


| 字段名 | 类型 | 是否必须 | 最大长度 | 说明 | 示例 | WES表字段 |
| --- | --- | --- | --- | --- | --- | --- |
| whs_id | string | 是 | 16 | 仓库id | SGL | shipment_header.warehouseCode |
| biz_type | int | 是 | 4 | 任务类型：1 - 销售出库<br>2 - RTS<br>3 - MTO | 2 | shipment_header.shipmentType |
| picking_task_list | List<PickingTaskList> | 是 | 100 | 拣货任务列表 | 详见下表 |  |

PickingTaskList字段详情


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

PickedInfo字段详情


| 字段名 | 类型 | 是否必须 | 最大长度 | 说明 | 示例 | WES表字段 |
| --- | --- | --- | --- | --- | --- | --- |
| id | string | 是 | 64 | vendor拣货id，待vendor提供<br>幂等用 |  | 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<UnitItem> | 否 | 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<string> | 是 |  | pickup_id维度 |  |
| failed_list | List<string> | 是 |  | 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 | 完成波次时通知<br>异步调用，接口失败需要重试 |


| 接口系统要求 |  |  |  |
| --- | --- | --- | --- |
| 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 - 销售出库<br>2 - RTS<br>3 - MTO | 1 | shipment_header.shipmentType |
| operator | string | 是 | 64 | operator邮箱 | xxx@shopee.com | 取工作站登录用户表的邮箱 |
| picked_order_number_list | List<PickedInfo> | 是 |  | 满拣需求sku列表 |  | 整单全拣货的单据<br>明细见下文 |
| shortage_order_info_list | List<PickedInfo> | 是 |  | 缺拣需求sku列表 | 缺拣（未拣满或者因为缺货零拣） | 整单部分拣货的单据<br>明细见下文 |
| zero_order_info_list | List<string> | 是 |  | 0拣需求列表 | 未拣货需求列表 | 整单未拣货的单据 |

PickedOrderInfo字段详情


| 字段名 | 类型 | 是否必须 | 最大长度 | 说明 | 示例 | WES表字段 |
| --- | --- | --- | --- | --- | --- | --- |
| id | string | 是 | 64 | vendor拣货id，待vendor提供<br>增量拣货明细有可能会丢请求，幂等用 |  | 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<UnitItem> | 否 | 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 换箱<br>作业接口，必须WMS成功再Vendor成功<br>同步调用，需要重试，接口未成功阻塞该波次的后续作业流程 |


| 接口系统要求 |  |  |  |
| --- | --- | --- | --- |
| 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 - 销售出库<br>2 - RTS<br>3 - MTO | 2 | shipment_header.shipmentType |
| station_type | int | 是 |  | 工作站类型<br>单据分播流程、分播出库流程<br>1：vendor pick to order<br>2：vendor batch picking<br>注意：如果是BatchPicking，需求池模式只能走FLowPicking产生新任务的换箱模式 | 1 | 按照工作站选的类型取值 |
| operator | string | 是 | 64 | operator邮箱 | xxx@shopee.com | 取工作站登录用户表的邮箱 |
| picked_order_number_list | List<PickedOrderInfo> | 是 |  | 满拣需求sku列表 |  | 整单全拣货的单据<br>明细见下文 |
| zero_order_info_list | List<string> | 是 |  | 0拣需求列表；<br>注意0拣时，订单在vendor终态了 | [“RORWMSSGD00026010600003”,”RORWMSSGD00026010600003”] | 整单未拣货的订单 |
| new_order_number_list | List<string> | 否 |  | 新task需求列表<br>长度必须>0 | [“RORWMSSGD00026010600003”,”RORWMSSGD00026010600003”] | shipment_header.erpOrderCode |

PickedOrderInfo字段详情


| 字段名 | 类型 | 是否必须 | 最大长度 | 说明 | 示例 | WES表字段 |
| --- | --- | --- | --- | --- | --- | --- |
| id | string | 是 | 64 | vendor拣货id，待vendor提供<br>增量拣货明细有可能会丢请求，幂等用 |  | 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<UnitItem> | 否 | 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<ResTaskAttrInfo> | 否 |  | 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<br>shipment_header.shopeeWave-新增字段，shopee波次号<br>同步接到两个字段中 |
| 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<br>新增字段，是否混拣 |
| group_key | string | 是 | 128 | 特征值，若可混拣，则有值 | xxx_xx_xx_xx | shipment_header.groupKey<br>新增字段，混拣特征值 |
| sku_info_list | List<SkuInfo> | 是 |  | 期望拣货数量 |  |  |
| single_attr_list | List<SingleAttr> | 是 |  | 属性列表（单属性）<br>当前有：<br>to_whs<br>expected_ob_date<br>order_source<br>transported_by |  |  |
| multi_attr_list | List<MultiAttr> | 是 |  | 属性列表（多属性）<br>当前attr_key有 |  |  |
| ticket_type | int | 是 |  | 单据类型：<br>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<br>指定冻结类型（Normal/临期/过期）<br>SKUBlockTypeNoNeed SKUBlockType = 0<br>SKUBlockTypeEXPIRING SKUBlockType = 1<br>SKUBlockTypeEXPIRED SKUBlockType = 3 | 0 | shipment_detail.shelfLifeSts<br>效期状态 |
| quality | int | 是 |  | 0 好品<br>指定好/坏品<br>SkuQualityTypeGood SkuQualityType = 0<br>SkuQualityTypeDamage SkuQualityType = 1 | 0 | shipment_detail.inventorySts<br>库存状态 |

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也支持取消）<br>注意：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成功<br>同步调用，需要重试，接口未成功阻塞该波次的后续作业流程 |


| 接口系统要求 |  |  |  |
| --- | --- | --- | --- |
| 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 | 是 |  | 工作站类型<br>单据分播流程、分播出库流程<br>1：vendor pick to order<br>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成功<br>同步调用，需要重试，接口未成功阻塞该波次的后续作业流程 |


| 接口系统要求 |  |  |  |
| --- | --- | --- | --- |
| 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不允许重复<br>异步调用，接口失败需要重试 |


| 接口系统要求 |  |  |  |
| --- | --- | --- | --- |
| Avg RT | Timeout | 幂等字段 | 降级方案 |
| 300ms | 10s | 无 | 无 |


###### 请求字段


| 字段名 | 类型 | 是否必须 | 最大长度 | 说明 | 示例 | WES表字段 |
| --- | --- | --- | --- | --- | --- | --- |
| whs_id | string | 是 | 16 | 仓库id | SGL | shipment_header.warehouseCode |
| picking_task_list | List<PickingTaskInfo> | 是 | 100 | 拣货任务列表 | [<br>] |  |

PickingTaskInfo字段详情


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

picked_info_list字段详情


| 字段名 | 类型 | 是否必须 | 最大长度 | 说明 | 示例 | WES表字段 |
| --- | --- | --- | --- | --- | --- | --- |
| id | string | 是 | 64 | vendor拣货id，待vendor提供<br>幂等用 |  | 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<UnitItem> | 否 | 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<string> | 是 |  | pickup_id维度 |  |
| failed_list | List<string> | 是 |  | 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<SkuPickedInfo> | 是 |  | 拣货明细列表 | 详见下表 |  |

picked_info_list字段详情


| 字段名 | 类型 | 是否必须 | 最大长度 | 说明 | 示例 | WES表字段 |
| --- | --- | --- | --- | --- | --- | --- |
| id | string | 是 | 64 | vendor拣货id，待vendor提供<br>增量拣货明细有可能会丢请求，幂等用 |  | 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<UnitItem> | 否 | 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<AttrItem> | 是 | 100 | 单据属性字段放到这里方便扩展<br>目前会有urgent_flag<br>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<SkuInfo> | 是 | 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生成的<br>和source_id必传一个 | RTSGL00020250102001 |
| source_id | string | 否 | 32 | Vendor生成的，source_id和rt_order_id必传一个 |  |
| remark | string | 否 | 128 | Vendor生成的必传remark<br>要做场景区分：<br>Expiring/expired rack transfer<br>Damage rack transfer<br>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<SkuInfo> | 否 | NA | 缺拣时不传 关箱的时候传所有明细<br>另外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<UnitItem> | 是 | 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<RTOrderItem> | 是 | NA | 移库单号(RT开头) 每一行代表一个移库单的拣货数据 |  |

RTOrderInfo


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

DeviceItem


| 字段名 | 类型 | 是否必须 | 最大长度 | 说明 | 示例 |
| --- | --- | --- | --- | --- | --- |
| sku_info_list | List<SkuInfo> | 是 | 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<UnitItem> | 是 | 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<SkuInfo> | 是 | 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<string> | 是 | 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<string> | 否 | 50 | Vendor传的单号(rt_order_list必传一个) |  |
| rt_order_id_list | List<string> | 否 | 50 | Source_id_list 和 rt_order_list必传一个 |  |


| wave_flag | int | 否 |  | 不传和传0一个逻辑<br>传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<string> | 否 |  | 仅在wave_type=1时必传 剔除掉这个时间范围的单号 避免返回太多没必要处理的数据 |  |


##### 响应字段


| 字段名 | 类型 | 是否必须 | 最大长度 | 说明 | 示例 |
| --- | --- | --- | --- | --- | --- |
| whs_id | string | 是 |  |  |  |
| rt_order_info_list | List<RTOrderInfo> | 是 |  | 控制传入的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<DeviceItem> | 是 | NA |  |  |

DeviceItem


| 字段名 | 类型 | 是否必须 | 最大长度 | 说明 | 示例 |
| --- | --- | --- | --- | --- | --- |
| sku_info_list | List<SkuInfo> | 是 | 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<UnitItem> | 否 | 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再取消<br>WMS调用失败会重试 |


| 接口系统要求 |  |  |  |
| --- | --- | --- | --- |
| Avg RT | Timeout | 幂等字段 | 降级方案 |
| 300ms | 5s |  |  |


##### 请求字段


| 字段名 | 类型 | 是否必须 | 最大长度 | 说明 | 示例 |
| --- | --- | --- | --- | --- | --- |
| whs_id | string | 是 | 16 | 仓库id | SGL |
| rt_order_list | List<RTOrderItem> | 是 | 1000 | 传的列表用于批量更新(最少传一个) |  |
| update_event | int | 是 | NA | 取消单据(取消只处理status) 1其他单据信息更新2 |  |

RTOrderItem


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

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<string> | 否 |  | 更新失败的单据 | ["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<BatchBlockType> | 是 |  | 状态有变化的批次以及状态；最大1000个，超过1000个分多次调用。 | [<br>{<br>batch_no:12345<br>batch_status: 1<br>}<br>] |

BatchBlockType


| 字段名 | 类型 | 是否必须 | 最大长度 | 说明 | 示例 |
| --- | --- | --- | --- | --- | --- |
| batch_no | bigint | 是 |  | 批次号 | 2025091757580761 |
| block_type | int | 是 |  | 批次状态<br>（固定枚举值） | 0-Normal<br>1-Expiring<br>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<String> | 否 |  | Sku_id 列表，一次最多1000个 | [<br>"123123",<br>"2332423423"<br>] |


##### 响应字段


| 字段名 | 类型 | 是否必须 | 最大长度 | 说明 | 示例 |
| --- | --- | --- | --- | --- | --- |
| page_no | int64 | 是 |  | 分页码，返回请求传的参数 | 1 |
| page_size | int64 | 是 |  | 分页大小，返回请求传的参数 | 20 |
| list | List<BatchInventory> | 是 |  | 详细库存信息 |  |

BatchInventory


| 字段名 | 类型 | 是否必须 | 最大长度 | 说明 | 示例 |
| --- | --- | --- | --- | --- | --- |
| sku_id | string | 是 | 64 | sku id | 101057873_10000551324 |
| batch_no | bigint | 是 |  | 批次号 | 2025091757580761 |
| block_type | int | 是 |  | 批次状态<br>（固定枚举值） | 0-Normal<br>1-Expiring<br>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> | 是 |  |  |  |

ReconciliationResult


| 字段名 | 类型 | 是否必须 | 最大长度 | 说明 | 示例 |
| --- | --- | --- | --- | --- | --- |
| sku_id | string | 是 | 64 | sku id | 101057873_10000551324 |
| batch_no | bigint | 是 |  | 批次号 | 2025091757580761 |
| shopee_block_type | int | 是 |  | wms批次状态<br>（固定枚举值） | 0-Normal<br>1-Expiring<br>3-Expired |
| vendor_block_type | int | 是 |  | vendor批次状态<br>（固定枚举值） | 0-Normal<br>1-Expiring<br>3-Expired |
| shopee_quantity | int | 是 |  | wms数量 | 100 |
| vendor_quantity | int | 是 |  | vendor数量 | 100 |
| shopee_uid_list | List<string> | 否 |  | wms uid列表 |  |
| vendor_uid_list | List<string> | 否 |  | 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<string> | 是 | 1000 | sku id、upc、uid列表 | [“101057873_10000551324”, “101057873_10000551322”] |


##### 响应字段


| 字段名 | 类型 | 是否必须 | 最大长度 | 说明 | 示例 |
| --- | --- | --- | --- | --- | --- |
| sku_list | List<SkuInfo> | 是 | 1000 | sku 信息列表 | [{<br>“sku_id”:”aaa”<br>},<br>{<br>“sku_id”:”bbb”<br>}] |

SkuInfo


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

SkuTag


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

Shop


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

Consumable


| 字段名 | 类型 | 是否必须 | 最大长度 | 说明 | 示例 |
| --- | --- | --- | --- | --- | --- |
| consumable_id | string | 是 | 36 | consumable id<br>（可变值） | CS00015 |
| consumable_name | string | 是 | 128 | consumable 名称<br>（可变值） | 123qwe## |
| count | int | 是 |  | 数量<br>（可变值） | 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<SkuInfo> | 是 |  | 与查询接口相同的结构体 |  |


##### 响应字段


| 字段名 | 类型 | 是否必须 | 最大长度 | 说明 | 示例 |
| --- | --- | --- | --- | --- | --- |
| 无 |  |  |  |  |  |


##### 返回码


| 返回码 | 描述 | 说明 | 是否需要自动重试 |
| --- | --- | --- | --- |
| -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<String> | 否 |  | robot id 列表，一次最多1000个 | [<br>"1",<br>"2"<br>] |


##### 响应字段


| 字段名 | 类型 | 是否必须 | 最大长度 | 说明 | 示例 |
| --- | --- | --- | --- | --- | --- |
| page_no | int64 | 是 |  | 分页码，返回请求传的参数 | 1 |
| page_size | int64 | 是 |  | 分页大小，返回请求传的参数 | 20 |
| list | List<AgvStatus> | 是 |  | 每台Agv状态信息 |  |

AgvStatus


| 字段名 | 类型 | 是否必须 | 最大长度 | 说明 | 示例 |
| --- | --- | --- | --- | --- | --- |
| robot_id | string | 是 | 32 | 机器人唯一编码 | 00001 |
| robot_type | int | 是 |  | 机器人类型 | 0-未知<br>1-拣货机器人<br>2-搬运机器人<br>3-拣货搬运一体机器人 |
| root_ip | string | 是 | 64 | 机器人ip | 192.168.1.2 |
| battery | int | 是 |  | 机器人电量，0-100 | 100 |
| status_list | List<Status> | 是 |  | 机器人状态列表，包括：连接状态、<br>行为状态、异常状态、在场状态<br>（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 | 是 |  | 连接状态<br>（固定枚举值） | 0-未知<br>1-在线<br>2-离线 |
| task_status | int | 是 |  | 行为状态<br>（固定枚举值） | 0-未知<br>1-空闲<br>2-充电<br>3-执行任务<br>4-暂停<br>5-异常 |
| task_desc | string | 是 | 1024 | 行为描述 | 升举货架<br>移动中 |
| exception_status | int | 是 |  | 异常状态<br>（固定枚举值） | 0-未知<br>1-正常<br>2-异常 |
| exception_desc | string | 是 | 1024 | 异常描述 | 充电桩异常 |
| onsite_status | int | 是 |  | 在场状态<br>（固定枚举值） | 0-未知<br>1-在场<br>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<int64> | 否 |  | batch_no 列表，一次最多1000个 | [<br>1,<br>2<br>] |


##### 响应字段


| 字段名 | 类型 | 是否必须 | 最大长度 | 说明 | 示例 |
| --- | --- | --- | --- | --- | --- |
| page_no | int64 | 是 |  | 分页码，返回请求传的参数 | 1 |
| page_size | int64 | 是 |  | 分页大小，返回请求传的参数 | 20 |
| list | List<UnitItem> | 是 |  | 每个 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

