电子面单下单接口
POST
https://api.kuaidi100.com/label/order通过快递公司或网点、菜鸟与淘宝提供的电子面单账号,支持只下单,或者生成图片使用本地打印设备打印输出,以及调用快递100云打印设备打印输出。使用快递100云打印则连接的设备必须是快递100云打印机或者快递100云盒。云盒可以支持不同品牌的打印机,具体支持品牌查询:云盒支持的打印机列表
param数据结构:
参数名 | 是否必填 | 类型 | 说明 |
---|---|---|---|
printType | 是 | string | 打印类型,NON:只下单不打印(默认); IMAGE:生成图片短链;HTML:生成html短链; CLOUD:使用快递100云打印机打印,使用CLOUD时siid必填 |
partnerId | 是 | string | 电子面单客户账户或月结账号,需贵司向当地快递公司网点申请(参考电子面单申请指南); 是否必填该属性,请查看参数字典 |
partnerKey | 否 | string | 电子面单密码,需贵司向当地快递公司网点申请; 是否必填该属性,请查看参数字典 |
partnerSecret | 否 | string | 电子面单密钥,需贵司向当地快递公司网点申请; 是否必填该属性,请查看参数字典 |
partnerName | 否 | string | 电子面单客户账户名称,需贵司向当地快递公司网点申请; 是否必填该属性,请查看参数字典 |
net | 否 | string | 收件网点名称,由快递公司当地网点分配, 若使用淘宝授权填入(taobao),使用菜鸟授权填入(cainiao), 使用京东授权填入(jdalpha),使用拼多多授权填入(pinduoduoWx),使用抖音授权填入(douyin),使用快手授权填入(kuaishou),使用唯品会授权填入(weipinhui)。 是否必填该属性,请查看参数字典 (若通过第三方授权方式获取单号partnerId,partnerKey参数为必填,参数值可通过第三方授权接口获取) |
code | 否 | string | 电子面单承载编号,需贵司向当地快递公司网点申请; 是否必填该属性,请查看参数字典 |
checkMan | 否 | string | 电子面单承载快递员名,需贵司向当地快递公司网点申请; 是否必填该属性,请查看参数字典 |
tbNet | 否 | string | 在使用菜鸟/淘宝/拼多多授权电子面单时,若月结账号下存在多个网点,则tbNet="网点名称,网点编号" ,注意此处为英文逗号 |
kuaidicom | 是 | string | 快递公司的编码,一律用小写字母,请查看参数字典 |
ΘrecMan | 是 | recMan | 收件人信息 |
¬name | 是 | string | 收件人姓名 |
¬mobile | 是 | string | 收件人的手机号,手机号和电话号二者其一必填 |
¬tel | 是 | string | 收件人的电话号,手机号和电话号二者其一必填 |
¬printAddr | 是 | string | 收件人所在完整地址,如广东深圳市南山区科技南十二路金蝶软件园B10 |
¬company | 否 | string | 收件人所在公司名称 |
ΘsendMan | 是 | sendMan | 寄件人信息 |
¬name | 是 | 寄件人姓名 | |
¬mobile | 是 | string | 寄件人的手机号,手机号和电话号二者其一必填 |
¬tel | 是 | string | 寄件人的电话号,手机号和电话号二者其一必填 |
¬printAddr | 是 | string | 寄件人所在的完整地址,如广东深圳市南山区科技南十二路金蝶软件园B10 |
¬company | 否 | string | 寄件人所在公司名称 |
cargo | 是 | string | 物品名称,例:文件 |
count | 是 | int | 包裹总数量。该属性与子单有关,如果需要子单(指同一个订单打印出多张电子面单,即同一个订单返回多个面单号),needChild = 1、count 需要大于1,如count = 2 则一个主单 一个子单,count = 3则一个主单 二个子单;返回的子单号码见返回结果的childNum字段 |
weight | 否 | Double | 物品总重量KG,例:1.5,单位kg。极兔速递必填,其他快递公司非必填 |
payType | 否 | string | 支付方式: SHIPPER:寄方付(默认) CONSIGNEE:到付 MONTHLY:月结 THIRDPARTY:第三方支付 (详细请查看参数字典 ) |
expType | 否 | string | 产品类型: 如标准快递(默认) 顺丰标快(陆运) EMS经济 (详细请请查看参数字典 ) |
remark | 否 | string | 备注 |
siid | 否 | string | 打印设备,通过打印机输出的设备码进行获取,printType为CLOUD时必填 |
direction | 否 | string | 打印方向, 0:正方向(默认); 1:反方向;只有printType为CLOUD时该参数生效 |
tempId | 是 | string | 主单模板,通过管理后台的快递公司模板V2信息获取 |
childTempId | 否 | string | 子单模板,部分快递公司需指定。通过管理后台的快递公司模板V2信息获取 |
backTempId | 否 | string | 回单模板,部分快递公司需指定。通过管理后台的快递公司模板V2信息获取 |
面单扩展属性 | |||
valinsPay | 否 | double | 保价额度 |
collection | 否 | double | 代收货款额度 |
needChild | 否 | string | 是否需要子单: 1:需要 0:不需要(默认) 如果需要子单(指同一个订单打印出多张电子面单,即同一个订单返回多个面单号); needChild = 1、count 需要大于1,如count = 2 一个主单 一个子单,count = 3 一个主单 二个子单,返回的子单号码见返回结果的childNum字段 |
needBack | 否 | string | 是否需要回单: 1:需要 0:不需要(默认) 返回的回单号见返回结果的returnNum字段 |
orderId | 否 | string | 贵司内部自定义的订单编号,需要保证唯一性,非必填 |
callBackUrl | 否 | string | 数据回调地址(打印状态以及OCR识别结果) |
salt | 否 | string | 签名用随机字符串,用于验证签名sign。salt值不为null时,推送数据将包含该加密签名,加密方式:md5(param+salt)。注意: salt值为空串时,推送的数据也会包含sign,此时可忽略sign的校验。 |
needSubscribe | 否 | boolean | 是否开启订阅功能 false:不开启(默认) true:开启 说明开启订阅功能时:pollCallBackUrl必须填入 此功能只针对有快递单号的单 |
pollCallBackUrl | 否 | string | 如果needSubscribe 设置为true时,pollCallBackUrl必须填入,用于跟踪回调 |
resultv2 | 否 | string | 添加此字段表示开通行政区域解析或地图轨迹功能 。 0:关闭(默认) 1或4:开通行政区域解析功能(不同值下的参数返回详见:快递信息推送接口文档), 3或5:开通地图轨迹及时效返回(不同值下的参数返回详见地图轨迹推送服务技术文档) |
needDesensitization | 否 | boolean | 是否脱敏 ,false:关闭(默认)true:开启。开启后生成的面单收寄件人手机号码会脱敏,使用前请先跟网点确认是否支持使用脱敏电话 |
needLogo | 否 | boolean | 面单是否需要logo false:关闭(默认)true:开启 |
thirdOrderId | 否 | string | 平台导入返回的订单id:如平台类加密订单,使用此下单为必填 |
oaid | 否 | string | 淘宝订单收件人ID (Open Addressee ID),长度不超过128个字符,淘宝订单加密情况用于解密 |
caid | 否 | string | 菜鸟解密地址ID,1688订单加密情况用于解密 |
thirdTemplateURL | 否 | string | 第三方平台面单基础模板链接,如为第三方平台导入订单选填,如不填写,默认返回两联面单模板 |
thirdCustomTemplateUrl | 否 | string | 第三方平台自定义区域模板地址 |
customParam | 否 | Map<String,String> | 面单自定义参数。方式传入为key-value格式,注意这里的key优先级高于面单生成的参数,例如:面单里面默认的快递单号对应参数为kuaidinum,如果这里的key也包含kuaidinum,将会覆盖原来的值。使用第三方平台订单时,也可配合thirdCustomTemplateUrl,实现自定义区域的传值 |
needOcr | 否 | boolean | 第三方平台订单是否需要开启ocr,开启后将会通过推送方式推送 false:关闭(默认)true:开启 |
ocrInclude | 否 | String[] | orc需要检测识别的面单元素。取值范围:barcode,qrcode,receiver,sender,bulkpen。不传或者 null 则默认为 ["barcode", "receiver", "sender"] |
height | 否 | string | 打印纸的高度,以mm为单位(该参数只有第三方平台订单,并且printType为CLOUD时起作用) |
width | 否 | string | 打印纸的宽度,以mm为单位(该参数只有第三方平台订单,并且printType为CLOUD时起作用) |
data数据结构
字段 | 类型 | 说明 | 备注 |
---|---|---|---|
taskId | string | 任务ID | |
kuaidinum | string | 快递单号 | |
childNum | string | 子单号 | 多个子单时使用”,”隔开。比如JD6666666,JD888888,JD99999 |
backNum | string | 回单号 | 部分快递公司回单会返回回单号 |
label | string | 面单短链,printType为IMAGE或者HTML时的面单短链 | 多个面单时使用”,”隔开。比如http://api.kuaidi100.com/label/1, http://api.kuaidi100.com/label/2, http://api.kuaidi100.com/label/3 面单异步生成,请求还未生成时,可以稍后重试 |
bulkpen | string | 大头笔 | 用于显示于电子面单上规定位置,非必需,是否有值取决于快递公司 |
orgCode | string | 始发地区域编码 | |
orgName | string | 始发地/始发网点名称 | |
destCode | string | 目的地区域编码 | |
destName | string | 目的地/到达网点 | |
orgSortingCode | string | 始发分拣编码 | |
orgSortingName | string | 始发分拣名称 | |
destSortingCode | string | 目的分栋编码 | |
destSortingName | string | 目的分栋中心名称 | |
orgExtra | string | 始发其他信息 | |
destExtra | string | 目的其他信息 | |
pkgCode | string | 集包编码 | |
pkgName | string | 集包地名称 | |
road | string | 路区 | |
qrCode | string | 二维码 | |
kdComOrderNum | string | 快递公司订单号 | |
expressCode | string | 快递业务类型编码 | |
expressName | string | 快递业务类型名称 |
注意:当net入参为taobao/cainiao/jdalpha/pinduoduoWx/douyin/kuaishou/weipinhui时,printType将不起作用,label返回的结果除了jdalpha是jpg,其他都是pdf格式
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 | 打印机状态不正确 | 打印机当前状态无法打单,需要检查 |
请求参数
Body 参数application/x-www-form-urlencoded
method
string
必需
业务类型(默认:order)
key
string
必需
授权码,请到快递100页面申请企业版接口获取
sign
string
必需
32位大写,签名,用于验证身份,按MD5 (param +t+key+ secret)的顺序进行MD5加密,不需要加上“+”号,secret在企业管理后台获取
t
string
必需
时间戳如:1576123932000
param
string
由其他字段拼接
示例代码
返回响应
成功(200)
失败(200)
HTTP 状态码: 200
内容格式: JSONapplication/json
数据结构
code
integer
返回编码
200为成功
data
object
必需
kuaidinum
string
快递单号
bulkpen
string
必需
sameCity
string
必需
sameProv
string
必需
taskId
string
任务ID
message
string
返回报文描述
time
integer
必需
success
boolean
提交结果
true提交成功,false失败
示例
成功示例
{
"code": 200,
"data": {
"kuaidinum": "ZJS8888888888",
"bulkpen": "371-转9999-C482",
"sameCity": "1",
"sameProv": "1",
"taskId": "7EEAFD6CBEF64FEBAA10022BD32378BC"
},
"message": "success",
"time": 0,
"success": true
}
修改于 2 年前