快递寄件接口
一、 商家寄件运力接口
查询全国快递公司运力覆盖情况。
1.1 接口格式
提供统一格式的HTTP POST或GET调用接口,并返回统一格式JSON数据。
1.2 请求地址
https://order.kuaidi100.com/order/borderbestapi.do
请求参数:
参数名 | 是否必填 | 类型 | 说明 |
---|---|---|---|
method | 是 | string | 业务类型(默认:querymkt) |
key | 是 | string | 授权码,请到快递100页面申请企业版接口获取 |
sign | 是 | string | 32位大写,签名,用于验证身份,按MD5 (param +t+key+ secret)的顺序进行MD5加密,不需要加上“+”号 secret可在企业管理后台查看 |
t | 是 | string | 时间戳如:1576123932000 |
param | 是 | param | 由其他字段拼接 |
param数据结构:
参数名 | 是否必填 | 类型 | 说明 |
---|---|---|---|
sendAddr | 是 | string | 寄件人所在的完整地址,如广东深圳市深圳市南山区科技南十二路2号金蝶软件园B10 |
1.3 返回结果
字段 | 类型 | 说明 | 备注 |
---|---|---|---|
result | boolean | 提交结果 | true提交成功,false失败 |
returnCode | string | 返回编码 | |
message | string | 返回报文描述 | |
data | data |
data数据结构
字段 | 类型 | 说明 | 备注 |
---|---|---|---|
province | string | 省 | |
city | string | 市 | |
district | string | 区 | |
addr | string | 地址 | |
latitude | string | 经度 | |
longitude | string | 纬度 | |
mktInfo | mktInfo | 覆盖运力快递公司列表 |
mktInfo数据结构
字段 | 类型 | 说明 | 备注 |
---|---|---|---|
serviceType | string | 业务服务类型 | |
mktId | string | 内部属性忽略 | |
kuaidiCom | string | 支持的快递公司编码 | |
bigCustPriceDOList | string | 内部属性忽略 |
1.4 提供数据内容
{
"data": {
"province": "广东",
"city": "深圳市",
"district": "南山区",
"latitude": "22.465335763306832",
"mktInfo": [
{
"serviceType": [
"快递包裹"
],
"mktId": 98959397,
"kuaidiCom": "youzhengguonei",
"bigCustPriceDOList": null
},
{
"serviceType": null,
"mktId": 98959397,
"kuaidiCom": "zhaijisong",
"bigCustPriceDOList": null
}
],
"addr": "海运大厦",
"longitude": "113.88346197876328"
},
"message": "成功",
"result": true,
"returnCode": "200"
}
1.5 信息代码含义
信息代码 | 信息内容描述 | 原因及建议处理方式 |
---|---|---|
200 | 提交成功 | 提交成功 |
201 | 无法获取运力 | 该地址没有快递公司运力,需联系快递100工作人员添加 |
400 | 参数错误 | 请根据技术文档请求,注意参数类型及是否必填。 |
400 | 非法IP | 请联系快递100工作人员添加白名单 |
500 | 服务器错误 | 快递100的服务器出理间隙或临时性异常,有时如果因为不按规范提交请求,比如快递公司参数写错等,也会报此错误 |
500 | 没法识别到寄件地址/地址缺失市区/地址缺失区信息/没有填入寄件人地址 | 地址错误,请填写完整的地址信息 |
503 | 签名认证失败 | 请检查加密方式,param + t + key + secret 的顺序进行MD5加密,加密后字符串转大写,不用加上“+”号 |
600 | 您不是合法的用户(即授权Key出错) | 账号无可用单量,需要充值 |
601 | KEY已过期 | 账号无可用单量,需要充值 |
二 、商家寄件(优选)下单接口
选择快递公司进行下单。
2.1 接口格式
提供统一格式的HTTP POST或GET调用接口,并返回统一格式JSON数据。
2.2 请求地址
https://order.kuaidi100.com/order/borderbestapi.do
请求参数:
参数名 | 是否必填 | 类型 | 说明 |
---|---|---|---|
method | 是 | string | 业务类型(默认:bOrderBest) |
key | 是 | string | 授权码,请申请企业版获取 |
sign | 是 | string | 32位大写,签名,用于验证身份,按MD5 (param +t+key+ secret)的顺序进行MD5加密,不需要加上“+”号,secret在企业管理后台查看 |
t | 是 | string | 时间戳如:1576123932000 |
param | 是 | param | 由其他字段拼接 |
param数据结构:
参数名 | 是否必填 | 类型 | 说明 |
---|---|---|---|
kuaidicom | 是 | string | 快递公司的编码,一律用小写字母,见《快递公司编码》 |
recManName | 是 | string | 收件人姓名 |
recManMobile | 是 | string | 收件人的手机号,手机号和电话号二者其一必填 |
recManPrintAddr | 是 | string | 收件人所在完整地址,如广东深圳市深圳市南山区科技南十二路2号金蝶软件园 |
sendManName | 是 | string | 寄件人姓名 |
sendManMobile | 是 | string | 寄件人的手机号,手机号和电话号二者其一必填 |
sendManPrintAddr | 是 | string | 寄件人所在的完整地址,如广东深圳市深圳市南山区科技南十二路2号金蝶软件园B10 |
callBackUrl | 是 | string | callBackUrl订单信息回调 |
cargo | 否 | string | 物品名称,例:文件 |
weight | 否 | string | 物品总重量KG,不需带单位,例:1.5 |
serviceType | 否 | string | 快递业务服务类型,例:标准快递,默认为标准快递 |
remark | 否 | string | 备注 |
salt | 否 | string | 签名用随机字符串 |
2.3 返回结果
字段 | 类型 | 说明 | 备注 |
---|---|---|---|
result | boolean | 提交结果 | true提交成功,false失败 |
returnCode | string | 返回编码 | |
message | string | 返回报文描述 | |
data | data |
data数据结构
字段 | 类型 | 说明 | 备注 |
---|---|---|---|
taskId | string | 任务ID | |
orderId | string | 订单ID |
2.4 返回结果示例
{
"result": true,
"returnCode": "200",
"message": "提交成功",
"data": {
"taskId": "****", // 任务ID
"orderId ": "****" // 订单ID
}
}
2.5 信息代码含义
信息代码 | 信息内容描述 | 原因及建议处理方式 |
---|---|---|
200 | 提交成功 | 提交成功 |
400 | 参数错误 | 请根据技术文档请求,注意参数类型及是否必填。 |
500 | 服务器错误 | 快递100的服务器出理间隙或临时性异常,有时如果因为不按规范提交请求,比如快递公司参数写错等,也会报此错误 |
500 | 下单失败 | 请根据技术文档请求,注意参数类型及是否必填。 |
503 | 签名认证失败 | 请检查加密方式,param + t + key + secret 的顺序进行MD5加密,加密后字符串转大写,不用加上“+”号 |
600 | 您不是合法的用户(即授权Key出错) | 账号无可用单量,需要充值 |
601 | KEY已过期 | 账号无可用单量,需要充值 |
700 | 错误的回调地址 | 检查回调地址,或者联系快递100工作人员 |
三、下单回调接口
订单有状态变更是会触发回调,回调后如果没有得到合作方正确返回,会重复回调多2次,即最多回调3次。间隔30分钟。
3.1 接口格式
提供统一格式的HTTP POST,并返回统一格式JSON数据。
请求报头:Content-Type=application/x-www-form-urlencoded;charset=UTF-8
3.2 请求地址
请求参数:
字段 | 类型 | 说明 | 备注 |
---|---|---|---|
taskId | string | 任务ID | |
sign | string | 签名 | MD5 (param +salt) |
param | param | 参数主体 |
param数据结构:
参数名 | 是否必填 | 类型 | 说明 |
---|---|---|---|
kuaidicom | 是 | string | 快递公司的编码,一律用小写字母,见《快递公司编码》,选填。 |
kuaidinum | 是 | string | 快递单号,单号的最大长度是32个字符。 |
status | 是 | string | 状态码 |
message | 是 | string | 状态描述 |
data | 是 | data | 订单内容 |
data数据结构:
参数名 | 是否必填 | 类型 | 说明 |
---|---|---|---|
orderId | 是 | string | 平台订单ID |
status | 是 | string | 订单状态: 1,'已接单', 2,'收件中', 3,'改派', 7,'快递员修改订单信息', 9,'用户主动取消', 10,'已取件', 15,'已结算', 99,'订单已取消', 101, '运输中' |
courierName | 否 | string | 快递员姓名 |
courierMobile | 否 | string | 快递员电话 |
weight | 否 | string | 重量 |
freight | 否 | string | 运费 |
3.3 返回结果
字段 | 说明 | 备注 |
---|---|---|
result | 提交结果 | true提交成功,false失败 |
returnCode | 返回编码 | |
message | 返回报文描述 |
3.4 返回结果示例
{
"result": true,
"returnCode": "200",
"message": "提交成功"
}
3.5 回调响应报文及错误码解释
字段名称 | 字段含义 |
---|---|
result | true表示成功,false表示失败。如果提交回调接口的地址失败,30分钟后重新回调,3次仍旧失败的,自动放弃 |
returnCode | 200: 提交成功 500: 服务器错误 其他错误请自行定义 |
message | 返回的提示 |
其他信息快递100会忽略。
四、商家寄件下单取消接口
对下完单进行取消操作
4.1 接口格式
提供统一格式的HTTP POST或GET调用接口,并返回统一格式JSON数据。
4.2 请求地址
https://order.kuaidi100.com/order/borderbestapi.do
请求参数:
参数名 | 是否必填 | 类型 | 说明 |
---|---|---|---|
method | 是 | string | 业务类型(默认:cancelBest) |
key | 是 | string | 授权码, 请申请企业版获取 |
sign | 是 | string | **32****位大写,**签名,用于验证身份,按MD5 (param +t+key+ secret)的顺序进行MD5加密,不需要加上“+”号。secret在企业管理后台可以查看。 |
t | 是 | string | 时间戳如:1576123932000 |
param | 是 | param | 由其他字段拼接 |
param数据结构:
参数名 | 是否必填 | 类型 | 说明 |
---|---|---|---|
taskId | 是 | string | 任务ID |
orderId | 是 | string | 订单ID |
cancelMsg | 是 | string | 取消原因,例:暂时不寄件了 |
4.3 返回结果
字段 | 类型 | 说明 | 备注 |
---|---|---|---|
result | boolean | 提交结果 | true提交成功,false失败 |
returnCode | string | 返回编码 | |
message | string | 返回报文描述 | |
data | data | 这里默认为空 |
4.4 返回结果示例
{
"result": true,
"returnCode": "200",
"message": "提交成功",
"data": {}
}
4.5 信息代码含义
信息代码 | 信息内容描述 | 原因及建议处理方式 |
---|---|---|
200 | 提交成功 | 提交成功 |
400 | 参数错误 | 请根据技术文档请求,注意参数类型及是否必填。 |
500 | 服务器错误 | 快递100的服务器出理间隙或临时性异常,有时如果因为不按规范提交请求,比如快递公司参数写错等,或者对已取消的订单重复操作取消,也会报此错误 |
501 | 重复提交 | 重复提交了请求 |
503 | 签名认证失败 | 请检查加密方式,param + t + key + secret 的顺序进行MD5加密,加密后字符串转大写,不用加上“+”号 |
600 | 您不是合法的用户(即授权Key出错) | 账号无可用单量,需要充值 |
601 | KEY已过期 | 账号无可用单量,需要充值 |
五、快递公司编码
快递公司 | 编码 |
---|---|
中通 | zhongtong |
圆通 | yuantong |
申通 | shentong |
韵达 | yunda |
天天 | tiantian |
百世(汇通) | huitongkuaidi |
宅急送 | zhaijisong |
极兔 | jtexpress |