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

电子面单图片接口

一、电子面单图片接口

通过快递公司或网点、菜鸟与淘宝提供的电子面单账号,提交生成电子面单;通过管理后台模板配置,选择面单模板并可进行编辑,生成图片输出,可自选方式打印。

1.1 接口格式

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

1.2 请求地址

https://poll.kuaidi100.com/printapi/printtask.do

请求参数(header)

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

请求参数(body)

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

param数据结构:

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

关于回单: 支持回单的网点面单包括顺丰速运、顺丰快运、德邦物流、德邦快递、京东快递、京东快运、跨越速运、汇森速运等,更多请查看参数字典

关于子单: 支持子单的网点面单包括顺丰速递、德邦物流、京东快递、德邦快递、宅急送、优速快递、中通快运、安能快运、顺丰快运等,更多请查看参数字典

1.3 请求参数示例

method = getPrintImg
key = kytRsteof
sign = 4BBDE07660E5EFF90873642CFAE9A8DD
t = 1470304729724
param = {
    "type": "10",
    "partnerId": "******",
    "partnerKey": "******",
    "net": "taobao",
    "kuaidicom": "yuantong",
    "recManName": "张三",
    "recManMobile": "13842569988",
    "recManPrintAddr": "广东深圳市深圳市南山区科技南十二路2号金蝶软件园",
    "sendManName": "李四",
    "sendManMobile": "13842569988",
    "sendManPrintAddr": "广东深圳市深圳市南山区科技南十二路2号金蝶软件园B10",
    "tempid": "e41bbe3a3c764409a8562b2715f656b2",
    "cargo": "发票",
    "count": "1",
    "weight": "0.5",
    "payType": "SHIPPER",
    "expType": "标准快递",
    "remark": "",
    "collection": "",
    "needChild": "",
    "needBack": "",
    "orderId": "",
    "height": "100",
    "width": "75",
    "salt": "123456789",
    "op": "0",
    "pollCallBackUrl": "",
    "resultv2": "0"
}

1.4 返回结果

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

data数据结构

字段类型说明备注
taskIdstring任务ID
kuaidinumstring快递单号
imgBase64string面单BASE64编码图片该属性为JsonArray结构,如果只有一个面单size为1,如果有字母单,或回单该size>1(第三方平台导入订单不返回图片,返回templateurl)
templateurlstring面单短链第三方平台导入订单返回该链接,通过链接下载面单内容(因面单内容生成耗时较长,一般在一秒内,可能会存在最大3秒的延迟)
eOrderstring快递面单附属属性,根据各个快递公司返回属性

eOrder数据结构

字段类型说明备注
bulkpenstring大头笔用于显示于电子面单上规定位置,非必需,是否有值取决于快递公司
orgCodestring始发地区域编码
orgNamestring始发地/始发网点名称
destCodestring目的地区域编码
destNamestring目的地/到达网点
orgSortingCodestring始发分拣编码
orgSortingNamestring始发分拣名称
destSortingCodestring目的分栋编码
destSortingNamestring目的分栋中心名称
orgExtrastring始发其他信息
destExtrastring目的其他信息
pkgCodestring集包编码
pkgNamestring集包地名称
roadstring路区
qrCodestring二维码
kdComOrderNumstring快递公司订单号
expressCodestring快递业务类型编码
expressNamestring快递业务类型名称

注意:eOrder实际返回的字段各家快递公司不同,以实际返回为准

1.5 返回报文示例

{
	"result": true,
	"returnCode": "200",
	"message": "提交成功",
	"data": {
		"taskId": "****",
		"kuaidinum": "****",
		"imgBase64": "****",
		"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 图片异步推送

开启asyn异步推送面单图片后,系统会根据客户提交的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>

请求参数

字段类型说明备注
taskIdstring任务ID
signstring签名
paramparam参数主体

param数据结构:

参数名类型说明
statusstring状态编码,200:生成图片成功,201生成失败功。
messagestring状态描述
kuaidicomstring快递公司编码
kuaidinumstring快递单号
datastring

data数据结构:

参数名类型说明
imgBase64stringJsonArray格式的base64图片数据

返回结果

字段类型说明备注
resultboolean提交结果true提交成功,false失败,如果提交回调接口的地址失败,30分钟后重新回调,3次仍旧失败的,自动放弃
returnCodestring返回编码
messagestring返回报文描述

返回报文示例

{
	"result": true,
	"returnCode": "200",
	"message": "提交成功"
	
	
}

1.7 返回的信息代码含义

信息代码信息内容描述原因及建议处理方式
200提交成功提交成功
400参数错误请根据技术文档请求,注意参数类型及是否必填。
500服务器错误快递100的服务器出现间歇或临时性异常,有时如果因为不按规范提交请求,比如快递公司参数写错等,也会报此错误
501重复提交重复提交打印请求
502提交内容含有敏感关键字,被安全防护拦截检查提交内容,可找快递100工作人员排查
503验证签名失败检查加密方式,param +t+key+ secret的顺序进行MD5加密,加密后字符串转32位大写,不用加上“+”号
600您不是合法的客户(即授权key出错)账号无可用单量,需要充值
601KEY已过期账号无可用单量,需要充值
601电子面单账号校验失败,请确认账号信息是否正确传入的电子面单账号信息错误,请联系当地网点获得正确的账号信息。
602电子面单数量余额不足,请联系合作网点客服充值申请的快递公司网点电子面单账号的电子面单数量不足,需要去网点充值面单数量。
603无法获取行政信息请填写详细的省市区信息
604该快递公司不支持子单号请查看1.2支持子单的快递公司
605该快递公司不支持回单请查看1.2支持回单的快递公司
606业务类型错误从参数字典选择合适的业务类型
607收件人手机号或电话不能同时为空传入收件人手机号或者电话
610菜鸟电子面单认证信息过期,请重新授权菜鸟授权一年有效,到期重新授权
697电子面单请求失败,请重新打印请根据技术文档请求,注意参数类型及是否必填。