快递鸟API电子面单接口说明文档

KJ-TD-KDN-【对外】接口技术文档快递鸟电子面单接口说明文档快递鸟2017-04-25版本日期版本说明作者2017-04-252.0创建文档，第一版请参考接口技术文档V4.2.1第三章3.3电子面单 蒋雪姣一、 前言1、 业务背景随着电子商务和物流信息化服务的迅猛发展，电子面单已经成为了商家快速发货并连接订单与物流的有力工具。快递鸟电子面单接口是快递鸟提供给独立电商、仓储管理系统、打单软件、物流供应链等物流系统平台使用的物流下单接口，满足商家在线发货需求并提供打印电子面单的服务。商家通过贵司系统选择物流公司发送请求通知快递公司有快递要发货，贵公司把数据通过此接口转发到快递鸟，由快递鸟为商家通知对应的快递公司快递员上门取件。电子面单成功下单后，快递鸟系统内将自动订阅，一旦轨迹发生变化时，快递鸟将调用贵司推送接收接口将物流信息反向推送至商家。同时若客户使用代收货款服务，快递鸟会将代收货款的货款状态独立推送给商家用户。电子面单具有如下特点：l 打印效率高相比传统针式打印机套打模式，打印速度提升6-8倍，热敏打印机打印速度平均30-40张/分。l 发货效率高包裹出库时减少了抽底单的工序，降低了操作成本、提升操作效率，运单和订单即时绑定，无需人工再次扫描绑定发货。目前商家在使用电子面单的过程中也存在一些情况导致部分用户无法顺畅使用，例如：l 大电商有多家合作快递公司，各家快递公司的模板尺寸不一，需要使用多个打印机打印面单。 l 单号作废后回收机制不完善导致电商成本升高。 l 二联电子面单无底单，运费核账存在问题（部分商家货物重量以称重为准）。l 打印时发现面单号余额不足，耽误发货。l 小B电商发货量不够申请网点的电子面单服务。快递鸟电子面单接口为解决客户以上问题，新增如下解决方案：l 电子面单余量查询：可通过电子面单余量查询接口查询，并且在快递鸟官网可设置余额不足提醒值（后续会加上余额不足短信/邮件提醒功能）l 电子面单取消/回收：可通过电子面单取消接口，回收部分加盟快递公司的面单号。l 通用电子面单模板，含二联、三联模板l 快递公司电子面单客户号在线申请l 散户模式电子面单：部分快递公司无需申请电子面单客户号即可直接打印电子面单。2、 名词解释1电子面单一种新型的快递面单。材料为热敏纸，有成本低、打印快、单号方便获取、管理等特点。2大客户与快递公司签订合作协议的客户，有快递公司客户号或月结账号。此类客户支持运费月结、到付、现付。3散户与快递公司无合作关系，无客户号，支持运费现付/到付运费。二、 快递鸟电子面单方案1、 编码规范目前接口支持了：顺丰（SF）、EMS（EMS）、宅急送（ZJS）、圆通（YTO）、百世快递（HTKY）、中通（ZTO）、韵达（YD）、申通（STO）、德邦（DBL）、优速（UC）、京东（JD）、信丰（XFEX）、全峰（QFKD）、跨越速运（KYSY）、安能小包（ANE）、快捷快递（FAST）、国通（GTO）、天天快递（HHTT），后续更多的快递公司正在对接中。散户模式（无需电子面单客户号）支持快递公司：顺丰（SF）、EMS（EMS）（仅支持广东省内发货）、快捷快递（FAST）、宅急送（ZJS），后续更多的快递公司正在对接中。电子面单客户号在线申请支持快递公司：优速（UC）、后续更多的快递公司正在对接中。余量查询接口支持快递公司：中通（ZTO）、韵达（YD）、优速（UC）、后续更多的快递公司正在对接中。面单回收接口支持快递公司：优速（UC）、后续更多的快递公司正在对接中。2、 业务流程n 商家需要做什么l 商家使用流程l 配置物料a) 电子面单需要使用热敏打印机，可与当地网点申请或自行通过淘宝、京东等电商平台购买，目前市场上支持的厂家和型号包括：斑马G886T、启锐、佳博等b) 打印纸：电子面单需要使用热敏纸，可与当地网点申请打印纸物料或者自行在淘宝等电商平台、线下文具店购买，打印纸尺寸需要根据打印模板尺寸购买或定制。l 商家在线申请电子面单客户号截图：申请服务商的界面截图截图：申请服务商的提交界面截图选择网点：网点为根据发货地址自动匹配，若有多个需您自行选择，快递公司总部审核通过后会分配正确的网点。l 申请快递公司电子面单客户号说明：a) 电子面单客户号即请求打印面单时的用户账号或月结编码或客户编码，不同物流服务商的叫法不同而已。b) 若商家无需月结运费，电子面单API请求参数CustomerName “电子面单客户账号”无需填写可直接请求打单，无需申请电子面单客户号。支持快递公司：顺丰（SF）、EMS（EMS）（仅支持广东省内发货）、快捷快递（FAST）、宅急送（ZJS），后续更多的快递公司正在对接中。c) 若商家已有电子面单客户号，则对接快递鸟电子面单API请求参数CustomerName “电子面单客户号”输入商家的客户号和密码通过验证即可打单。d) 在线申请客户号说明：因为物流快递商运营模式的不同（分为加盟和直营），加盟型运营商是以网点为单位进行账户核算，所以您需要和每个快递网点建立合作，通过快递鸟申请服务后，网点会联系您审核并且办理单量充值。而直营型服务商由快递总部与发货人绑定运费结算关系，无需再联系快递公司充值单号，直营快递公司审核通过后即可打单。目前支持在线申请客户号的快递公司：优速（UC），后续更多的快递公司正在对接中。l 电子面单余量提醒值设置快递鸟官网-用户管理后台-电子面单-账户信息-批量设置余量不足提醒值。 n 系统对接需要做什么l 快递鸟接口对接通用流程：l 电子面单接口对接流程：a) 注册快递鸟ID：/regb) 实名认证：c) 申请电子面单API：在快递鸟用户管理后台-申请API页面，点击申请电子面单API，快递鸟审核通过后即可开始对接。d) 对接联合注册接口：若贵司平台系统有多家发货商家，建议同时对接联合注册接口，以便区分您平台用户，并实现各发货商家独立使用代收货款服务。接口文档参考：快递鸟代收货款-1.1 用户注册接口。非必需接入。e) 对接电子面单接口：请参考第三章：接口说明f) 前端界面开发：您需要为商家增加打印电子面单的组件，包括：添加电子面单打印模板（模板保存在系统本地或通过接口即时在线获取均可）、商家绑定电子面单客户账号（账号、密码、取件网点等信息，具体参考快递鸟电子面单参数配置对照表，建议在商家选择快递公司打印模板时让商家输入提交保存。）、打印界面和控件调试（偏移调试）。3、 系统设计规范添加电子面单打印模板/添加快递公司界面示例：商家需要绑定电子面单账号信息，建议根据快递鸟电子面单参数配置对照表显示各家快递公司需要输入的字段。4、 应用场景说明n 下单+打印a) 商家操作发货时同步订单的发/收件人信息、货物信息，通过接口直接发送到快递公司获取电子面单单号、大头笔、电子面单打印模板等信息。通过浏览器或CS结构客户端打印工具进行打印电子面单。n 筛单a) 电子面单下单时快递公司需要确认订单是否在收派范围之内，故需要将订单信息的收件地址和寄件地址进行筛单校验。n 取消/回收单号a) 已生成电子面单运单号的面单，在快递公司未揽件前可申请取消面单。b) 面单号取消后，加盟型快递公司大客户号的面单会按每家快递公司规则回收，余量对应加1。c) 每个面单号只支持取消一次。d) 每个客户号取消的单号总量不能超过获取单号数量的20%。e) 快递公司回收单号机制配置表如下：快递公司手动取消自动取消/回收EMS不支持不支持顺丰不支持不支持圆通不支持每月10日左右回收往前两个月一整月浪费面单号。如当前月为4月，则回收2月整月已拉取无物流路由信息的电子面单单号，返款给站点，由站点与商家结算回收单号。百世支持单号获取后2个月内无路由信息，自动回收单号，返款给站点，由站点与商家结算回收单号。中通快递鸟暂不支持快递鸟暂不支持韵达支持单号获取后30天无路由信息，自动回收单号，单号可以再次使用。申通快递鸟暂不支持不支持德邦快递鸟暂不支持单号获取后30天无路由信息，自动回收单号.优速请求取消后15天无路由信息回收单号单号获取后30天无路由信息，自动回收单号.宅急送不支持不支持京东不支持不支持信丰不支持不支持全峰不支持不支持跨越速运不支持不支持安能不支持单号获取后30天无路由信息，自动回收单号。快捷不支持不支持天天快递鸟暂不支持快递鸟暂不支持国通快递鸟暂不支持不支持n 余量查询a) 与网点预充值单量情况下才需要查询余量。散户模式无需查询余量。b) 直营快递公司无需查询余量。c) 单量查询快递公司配置表。快递公司是否支持EMS不支持顺丰不支持圆通快递鸟暂不支持，请至官网查询百世快递鸟暂不支持，请至官网查询中通支持韵达支持申通快递鸟暂不支持，请至官网查询德邦快递鸟暂不支持，请至官网查询优速支持宅急送快递鸟暂不支持，请至官网查询京东快递鸟暂不支持，请至官网查询信丰快递鸟暂不支持，请至官网查询全峰快递鸟暂不支持，请至官网查询跨越速运快递鸟暂不支持，请至官网查询安能快递鸟暂不支持，请至官网查询快捷快递鸟暂不支持，请至官网查询天天快递鸟暂不支持，请至官网查询国通快递鸟暂不支持，请至官网查询三、 接口说明1.1 电子面单1.1.1 功能说明电子面单接口是快递鸟提供给独立电商、仓储管理系统、物流供应链等物流系统平台使用的下单接口，满足客户在线发货需求并提供打印面单的服务，客户通过网络选择物流公司发送请求通知贵公司有快递要发货，贵公司把数据通过此接口转发到快递鸟，由快递鸟为您通知对应的快递公司快递员上门取件。电子面单成功下单后，快递鸟系统内将自动订阅，一旦轨迹发生变化时，快递鸟将调用客户方推送接收接口。同时若客户使用代收货款服务，快递鸟会将代收货款的货款状态独立推送给用户。1.1.2 接口规则(1)、只支持Json格式。接口指令1007。(2)、订单编号(OrderCode)不可重复提交，重复提交系统会返回具体错误代码。(3)、目前接口支持了：顺丰（SF）、EMS（EMS）、宅急送（ZJS）、圆通（YTO）、百世快递（HTKY）、中通（ZTO）、韵达（YD）、申通（STO）、德邦（DBL）、优速（UC）、京东（JD）、信丰（XFEX）、全峰（QFKD）、跨越速运（KYSY）、安能小包（ANE）、快捷快递（FAST）、国通（GTO）、天天快递（HHTT），后续更多的快递公司正在对接中。散户模式（无需电子面单客户号）支持快递公司：顺丰（SF）、EMS（EMS）（仅支持广东省内发货）、优速（UC）、快捷快递（FAST）、宅急送（ZJS），后续更多的快递公司正在对接中。(4)、测试地址：http:/testapi.kdniao.cc:8081/api/eorderservice/(5)、正式地址：http:/api.kdniao.cc/api/EOrderService (6)、请求报文中不允许出现以下特殊字符： # & + 1.1.3 系统级和应用级输入参数系统级输入参数应用级输入参数类型是否必须描述RequestData（必填参数，请求内容，JSON格式,须和DataType一致）CallBackStringO用户自定义回调信息MemberIDStringO会员标识平台方与快递鸟统一用户标识的商家IDCustomerNameStringO电子面单客户账号（与快递网点申请或通过快递鸟官网申请或通过申请电子面单客户号申请）CustomerPwdStringO电子面单密码SendSiteStringO收件网点标识ShipperCodeStringR快递公司编码LogisticCodeStringO快递单号ThrOrderCodeStringO第三方订单号OrderCodeStringR订单编号MonthCodeStringC月结编码PayTypeIntR邮费支付方式:1-现付，2-到付，3-月结，4-第三方支付ExpTypeStringR快递类型：1-标准快件IsNoticeIntO是否通知快递员上门揽件：0-通知；1-不通知；不填则默认为1CostDoubleO寄件费（运费）OtherCostDoubleO其他费用ReceiverCompanyStringO收件人公司NameStringR收件人TelStringR电话与手机，必填一个MobileStringPostCodeStringO收件人邮编ProvinceNameStringR收件省（如广东省，不要缺少“省”）CityNameStringR收件市（如深圳市，不要缺少“市”）ExpAreaNameStringO收件区（如福田区，不要缺少“区”或“县”）AddressStringR收件人详细地址SenderCompanyStringO发件人公司NameStringR发件人TelStringR电话与手机，必填一个MobileStringPostCodeStringO发件人邮编ProvinceNameStringR发件省（如广东省，不要缺少“省”）CityNameStringR发件市（如深圳市，不要缺少“市”）ExpAreaNameStringO发件区（如福田区，不要缺少“区”或“县”）AddressStringR发件详细地址StartDateStringO上门取货时间段:yyyy-MM-dd HH:mm:ss格式化，本文中所有时间格式相同EndDateStringOWeightDoubleO物品总重量kgQuantityIntO件数/包裹数VolumeDoubleO物品总体积m3RemarkStringO备注AddServiceNameString0增值服务名称ValueString0增值服务值CustomerIDString0客户标识(选填)CommodityGoodsNameStringR商品名称GoodsCodeStringO商品编码GoodsquantityIntO件数GoodsPriceDoubleO商品价格GoodsWeightDoubleO商品重量kgGoodsDescStringO商品描述GoodsVolDoubleO商品体积m3IsReturnPrintTemplateStringO返回电子面单模板：0-不需要；1-需要TemplateSizeStringO模板尺寸EBusinessIDStringR商户IDRequestTypeStringR请求指令类型：1007DataSignStringR数据内容签名DataTypeStringR请求、返回数据类型： 2-json1.1.4 返回结果参数l 同步返回参数名称类型必须要求说明EBusinessIDStringR电商用户IDOrderOrderCodeStringR订单编号ShipperCodeStringR快递公司编码LogisticCodeStringR快递单号MarkDestinationStringO大头笔OriginCodeStringO始发地区域编码OriginNameStringO始发地/始发网点DestinatioCodeStringO目的地区域编码DestinatioNameStringO目的地/到达网点SortingCodeStringO分拣编码PackageCodeStringO集包编码SuccessBoolR成功与否ResultCodeStringR错误编码ReasonStringO失败原因UniquerRequestNumberStringR唯一标识PrintTemplateStringO面单打印模板EstimatedDeliveryTimeStringO订单预计到货时间yyyy-mm-ddCallbackStringO用户自定义回调信息SubCountIntO子单数量SubOrdersStringO子单号SubPrintTemplatesStringO子单模板ReceiverSafePhoneStringO收件人安全电话SenderSafePhoneString0寄件人安全电话DialPageStringR拨号页面网址（转换成二维码可扫描拨号）1.2 电子面单余量查询接口1.2.1 功能说明用户查询客户号在快递公司的单号剩余量。1.2.2 接口规则(1) 、接口只支持Json格式参数，接口指令1127。只支持POST请求方式，utf-8编码。(2) 、目前支持快递公司：优速，后续更多的快递公司正在对接中。 1.2.3 系统级和应用级输入参数系统级输入参数类型应用级输入参数必须要求描述RequestData（必填参数，请求内容，JSON格式,须和DataType一致）StringShipperCodeR快递公司编码StringCustomerNameR电子面单账号StringCustomerPwdO电子面单密码StringStationCodeO网点编码StringStationNameO网点EBusinessIDStringR电商IDRequestTypeStringR请求指令类型：1127DataSignStringR数据内容签名DataTypeStringR请求、返回数据类型： 2-json；1.2.4 返回结果参数参数名称类型必须要求说明EbusinessIDStringR用户IDSuccessBoolR成功与否：true,falseReasonStringO原因ResultCodeStringR返回结果编号EorderBalanceTotalNumIntO累计充值数量，电子面单总量(包含已使用/未使用)AvailableNumIntO可用量(剩余量) ShipperCode: UC, CustomerName: , CustomerPwd: c0bfe0ba86b66baec53db0a81, StationCode: 3001, StationName: 福田网点1.2.5 JSON请求示例1.2.6 JSON返回示例 EBusinessID: , Success: true, Reason: , ResultCode: 100, EorderBalance: AvailableNum: 0, TotalNum: 0 1.3 电子面单单号取消1.3.1 功能说明快递鸟通用接口提交快递公司编码、快递单号，则可以取消提交单号。仅支持未揽件状态快递单进行取消，取消后的回收规则以快递公司为准。1.3.2 接口规则(1) 、接口指令1147。(2) 、目前支持快递公司：优速，后续更多的快递公司正在对接中。1.3.3 系统级和应用级输入参数系统级输入参数类型应用级输入参数必须要求描述RequestData（必填参数，请求内容，JSON格式,须和DataType一致）StringShipperCodeR快递公司编码StringExpNoR运单号StringCustomerNameR客户号StringCustomerPwdO客户号密码EBusinessIDStringR电商IDRequestTypeStringR请求指令类型：1147DataSignStringR数据内容签名DataTypeStringR请求、返回数据类型： 2-json；1.3.4 返回结果参数参数名称类型必须要求说明EbusinessIDStringR用户IDSuccessBoolR成功与否：true,falseResultCodeStringO结果编码ReasonStringO原因1.3.5 Json请求示例 ShipperCode: UC, ExpNo: 0, CustomerName: , CustomerPwd: c0bfe0ba86b66baec53db0a8b1.3.6 Json请求返回示例 EBusinessID: , Success: true, ResultCode: 1001.4 申请电子面单客户号1.4.1 功能说明客户通过快递鸟平台向快递公司申请客户号1.4.2 接口规则(1)、接口只支持Json格式参数，接口指令1107。只支持POST请求方式，utf-8编码。 (2)、测试地址：http:/testapi.kdniao.cc:8081 /api/apiservice(3) 、正式地址：http:/api.kdniao.cc /api/apiservice(4) 、目前支持快递公司：优速，后续更多的快递公司正在对接中。1.4.3 系统级和应用级输入参数系统级输入参数类型应用级输入参数必须要求描述RequestData（必填参数，请求内容，JSON格式,须和DataType一致）stringShipperCodeR快递公司编码StationCodeR网点编码StationNameR网点ApplyIDO申请ID（用户记录在快递公司的标识）CompanyO公司NameR联系人TelC电话MobileC手机ProvinceNameR省份ProivnceCodeO省编码CityNameR城市CityCodeO城市编码ExpAreaNameR区县ExpAreaCodeO区县编码AddressR详细地址EBusinessIDStringR电商IDRequestTypeStringR请求指令类型：1107DataSignStringR数据内容签名DataTypeStringR请求、返回数据类型： 2-json；1.4.4 返回结果参数参数名称类型是否必须描述EbusinessIDStringR用户IDSuccessBoolR成功与否：true,falseResultCodeStringO结果编码ReasonStringO原因1.4.5 Json请求示例 ShipperCode: UC, Company: XXX, ApplyID: , Name: hoo123, Tel: , Mobile: , ProvinceName: 广东省, ProivnceCode: , CityName: 深圳市, CityCode: , ExpAreaName: 宝安区, ExpAreaCode: , Address: 西乡, StationCode: 西乡网点, StationName: 西乡网点1.4.6 Json请求返回示例 EBusinessID: , Success: true, Reason: 提交申请成功, ResultCode: 1001.5 申请客户号信息推送1.5.1 功能说明将审核通过客户号信息发送到用户配置的接收地址。1.5.2 接口规则(1)、接口指令1117。 （2）目前支持快递公司：优速，后续更多的快递公司正在对接中。1.5.3 系统级和应用级输入参数系统级输入参数类型应用级输入参数必须要求描述PushData（请求内容，JSON格式,须和DataType一致）StringCustomerNameR客户号StringCustomerPwdR客户号密码StringStationCodeR网点编号StringStationNameR网点名称EBusinessIDStringR用户标识RequestTypeStringR请求指令类型：1117PushTimeStringR推送时间1.5.4 返回结果参数参数名称类型必须要求说明EBusinessIDStringR请求用户标识RequestTypeStringR请求指令SuccessBoolR成功与否MessageStringO返回消息1.5.5 Json请求示例RequestData= CustomerName: , CustomerPwd: c0bfe0ba86b66baec53db0a8b, StationCode: 闵行八部, StationName: 闵行八部&EBusinessID=&PushTime=2017-04-18 23:34:29&RequestType=11171.5.6 Json请求返回示例 EBusinessID: , Message: 成功, RequestType: 1117, Success: true1.6 增值服务列表名称代码说明备注普通代收货款CODValue 为货款，保留3 位小数。CustomerID 为代收货款卡号快递公司自有代收货款业务货款直退CODBACK签收后快递鸟直接返款给客户，返款时效规范 货款垫付CODPAY最快发件后4小时快递鸟垫付返款给商家隐私快递Safe