文档中心
电子面单HTML接口 API调试工具

电子面单HTML接口

一、电子面单HTML接口

通过快递公司或网点、菜鸟与淘宝提供的电子面单账号,提交生成电子面单号,返回固定面单模板,调用本地打印机即可打印出电子面单。

1.1 接口格式

提供统一格式的HTTP POST或GET调用接口,并返回统一格式JSON数据。

1.2 请求地址

http://poll.kuaidi100.com/eorderapi.do

请求参数(header)

名称类型默认值
Content-Typestringapplication/x-www-form-urlencoded

请求参数(body)

参数名是否必填类型说明
methodstring业务类型(默认:getElecOrder)
keystring授权码,请申请企业版获取
signstring32位大写 ,签名,用于验证身份,按MD5 (param +t+key+ secret)的顺序进行MD5加密,不需要加上“+”号,secret可在企业管理后台查看
tstring时间戳如:1576123932000
paramparam由其他字段拼接

param数据结构

参数名是否必填类型说明
partnerIdstring电子面单客户账户或月结账号,需贵司向当地快递公司网点申请(参考电子面单申请指南); 是否必填该属性,请查看参数字典
partnerKeystring电子面单密码,需贵司向当地快递公司网点申请; 是否必填该属性,其他请查看参数字典
partnerSecretstring电子面单密钥,需贵司向当地快递公司网点申请; 是否必填该属性,请查看参数字典
partnerNamestring电子面单客户账户名称,需贵司向当地快递公司网点申请; 是否必填该属性,请查看参数字典
netstring收件网点名称,由快递公司当地网点分配,若使用淘宝授权填入(taobao),使用菜鸟授权填入(cainiao), 使用京东授权填入(jdalpha),使用拼多多授权填入(pinduoduoWx),使用抖音授权填入(douyin),使用快手授权填入(kuaishou)。是否必填该属性,请查看参数字典(若通过第三方授权方式获取单号partnerId,partnerKey参数为必填,参数值可通过第三方授权接口获取)
codestring电子面单承载编号,需贵司向当地快递公司网点申请; 是否必填该属性,请查看参数字典
checkManstring电子面单承载快递员名,需贵司向当地快递公司网点申请; 是否必填该属性,请查看参数字典
tbNetstring在使用菜鸟/淘宝/拼多多授权电子面单时,若月结账号下存在多个网点,则tbNet="网点名称,网点编号" ,注意此处为英文逗号
kuaidicomstring快递公司的编码,一律用小写字母,见参数字典
ΘrecManobject收件人信息
¬namestring收件人姓名
¬mobilestring收件人的手机号,手机号和电话号二者其一必填
¬printAddrstring收件人所在完整地址,如广东深圳市深圳市南山区科技南十二路2号金蝶软件园B10
¬companystring收件人所在公司名称
ΘsendManobject寄件人信息
¬namestring寄件人姓名
¬mobilestring寄件人的手机号,手机号和电话号二者其一必填
¬printAddrstring寄件人所在的完整地址,如广东深圳市深圳市南山区科技南十二路2号金蝶软件园B10
¬companystring寄件人所在公司名称
cargostring物品名称,例:文件
countstring包裹总数量。该属性与子单有关,如果需要子单(指同一个订单打印出多张电子面单,即同一个订单返回多个面单号),needChild = 1、count 需要大于1,如count = 2 则一个主单 一个子单,count = 3则一个主单 二个子单;返回的子单号码见返回结果的childNum字段
weightstring物品总重量KG,例:1.5,单位kg,京东、极兔速递必填,其他快递公司非必填
payTypestring支付方式: SHIPPER:寄方付(默认) CONSIGNEE:到付 MONTHLY:月结 THIRDPARTY:第三方支付 (详细请参考参数字典
expTypestring产品类型: 标准快递(默认) 顺丰标快(陆运) EMS经济 (详细请参考参数字典
remarkstring备注
thirdPrintstring第三方平台明文订单直连平台面单模板生成电子面单,默认值为空,如为第三方明文订单,需设置为1才可以按照thirdTemplateURL对应模板返回,否则按照html固定模板返回
thirdTemplateURLstring第三方平台面单基础模板链接,如为第三方平台导入订单选填,如不填写,默认返回两联面单模板
thirdOrderIdstring平台导入返回的订单id:如平台类加密订单,使用此下单为必填
oaidstring淘宝订单收件人ID (Open Addressee ID),长度不超过128个字符,淘宝订单加密情况用于解密
面单扩展属性
valinsPaystring保价额度
collectionstring代收货款额度
needChildstring是否需要子单: 1:需要 0:不需要(默认) 如果需要子单(指同一个订单打印出多张电子面单,即同一个订单返回多个面单号); needChild = 1、count 需要大于1,如count = 2 一个主单 一个子单,count = 3 一个主单 二个子单,返回的子单号码见返回结果的childNum字段
needBackstring是否需要回单: 1:需要 0:不需要(默认) 返回的回单号见返回结果的returnNum字段
orderIdstring贵司内部自定义的订单编号,需要保证唯一性,非必填
needTemplatestring是否返回面单: 0:不需要(默认) 1:需要 如果需要,则返回要打印的模版的HTML代码,贵司可以直接将之显示到IE等浏览器,然后通过浏览器进行打印
saltstring签名用随机字符串,用于验证签名sign。salt值不为null时,推送数据将包含该加密签名,加密方式:md5(param+salt)。注意: salt值为空串时,推送的数据也会包含sign,此时可忽略sign的校验。
opstring是否开启订阅功能: 0:不开启(默认) 1:开启 说明开启订阅功能时:pollCallBackUrl必须填入此功能只针对有快递单号的单
pollCallBackUrlstring如果op设置为1时,pollCallBackUrl必须填入,用于跟踪回调
resultv2string添加此字段表示开通行政区域解析或地图轨迹功能 。
0:关闭(默认)
1:开通行政区域解析功能(详见:快递信息推送接口文档-2.3 推送输入参数),
3:开通地图轨迹及时效返回(回调报文参考地图轨迹推送服务技术文档-推送接口

1.3 请求参数示例

method = getElecOrder
key = kytRsteof
sign = 4BBDE07660E5EFF90873642CFAE9A8DD
t = 1470304729724
param = {
    "partnerId": "******",
    "partnerKey": "",
    "net": "",
    "kuaidicom": "yuantong",
    "recMan": {
        "name": "张三",
        "mobile": "13751866787",
        "printAddr": "广东深圳市深圳市南山区科技南十二路2号金蝶软件园B10",
        "company": ""
    },
    "sendMan": {
        "name": "李四",
        "mobile": "13751866787",
        "printAddr": "广东深圳市深圳市南山区科技南十二路2号金蝶软件园",
        "company": ""
    },
    "cargo": "发票",
    "count": "1",
    "weight": "0.5",
    "payType": "SHIPPER",
    "expType": "标准快递",
    "remark": "",
    "valinsPay": "",
    "collection": "",
    "needChild": "0",
    "needBack": "0",
    "orderId": "2147895476",
    "needTemplate": "1",
    "salt": "",
    "op": "0",
    "pollCallBackUrl": "",
    "resultv2": "0"
}

1.4 返回结果

字段类型说明备注
resultboolean提交结果true提交成功,false失败
statusstring返回编码
messagestring返回报文描述
datadataJson

data数据结构

字段类型说明备注
taskIdstring任务ID
kuaidinumstring快递单号
returnNumstring回单号
childNumstring子单号,如果有多个,逗号分隔如果需要子单 则需要提交报文needChild = 1、count 需要大于1。 如count = 2则一个主单、一个子单,count=3则一个主单、二个子单
快递公司面单基础信息
bulkpenstring大头笔用于显示于电子面单上规定位置,非必需,是否有值取决于快递公司
orgCodestring始发地区域编码
orgNamestring始发地/始发网点名称
destCodestring目的地区域编码
destNamestring目的地/到达网点
orgSortingCodestring始发分拣编码
orgSortingNamestring始发分拣名称
destSortingCodestring目的分栋编码
destSortingNamestring目的分栋中心名称
orgExtrastring始发其他信息
destExtrastring目的其他信息
pkgCodestring集包编码
pkgNamestring集包地名称
roadstring路区
qrCodestring二维码
kdComOrderNumstring快递公司订单号
expressCodestring快递业务类型编码
expressNamestring快递业务类型名称
templateurlstring在线显示电子面单模版的网址用浏览器打开该网址,就能看到生成的电子面单,直接通过浏览器的打印功能即可完成打印
templatestring电子面单模板内容

注意:面单基础信息实际返回的字段各家快递公司不同,以实际返回为准

1.5 返回结果示例

不带模版返回

{  
    "result": true,
    "message": "成功",
    "status": "200",
    "data": [
        {
            "kuaidinum": "606568155331",
      	    "returnNum": "",
            "childNum": "",
            "bulkpen": "大头笔",
            "orgCode": "755",
            "orgName": "始发地区域编码",
            "destCode": "755",
            "destName": "目的地/到达网点",
            "orgSortingCode": "始发分拣编码",
            "orgSortingName": "始发分拣名称",
            "destSortingCode": "目的分栋编码",
            "destSortingName": "目的分栋中心名称",
            "orgExtra": "始发其他信息",
            "destExtra": "目的其他信息",
            "pkgCode": "集包编码",
            "pkgName": "集包地名称",
            "road": "路区",
            "qrCode": "二维码",
            "kdComOrderNum": "快递公司订单号",
            "expressCode": "快递业务类型编码",
            "expressName": "标准快递"
        }
    ]
}

带模板返回

{  
    "result": true,
    "message": "成功",
    "status": "200",
    "data": [
      {
        "kuaidinum": "611399236259",
        "returnNum": "",
        "childNum": "",
        "bulkpen": "大头笔",
        "orgCode": "755",
        "orgName": "始发地区域编码",
        "destCode": "755",
        "destName": "目的地/到达网点",
        "orgSortingCode": "始发分拣编码",
        "orgSortingName": "始发分拣名称",
        "destSortingCode": "目的分栋编码",
        "destSortingName": "目的分栋中心名称",
        "orgExtra": "始发其他信息",
        "destExtra": "目的其他信息",
        "pkgCode": "集包编码",
        "pkgName": "集包地名称",
        "road": "路区",
        "qrCode": "二维码",
        "kdComOrderNum": "快递公司订单号",
        "expressCode": "快递业务类型编码",
        "expressName": "标准快递",
        "templateurl": "http://ckd.im/u2WB5"
        "template": [
        "<!DOCTYPE html>
          <html>
            <head>
              <meta charset=\"utf-8\">
              <title>顺丰</title>
                <style>
                  * { margin: 0;
                     padding: 0
                    }
                  table {
                    margin-top: -1px;
                    font: 12px \"Microsoft YaHei\", Verdana,arial,sans-serif;
                    border-collapse: collapse;
                  }
                  table.container {
                    width: 375px;
                  }
                  table td {
                    border: 1px solid #000;
                  }
                  table.nob {
                    width: 100%;
                  }
                  table.nob td { 
                    border: 0;
                  }
                  table td.center {
                    text-align: center;
                  }
                  table td.right {
                    text-align: right;
                  }
                  ……………</table></body>
          </html>"
         ]
      }
   ]
}

错误返回示例

{
"data": {},
"message": "Print:KEY已过期",
"result": false,
"returnCode": "601"
}

返回的打印模版示例(即template或访问templateurl后显示的效果) 将template字段写到一个html文件后通过浏览器打开并显示出来后的效果示例:顺丰:

示例图片

1.6 返回信息代码含义

信息代码信息内容描述原因及建议处理方式
200成功提交成功
401参数错误请根据技术文档请求,注意参数类型及是否必填。
402未指明服务请检查业务类型是否填错
601KEY已过期账号无可用单量,需要充值
601电子面单账号校验失败,请确认账号信息是否正确传入的电子面单账号信息错误,请联系当地网点获得正确的账号信息。
602电子面单数量余额不足,请联系合作网点客服充值检查提交内容,可找快递100工作人员排查
603无法获取行政信息请填写详细的省市区信息
604该快递公司不支持子单号请查看1.2支持子单的快递公司
605该快递公司不支持回单请查看1.2支持回单的快递公司
606业务类型错误从参数字典选择合适的业务类型。
607收件人手机号或电话不能同时为空传入收件人手机号或者电话
610菜鸟电子面单认证信息过期,请重新授权菜鸟授权一年有效,到期重新授权
697电子面单请求失败,请重新打印请根据技术文档请求,注意参数类型及是否必填。
699请求快递公司失败,请稍候重试请根据技术文档请求,注意参数类型及是否必填。

1.7 支持的快递公司列表

电子面单HTML接口返回的是固定快递模板,支持的快递公司列表如下:

快递公司名称 快递公司代码 模板预览
顺丰速运(不支持丰密面单) shunfeng 预览
申通快递 shentong 预览
中通快递 zhongtong 预览
圆通快递 yuantong 预览
德邦快递 debangkuaidi 预览
韵达快递 yunda 预览
京东物流 jd 预览
EMS ems 预览
百世快递 huitongkuaidi 预览
宅急送 zhaijisong 预览
极兔快递 jtexpress 预览
优速快递 youshuwuliu 预览