文档中心 > 开放业务&解决方案

同城零售履约篇

更新时间：2021/04/12 访问次数：2809

业务背景
业务框架&场景
官方场景&权限包
履约接口列表
履约对接外部仓接口

业务背景

合作商家拥有门店打印小票设备、门店拣打作业一系列管理流程和系统保障。并且商家期望保持原有门店作业流，为此同城零售共享库存方案为商家提供店仓作业开放能力。

商家店仓系统可承接同城零售作业任务。

业务框架&场景

场景：

1、REX履约中台下发外部仓拣货作业任务，仓接收任务后进行拣货、打包并回传履约中台状态。

2、仓内作业取消：在仓内作业未完成前，用户取消订单，履约下发仓作业取消。

3、仓逆向：仓打包出库后的逆向退货退仓，REX履约中台会下发退仓单，商家仓进行库存入库，并回执结果。

官方场景&权限包

作业下发、取消、退仓下发三个接口，是REX中台通过奇门调用商家，商家接收任务消息

商家必须进入奇门关联场景“五道口履约场景” 并完成平台接口配置

奇门入驻配置手册：https://hema.open.taobao.com/doc?docId=108926&docType=1

关联场景(奇门官方老场景）：五道口履约场景

TOP网关权限：

作业单回传、退仓单回传两个接口，是商家门店作业处理完成后调用TOP接口同步REX平台。开发接口前联系开放技术支持开通权限包。

APPKEY应用权限扩包“五道口履约域”--------用于回传接口

业务提醒:

半日达奇门防止订单丢失方案：

sourceOrderIds 猫超主订单，因为上线门店多的话同个物流点有多个门店，业务上可能会出现，用户一个订单买了两个或多个门店的商品，

就会有一个用户主订单，子单被拆分成多个作业单下发给门店。

如果以作业单中同城令牌workOrderUnitId 作为记录，是不会有问题的，一个作业单，对应一个同城令牌。

不建议使用，用户主订单（猫超主订单）sourceOrderIds 做记录或幂等，容易丢失后面的作业信息。

履约小票样式（保证小票实例上的参数信息必须存在）：

小时达小票模板

履约接口列表

业务	接口名称	api	网关
履约	仓作业单下发接口	qimen.alibaba.wdk.fulfill.warehouse.order.dispatch	奇门
	仓作业单-回传接口	alibaba.wdk.fulfill.warehouse.work.order.callback	TOP
	仓作业取消单下发接口	qimen.alibaba.wdk.fulfill.work.order.cancel.by.unit.content	奇门
	仓退仓单下发接口	qimen.alibaba.wdk.fulfill.do.return.warehouse.task	奇门
	仓退仓单-回传接口	alibaba.wdk.fulfill.bill.return.warehouse.on.task.status.changed	TOP

履约对接外部仓接口

1. 仓作业单下发接口

接口名称：qimen.alibaba.wdk.fulfill.warehouse.order.dispatch

接口用途：履约已完成集批动作，同步通知作业单内容到外部仓储进行门店作业.

请求参数：

名称	参数类型	是否必须	示例值	描述
workOrder	WorkOrder	可选		作业单
└ workOrderId	String	必须	34354354353	作业单号(履约批次号)
└ workOrderName	String	必须	171215-中一区B-08:00-08:30	作业单名称
└ merchantCode	String	必须	TCCSSJ	商户编码
└ nodeCode	String	必须	UDTCCSSJ	节点编码（店仓编码）
└ earliestArriveTime	String	必须	2017-04-26 19:17:55	作业单最早送达时间，格式： yyyy-MM-dd HH:mm:ss
└ latestArriveTime	String	必须	2017-04-26 19:47:55	作业单最晚送达时间，格式： yyyy-MM-dd HH:mm:ss
└ isTest	Boolean	必须	TRUE	是否测试单
└ workOrderUnits	WorkOrderUnit[]	必须		作业单元;fulfillOrderList最大列表长度：100
└ workOrderUnitId	String	必须	半日达：204564536545231 小时达：152521386182213	半日达下发“”同城令牌号小时达下发：履约主单号
└ sourceFrom	String	必须	TC	订单来源:MEITUAN("美团"),ELEME("饿了么"),TDD("淘点点"),BAIDU("百度"),WEIXIN("微信"),TC("自营"),DAILY_FRESH("每日优鲜")
└ earliestArriveTime	String	必须	2017-04-26 19:17:55	最早开始时间
└ latestArriveTime	String	必须	2017-04-26 19:47:55	最晚送达时间
└ orderTime	String	必须	2017-04-26 10:15:00	下单时间
└ receiver	Receiver	必须		收货人对象
└ receiverName	String	必须	张三	收货人姓名
└ receiverPhone	String	必须	1341432334	收货人电话
└ receiverAddress	String	必须	上海市长宁区新兴路1号	收货人地址
└ workOrderUnitContents	WorkOrderUnitContent[]	必须		作业内容;最大列表长度：999999
└ workUnitContentId	String	必须	645234534	作业内容单号(fulfillSubOrderId作业子单号)
└ subSourceOrderId	String	必须	7685678	外部子单号(猫超子订单号)
└ skuCode	String	必须	465465	REX平台商品编码
└ skuName	String	必须	可口可乐	商品名称
└ saleUnit	String	必须	瓶	销售单位
└ stockUnit	String	必须	箱	库存单位
└ expectSaleQuantity	String	必须	1	销售单位购买数量
└ expectStockQuantity	String	必须	1	库存单位购买库数量
└ isStandardSku	Boolean	必须	TRUE	是否是标品
└ isGift	Boolean	必须	TRUE	是否赠品
└ status	String	可选	CANCELED	状态： CANCELED("取消")，为空该商品可以正常捡货
└ operationalRequirement	OperationalRequirement	可选		作业要求
└ processService	String	可选	宰杀	加工服务
└ thermosphere	String	可选	常温	温层要求
└ attribute	String	可选	{ }	预留扩展
└ shopCode	String	必须	1234	前端销售门店编码
└ sourceOrderIds	String []	必须	45364565	外部订单号集合,可能1对多(猫超主订单号，一单一批或多单一批)
└ attribute	String	可选	{"pickupCode":"123","containerCodes":["123","456"]," businessSourceFrom":"MAOCHOA_SELLER", "batchStrategy":"O2O/O2O_HALF_DAY"}；	扩展字段Map。取件码key是pickupCode；业务来源key是businessSourceFrom，value取值MAOCHOA_SELLER代表猫超共享库存，value取值TAOBAO_SELLER代表淘鲜达；batchStrategy是作业策略,O2O代表小时达,O2O_SELF_TAKE_AT_SHOP代表自提 O2O_HALF_DAY半日达
└ attribute	String	可选	{ }	预留扩展
API出参
名称	参数类型/SDK类型	是否必须	示例值	描述
success	Boolean	必须	ture	是否成功
respCode	String	必须	SUCCESS	响应code
respMessage	String	必须	下发成功	响应提示信息

2.仓作业单-回传接口

接口名称：alibaba.wdk.fulfill.warehouse.work.order.callback

接口用途：由仓系统将作业节点状态拣货完成、打包完成回传到履约中心，包括缺货出情况。

注意：拣货完成和打包完成是必须回传的节点 PICK_FINISH(“拣货完成”)，PACKAGE_FINISH(“打包完成”);

提醒：加上重试机制，避免因为接口异常情况返回错误无法正常回传任务。重试需要识别 is_success 进行重试为false业务处理失败需要重试

请求参数:

callback_order	DrfHalfDayCcCallbackOrder	可选		作业单回传对象
└status_change_time	String	必须	2017/4/2619:17	作业状态变更时间
└status_change_type	String	必须	START_PICK	作业状态变更类型：START_PICK(“开始拣货”)， PICK_FINISH(“拣货完成”)，START_PACKAGE(“开始打包”), PACKAGE_FINISH(“打包完成”); 拣货完成和打包完成必传,拣货在前打包在后
└node_code	String	必须	ERPCSMD	店/仓编码
└work_order_type	String	必须	BATCH	作业单类型：BATCH("批次"),ORDER("物流单默认传：BATCH
└work_order_id	String	必须	450834096721030400	作业单号
└callback_units	DrfHalfDayCcCallBackUnit[]	必须		作业单元最大列表长度：100
└callback_contents	DrfHalfDayCcCallBackContent[]	必须		作业内容最大列表长度：100
└is_shortage	Boolean	必须	false	是否缺货出缺货;true 不缺：false
└sku_name	String	必须	帝王蟹	商品名称
└sku_code	String	必须	1231213	商品编码
└out_of_stock_stock_quantity	String	必须	0	缺货出库存数量
└out_of_stock_sale_quantity	String	必须	0	缺货出销售数量
└actual_stock_quantity	String	必须	1	实际库存拣货数量
└actual_sale_quantity	String	必须	1	实际销售拣货数量
└work_unit_content_id	String	必须	252927176121030420	作业内容单号,履约子单号
└attribute	String	可选	{"exchangeGoods":[ {"skuCode":"122","skuname":"商品名称","actualSaleQuantity":1,"actualStockQuantity":1}], "containerType":"1","containerCodes":["123","456"]}	作业内容扩展属性
└same_town_packages	SameTownPackage[]	可选		子单出库关联的同城令牌最大列表长度：999
└token_code	String	可选	2.11235E+17	令牌号
└pickup_code	String	可选	124567	6位交接码
└actual_sale_quantity	String	可选	1	包裹中商品出库销售数量
└actual_stock_quantity	String	可选	1.2	包裹中商品出库库存数量
└container	Container	可选		周转箱
└container_type	String	可选	NORMAL_BOX("周转箱"),INSULATION_BOX("保温箱") ,SKU_PACK("异形件sku捆绑，不能装入箱子，需要另外打包")	容器类型
└container_code	String	可选	DRF12345678	容器编码
└work_order_unit_id	String	可选	56876877	半日达传同城令牌号）小时达传：履约主单号对应字段：workOrderUnitId
└attribute	String	可选	{"exchangeGoods": [{"skuCode":"122","skuname":"商品名称","actualSaleQuantity":1,"actualStockQuantity":1}], "containerType":"1","containerCodes":["123","456"]}	作业单元扩展属性
└is_final	Boolean	必须	false	是否作业节点终态正常或部分缺作业：拣货回false;打包回true; 全缺货：拣货回true
└operator	Operator	必须		操作员
└operator_code	String	必须	8888	操作员编码
└operator_name	String	必须	李四	操作员姓名
containers	Container[]	必须		容器列表，最大列表长度：200。波次达必须，小时达不必须
└ container_type	String	必须	NORMAL_BOX("周转箱"),INSULATION_BOX("保温箱"),SKU_PACK("异形件sku捆绑，不能装入箱子，需要另外打包")	容器类型，默认传SKU_PACK
└ container_code	String	必须		容器编码半日达传同城令牌号）小时达传：履约主单号对应字段：workOrderUnitId

接口响应

名称	参数类型/SDK类型	是否必须	示例值	描述
is_success	Boolean	必须	true	是否成功成功：true 失败false
resp_message	String	否	回传成功	响应提示信息
resp_code	String	否	SUCCESS	响应code

3.仓作业取消单下发接口

接口名称：qimen.alibaba.wdk.fulfill.work.order.cancel.by.unit.content

接口描述：履约取消子作业单，同步给仓系统，需要仓系统对相关取消子作业单进行拦截。

提醒:小时达按照商品维度下发取消单：例如5个商品取消就是5个取消单，半日达所有商品一起下发

API 出参需要以子单维度处理 data字段需要包含子单数据

接口参数：

API入参
名称	参数类型/SDK类型	是否必须	示例值	描述
cancelRequest	CancelRequest	必须		取消请求
└ workOrderId	String	必须	42543513	作业单号(履约批次号)
└ nodeCode	String	必须	65787	作业节点编码
└ workOrderUnitId	String	必须	32534252132	作业单元单号(履约单号) 半日达下发“”同城令牌号小时达下发：履约主单号
└ workUnitContentIds	String []	必须		作业内容号列表(fulfillSubOrderId履约子单号);最大列表长度：999
API出参
名称	参数类型/SDK类型	是否必须	示例值	描述
success	Boolean	必须	TRUE	是否成功
respCode	String	必须	SUCCESS	响应code
respMessage	String	必须	下发成功	响应提示信息
data	ResultDetail[]	必须		单据取消结果列表
└ bizNo	String	必须	2521868216312	业务单据号（作业单元Id；履约子订单)
└ resultCode	String	必须	SUCCESS	单据操作结果：SUCCESS 已拦截（仓内作业不出库，配送作业不配送到客户）； FAILURE：未拦截
└ resultDesc	String	必须	已拦截	返回码含义描述

4.仓退仓单下发接口

接口名称：qimen.alibaba.wdk.fulfill.do.return.warehouse.task

接口用途：当订单打包出库之后发生售中取消，拒收，及售后退货时，由履约下发退仓单，通知仓系统完成入库。

提醒；因为退仓单是配送创建，如果有多单一个门店会合在一起处理下发，需要商家系统支持识别到正向单号进行处理

请求参数：

API入参
名称	参数类型/SDK类型	是否必须	示例值	描述
returnWarehouseBill	ReturnWarehouseBill	必须		退仓单
└ returnWarehouseBillId	String	必须	2343243241	退仓单号
└ warehouseCode	String	必须	DRF1102	仓编码
└ sourceMerchantCode	String	必须	DARUNFA	来源商家编码
└ sourceNodeCode	String	必须	UDDRF1001	来源配送站编码\仓编码(若存在配送站，给配送站编码；若不存在配送站，给仓编码)
└ contactInfo	String	可选	手机号：3334443434	联系方式
└ remark	String	可选	退仓	备注
└ isTest	Boolean	必须	TRUE	是否测试单
└ containerList	String []	必须		容器列表;最大列表长度：999
└ isVirtual	Boolean	必须	FALSE	是否是虚拟退仓单
└ skuInfoList	ReverseSkuInfo[]	必须		子单列表;最大列表长度：999
└ reverseFulfillOrderId	String	必须	4352345	逆向履约主单号
└ reverseFulfillSubOrderId	String	必须	2341241324	逆向履约子单号
└ relatedFulfillOrderId	String	必须	13423324	关联的正向履约单号：workOrderUnitId
└ relatedFulfillSubOrderId	String	必须	2435345345	关联的正向履约子单号：
└ relatedSourceOrderId	String	必须	4563345654	关联的正向淘系交易主单号：
└ relatedSubSourceOrderId	String	必须	34546436	关联的正向淘系交易子单号
└ relatedBizOrderId	String	可选	3454354	关联的正向REX交易主单号
└ relatedSubBizOrderId	String	必须	324535345	关联的正向REX交易子单号
└ reverseSaleOrderCode	String	可选	5464536345	REX逆向退货单号
└ refundId	String	可选	43534	退款单号
└ orderChannel	String	必须	APP	销售渠道："POS"，"APP"
└ reverseOrderSource	String	必须	AFTER_SALE	逆向单来源： 1,AFTER_SALE （售后退货）; 2,IN_SALE（售中取消）;
└ skuCode	String	必须	100344	商品编码
└ skuName	String	必须	可口可乐	商品名称
└ stockUnit	String	必须	瓶	库存单位
└ isStandardSku	Boolean	必须	TRUE	是否是标品：true（“标品”），false（“非标品”）
└ refundStockQuantity	String	必须	10	退款数量（库存单位）
└ shouldFetchStockQuantity	String	必须	10	应取数量（库存单位）
└ enterDockStockQuantity	String	必须	8	入站数量（库存单位）
└ returnBoundStockQuantity	String	必须	6	退仓数量（库存单位）
└ customerLossStockQuantity	String	必须	0	客损数量（库存单位）：退款数量-应取数量
└ riderLossStockQuantity	String	必须	2	骑手损数量（库存单位）：应取数量-入站数量
└ deliveryLossStockQuantity	String	必须	2	站损数量（库存单位）：入站数量-退仓数量
└ sourceSellerId	String	可选	725677994	卖家id
API出参
名称	参数类型/SDK类型	是否必须	示例值	描述
success	Boolean	否	TRUE	调用是否成功
errorCode	String	否	SYSTEM_ERROR	错误码
errorDesc	String	否	系统异常	返回码含义描述

5.仓退仓单-回传接口

接口名称：alibaba.wdk.fulfill.bill.return.warehouse.on.task.status.changed

接口用途：仓系统将退仓入站结果回传通知履约。

请求参数:

API入参
名称	参数类型/SDK类型	是否必须	示例值	描述
return_warehouse_result	ReturnWarehouseResult	必须		退仓结果
└warehouse_code	String	必须	ERPCSMD	店/仓编码，
└return_warehouse_bill_id	String	必须	427123432421352	退仓单号
└sku_info_list	ReverseSkuInfo[]	必须		子订单信息列表;最大列表长度：999
└warehouse_loss_stock_quantity	String	必须	2	仓内报损数量（退仓数量-实际入库数量）
└actual_in_bound_stock_quantity	String	必须	4	实际入库数量(库存单位)
└sku_code	String	必须	102010001	商品编码
└reverse_fulfill_order_id	String	必须	34453543	逆向履约单号
└reverse_fulfill_sub_order_id	String	必须	456345643	逆向履约子单号
└warehouse_loss_reason_list	WarehouseLossReason[]	可选		仓内报损原因列表;最大列表长度：20 若有报损以下信息必须回传
└warehouse_loss_reason	String	可选	商品破损	报损原因描述
└warehouse_loss_reason_code	String	可选	001	报损原因编码 001：商品破损 002：商品过期
└warehouse_loss_stock_quantity	String	可选	2	仓内报损数量
└related_fulfill_order_id	String	必须	345435345	关联的正向（同城令牌）
└related_fulfill_sub_order_id	String	必须	234234324	关联的正向履约子单号
API出参
名称	参数类型/SDK类型	是否必须	示例值	描述
result	FulfillVoidResult	必须		fulfillVoidResult
└error_desc	String	可选	系统异常	返回码含义描述
└error_code	String	可选	SYSTEM_ERROR	返回码(success=false时不能为空)：SYSTEM_ERROR:系统异常(指令可重发)PARAM_ERROR:参数错误(指令不可重发，监控报警)BUSINESS_ERROR:业务异常(指令不可重发，监控报警)
└success	Boolean	必须	FALSE	true调用成功false调用失败

提醒：下发接口会重试吗？

作业下发：1分钟一次，24小时内循环，取消下发失败，重试18次，18次后不再重试。退仓单下发重试60次，1分钟一次。

FAQ

关于此文档暂时还没有FAQ

有用(0) 我要提问

开放平台

开放业务&解决方案