文档中心
一、电子面单下单接口 二、电子面单复打接口 三、打印状态回调 四、OCR识别结果回调 API调试工具

一、电子面单下单接口

通过快递公司或网点、菜鸟与淘宝提供的电子面单账号,支持只下单,或者生成图片使用本地打印设备打印输出,以及调用快递100云打印设备打印输出。使用快递100云打印则连接的设备必须是快递100云打印机或者快递100云盒。云盒可以支持不同品牌的打印机,具体支持品牌查询:云盒支持的打印机列表

1.1 接口格式

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

1.2 请求地址

https://api.kuaidi100.com/label/order

请求参数(header)

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

请求参数(body)

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

param数据结构:

参数名是否必填类型说明
printTypestring打印类型,NON:只下单不打印(默认); IMAGE:生成图片短链;HTML:生成html短链; CLOUD:使用快递100云打印机打印,使用CLOUD时siid必填
partnerIdstring电子面单客户账户或月结账号,需贵司向当地快递公司网点申请(参考电子面单申请指南); 是否必填该属性,请查看参数字典
partnerKeystring电子面单密码,需贵司向当地快递公司网点申请; 是否必填该属性,请查看参数字典
partnerSecretstring电子面单密钥,需贵司向当地快递公司网点申请; 是否必填该属性,请查看参数字典
partnerNamestring电子面单客户账户名称,需贵司向当地快递公司网点申请; 是否必填该属性,请查看参数字典
netstring收件网点名称,由快递公司当地网点分配, 若使用淘宝授权填入(taobao),使用菜鸟授权填入(cainiao), 使用京东授权填入(jdalpha),使用拼多多授权填入(pinduoduoWx),使用抖音授权填入(douyin),使用快手授权填入(kuaishou)。 是否必填该属性,请查看参数字典 (若通过第三方授权方式获取单号partnerId,partnerKey参数为必填,参数值可通过第三方授权接口获取)
codestring电子面单承载编号,需贵司向当地快递公司网点申请; 是否必填该属性,请查看参数字典
checkManstring电子面单承载快递员名,需贵司向当地快递公司网点申请; 是否必填该属性,请查看参数字典
tbNetstring在使用菜鸟/淘宝/拼多多授权电子面单时,若月结账号下存在多个网点,则tbNet="网点名称,网点编号" ,注意此处为英文逗号
kuaidicomstring快递公司的编码,一律用小写字母,请查看参数字典
ΘrecManrecMan收件人信息
¬namestring收件人姓名
¬mobilestring收件人的手机号,手机号和电话号二者其一必填
¬telstring收件人的电话号,手机号和电话号二者其一必填
¬printAddrstring收件人所在完整地址,如广东深圳市深圳市南山区科技南十二路2号金蝶软件园B10
¬companystring收件人所在公司名称
ΘsendMansendMan寄件人信息
¬name 寄件人姓名
¬mobilestring寄件人的手机号,手机号和电话号二者其一必填
¬telstring寄件人的电话号,手机号和电话号二者其一必填
¬printAddrstring寄件人所在的完整地址,如广东深圳市深圳市南山区科技南十二路2号金蝶软件园B10
¬companystring寄件人所在公司名称
cargostring物品名称,例:文件
countint包裹总数量。该属性与子单有关,如果需要子单(指同一个订单打印出多张电子面单,即同一个订单返回多个面单号),needChild = 1、count 需要大于1,如count = 2 则一个主单 一个子单,count = 3则一个主单 二个子单;返回的子单号码见返回结果的childNum字段
weightDouble物品总重量KG,例:1.5,单位kg。极兔速递必填,其他快递公司非必填
payTypestring支付方式: SHIPPER:寄方付(默认) CONSIGNEE:到付 MONTHLY:月结 THIRDPARTY:第三方支付 (详细请查看参数字典
expTypestring产品类型: 如标准快递(默认) 顺丰标快(陆运) EMS经济 (详细请请查看参数字典
remarkstring备注
siidstring打印设备,通过打印机输出的设备码进行获取,printType为CLOUD时必填
directionstring打印方向, 0:正方向(默认); 1:反方向;只有printType为CLOUD时该参数生效
tempIdstring主单模板,通过管理后台的快递公司模板V2信息获取
childTempIdstring子单模板,部分快递公司需指定。通过管理后台的快递公司模板V2信息获取
backTempIdstring回单模板,部分快递公司需指定。通过管理后台的快递公司模板V2信息获取
面单扩展属性
valinsPaydouble保价额度
collectiondouble代收货款额度
needChildstring是否需要子单: 1:需要 0:不需要(默认) 如果需要子单(指同一个订单打印出多张电子面单,即同一个订单返回多个面单号); needChild = 1、count 需要大于1,如count = 2 一个主单 一个子单,count = 3 一个主单 二个子单,返回的子单号码见返回结果的childNum字段
needBackstring是否需要回单: 1:需要 0:不需要(默认) 返回的回单号见返回结果的returnNum字段
orderIdstring贵司内部自定义的订单编号,需要保证唯一性,非必填
callBackUrlstring数据回调地址(打印状态以及OCR识别结果),默认仅支持http
saltstring签名用随机字符串,用于验证签名sign。salt值不为null时,推送数据将包含该加密签名,加密方式:md5(param+salt)。注意: salt值为空串时,推送的数据也会包含sign,此时可忽略sign的校验。
needSubscribeboolean是否开启订阅功能 false:不开启(默认) true:开启 说明开启订阅功能时:pollCallBackUrl必须填入 此功能只针对有快递单号的单
pollCallBackUrlstring如果needSubscribe 设置为true时,pollCallBackUrl必须填入,用于跟踪回调
resultv2string添加此字段表示开通行政区域解析或地图轨迹功能 。
0:关闭(默认)
1:开通行政区域解析功能(详见:快递信息推送接口文档-2.3 推送输入参数),
3:开通地图轨迹及时效返回(回调报文参考地图轨迹推送服务技术文档-推送接口
needDesensitizationboolean是否脱敏 ,false:关闭(默认)true:开启。开启后生成的面单收寄件人手机号码会脱敏,使用前请先跟网点确认是否支持使用脱敏电话
needLogoboolean面单是否需要logo false:关闭(默认)true:开启
thirdOrderIdstring平台导入返回的订单id:如平台类加密订单,使用此下单为必填
oaidstring淘宝订单收件人ID (Open Addressee ID),长度不超过128个字符,淘宝订单加密情况用于解密
thirdTemplateURLstring第三方平台面单基础模板链接,如为第三方平台导入订单选填,如不填写,默认返回两联面单模板
thirdCustomTemplateUrlstring第三方平台自定义区域模板地址
customParamMap<String,String>面单自定义参数。方式传入为key-value格式,注意这里的key优先级高于面单生成的参数,例如:面单里面默认的快递单号对应参数为kuaidinum,如果这里的key也包含kuaidinum,将会覆盖原来的值。使用第三方平台订单时,也可配合thirdCustomTemplateUrl,实现自定义区域的传值
needOcrboolean第三方平台订单是否需要开启ocr,开启后将会通过推送方式推送 false:关闭(默认)true:开启
ocrIncludeString[]orc需要检测识别的面单元素。取值范围:barcode,qrcode,receiver,sender,bulkpen。不传或者 null 则默认为 ["barcode", "receiver", "sender"]
heightstring打印纸的高度,以mm为单位(该参数只有第三方平台订单,并且printType为CLOUD时起作用)
widthstring打印纸的宽度,以mm为单位(该参数只有第三方平台订单,并且printType为CLOUD时起作用)

1.3 请求参数示例

method = order
key = ** ** *
	sign = ** ** *
	t = 1470304729724
param = {
	"partnerId": "123456",
	"partnerKey": "",
	"code": "",
	"kuaidicom": "zhaijisong",
	"recMan": {
		"name": "张三",
		"mobile": "13888888888",
		"printAddr": "广东深圳市南山区金蝶软件园",
		"company": ""
	},
	"sendMan": {
		"name": "李四",
		"mobile": "13888888888",
		"printAddr": "广东深圳市南山区金蝶软件园",
		"company": ""
	},
	"cargo": "test",
	"tempId": "60f6c17c7c223700131d8bc3",
	"childTempId": "61bff9efc66fb00013a1b168",
	"backTempId": "61bffa26c66fb00013a1b16c",
	"payType": "SHIPPER",
	"expType": "标准快递",
	"remark": "测试下单,请勿发货",
	"collection": "0",
	"needChild": "0",
	"needBack": "0",
	"count": 1,
	"printType": "CLOUD",
	"siid": "KX100*******",
	"needDesensitization": true,
	"needLogo": true,
	"needOcr": false
}

1.4 返回结果

字段类型说明备注
successboolean提交结果true提交成功,false失败
codeint返回编码200为成功
messagestring返回报文描述
dataObject

data数据结构

字段类型说明备注
taskIdstring任务ID
kuaidicomstring快递公司编码
kuaidinumstring快递单号
childNumstring子单号多个子单时使用”,”隔开。比如JD6666666,JD888888,JD99999
backNumstring回单号部分快递公司回单会返回回单号
labelstring面单短链,printType为IMAGE或者HTML时的面单短链多个面单时使用”,”隔开。比如http://api.kuaidi100.com/label/1, http://api.kuaidi100.com/label/2, http://api.kuaidi100.com/label/3 面单异步生成,请求还未生成时,可以稍后重试
bulkpenstring大头笔用于显示于电子面单上规定位置,非必需,是否有值取决于快递公司
orgCodestring始发地区域编码
orgNamestring始发地/始发网点名称
destCodestring目的地区域编码
destNamestring目的地/到达网点
orgSortingCodestring始发分拣编码
orgSortingNamestring始发分拣名称
destSortingCodestring目的分栋编码
destSortingNamestring目的分栋中心名称
orgExtrastring始发其他信息
destExtrastring目的其他信息
pkgCodestring集包编码
pkgNamestring集包地名称
roadstring路区
qrCodestring二维码
kdComOrderNumstring快递公司订单号
expressCodestring快递业务类型编码
expressNamestring快递业务类型名称

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

1.5 返回结果示例

成功示例

{
	"code": 200,
	"data": {
		"kuaidinum": "ZJS8888888888",
		"bulkpen": "371-转9999-C482",
		"sameCity": "1",
		"sameProv": "1",
		"taskId": "7EEAFD6CBEF64FEBAA10022BD32378BC"
	},
	"message": "success",
	"time": 0,
	"success": true
}    

失败示例

{
	"code": 30005,
	"message": "电子面单账号校验失败,请确认账号信息是否正确",
	"time": 0,
	"success": false
}

1.6 返回信息代码含义

信息代码信息内容描述原因及建议处理方式
-1服务器错误快递100的服务器出现间歇或临时性异常,有时如果因为不按规范提交请求,比如快递公司参数写错等,也会报此错误
200提交成功提交成功
30001参数错误请根据技术文档请求,注意参数类型及是否必填
30002验证签名失败检查加密方式,param +t+key+ secret的顺序进行MD5加密,加密后字符串转32位大写,不用加上“+”号
30003账号信息不正确检查key是否正确
30004账号单量不足单量不足需要充值
30005快递公司返回异常按照描述可以自行检查是否参数缺失或者错误
30006参数转换异常按照描述可以自行检查参数的数据类型是否正确
30007模板id不正确检查传入tempId、childTempId、backTempId是否正确
30008第三方平台生成面单失败平台订单面单生成失败,一般是网络问题可以稍后重试
30010打印机状态不正确打印机当前状态无法打单,需要检查

二、电子面单复打接口

该接口支持在提交打印请求2天内的打印任务进行复打20次的操作。

2.1 接口格式

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

2.2 请求地址

https://api.kuaidi100.com/label/order

请求参数:

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

param数据结构:

参数名是否必填类型说明
taskIdstring任务ID
siidstring快递100打印机,不填默认为下单时填入的siid

2.3 返回结果

字段类型说明备注
successboolean提交结果true提交成功,false失败
codestring返回编码
messageString返回报文描述
dataString图片复打时会有返回

2.4 提供数据内容

打印设备复打成功返回示例

{
	"code": 200,
	"message": "success",
	"time": 0,
	"success": true
} 

错误示例:

{
	"code": 30009,
	"message": "查无此单",
	"time": 0,
	"success": false
} 

2.5 返回信息代码含义

信息代码信息内容描述原因及建议处理方式
-1服务器错误快递100的服务器出现间歇或临时性异常,有时如果因为不按规范提交请求,比如快递公司参数写错等,也会报此错误
200提交成功提交成功
30001参数错误请根据技术文档请求,注意参数类型及是否必填
30002验证签名失败检查加密方式,param +t+key+ secret的顺序进行MD5加密,加密后字符串转32位大写,不用加上“+”号
30003账号信息不正确检查key是否正确
30004账号单量不足单量不足需要充值
30009查无此单可能调用过期或复打次数超过限制

三、打印状态回调

通过上述接口提交的打印请求,进行打印状态返回。

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="签名字符串" />
    <input type="text" name="type" value="printStatus" />
</form>

请求参数:

字段类型说明备注
taskIdstring任务ID
signstring加密字符串签名:MD5 (param +salt)
typestring推送类型,默认为 printStatus
paramparam参数主体

param数据结构:

参数名类型说明
statusstring状态编码,200:打印成功,201打印不成功
messagestring状态描述

3.3 返回结果

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

3.4 返回结果示例

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

说明:

字段名称字段含义
resulttrue表示成功,false表示失败。如果提交回调接口的地址失败,30分钟后重新回调,3次仍旧失败的,自动放弃
returnCode200: 提交成功 500: 服务器错误 其他错误请自行定义
message返回的提示

其他信息快递100会忽略。

四、OCR识别结果回调

通过上述接口提交的第三方平台打单,开启ocr后(needOcr为true时),会通过callBackUrl推送。

4.1 接口格式

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

4.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="签名字符串" />
    <input type="text" name="type" value="ocr" />
</form>

请求参数:

字段类型说明备注
taskIdstring任务ID
signstring加密字符串签名:MD5 (param +salt)
typestring推送类型,默认为 ocr
paramparam参数主体

param数据结构:

参数名称数据类型是否必填参数描述
barcodestring[]条形码值
qrcodestring[]二维码值
ΘreceiverObject收件人信息,明细项目请展开
└ addressstring详细地址
└provincestring
└ citystring
└ countystring县/区
└ mobilestring电话
└ namestring姓名
└ textstring原始文本
└confidencenumber可信度,仅供参考
ΘsenderObject寄件人信息,明细项目请展开
└ addressstring详细地址
└provincestring
└ citystring
└ countystring县/区
└ mobilestring电话
└ namestring姓名
└ textstring原始文本
└confidencenumber可信度
ΘbulkpenObject大头笔信息,明细项目请展开
└confidencenumber可信度
└ textstring原始文本

4.3 返回结果

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

4.4 返回结果示例

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

说明:

字段名称字段含义
resulttrue表示成功,false表示失败。如果提交回调接口的地址失败,30分钟后重新回调,3次仍旧失败的,自动放弃
returnCode200: 提交成功 500: 服务器错误 其他错误请自行定义
message返回的提示

其他信息快递100会忽略。