文档中心
一、自定义打印接口 二、打印状态回调 三、 硬件状态查询接口 API调试工具

一、自定义打印接口

如有发票、发货单、面单等打印需求,可使用该接口。通过管理后台模板配置,配置自定义模板,实现自定义打印功能。该接口支持在提交打印请求2天内的打印任务进行复打20次的操作

1.1 接口格式

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

1.2 请求地址

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

请求参数(header)

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

请求参数(body)

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

param数据结构:

参数名是否必填类型说明
tempidstring通过管理后台的打印模板V2信息获取
printTypestring打印类型(IMAGE,CLOUD,HTML)。IMAGE:生成图片短链;HTML:生成html短链;CLOUD:使用快递100云打印机打印,使用CLOUD时siid必填
siidstring打印设备,通过打印机输出的设备码进行获取,printType为CLOUD时必填
directionstring打印方向(默认0) 0-正方向 1-反方向;只有printType为CLOUD有作用
callBackUrlstring打印状态回调地址,默认仅支持http
customParamMap<String,Object>自定义参数。方式传入为key-value格式

1.3 返回结果

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

data数据结构

字段类型说明备注
taskIdstring任务ID
labelstring面单短链,printType为IMAGE或者HTML时的面单短链比如http://api.kuaidi100.com/label/1面单异步生成,请求还未生成时,可以稍后重试

1.4 请求参数示例

method = custom
key = kytRsteof
sign = 4 BBDE07660E5EFF90873642CFAE9A8DD
t = 1470304729724
param = {
	"tempId": "476f6f769e57447fb84398eefae2ae28",
	"printType": "CLOUD",
	"siid": "KX100siid",
	"customParam": {
		"name": "12213",
		"flag": "出库",
		"count": 111,
		"unit": "货柜",
		"total": "2000",
		"orderId": "8888888888888",
		"customerId": "66666666",
		"cargo1": "苹果",
		"cargo2": "玉米",
		"num": "SF1536245218562",
		"label": "拼多多",
		"qrCode": "6666666666666",
		"org": "快递100"
	}
}

1.5 返回结果示例

成功返回示例

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

失败返回示例

{
	"code": 30007,
	"message": "模板不存在,请检查476f6f769e57447fb84398eefae2ae28",
	"time": 0,
	"success": false
}

1.6信息代码含义

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

二、打印状态回调

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

2.1 接口格式

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

2.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状态描述

2.3 返回结果

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

2.4 返回结果示例

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

说明:

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

其他信息快递100会忽略。

三、 硬件状态查询接口

获取云打印机设备通讯状态。

3.1 接口格式

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

3.2 请求地址

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

请求参数:

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

param数据结构:

参数名是否必填类型说明
siidstring设备码

3.3 返回结果

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

data数据结构

字段类型说明备注
onLinestring设备状态1,在线,0未在线

3.4 提供数据内容

{
    "result": true,
    "returnCode": "200",
    "message": "成功",
    "data": {
          "onLine": "****"  //设备状态
     }
} 

3.5 信息代码含义

信息代码字段含义
200提交成功
400参数错误
600您不是合法的用户(即授权Key出错)
601KEY已过期
500获取失败
503验证签名失败
504获取受限