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

顺丰取号指南

更新时间：2022/07/14 访问次数：19279

背景说明
面单模板获取接口 cainiao.cloudprint.stdtemplates.get
商家自定义区获取接口
查询面单服务订购及面单使用情况接口
电子面单云打印接口
物流订单确认接口
物流订单取消接口
派件通知接口
常见问题

背景说明

顺丰本次接入菜鸟电子面单是以多品牌的方式接入，接入了两个品牌，分别是顺丰速运，顺丰快运。

菜鸟电子面单取号领域引入品牌的概念，顺丰的面单模版绑定在品牌下，不同品牌面单模版不同；取顺丰号时，也需要需要传入品牌code。

面单模板获取接口
cainiao.cloudprint.stdtemplates.get

链接：https://open.taobao.com/api.htm?spm=a219a.15212433.0.0.3891669ahPipmo&source=search&docId=26756&docType=2

图中红色的参数表示本次新增，以及新增的位置。响应参数增加品牌code

其他无品牌cp的brandCode为 default

商家自定义区获取接口

cainiao.cloudprint.mystdtemplates.get

无品牌的模板对应的自定义区的 brand_code 字段为 default

查询面单服务订购及面单使用情况接口

cainiao.waybill.ii.search

链接： https://open.taobao.com/doc.htm?docId=27125&docType=2#s20

图中红色的参数表示本次新增，以及新增的位置。接口返回值增加参数 brand_code、customer_code

返回值说明

名称

类型

描述

brand_code

String

品牌编码。顺丰目前有两个品牌

（

顺丰速运，SF

顺丰快运, FOP

），可从订购关系查询接口cainiao.waybill.ii.search 中获取品牌code，

为了兼容原有逻辑，顺丰品牌code还会有default类型，用来表示本次接入前就存在的旧的顺丰订购关系，只有部分商家会存在这样的订购关系，后面新增的商家不会有这样的订购关系。取号时传入brandCode传入default，会走老的菜鸟取号链路，而不是直连顺丰取号。

customer_code_list

数组

商家的月结卡号列表

电子面单云打印接口

cainiao.waybill.ii.get

链接： https://open.taobao.com/api.htm?docId=26869&docType=2

新增参数具体说明

参数名	参数类型	是否必须	描述
brand_code	String	否，（SF取号必须）。	品牌编码。顺丰目前有两个品牌（顺丰速运，SF 顺丰快运, FOP ），可从订购关系查询接口cainiao.waybill.ii.search 中获取品牌code，为了兼容原有逻辑，顺丰品牌code还会有default类型，用来表示本次接入前就存在的旧的顺丰订购关系，只有部分商家会存在这样的订购关系，后面新增的商家不会有这样的订购关系。取号时传入brandCode传入default，会走老的菜鸟取号链路，而不是直连顺丰取号。
customer_code	String	否（SF取号速运、快运必须）	月结卡号，可从订购关系中获取。丰网速运无需月结卡号，月结卡号无需和订购关系的地址绑定，即用A订购关系地址，可以用B订购关系的月结卡号取号。丰网速运无需传入此参数
extra_info	String	否	扩展字段，jsonstring。用于传递各种顺丰个性化参数
call_door_pick_up	boolean	否	是否预约上门收件
door_pick_up_time	String	否	预约上门收件时间，示例值：2021-08-07 12:34:30
door_pick_up_end_time	String	否	预约上门截止时间，示例值: 2021-08-07 12:34:30
good_value	number	否	物品价值，单位元
length	number	否	包裹长，单位厘米
width	number	否	包裹宽，单位厘米
height	number	否	包裹高，单位厘米
waybill_code	String	否	传入面单进行取号，取号成功，将返回此面单号

原顺丰取号参数与菜鸟取号参数映射

