冷库库存转代卖 · 前端对接文档

两阶段流程

• ① 运营后台（客服）：暂存列表操作「转代卖」→ 先调 预填信息接口 弹窗展示可转扎数上限 → 客服填写扎数、备注后调 确认转代卖，生成一条待出库的转代卖任务并锁定库存。
• ② 仓库小程序：在暂存出库列表看到该任务（outType=3），点击出库时必须填写最终出库扎数（其余照片必传、备注选填等同现有出库）。
• 待出库期间客服可撤销（复用现有撤销接口），撤销后库存解锁：包裹回暂存中、裸花回待发货。

两种暂存类型的口径差异

outType 出库方式（新增值）

1 关联发货单 2 直接出库 3 转代卖（新增）

历史出库记录、暂存出库列表等所有带 outType 的接口天然支持值 3，筛选参数无需改动。任务状态枚举不变：10 待出库20 已出库30 已撤销

POST新增/cold/convert-sale/info转代卖预填信息

点「转代卖」弹窗前调用，返回暂存类型与可转扎数上限。同时做资格预检——不满足条件（城市仓货架、已有待出库任务、没有在库包裹等）会直接报错，前端 toast 错误信息即可，避免弹窗填完提交才被拒。

请求参数

返回 data

示例

// 请求
{ "coldStockId": 1024 }

// 返回（裸花）
{ "code": 200, "data": { "storeType": 2, "maxBunchNum": 15 } }

// 返回（包裹，快照查不到）
{ "code": 200, "data": { "storeType": 1, "maxBunchNum": null } }

POST新增/cold/convert-sale确认转代卖

生成待出库的转代卖任务。包裹暂存会锁定该库存全部在库包裹；实际出库由仓库小程序完成。返回 data 为任务 id。

请求参数

业务报错文案（toast 展示即可）

• 「城市仓货架暂存不支持转代卖」
• 「存在待出库任务，请先完成或撤销后再转代卖」（包裹）
• 「该库存没有可转代卖的在库包裹」（包裹）
• 「转代卖扎数不能大于发货单总扎数X扎」（包裹，快照有值时）
• 「转代卖扎数不能大于当前剩余暂存X扎」（裸花）

示例

// 请求
{ "coldStockId": 1024, "bunchNum": 10, "remark": "客户不要了，转平台代卖" }

// 返回
{ "code": 200, "data": 88 }   // data = 出库任务 id

POST复用/cold/out/cancel撤销出库任务

转代卖任务待出库期间的撤销完全复用现有撤销接口，入参出参不变。撤销后：包裹解锁回「暂存中」，裸花库存回「待发货」；历史出库记录中该任务显示 outType=3 及撤销信息。

POST字段变更/cold/out/records历史出库记录

入参不变（outType 筛选传 3 即可查转代卖记录）。返回行新增/调整字段：

POST字段变更/cold/stock/page暂存列表

返回行新增字段，用于在列表上给待出库的转代卖库存打标签：

POST字段变更/cold/mini/out/finish点击出库

入参新增 bunchNum。任务为转代卖（outType=3）时前端必须让仓库人员填写最终出库扎数；其他任务类型不传。照片必传、备注选填等原有规则不变。

入参新增字段

业务报错文案

• 「请填写最终出库扎数」（转代卖任务未填或 ≤0）
• 「最终出库扎数不能大于客服审批的转代卖扎数X扎」
• 「最终出库扎数不能大于当前剩余暂存扎数」（裸花，并发或超量）

示例

// 转代卖任务出库请求
{
  "outTaskId": 88,
  "imageUrls": "https://cdn.example.com/a.jpg,https://cdn.example.com/b.jpg",
  "remark": "已搬到代卖区",
  "bunchNum": 8
}

POST字段变更/cold/mini/out/page暂存出库列表

入参不变，转代卖任务会自然出现在待出库/已出库列表中。返回行新增/调整字段：