一、自定义模板打印接口
如有发票、发货单、面单等打印需求,可使用该接口。通过管理后台模板配置,配置自定义模板,实现自定义打印功能。该接口支持在提交打印请求2天内的打印任务进行复打10次的操作
1.1 接口格式
提供统一格式的HTTP POST或GET调用接口,并返回统一格式JSON数据。
1.2 请求地址
https://api.kuaidi100.com/label/order
请求参数(header)
名称 | 类型 | 默认值 |
---|---|---|
Content-Type | string | application/x-www-form-urlencoded |
请求参数(body)
参数名 | 是否必填 | 类型 | 说明 |
---|---|---|---|
method | 是 | string | 业务类型(默认:custom) |
key | 是 | string | 授权码,请申请企业版获取 |
sign | 是 | string | 32位大写,签名,用于验证身份,按MD5 (param +t+key+ secret)的顺序进行MD5加密,不需要加上“+”号,secret在企业管理后台获取 |
t | 是 | string | 时间戳如:1576123932000 |
param | 是 | param | 由其他字段拼接 |
param数据结构:
参数名 | 是否必填 | 类型 | 说明 |
---|---|---|---|
tempid | 是 | string | 通过管理后台的打印模板V2信息获取 |
printType | 是 | string | 打印类型(IMAGE,CLOUD,HTML)。IMAGE:生成图片短链;HTML:生成html短链;CLOUD:使用快递100云打印机打印,使用CLOUD时siid必填 |
siid | 否 | string | 打印设备,通过打印机输出的设备码进行获取,printType为CLOUD时必填 |
direction | 否 | string | 打印方向(默认0) 0-正方向 1-反方向;只有printType为CLOUD有作用 |
callBackUrl | 否 | string | 打印状态回调地址 |
customParam | 否 | Map<String,Object> | 自定义参数。方式传入为key-value格式 |
1.3 返回结果
字段 | 类型 | 说明 | 备注 |
---|---|---|---|
success | boolean | 提交结果 | true提交成功,false失败 |
code | int | 返回编码 | |
message | string | 返回报文描述 | |
data | String |
data数据结构
字段 | 类型 | 说明 | 备注 |
---|---|---|---|
taskId | string | 任务ID | |
label | string | 面单短链,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天内的打印任务进行复打10次的操作。
2.1 接口格式
提供统一格式的HTTP POST或GET调用接口,并返回统一格式JSON数据。
2.2 请求地址
https://api.kuaidi100.com/label/order
请求参数:
参数名 | 是否必填 | 类型 | 说明 |
---|---|---|---|
method | 是 | string | 业务类型(默认:printOld) |
key | 是 | string | 授权码,请申请企业版获取 |
sign | 是 | string | 32位大写,签名,用于验证身份,按MD5 (param +t+key+ secret)的顺序进行MD5加密,不需要加上“+”号secret在企业管理后台查看 |
t | 是 | string | 时间戳如:1576123932000 |
param | 是 | param | 由其他字段拼接 |
param数据结构:
参数名 | 是否必填 | 类型 | 说明 |
---|---|---|---|
taskId | 是 | string | 任务ID |
siid | 否 | string | 快递100打印机,不填默认为下单时填入的siid |
2.3 返回结果
字段 | 类型 | 说明 | 备注 |
---|---|---|---|
success | boolean | 提交结果 | true提交成功,false失败 |
code | string | 返回编码 | |
message | String | 返回报文描述 | |
data | String | 图片复打时会有返回 |
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="签名字符串" />
</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会忽略。
四、 硬件状态查询接口
获取云打印机设备通讯状态。
4.1 接口格式
提供统一格式的HTTP POST或GET调用接口,并返回统一格式JSON数据。
4.2 请求地址
https://poll.kuaidi100.com/printapi/printtask.do
请求参数:
参数名 | 是否必填 | 类型 | 说明 |
---|---|---|---|
method | 是 | string | 业务类型(默认:devstatus) |
key | 是 | string | 授权码,请申请企业版获取 |
sign | 是 | string | 32位大写 ,签名,用于验证身份,按MD5 (param +t+key+ secret)的顺序进行MD5加密,不需要加上“+”号,secret在企业管理后台查看 |
t | 是 | string | 时间戳如:1576123932000 |
param | 是 | param | 由其他字段拼接 |
param数据结构:
参数名 | 是否必填 | 类型 | 说明 |
---|---|---|---|
siid | 是 | string | 设备码 |
4.3 返回结果
字段 | 类型 | 说明 | 备注 |
---|---|---|---|
result | boolean | 提交结果 | true提交成功,false失败 |
returnCode | string | 返回编码 | |
message | string | 返回报文描述 | |
data | data |
data数据结构
字段 | 类型 | 说明 | 备注 |
---|---|---|---|
onLine | string | 设备状态 | 1,在线,0未在线 |
4.4 提供数据内容
{
"result": true,
"returnCode": "200",
"message": "成功",
"data": {
"onLine": "****" //设备状态
}
}
4.5 信息代码含义
信息代码 | 字段含义 |
---|---|
200 | 提交成功 |
400 | 参数错误 |
600 | 您不是合法的用户(即授权Key出错) |
601 | KEY已过期 |
500 | 获取失败 |
503 | 验证签名失败 |
504 | 获取受限 |