快递100电商快递物流电子面单图片接口API案例代码

原创

快递100API

修改于 2021-05-19 15:50:23

1.3K0

修改于 2021-05-19 15:50:23

文章被收录于专栏：程序员也要懂业务

一、电子面单图片接口

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

1.1 接口格式

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

1.2 请求地址

<p>https://poll.kuaidi100.com/printapi/printtask.do</p>

请求参数（header）

名称	类型	默认值
Content-Type	string	application/x-www-form-urlencoded

请求参数（body）

参数名	是否必填	类型	说明
method	是	string	业务类型（默认：getPrintImg）
key	是	string	授权码，请<a href="https://api.kuaidi100.com/register/enterprise" target="_blank">申请企业版</a>获取
sign	是	string	32位大写，签名，用于验证身份，按MD5 (param +t+key+ secret)的顺序进行MD5加密，不需要加上“+”号，secret在企业管理后台查看
t	是	string	时间戳如：1576123932000
param	是	string	由其他字段拼接

param数据结构：

参数名	是否必填	类型	说明
type	是	string	业务类型，默认为10
partnerId	是	string	电子面单客户账户或月结账号，需贵司向当地快递公司网点申请（参考<a href="https://api.kuaidi100.com/document/5f6abba0ddc961732a1c2353.html" target="_blank">电子面单申请指南</a>）；是否必填该属性，请查看<a href="https://api.kuaidi100.com/document/5f0ff6e82977d50a94e10237.html" target="_blank">参数字典</a>
partnerKey	否	string	电子面单密码，需贵司向当地快递公司网点申请；是否必填该属性，请查看<a href="https://api.kuaidi100.com/document/5f0ff6e82977d50a94e10237.html" target="_blank">参数字典</a>
partnerName	否	string	商家名称，net为jdalpha时必填
net	否	string	收件网点名称,由快递公司当地网点分配，若使用淘宝授权填入（taobao），使用菜鸟授权填入（cainiao）。是否必填该属性，请查看<a href="https://api.kuaidi100.com/document/5f0ff6e82977d50a94e10237.html" target="_blank">参数字典</a>(若通过淘宝/菜鸟授权方式获取单号partnerId,partnerKey参数为必填,参数值可通过菜鸟淘宝账号授权接口获取)
tbNet	否	string	在使用菜鸟/淘宝/拼多多授权电子面单时，若月结账号下存在多个网点，则tbNet="网点名称,网点编号" ，注意此处为英文逗号
kuaidicom	是	string	快递公司的编码，一律用小写字母，见<a href="https://api.kuaidi100.com/document/5f0ff6e82977d50a94e10237.html" target="_blank">参数字典</a>
recManName	是	string	收件人姓名
recManMobile	是	string	收件人的手机号，手机号和电话号二者其一必填
recManPrintAddr	是	string	收件人所在完整地址，如广东深圳市深圳市南山区科技南十二路2号金蝶软件园
sendManName	是	string	寄件人姓名
sendManMobile	是	string	寄件人的手机号，手机号和电话号二者其一必填
sendManPrintAddr	是	string	寄件人所在的完整地址，如广东深圳市深圳市南山区科技南十二路2号金蝶软件园B10
tempid	是	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：第三方支付（详细请参考<a href="https://api.kuaidi100.com/document/5f0ff6e82977d50a94e10237.html" target="_blank">参数字典</a>）
expType	否	string	快递类型：标准快递（默认）顺丰标快（陆运） EMS经济等（详细请参考<a href="https://api.kuaidi100.com/document/5f0ff6e82977d50a94e10237.html" target="_blank">参数字典</a>）
remark	否	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为单位，例如：100
width	否	string	生成图片的宽，以mm为单位，例如：75
salt	否	string	签名用随机字符串
op	否	string	是否开启订阅功能 0：不开启(默认) 1：开启说明开启订阅功能时：pollCallBackUrl必须填入此功能只针对有快递单号的单
pollCallBackUrl	否	string	如果op设置为1时，pollCallBackUrl必须填入，用于跟踪回调
resultv2	否	string	添加此字段表示开通行政区域解析功能, 详细见：快递信息推送接口文档相关说明。 0：关闭（默认） 1：开通行政区域解析功能

关于回单：

支持回单的网点面单包括顺丰、顺丰快运、德邦快递、德邦物流、京东、跨越、汇森速运、加运美物流、顺心捷达；

支持回单的菜鸟面单包括申通快运、中通快运、韵达快运、德邦快运；

关于子单：

支持子单的网点面单包括顺丰、顺丰快运、德邦快递、德邦物流、京东、品骏、全一快递、速尔快递、信丰物流、优速快递、宅急送、圆通承诺达、龙邦快递、D速快递、汇森速运、加运美物流、京广速递、顺心捷达、壹米滴答；

支持子单的菜鸟面单包括申通快运、中通快运、韵达快运、德邦快运、安能快运、百世快运；

1.3 请求参数示例

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

1.4 返回结果

字段	类型	说明	备注
result	boolean	提交结果	true提交成功，false失败
returnCode	string	返回编码
message	string	返回报文描述
data	data

data数据结构

字段	类型	说明	备注
taskId	string	任务ID
kuaidicom	string	快递公司编码
kuaidinum	string	快递单号
imgBase64	string	面单BASE64编码图片	该属性为JsonArray结构，如果只有一个面单size为1，如果有子母单，面单size>1
	string	快递面单附属属性，根据各个快递公司返回属性

1.5 返回报文示例

{  
    "result": true,
    "returnCode": "200",
    "message": "提交成功",
    "data": {
        "taskId": "****",    // 任务ID 
    	"kuaidicom": "****", // 快递公司编码 
    	"kuaidinum": "****", // 快递单号 
    	"imgBase64": "****", // 面单BASE64编码图片 
    	******
  }
}

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	电子面单请求失败，请重新打印	请根据技术文档请求，注意参数类型及是否必填。