注意:以下文档只适用于TOP接口,请谨慎使用!

文档中心 > 电子面单对接知识库

网络型快运电子面单接入白皮书

更新时间:2019/04/02 访问次数:8775

网络型快运电子面单接入白皮书

为了提升商家发货效率、降低发货成本, 菜鸟电子面单开始逐步支持国内快运公司。该方案可以解决多环节打单、贴单的问题,实现一单到底,节省成本、提升效率。

本次接入的网络型快运公司有

快运公司 cpCode
德邦快运 CN7000001009020
百世快运 BESTQJT
安能快运 CN7000001000869
壹米滴答 2744832184_543
韵达快运 CN7000001021040
中通快运 3108002701_1011
速尔快运 SURE

目前快运的物流公司都是独立的cpCode,比如德邦快递和德邦快运,是不同的cpCode,当快运电子面单取号时,直接获取子母件单号。

接入菜鸟电子面单

ISV首先需要使用菜鸟电子面单进行打单,并且需要使用云打印模板。
如果之前没有接入过电子面单,请参考ERP服务商入口文档

注意
子母单号生成递增序号是基于之前取到的序号之上的,如果并发来获取,可能会导致两个请求同时到达系统,会导致只有一个成功取到单号,因此大家对于子母单件必须是串行取号,前一个单号生成了再获取下个单号。

网络型快运公司电子面单接口变更

  • 快运电子面单与之前的电子面单云打印接口为同一接口, 所以接口的行为保持一致。每次传入一个包裹,返回一个子单号和对应的母单号。
  • 子母件模式不支持批量取号。如果需要取得连续递增的子单号,每次需要在同一个sellerId下传入相同的订单id列表,不同的包裹id, 如果订单列表相同,包裹id也相同,会触发幂等。
  • 子件面单除子单号不同,其他信息完全相同。
  • 入参新增包裹总件数字段 trade_order_info_dtos.package_info.total_packages_count,快运公司需要在面单上体现包裹的总件数,必填
  • 入参新增包装类型字段 trade_order_info_dtos.package_info.packaging_description,选填
  • 入参新增货品类型字段 trade_order_info_dtos.package_info.goods_description,选填
  • 接口返回数据中包含子母件的子单号(waybillCode)和母单号(parentWaybillCode)
  • ISV需要注意,在快递模式下,返回的单号只有waybillCode,waybillCode是挂载物流详情和用来发货的单号,而在子母件中,这个对应的是parentWaybillCode, 而waybillCode是子单号,不能用来发货。

ERP系统功能支持

ISV要支持用户填入获取快运子母件的必要参数,并且支持用户选择快递公司提供的物流服务。
当商家使用ERP系统填入需要获取 的总件数,

重量体积等单位转换

电子面单cainiao.waybill.ii.get接口中接受的重量体积的单位分别是g, ml。目前ISV -> CAINIAO -> 物流公司 之间的数据传输的单位都是以这个单位为准。 但是对于快运大件场景,如果仍然让用户填入g, ml 显然会不合适。ISV给客户展示的单位需要展示为kg, m3,在取号时,再将数据转换成g, ml传入接口。 数据的转换关系如下:
1 kg = 10 ^ 3 g
1 m3 = 10 ^ 6 ml

物流服务服务传值方式

请参考电子面单物流服务接入指南 中的5. ISV物流服务接入流程。
目前快运公司的物流服务均不需要订购和审核,ISV只需要按照文档的规则进行传值。

快运公司支持的物流服务

以下给出的服务定义,仅供参考, 实际服务选择应该以接口返回的数据,动态来创建。

