一、电子面单打印接口
通过快递公司或网点、菜鸟与淘宝提供的电子面单账号,调用打印设备打印输出。打印接口连接的设备必须是快递100云打印机
电子面单打印接口可选择面单模板并进行编辑,支持远程打印和共享打印。支持面单复打,两天内可以复打10次。
1.1 接口格式
提供统一格式的HTTP POST或GET调用接口,并返回统一格式JSON数据。
1.2 请求地址
https://poll.kuaidi100.com/printapi/printtask.do
请求参数(header)
名称 | 类型 | 默认值 |
---|---|---|
Content-Type | string | application/x-www-form-urlencoded |
请求参数(body)
参数名 | 是否必填 | 类型 | 说明 |
---|---|---|---|
method | 是 | string | 业务类型(默认:eOrder) |
key | 是 | string | 授权码,请到快递100页面申请企业版接口获取 |
sign | 是 | string | 32位大写,签名,用于验证身份,按MD5 (param +t+key+ secret)的顺序进行MD5加密,不需要加上“+”号,secret可在企业管理后台中企业信息查看 |
t | 是 | string | 时间戳如:1576123932000 |
param | 是 | param | 由其他字段拼接 |
param数据结构:
参数名 | 是否必填 | 类型 | 说明 |
---|---|---|---|
type | 是 | string | 业务类型,默认为10 |
partnerId | 是 | string | 电子面单客户账户或月结账号,需贵司向当地快递公司网点申请(参考电子面单申请指南); 是否必填该属性,请查看参数字典 |
partnerKey | 否 | string | 电子面单密码,需贵司向当地快递公司网点申请; 是否必填该属性,请查看参数字典 |
partnerSecret | 否 | string | 电子面单密钥,需贵司向当地快递公司网点申请; 是否必填该属性,请查看参数字典 |
partnerName | 否 | string | 电子面单客户账户名称,需贵司向当地快递公司网点申请; 是否必填该属性,请查看参数字典 |
net | 否 | string | 收件网点名称,由快递公司当地网点分配, 若使用淘宝授权填入(taobao),使用菜鸟授权填入(cainiao), 使用京东授权填入(jdalpha),使用拼多多授权填入(pinduoduoWx),使用抖音授权填入(douyin),使用快手授权填入(kuaishou)。 是否必填该属性,请查看参数字典 (若通过第三方授权方式获取单号partnerId,partnerKey参数为必填,参数值可通过第三方授权接口获取) |
code | 否 | string | 电子面单承载编号,需贵司向当地快递公司网点申请; 是否必填该属性,请查看参数字典 |
checkMan | 否 | string | 电子面单承载快递员名,需贵司向当地快递公司网点申请; 是否必填该属性,请查看参数字典 |
tbNet | 否 | string | 在使用菜鸟/淘宝/拼多多授权电子面单时,若月结账号下存在多个网点,则tbNet="网点名称,网点编号" ,注意此处为英文逗号 |
kuaidicom | 是 | string | 快递公司的编码,一律用小写字母,请查看参数字典 |
ΘrecMan | 是 | recMan | 收件人信息 |
¬name | 是 | string | 收件人姓名 |
¬mobile | 是 | string | 收件人的手机号,手机号和电话号二者其一必填 |
¬printAddr | 是 | string | 收件人所在完整地址,如广东深圳市深圳市南山区科技南十二路2号金蝶软件园B10 |
¬company | 否 | string | 收件人所在公司名称 |
ΘsendMan | 是 | sendMan | 寄件人信息 |
¬name | 是 | 寄件人姓名 | |
¬mobile | 是 | string | 寄件人的手机号,手机号和电话号二者其一必填 |
¬printAddr | 是 | string | 寄件人所在的完整地址,如广东深圳市深圳市南山区科技南十二路2号金蝶软件园B10 |
¬company | 否 | string | 寄件人所在公司名称 |
cargo | 是 | string | 物品名称,例:文件 |
count | 是 | string | 包裹总数量。该属性与子单有关,如果需要子单(指同一个订单打印出多张电子面单,即同一个订单返回多个面单号),needChild = 1、count 需要大于1,如count = 2 则一个主单 一个子单,count = 3则一个主单 二个子单;返回的子单号码见返回结果的childNum字段 |
weight | 否 | string | 物品总重量KG,例:1.5,单位kg,京东快递、京东快运、极兔速递必填,其他快递公司非必填 |
payType | 否 | string | 支付方式: SHIPPER:寄方付(默认) CONSIGNEE:到付 MONTHLY:月结 THIRDPARTY:第三方支付 (详细请查看参数字典 ) |
expType | 否 | string | 产品类型: 如标准快递(默认) 顺丰标快(陆运) EMS经济 (详细请请查看参数字典 ) |
remark | 否 | string | 备注 |
siid | 是 | string | 打印设备,通过打印机输出的设备码进行获取 |
tempid | 是 | string | 通过管理后台的电子面单模板信息获取 |
thirdOrderId | 否 | string | 平台导入返回的订单id:如平台类加密订单,使用此下单为必填 |
oaid | 否 | string | 淘宝订单收件人ID (Open Addressee ID),长度不超过128个字符,淘宝订单加密情况用于解密 |
thirdPrint | 否 | string | 第三方平台明文订单直连平台面单模板生成电子面单,默认值为空,如为第三方明文订单,需设置为1才可以按照thirdTemplateURL对应模板返回,否则按照tempid对应模板返回 |
thirdTemplateURL | 否 | string | 第三方平台面单基础模板链接,如为第三方平台导入订单选填,如不填写,默认返回两联面单模板 |
面单扩展属性 | |||
valinsPay | 否 | string | 保价额度 |
collection | 否 | string | 代收货款额度 |
needChild | 否 | string | 是否需要子单: 1:需要 0:不需要(默认) 如果需要子单(指同一个订单打印出多张电子面单,即同一个订单返回多个面单号); needChild = 1、count 需要大于1,如count = 2 一个主单 一个子单,count = 3 一个主单 二个子单,返回的子单号码见返回结果的childNum字段 |
needBack | 否 | string | 是否需要回单: 1:需要 0:不需要(默认) 返回的回单号见返回结果的returnNum字段 |
orderId | 否 | string | 贵司内部自定义的订单编号,需要保证唯一性,非必填 |
height | 否 | string | 打印纸的高度,以mm为单位,请按照面单模板尺寸传入 |
width | 否 | string | 打印纸的宽度,以mm为单位,请按照面单模板尺寸传入 |
callBackUrl | 否 | string | 打印状态回调地址,默认仅支持http |
salt | 否 | string | 签名用随机字符串,用于验证签名sign。salt值不为null时,推送数据将包含该加密签名,加密方式:md5(param+salt)。注意: salt值为空串时,推送的数据也会包含sign,此时可忽略sign的校验。 |
op | 否 | string | 是否开启订阅功能 0:不开启(默认) 1:开启 说明开启订阅功能时:pollCallBackUrl必须填入 此功能只针对有快递单号的单 |
pollCallBackUrl | 否 | string | 如果op设置为1时,pollCallBackUrl必须填入,用于跟踪回调 |
resultv2 | 否 | string | 添加此字段表示开通行政区域解析或地图轨迹功能 。 0:关闭(默认) 1:开通行政区域解析功能(详见:快递信息推送接口文档-2.3 推送输入参数), 3:开通地图轨迹及时效返回(回调报文参考地图轨迹推送服务技术文档-推送接口) |
****** | 否 | string | 其他面单特殊需求参数显示,可以到后台-面单模板选择该模板,下方有对应产生列表 |
1.3 请求参数示例
method=eOrder
key=kytRsteof
sign=4BBDE07660E5EFF90873642CFAE9A8DD
t=1470304729724
param={
"type": "10",
"partnerId":"343252463",
"partnerKey":"332524627",
"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":"",
"tempid":"e41bbe3a3c764409a8562b2715f656b2",
"siid":"225684557",
"valinsPay":"",
"collection":"",
"needChild":"0",
"needBack":"0",
"orderId":"2147895476",
"height":"100",
"width":"75",
"callBackUrl":"",
"salt":"",
"op":"0",
"pollCallBackUrl":"",
"resultv2":"0"
}
1.4 返回结果
字段 | 类型 | 说明 | 备注 |
---|---|---|---|
result | boolean | 提交结果 | true提交成功,false失败 |
returnCode | string | 返回编码 | |
message | string | 返回报文描述 | |
data | data |
data数据结构
字段 | 类型 | 说明 | 备注 |
---|---|---|---|
taskId | string | 任务ID | |
kuaidinum | string | 快递单号 | |
eOrder | string | 快递面单附属属性,根据各个快递公司返回属性 |
eOrder数据结构
字段 | 类型 | 说明 | 备注 |
---|---|---|---|
bulkpen | string | 大头笔 | 用于显示于电子面单上规定位置,非必需,是否有值取决于快递公司 |
orgCode | string | 始发地区域编码 | |
orgName | string | 始发地/始发网点名称 | |
destCode | string | 目的地区域编码 | |
destName | string | 目的地/到达网点 | |
orgSortingCode | string | 始发分拣编码 | |
orgSortingName | string | 始发分拣名称 | |
destSortingCode | string | 目的分栋编码 | |
destSortingName | string | 目的分栋中心名称 | |
orgExtra | string | 始发其他信息 | |
destExtra | string | 目的其他信息 | |
pkgCode | string | 集包编码 | |
pkgName | string | 集包地名称 | |
road | string | 路区 | |
qrCode | string | 二维码 | |
kdComOrderNum | string | 快递公司订单号 | |
expressCode | string | 快递业务类型编码 | |
expressName | string | 快递业务类型名称 |
注意:eOrder实际返回的字段各家快递公司不同,以实际返回为准
1.5 返回结果示例
{
"result": true,
"returnCode": "200",
"message": "提交成功",
"data": {
"taskId": "****", // 任务ID
"kuaidinum": "****", // 快递单号
"needBackTaskIds": "[*****,***]", // 回单任务ID,只有带回单才会出现
"needChildTaskIds": "[*****,***]", // 子单任务ID,只有带子单才会出现
"eOrder": "[{\"kuaidinum\":\"DPK364048794751\",\"expressName\":\"标准快递\",\"destName\":null,\"sameCity\":\"1\",\"orgName\":null,\"pkgCode\":null,\"sameProv\":\"1\",\"pkgName\":null,\"bulkpen\":\"上海-S33-K27-P\",\"kdComOrderNum\":\"EK01645578972867uyJHBV\",\"orgExtra\":null}]"
}
}
1.6 返回信息代码含义
信息代码 | 信息内容描述 | 原因及建议处理方式 |
---|---|---|
200 | 提交成功 | 提交成功 |
400 | 参数错误 | 请根据技术文档请求,注意参数类型及是否必填。 |
500 | 服务器错误 | 快递100的服务器出现间歇或临时性异常,有时如果因为不按规范提交请求,比如快递公司参数写错等,也会报此错误 |
501 | 重复提交 | 重复提交打印请求 |
502 | 提交内容含有敏感关键字,被安全防护拦截 | 检查提交内容,可找快递100工作人员排查 |
503 | 验证签名失败 | 检查加密方式,param +t+key+ secret的顺序进行MD5加密,加密后字符串转32位大写,不用加上“+”号 |
600 | 您不是合法的客户(即授权key出错) | 账号无可用单量,需要充值 |
601 | KEY已过期 | 账号无可用单量,需要充值 |
601 | 电子面单账号校验失败,请确认账号信息是否正确 | 传入的电子面单账号信息错误,请联系当地网点获得正确的账号信息。 |
602 | 电子面单数量余额不足,请联系合作网点客服充值 | 申请的快递公司网点电子面单账号的电子面单数量不足,需要去网点充值面单数量。 |
603 | 无法获取行政信息 | 请填写详细的省市区信息 |
604 | 该快递公司不支持子单号 | 请查看1.2支持子单的快递公司 |
605 | 该快递公司不支持回单 | 请查看1.2支持回单的快递公司 |
606 | 业务类型错误 | 从参数字典选择合适的业务类型 |
607 | 收件人手机号或电话不能同时为空 | 传入收件人手机号或者电话 |
610 | 菜鸟电子面单认证信息过期,请重新授权 | 菜鸟授权一年有效,到期重新授权 |
697 | 电子面单请求失败,请重新打印 | 请根据技术文档请求,注意参数类型及是否必填。 |
二、电子面单复打接口
该接口支持在提交打印请求2天内的打印任务进行复打10次的操作。
2.1 接口格式
提供统一格式的HTTP POST或GET调用接口,并返回统一格式JSON数据。
2.2 请求地址
https://poll.kuaidi100.com/printapi/printtask.do
请求参数:
参数名 | 是否必填 | 类型 | 说明 |
---|---|---|---|
method | 是 | string | 业务类型(默认:printOld) |
key | 是 | string | 授权码,请申请企业版获取 |
sign | 是 | string | 32位大写,签名,用于验证身份,按MD5 (param +t+key+ secret)的顺序进行MD5加密,不需要加上“+”号secret在企业管理后台查看 |
t | 是 | string | 时间戳如:1576123932000 |
param | 是 | param | 由其他字段拼接 |
param数据结构:
参数名 | 是否必填 | 类型 | 说明 |
---|---|---|---|
taskId | 是 | string | 任务ID |
2.3 返回结果
字段 | 类型 | 说明 | 备注 |
---|---|---|---|
result | boolean | 提交结果 | true提交成功,false失败 |
returnCode | string | 返回编码 | |
message | String | 返回报文描述 | |
data | String | 图片复打时会有返回 |
2.4 提供数据内容
打印设备复打返回示例
{
"result": true,
"returnCode": "200",
"message": "复打成功"
}
返回图片示例:
{
"result": true,
"returnCode": "200",
"message": "提交成功",
"data": {
"imgBase64": "****" // JSONArray格式的String串
}
}
2.5 返回信息代码含义
信息代码 | 信息内容描述 | 原因及建议处理方式 |
---|---|---|
200 | 成功 | 提交成功 |
201 | 查无此单 | 可能调用过期或复打次数超过限制 |
400 | 参数错误 | 请根据技术文档请求,注意参数类型及是否必填。 |
500 | 服务器错误 | 快递100的服务器出现间歇或临时性异常,有时如果因为不按规范提交请求,比如快递公司参数写错等,也会报此错误 |
501 | 重复提交 | 重复提交了请求 |
503 | 验证签名失败 | 检查加密方式,param +t+key+ secret的顺序进行MD5加密,加密后字符串转32位大写,不用加上“+”号 |
600 | 您不是合法的用户(即授权key出错) | 快递100账号无可用电子面单单量,需要充值 |
601 | KEY已过期 | 快递100账号无可用电子面单单量,需要充值 |
三、打印接口回调
通过上述接口提交的打印请求,进行打印状态返回。
3.1 接口格式
提供统一格式的HTTP POST或GET调用接口,并返回统一格式JSON数据。
3.2 请求地址
由贵司在电子面单打印请求中通过callBackUrl字段提供
<form method="post" name="" action="[callbackUrl]">
<input type="text" name="taskId" value="{XXX}" />
<input type="text" name="param" value="{XXX}" />
<input type="text" name="sign" value="签名字符串" />
</form>
请求参数:
字段 | 类型 | 说明 | 备注 |
---|---|---|---|
taskId | string | 任务ID | |
sign | string | 加密字符串签名:MD5 (param +salt) | |
param | param | 参数主体 |
param数据结构:
参数名 | 类型 | 说明 |
---|---|---|
status | string | 状态编码,200:打印成功,201打印不成功 |
message | string | 状态描述 |
3.3 返回结果
字段 | 类型 | 说明 | 备注 |
---|---|---|---|
result | boolean | 提交结果 | true提交成功,false失败 |
returnCode | string | 返回编码 | |
message | string | 返回报文描述 |
3.4 返回结果示例
{
"result": true,
"returnCode": "200",
"message": "提交成功"
}
说明:
字段名称 | 字段含义 |
---|---|
result | true表示成功,false表示失败。如果提交回调接口的地址失败,30分钟后重新回调,3次仍旧失败的,自动放弃 |
returnCode | 200: 提交成功 500: 服务器错误 其他错误请自行定义 |
message | 返回的提示 |
其他信息快递100会忽略。