三合一订单下发接口

基本信息

请求方式 Post application/x-www-form-urlencoded
功能描述 商家将订单信息推送给菜鸟速递EDI(取号,预分拣,下单三步合一),菜鸟速递返回预分拣及运单号信息
编码 UTF-8

入参

项目 名称 类型 必填 描述
对接码 logistic_provider_id String 菜鸟侧提供
签名 data_digest String Base64(Md5(logistics_interface+双方约定的secretKey)),0.2 签名方法
业务报文 logistics_interface Waybill JSON

出参

项目 名称 类型 必填
成功标识 success boolean
错误码 errorCode String
错误说明 errorMsg String
运单号 mailNo String
预分拣信息 sortingDataResponseDTO SortingDataResponseDTO

注意:

该接口必填参数:
字段 类型 描述
waybill->receiver->receiverName String(40) 收件人姓名
waybill->receiver->receiverMobile String(20) 收件人手机 不能有"-"以外的特殊字符
waybill->receiver->receiverProvince String(20) 收件人省份
waybill->receiver->receiverAddress String(256) 收件人详细地址 因部分区域行政区划没有市或者区,所以接口市和区县字段是非必填的,实际为了避免错分,需要把市和区县信息放到对应的字段传过来或者将完整地址信息放在详细地址里
waybill->sender->senderName String(40) 寄件人姓名
waybill->sender->senderMobile String(20) 寄件人手机
waybill->sender->senderProvince String(20) 寄件人省份
waybill->sender->senderAddress String(256) 寄件人详细地址 因部分区域行政区划没有市或者区,所以接口市和区县字段是非必填的,实际为了避免错分,需要把市和区县信息放到对应的字段传过来或者将完整地址信息放在详细地址里
waybill->packageInfo->goodsItems->itemName String(128) 商品名称
waybill->packageInfo->goodsItems->itemNum Integer 商品数量
waybill->packageInfo->weight Integer 包裹重量(g)
waybill->packageInfo->packageNums Integer 包裹个数
waybill->order->planReceiveAmount Double 应收金额,没有给0.0
waybill->order->planReturnAmount Double 应退金额,没有给0.0
waybill->order->goodsAmount Double 货物金额,没有给0.0
waybill->order->logisticsId String(32) 订单号
waybill->order->storeOrderCode String(32) 订单号,同logisticsId
waybill->order->deliveryType String 运单类型 1-配送单
waybill->sortingInfo->scheduleType String 时效要求 103-次日达
waybill->isNeedDeclaration Boolean 是否报关

其他可能用到的非必填参数:

字段 类型 描述
waybill->order->extendFields->logisticsProductCode String 物流产品编码 CN001-菜鸟电商标快 CN002-菜鸟标快 [{"key":"logisticsProductCode","value":"CN002"}]
waybill->order->extendFields->expectedGotStartDate String 预约开始时间 yyyy-MM-dd HH:mm:ss [{"key":"expectedGotStartDate","value":"2024-07-22 17:16:25"}]
waybill->order->extendFields->expectedGotEndDate String 预约结束时间 yyyy-MM-dd HH:mm:ss [{"key":"expectedGotStartDate","value":"2024-07-22 17:16:25"}]
接口是以logisticsId+packageCode(不传packageCode就是以订单号幂等)维度幂等,一单多件需要调用多次接口,给相同的logisticsId,不同的packageCode

示例报文

url:

http://edi-daily.xpm.cainiao.com/ext/gateway/orderAccept/commonReceive/api

请求: 仅供参考,实际测试账号需联系菜鸟速递开发提供

logistic_provider_id: edi_test_json

data_digest: Mq0TSL0kq6YZxgzJyOLxeQ==

logistics_interface:

{"isNeedDeclaration":false,"order":{"deliveryType":"1","extendFields":[{"key":"declarePort","value":"3105"},{"key":"platformCusCode","value":"3114965330"},{"key":"importDate","value":"2019-08-11 00:00:50"}],"goodsAmount":"90.75","logisticsId":"test190812001","mailNo":"","planReceiveAmount":"0.0","planReturnAmount":"0.0","storeOrderCode":"test190812001","tmsCode":""},"packageInfo":{"goodsItems":[{"extendFields":[{"key":"hsCode","value":"3305100090"}],"itemName":"测试商品","itemSpec":"4901301335975","itemNum":1},{"extendFields":[{"key":"hsCode","value":"5601210000"}],"itemName":"测试","itemSpec":"4903111455546","itemNum":1},{"extendFields":[{"key":"hsCode","value":"5601210000"}],"itemName":"测试","itemSpec":"4903111455546","itemNum":1}],"packageNums":"6","weight":"870"},"receiver":{"receiverAddress":"中节能西溪首座","receiverArea":"西湖区","receiverCity":"杭州市","receiverMobile":"13111111111","receiverName":"张三","receiverProvince":"浙江省"},"sender":{"senderAddress":"宁波市北仑区保税南区九龙山路一号","senderArea":"北仑区保税南区","senderCity":"宁波市","senderCountry":"中国","senderMobile":"13111111111","senderName":"测试","senderProvince":"浙江省"},"sortingInfo":{"scheduleType":"103"}}

返回:

{"mailNo":"621000000000011","success":true,"sortingDataResponseDTO":{"endChuteShortCode":"1D","siteAreaCode":"05","cpShortCode":"K","siteName":"成都石羊场站Z","endRdcShortCode":"901","endRdcShortName":"双流","firstRdcShortCode":"33G","firstRdcShortName":"下沙","aoiCommunityName":"北南城都汇","cityShortCode":"P1","bizId":"test190812001","siteShortCode":"L29","omsRdcChuteCodeDTOS":[{"rdcShortName":"下沙","rdcId":60017,"rdcShortCode":"33G"},{"rdcShortName":"双流","rdcId":15222,"rdcShortCode":"901","chuteShortCode":"1D"}]}}

附录

常见错误码

错误码 原因
13101 未订购服务产品
13102 保价未订购
13103 线路未订购
13104 超出接单范围
13105 无法上门收件
13106 无法识别地址
13107 未配置提货点
13108 提货点未配置交接组织
13000 其他错误