CP Code Service Code 服务名称 服务描述 需要审核 需要订购 需要属性 需要必填 属性描述
安能快运(CN7000001000869) SVC-INSURE 保价服务 保价服务 false false true true
[
	{
		"name":"保价金额",
		"type":{
			"min":0,
			"type":"number",
			"required":true
		},
		"key":"value"
	}
]
安能快运(CN7000001000869) SVC-ANE56-PAYMENT-TYPE 安能物流产品支付类型服务 安能物流产品支付类型服务 false false true true
[
	{
		"name":"支付类型",
		"type":{
			"type":"enum",
			"required":true,
			"desc":{
				"102":"现金",
				"103":"到付",
				"104":"月结"
			}
		},
		"key":"value"
	}
]
安能快运(CN7000001000869) SVC-ANE56-DELIVERY-TYPE 安能物流配送类型服务 安能物流配送类型服务 false false true true
[
	{
		"name":"配送类型",
		"type":{
			"type":"enum",
			"required":true,
			"desc":{
				"179":"送货上楼",
				"180":"送货上门",
				"285":"自提"
			}
		},
		"key":"value"
	}
]
安能快运(CN7000001000869) SVC-ANE56-PRODUCT-TYPE 安能物流产品类型服务 安能物流产品类型 false false true true
[
	{
		"name":"产品类型",
		"type":{
			"type":"enum",
			"required":true,
			"desc":{
				"23":"定时达, 重量>70KG",
				"24":"标准快运",
				"211":"易碎品(标准快运), 重量>70KG",
				"212":"易碎品(定时达),重量>70KG",
				"213":"易碎品(mini小包),重量<=70KG",
				"270":"普惠达, 重量>1000KG",
				"95":"Mini小包, 重量<=70KG"
			}
		},
		"key":"value"
	}
]
韵达快运(CN7000001021040) SVC-YDKY-DELIVERY-RECEIPT 签收回单 签收回单 false false true false
[
	{
		"name":"签收回单",
		"type":{
			"type":"enum",
			"required":true,
			"desc":{
				"SIGNED":"签回单"
			}
		},
		"key":"value"
	}
]
韵达快运(CN7000001021040) SVC-YDKY-BIZ-TYPE 韵达快运业务类型 韵达快运业务类型 false false true true
[
	{
		"name":"业务类型",
		"type":{
			"type":"enum",
			"required":true,
			"desc":{
				"ECOMMERCE":"电商"
			}
		},
		"key":"value"
	}
]
韵达快运(CN7000001021040) SVC-YDKY-PRODUCT-TYPE 韵达快运产品类型 韵达快运产品类型 false false true true
[
	{
		"name":"产品类型",
		"type":{
			"min":0,
			"type":"enum",
			"required":true,
			"desc":{
				"YDKY-PROMISED-DELIVERY":"韵准达",
				"YDKY-168":"168大件",
				"YDKY-YUE-PROMISED-DELIVERY":"粤准达",
				"STANDARD_EXPRESS":"标准快运"
			}
		},
		"key":"value"
	}
]
韵达快运(CN7000001021040) SVC-INSURE 保价服务 用于定义保价金额 false false true true
[
	{
		"name":"保价金额",
		"type":{
			"min":0,
			"type":"number",
			"required":true
		},
		"key":"value"
	}
]
韵达快运(CN7000001021040) SVC-YDKY-PAYMENT-TYPE 韵达支付类型服务 用于定义运费的付款方式 false false true true
[
	{
		"name":"付款方式",
		"type":{
			"type":"enum",
			"required":true,
			"desc":{
				"RECEIVER-PAY":"到付",
				"MONTHLY-PAY":"月结",
				"CASH":"现金"
			}
		},
		"key":"value"
	}
]
韵达快运(CN7000001021040) SVC-YDKY-DELIVERY-TYPE 派送方式 派送方式 false false true true
[
	{
		"name":"派送方式",
		"type":{
			"type":"enum",
			"required":true,
			"desc":{
				"FLOOR":"送货上楼",
				"SELF":"自提",
				"SEND":"派送"
			}
		},
		"key":"value"
	}
]
壹米滴答快运(2744832184_543) SVC-YMDD-COD 壹米滴答货到付款 壹米滴答货到付款 false false true false
[
	{
		"name":"货到付款金额",
		"type":{
			"min":0,
			"type":"number",
			"required":true
		},
		"key":"value"
	},
	{
		"name":"账号名",
		"type":{
			"minLength":0,
			"type":"number",
			"maxLength":128,
			"required":true
		},
		"key":"account"
	},
	{
		"name":"用户名",
		"type":{
			"minLength":0,
			"type":"number",
			"maxLength":128,
			"required":true
		},
		"key":"name"
	},
	{
		"name":"退款类型",
		"type":{
			"type":"enum",
			"required":true,
			"desc":{
				"1":"无要求",
				"2":"24小时",
				"3":"48小时",
				"4":"72小时",
				"5":"96小时",
				"6":"特殊时效",
				"7":"现金发款"
			}
		},
		"key":"refunds"
	}
]
壹米滴答快运(2744832184_543) SVC-YMDD-TIMED-DELIVERY 壹米滴答时效服务 壹米滴答时效服务 false false true true
[
	{
		"name":"运输方式",
		"type":{
			"type":"enum",
			"required":true,
			"desc":{
				"1":"标准件",
				"2":"次日达",
				"3":"次晨达",
				"4":"优运件",
				"5":"内部件"
			}
		},
		"key":"value"
	}
]
壹米滴答快运(2744832184_543) SVC-INSURE 保价服务 保价服务 false false true true
[
	{
		"name":"保价金额",
		"type":{
			"min":0,
			"type":"number",
			"required":true
		},
		"key":"value"
	}
]
壹米滴答快运(2744832184_543) SVC-YMDD-PAYMENT-TYPE 壹米滴答支付类型服务 壹米滴答支付类型服务 false false true true
[
	{
		"name":"付款方式",
		"type":{
			"type":"enum",
			"required":true,
			"desc":{
				"1":"寄付",
				"2":"到付",
				"3":"月结"
			}
		},
		"key":"value"
	}
]
壹米滴答快运(2744832184_543) SVC-YMDD-DELIVERY-TYPE 壹米滴答配送类型服务 用于定义收货客户的提货方式 false false true true
[
	{
		"name":"提货方式",
		"type":{
			"type":"enum",
			"required":true,
			"desc":{
				"1":"港到门",
				"2":"港到港",
				"3":"门到门",
				"4":"门到港"
			}
		},
		"key":"value"
	}
]
百世物流(BESTQJT) SVC-BESTQJT-DELIVERY-RECEIPT 签收回单 签收回单 false false true false
[
	{
		"name":"回单方式",
		"type":{
			"type":"enum",
			"required":true,
			"desc":{
				"RECEIPT":"原单",
				"PHOTO":"拍照"
			}
		},
		"key":"value"
	}
]
百世物流(BESTQJT) SVC-BESTQJT-DELIVERY-SERVICE 百世配送类型增值服务 百世配送类型增值服务 false false true false
[
	{
		"name":"增值服务",
		"type":{
			"type":"enum",
			"required":true,
			"desc":{
				"UPSTAIRS":"上楼",
				"WAREHOUSE":"进仓"
			}
		},
		"key":"value"
	}
]
百世物流(BESTQJT) SVC-BESTQJT-COD 百世货到付款服务 百世货到付款服务 false false true false
[
	{
		"name":"金额",
		"type":{
			"min":0,
			"type":"number",
			"required":true
		},
		"key":"value"
	},
	{
		"name":"开户名",
		"type":{
			"minLength":1,
			"type":"string",
			"maxLength":128,
			"required":true
		},
		"key":"name"
	},
	{
		"name":"开户账户",
		"type":{
			"minLength":0,
			"type":"string",
			"maxLength":128,
			"required":true
		},
		"key":"account"
	},
	{
		"name":"退款方式",
		"type":{
			"type":"enum",
			"required":true,
			"desc":{
				"TODAY":"即日退",
				"THREE-DAYS":"三日退"
			}
		},
		"key":"refunds"
	}
]
百世物流(BESTQJT) SVC-BESTQJT-TRANSPORT-TYPE 百世运输类型服务 百世运输类型服务 false false true true
[
	{
		"name":"运输类型",
		"type":{
			"type":"enum",
			"required":true,
			"desc":{
				"ECOMMERCE":"电商"
			}
		},
		"key":"value"
	}
]
百世物流(BESTQJT) SVC-BESTQJT-INSURE 保价服务 保价服务 false false true true
[
	{
		"name":"保价金额",
		"type":{
			"min":0,
			"type":"number",
			"required":true
		},
		"key":"value"
	}
]
百世物流(BESTQJT) SVC-BESTQJT-RECEIVER-PAY 百世到付 百世到付 false false true false
[
	{
		"name":"到付金额",
		"type":{
			"min":0,
			"type":"number",
			"required":true
		},
		"key":"value"
	}
]
百世物流(BESTQJT) SVC-BESTQJT-DELIVERY-TYPE 百世配送类型服务 百世配送类型服务 false false true true
[
	{
		"name":"配送类型",
		"type":{
			"type":"enum",
			"required":true,
			"desc":{
				"SELF":"自提",
				"SEND":"送货"
			}
		},
		"key":"value"
	}
]
德邦快运(CN7000001009020) SVC-DELIVERY-RECEIPT 德邦签收回单 德邦签收回单服务 false false true false
[
	{
		"name":"签收回单",
		"type":{
			"type":"enum",
			"required":true,
			"desc":{
				"BILL_SIGNED_FAX":"运单到达联传真返回",
				"CUSTOMER_SIGNED_ORIGINAL":"签收单原件返回",
				"CUSTOMER_SIGNED_FAX":"客户签收单传真返回",
				"NO_RETURN_SIGNED":"无需返单"
			}
		},
		"key":"value"
	}
]
德邦快运(CN7000001009020) TRANSPORT-TYPE 德邦运输类型服务 德邦运输类型服务 false false true true
[
	{
		"name":"运输方式",
		"type":{
			"type":"enum",
			"required":true,
			"desc":{
				"SLOW-TRUCKS":"慢车",
				"FAST-TRUCKS":"快车"
			}
		},
		"key":"value"
	}
]
德邦快运(CN7000001009020) SVC-COD 德邦货到付款 德邦货到付款 false false true false
[
	{
		"name":"金额",
		"type":{
			"min":0,
			"type":"number",
			"required":true
		},
		"key":"value"
	},
	{
		"name":"开户名",
		"type":{
			"minLength":1,
			"type":"string",
			"maxLength":128,
			"required":true
		},
		"key":"name"
	},
	{
		"name":"开户账户",
		"type":{
			"minLength":1,
			"type":"string",
			"maxLength":128,
			"required":true
		},
		"key":"account"
	},
	{
		"name":"退款方式",
		"type":{
			"type":"enum",
			"required":true,
			"desc":{
				"TODAY":"即日退",
				"THREE-DAYS":"三日退"
			}
		},
		"key":"refunds"
	}
]
德邦快运(CN7000001009020) SVC-INSURE 保价服务 保价服务 false false true true
[
	{
		"name":"保价金额",
		"type":{
			"min":0,
			"type":"number",
			"required":true
		},
		"key":"value"
	}
]
德邦快运(CN7000001009020) PAYMENT-TYPE 德邦支付类型服务 德邦支付类型服务 false false true true
[
	{
		"name":"支付类型",
		"type":{
			"type":"enum",
			"required":true,
			"desc":{
				"RECEIVER-PAY":"到付",
				"MONTHLY":"月结",
				"SENDER-PAY":"现付"
			}
		},
		"key":"value"
	}
]
德邦快运(CN7000001009020) DELIVERY-TYPE 德邦配送类型服务 德邦配送类型服务 false false true true
[
	{
		"name":"配送类型",
		"type":{
			"type":"enum",
			"required":true,
			"desc":{
				"UPSTAIRS":"上楼",
				"SELF":"自提",
				"SEND":"送货"
			}
		},
		"key":"value"
	}
]
速尔快递(SURE) SVC-DELIVERY-RECEIPT 签收单 签收单 false false true false
[
	{
		"name":"签收单的返单类型",
		"type":{
			"type":"enum",
			"required":true,
			"desc":{
				"BILL_SIGNED_FAX":"运单到达联传真返回",
				"CUSTOMER_SIGNED_ORIGINAL":"签收单原件返回",
				"CUSTOMER_SIGNED_FAX":"客户签收单传真返回",
				"NO_RETURN_SIGNED":"无需返单"
			}
		},
		"key":"value"
	}
]
速尔快递(SURE) SVC-TRANSPORT-TYPE 运输方式 运输方式 false false true true
[
	{
		"name":"运输方式",
		"type":{
			"type":"enum",
			"required":true,
			"desc":{
				"VEHICLE":"汽运",
				"AIR":"空运"
			}
		},
		"key":"value"
	}
]
速尔快递(SURE) SVC-INSURE 保价 保价 false false true false
[
	{
		"name":"保价金额",
		"type":{
			"min":0,
			"type":"number",
			"required":true
		},
		"key":"value"
	}
]
速尔快递(SURE) PAYMENT-TYPE 付款方式 付款方式 false false true true
[
	{
		"name":"付款方式",
		"type":{
			"type":"enum",
			"required":true,
			"desc":{
				"RECEIVER-PAY":"到付",
				"SENDER-MONTHLY-PAY":"寄付月结",
				"SENDER-PAY":"寄付"
			}
		},
		"key":"value"
	}
]
速尔快递(SURE) SVC-DELIVERY-TYPE 交货方式 交货方式 false false true false
[
	{
		"name":"提货方式",
		"type":{
			"type":"enum",
			"required":true,
			"desc":{
				"SELF":"自提",
				"SEND":"派送"
			}
		},
		"key":"value"
	}
]
中通快运(3108002701_1011) SVC-ZTOKY-DELIVERY-RECEIPT 中通快运签收回单 中通快运签收回单 false false true false
[
	{
		"name":"签收回单",
		"type":{
			"type":"enum",
			"required":true,
			"desc":{
				"BILL_SIGNED_FAX":"运单到达联传真返回",
				"CUSTOMER_SIGNED_ORIGINAL":"签收单原件返回",
				"CUSTOMER_SIGNED_FAX":"客户签收单传真返回",
				"NO_RETURN_SIGNED":"无需返单"
			}
		},
		"key":"value"
	}
]
中通快运(3108002701_1011) SVC-ZTOKY-COD 中通快运代收货款 中通快运代收货款 false false true false
[
	{
		"name":"金额",
		"type":{
			"min":0,
			"type":"number",
			"required":true
		},
		"key":"value"
	},
	{
		"name":"开户名",
		"type":{
			"minLength":1,
			"type":"string",
			"maxLength":128,
			"required":true
		},
		"key":"name"
	},
	{
		"name":"开户账户",
		"type":{
			"minLength":1,
			"type":"string",
			"maxLength":128,
			"required":true
		},
		"key":"account"
	},
	{
		"name":"退款方式",
		"type":{
			"type":"enum",
			"required":true,
			"desc":{
				"TODAY":"即日退",
				"THREE-DAYS":"三日退"
			}
		},
		"key":"refunds"
	}
]
中通快运(3108002701_1011) SVC-ZTOKY-TRANSPORT-TYPE 中通快运运输类型 中通快运运输类型 false false true true
[
	{
		"name":"运输类型",
		"type":{
			"type":"enum",
			"required":true,
			"desc":{
				"STANDARD":"标准快运"
			}
		},
		"key":"value"
	}
]
中通快运(3108002701_1011) SVC-INSURE 保价服务 保价服务 false false true true
[
	{
		"name":"保价金额",
		"type":{
			"min":0,
			"type":"number",
			"required":true
		},
		"key":"value"
	}
]
中通快运(3108002701_1011) SVC-ZTOKY-PAYMENT-TYPE 中通快运付款方式 中通快运付款方式 false false true true
[
	{
		"name":"付款方式",
		"type":{
			"type":"enum",
			"required":true,
			"desc":{
				"RECEIVER-PAY":"到付",
				"MONTHLY":"月结"
			}
		},
		"key":"value"
	}
]
中通快运(3108002701_1011) SVC-ZTOKY-DELIVERY-TYPE 中通快运配送方式 中通快运配送方式 false false true true
[
	{
		"name":"配送方式",
		"type":{
			"type":"enum",
			"required":true,
			"desc":{
				"SELF":"自提",
				"SEND":"派送"
			}
		},
		"key":"value"
	}
]