顺丰取号参数字段	顺丰解释	菜鸟取号接口参数
waybillNoInfoList	快运场景下，需要传递长宽高	新增参数 length 包裹长度，单位厘米（trade_order_info_dtos.package_info.length） width 包裹宽度，单位厘米 (trade_order_info_dtos.package_info.width) height 包裹高度，单位厘米 (trade_order_info_dtos.package_info.height)
cargoDetails	拖寄物信息	trade_order_info_dtos.package_info.item.name
cargoDesc	拖寄物类型描述,如：文件，电子产品，衣服等	goods_description
extraInfoList	扩展属性	新增字段，extraInfo，为jsonstring格式
serviceList	增值服务信息	已有参数,取logistics_services
contactInfoList	收寄双方信息	已有参数,收寄双方信息
monthlyCard	顺丰月结卡号	新增字段，customer_code
expressTypeId	快件产品类别	已有参数，取product_code
parcelQty	包裹数，一个包裹对应一个运单号；若包裹数大于1，则返回一个母运单号和N-1个子运单号。	total_packages_count
totalLength	客户订单货物总长，单位厘米，精确到小数点后3位，包含子母件。	置于extraInfo中
totalWidth	客户订单货物总宽，单位厘米，精确到小数点后3位，包含子母件。	置于extraInfo中
totalHeight	客户订单货物总高，单位厘米，精确到小数点后5位，包含子母件。	置于extraInfo中
totalVolume	订单货物总体积，单位立方厘米，精确到小数点后3位，会用于计抛（是否计抛具体商务沟通中双方约定）	置于extraInfo中
totalWeight	订单货物总重量，包含子母件，单位千克，精确到小数点后3位，如果提供此值，必须>0	置于extraInfo中
totalNetWeight	商品总净重	置于extraInfo中
sendStartTm	要求上门取件开始时间，格式：YYYY-MM-DD HH24:MM:SS，示例：2012-7-30 09:30:00。	door_pick_up_time
isDocall	是否通过手持终端通知顺丰收派员上门收件，支持以下值 1：要求 0：不要求	call_door_pick_up
isSignBack	是否返回签回单（签单返还）的运单号，支持以下值： 1：要求 0：不要求	置于extraInfo中
custReferenceNo	客户参考编码：如客户原始订单	trade_order_list
temperatureRange	温度范围类型，当express_type为12医药温控件时必填，支持以下值： 1:冷藏 3：冷冻	置于extraInfo中
orderSource	订单平台类型	order_channels_type
remark	备注	置于extraInfo中
isOneselfPickup	快件自取，支持以下值： 1：客户同意快件自取 0：客户不同意快件自取	置于extraInfo中
specialDeliveryTypeCode	特殊派送类型代码 1:身份验证 2:极效前置单	置于extraInfo中
specialDeliveryValue	1>特殊派件具体表述证件类型:证件后8位如：1:09296231（1表示身份证，暂不支持其他证件） 2>.极效前置单时:Y:若不支持则返回普通运单 N:若不支持则返回错误码	置于extraInfo中
podModelAddress	签单返还范本地址	置于extraInfo中
isvClientCode	客户接入编码	置于extraInfo中，原SF直连取号的顾客编码
payMethod	支付方式	置于extraInfo中，如 {"extra_info": "{\"payMethod\": 3}"}。丰网速运不支持此参数。支付方式说明：普通月结：无需传入payMethod 现结： payMethod = 1,无需传入月结卡号到付：payMethod = 2，无需传入月结卡号第三方付：payMethod = 3，需月结卡号

响应参数

响应参数，新增extra_info

字段名	参数类型	描述
extra_info	String	扩展字段。目前支持透出顺丰取号接口返回值的remark字段。示例： {"remark": "xxxx"}

物流订单确认接口

cainiao.waybill.ii.confirm

请求参数

{
  "cp_code": "SF",
  "waybill_info" : [
    {
      "waybill_code": "",
      "length": 1, // 包裹长，单位厘米
      "width": 2,  // 包裹宽，单位厘米
      "height": 2, // 包裹高，单位厘米
      "volume": 1, //体积, 单位 ml
      "weight": 1, //重量,单位 g
    }
  ],
  "product_code": "产品编码",
  "extra_info": "扩展字段",
  "logistics_services": "物流服务",
  "call_door_pick_up": false, // 预约上门收件
  "door_pick_up_time": "2021-08-07 12:34:30" ,// 预约上门的时间
  "door_pick_up_end_time" : "2021-08-07 12:34:30" , //预约上门截止时间
  "totalLength": 11 , // "客户订单货物总长,单位厘米",
  "totalWidth" : 11, // "客户订单货物总宽，单位厘米",
  "totalHeight": 12, // "客户订单货物总高，单位厘米"
  
}

字段	数据类型	是否必须	说明
cp_code	String	是	物流供应商编码
waybill_info	Array	是	普通包裹只能传一个，只有子母件可以一次性将子母单号一起传入
waybill_info.waybill_code	String	是	面单号
waybill_info.length	number	否	包裹长，单位厘米
waybill_info.width	number	否	包裹宽，单位厘米
waybill_info.height	number	否	包裹高，单位厘米
waybill_info.volume	number	否	体积, 单位 ml
waybill_info.weight	number	否	重量,单位 g
product_code	String	否	产品编码, 对应顺丰expressTypeId字段
extra_info	String	否	扩展字段，jsonString
logistics_services	String	否	物流服务
call_door_pick_up	boolean	否	是否预约上门
door_pick_up_time	String	否	预约上门时间，2021-08-07 12:34:30
door_pick_up_end_time	String	否	预约上门截止时间，2021-08-07 12:34:30
totalLength	number	否	订单货物总长,单位厘米
totalWidth	number	否	订单货物总宽，单位厘米
totalHeight	number	否	客户订单货物总高，单位厘米

顺丰个性化参数 specialDeliveryTypeCode、specialDeliveryValue 置于extra_info中传入，extra_info会透传给顺丰，个性化参数可以置于其中。

响应参数

成功参数