服务选择

本次订购关系查询接口cainiao.waybill.ii.search 中新增服务属性相关数据,前端可以根据该服务属性实现服务选择界面
商家选择快运的快递公司后,需要给商家提供选择快运服务的能力,这个和之前的快递选择服务是一样的接口。

  • service_desc 是该服务的描述,可以展示给前端
  • service_attributes是该服务支持的所有的属性
  • attribute_code是属性的key
  • attribute_name属性的名称
  • attribute_type属性的类型,可能值有 [number, string, enum, boolean]
  • type_desc枚举类型的枚举值,key为用户选中的需要传值的数据,value为对应的描述,可以作为前端的展示, type为enum类型的渲染成下拉选择框,其它的type可以渲染成输入框,一个可能作为参考的UI如下

image

以下是cainiao.waybill.ii.search接口返回的,关于服务部分的数据

"service_info_cols":{
                                    "service_info_dto":[
                                        {
                                            "service_name":"物流产品类型服务",
                                            "service_code":"SVC-ANE56-PRODUCT-TYPE",
                                            "service_attributes":{
                                                "service_attribute_dto":[
                                                    {
                                                        "attribute_code":"value",
                                                        "attribute_name":"产品类型",
                                                        "attribute_type":"enum",
                                                        "type_desc":"{\"type\":\"enum\",\"desc\":{\"95\":\"Mini小包, 重量<=70KG\",\"23\":\"定时达, 重量>70KG\",\"270\":\"普惠达, 重量>1000KG\",\"211\":\"易碎品(标准快运), 重量>70KG\",\"212\":\"易碎品(定时达),重量>70KG\",\"213\":\"易碎品(mini小包),重量<=70KG\"}}"
                                                    }
                                                ]
                                            },
                                            "service_desc":"安能物流产品类型",
                                            "required":true
                                        }
                                    ]
                                }

ISV在实现物流服务选择界面时,可以考虑通过客户端缓存的数据,动态的渲染,不要讲服务相关数据写死,以便以后快递公司服务属性调整。当物流服务变更时,ISV不需要感知。

在电子面单的取号接口cainiao.waybill.ii.get
trade_order_info_dtos.logistics_services 字段中传入用户选择的物流服务。

当服务的属性 "required":true 时, 表明该服务为必选服务,必选服务必须传入。

当service_attributes节点为空的时候,说明该服务不需要属性,可以传入空的属性

{ "SVC-PRIOR-DELIVERY": {} }

传值规范为

{"$service_code" : {"$attribute_code": $attribute_value, ...}}

比如

{ "SVC-ANE56-PRODUCT-TYPE": { "value": "24" } }

云打印模板的选择

ISV可以根据快运物流公司,使用云打印查询接口获取到对应的打印模板。

子母件取消接口行为

  • 不能取消子件
  • 取消母件则取消所有子件

子母件更新接口行为

子母件不允许更新

云打印报文加密

返回的报文将对非客户相关信息进行加密,客户端可以获取到子母件的子单号和母单号。

FAQ

关于此文档暂时还没有FAQ
返回
顶部