{
  "cainiao_waybill_ii_confirm_response": {
    "confirm_response": {
      "waybill_order_confirm_response": [
        {
          "waybill_code": "ADBS123445"
        }
      ]
    },
    "request_id": "14xz572dtb45i"
  }
}

失败示例

{
  "error_response": {
    "code": 15,
    "msg": "Remote service error",
    "sub_code": "METHOD_NOT_SURPORT",
    "sub_msg": "此接口暂未上线",
    "request_id": "14xz572d5243u"
 }

物流订单取消接口

cainiao.waybill.ii.cancel

链接：https://open.taobao.com/api.htm?docId=26766&docType=2&source=search

此接口无变更，直接按照文档对接即可。

派件通知接口

cainiao.waybill.ii.delivery

链接 https://open.taobao.com/api.htm?docId=58834&docType=2

这个是一个在电商节时必用的一个接口，派件通知，意思为商家提前下单，客户付款后才通知CP进行派件

常见问题

问题：顺丰是否支持批量取号？

答：顺丰除子母件外，普通包裹不支持批量取号。

问题：顺丰子母件该如何传参数？

答：trade_order_info_dtos[0].package_info.total_packages_count 大于等于1则表示子母件取号。顺丰的子母件取号支持批量取号，子母件批量最大取号数量可以支持10个。但需要保证批量取号请求中，订单号trade_order_list一致，包裹号package_info.id不同。同时顺丰的子母件支持子单号追加，一开始total_packages_count=10，取完10个单号后，还可以继续追加取出子母件单号，这时只要保证trade_order_list跟之前一致，package_info.id不同即可。

问题: 为什么打出来的模板没有三段码信息等信息

答: 如果取号时候使用了带品牌的取号方式,那么也必须使用带品牌的模板,如果两者混用,则会出现面单缺失信息

问题：丰网速运如何取号？

答：丰网速运为加盟型快递业务，在电子面单平台申请订购关系后，需要网点审核。网点审核后，还需要充值面单余额，取号传入的寄件地址需要与订购的地址完全相同才能取号成功。

问题：丰网速运是否支持子母件

答：丰网暂不支持子母件，请不要设置 total_packages_count的值

问题：顺丰速运、快运支持哪些支付方式？

答：支付方式，在extra_info中传入payMethod, 如 {"extra_info": "{\"payMethod\": 3}"}。丰网速运不支持此参数。支付方式说明

普通月结：无需传入payMethod

现结： payMethod = 1, 无需传入月结卡号
到付：payMethod = 2，无需传入月结卡号

第三方付：payMethod = 3，需月结卡号

问题：顺丰链路是否支持隐私面单？

答：顺丰链路不支持隐私面单服务：SVC-PRIVACY-OPTIN。请不要传入，顺丰链路的隐私面单由淘宝前台放量控制。

问题：取号提示重复下单，是什么原因？

答：取号提示重复下单，一般是因为当前订单号取过一次面单号，取消后再来取号就会出现这样的情况。请修改
trade_order_list的订单号再来重新取号。如果之前trade_order_list传入的淘宝真实交易单号，修改后无法解密。可以将淘宝真实交易订单号置于tid中，trade_order_list传入自己系统的其他单号取号即可。

问题：速运，快运，丰密，脱敏，加密，隐私面单都是什么

答：速运、快运都是顺丰的品牌，丰密是顺丰的叫法，指的是面单信息是脱敏显示的，目前速运、快运是丰密模板，而丰网目前是明文显示的。隐私面单是指菜鸟提供的用户信息脱敏功能，除了显示的信息脱敏之外，还会在面单上提供一个虚拟号码，用于联系收件人。所谓的脱敏就是将面单上的部分信息用*来代替。

FAQ

关于此文档暂时还没有FAQ

有用(0) 我要提问

电子面单对接知识库

顺丰取号指南

背景说明

面单模板获取接口cainiao.cloudprint.stdtemplates.get

商家自定义区获取接口

查询面单服务订购及面单使用情况接口

电子面单云打印接口

新增参数具体说明

响应参数

物流订单确认接口

请求参数

响应参数

物流订单取消接口

派件通知接口

常见问题

问题： 顺丰是否支持批量取号？

问题：顺丰子母件该如何传参数？

问题: 为什么打出来的模板没有三段码信息等信息

问题： 丰网速运如何取号？

问题： 丰网速运是否支持子母件

问题： 顺丰速运、快运支持哪些支付方式？

问题： 顺丰链路是否支持隐私面单？

问题：取号提示重复下单，是什么原因？

问题：速运，快运，丰密，脱敏，加密，隐私面单都是什么

FAQ

面单模板获取接口
cainiao.cloudprint.stdtemplates.get

问题：顺丰是否支持批量取号？

问题：丰网速运如何取号？

问题：丰网速运是否支持子母件

问题：顺丰速运、快运支持哪些支付方式？

问题：顺丰链路是否支持隐私面单？