文档中心
一 、C端寄件下单接口 二、下单回调接口 三、C端寄件下单取消接口 四、C端寄件价格查询接口 五、快递信息推送接口 六、快递公司编码 调试工具

一、C端寄件下单接口

选择快递公司进行下单。

1.1 接口格式

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

1.2 请求地址

https://order.kuaidi100.com/order/corderapi.do

请求参数:

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

param数据结构:

参数名是否必填类型说明
kuaidicomstring快递公司的编码,一律用小写字母,见《快递公司编码》
recManNamestring收件人姓名
recManMobilestring收件人的手机号,手机号和电话号二者其一必填
recManPrintAddrstring收件人所在完整地址,如广东深圳市深圳市南山区科技南十二路2号金蝶软件园
sendManNamestring寄件人姓名
sendManMobilestring寄件人的手机号,手机号和电话号二者其一必填
sendManPrintAddrstring寄件人所在的完整地址,如广东深圳市深圳市南山区科技南十二路2号金蝶软件园B10
callBackUrlstringcallBackUrl订单信息回调
cargostring物品名称,例:文件
paymentstring支付方式,SHIPPER: 寄方付(默认),CONSIGNEE: 到付(中通不支持)
weightstring物品总重量KG,不需带单位,例:1.5
remarkstring备注
dayTypestring预约日期,例如:今天/明天/后天
pickupStartTimestring预约起始时间,24小时制(HH:mm),例如:09:00
pickupEndTimestring预约截止时间,24小时制(HH:mm),例如:10:00
saltstring签名用随机字符串
opstring是否开启订阅功能 0:不开启(默认) 1:开启 说明开启订阅功能时:pollCallBackUrl必须填入 此功能只针对有快递单号的单
pollCallBackUrlstring如果op设置为1时,pollCallBackUrl必须填入,用于跟踪回调。此为免费服务,回调内容通过五、快递信息推送接口 返回(免费服务)
resultv2string添加此字段表示开通行政区域解析功能 。
0:关闭(默认)
1:开通行政区域解析功能以及物流轨迹增加物流状态名称
4:开通行政解析功能以及物流轨迹增加物流高级状态名称、状态值并且返回出发、目的及当前城市信息(详见:快递信息推送接口文档)
thirdOrderIdstring平台订单号,最大32位。若此参数与之前的重复,48小时内返回第一次下单内容,否则会重新下单。

1.3 返回结果

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

data数据结构

字段类型说明备注
taskIdstring任务ID
orderIdstring订单ID

1.4 返回结果示例

{
    "result": true,
    "returnCode": "200",
    "message": "提交成功",
    "data": {
        "taskId": "****",  // 任务ID
        "orderId ": "****" // 订单ID
    }
} 

1.5 信息代码含义

信息代码信息内容描述原因及建议处理方式
200提交成功提交成功
400参数错误请根据技术文档请求,注意参数类型及是否必填。
500服务器错误快递100的服务器出理间隙或临时性异常,有时如果因为不按规范提交请求,比如快递公司参数写错等,也会报此错误
501重复提交
503签名认证失败请检查加密方式,param + t + key + secret 的顺序进行MD5加密,加密后字符串转大写,不用加上“+”号
600您不是合法的用户(即授权Key出错)检查KEY是否填写正确或账号无可用单量,需要充值
601KEY已过期账号无可用单量,需要充值
700错误的回调地址检查回调地址,或者联系快递100工作人员

二、下单回调接口

订单有状态变更是会触发回调,回调后如果没有得到合作方正确返回,会重复回调多2次,即最多回调3次。间隔30分钟。

2.1 接口格式

提供统一格式的HTTP POST,并返回统一格式JSON数据。

请求报头:Content-Type=application/x-www-form-urlencoded;charset=UTF-8

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="签名字符串" />
</form>

请求参数:

字段类型说明备注
taskIdstring任务ID
signstring签名MD5 (param +salt)
paramparam参数主体

param数据结构:

参数名是否必填类型说明
kuaidicomstring快递公司的编码,一律用小写字母,见《快递公司编码》
kuaidinumstring快递单号,单号的最大长度是32个字符
statusstring状态码
messagestring状态描述
datadata订单内容

data数据结构:

参数名是否必填类型说明
orderIdstring平台订单ID
statusint订单状态,0:'下单成功';1:'已接单';2:'收件中';9:'用户主动取消';10:'已取件';101:'运输中';11:'揽货失败';12:'已退回';13:'已签收';14:'异常签收';99:'订单已取消';101:'运输中';200:'已出单';201:'出单失败';610:'下单失败';155:'修改重量'(注意需要在工单系统中发起异常反馈并由快递100服务人员确认调重后才会有此状态回调,回调内容包含修改重量后的重量、运费、费用明细、业务类型);166:订单复活(订单被取消,但是实际包裹已经发出,正常计费);400:派送中
courierNamestring快递员姓名
courierMobilestring快递员电话
weightstring重量
freightstring运费

2.3 返回结果

字段说明备注
result提交结果true提交成功,false失败
returnCode返回编码
message返回报文描述

2.4 返回结果示例

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

2.5 回调响应报文及错误码解释

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

其他信息快递100会忽略。

三、C端寄件下单取消接口

对下完的单进行取消操作

3.1 接口格式

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

3.2 请求地址

https://order.kuaidi100.com/order/corderapi.do

请求参数:

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

param数据结构:

参数名是否必填类型说明
taskIdstring任务ID
orderIdstring订单ID
cancelMsgstring取消原因,例:暂时不寄件了,最大长度不超过30字符

3.3 返回结果

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

3.4 返回结果示例

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

3.5 信息代码含义

信息代码信息内容描述原因及建议处理方式
200提交成功提交成功
400参数错误请根据技术文档请求,注意参数类型及是否必填。
500服务器错误快递100的服务器出理间隙或临时性异常,有时如果因为不按规范提交请求,比如快递公司参数写错等,或者对已取消的订单重复操作取消,也会报此错误
501重复提交重复提交了请求
503签名认证失败请检查加密方式,param + t + key + secret 的顺序进行MD5加密,加密后字符串转大写,不用加上“+”号
600您不是合法的用户(即授权Key出错)检查KEY是否填写正确或账号无可用单量,需要充值
601KEY已过期账号无可用单量,需要充值

四、C端寄件价格查询接口

查看从出发地到目的地的价格

4.1 接口格式

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

4.2 请求地址

https://order.kuaidi100.com/order/corderapi.do

请求参数:

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

param数据结构:

参数名是否必填类型说明
kuaidicomstring快递公司编码,顺丰冷运、百世快运暂不支持价格查询。
serviceTypestring业务类型,顺丰速运需要传业务类型为"顺丰标快",其他快递公司可不传
sendManPrintAddrstring出发地地址,最小颗粒到市级,例如:广东省深圳市。(注意:京东快递需传详细收发地址查询价格)
recManPrintAddrstring目的地地址,最小颗粒到市级,例如:广东省深圳市。(注意:京东快递需传详细收发地址查询价格)
weightstring重量,单位:kg,默认:1

4.3 返回结果

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

data数据结构:

参数名类型说明
pricestring运费,单位:元

4.4 提供数据内容

返回结果示例

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

说明:

信息代码信息内容描述原因及建议处理方式
200提交成功提交成功
400参数错误等请根据技术文档请求,注意参数类型及是否必填
500服务器错误快递100的服务器出理间隙或临时性异常,有时如果因为不按规范提交请求,比如快递公司参数写错等,也会报此错误
503验证签名失败请检查加密方式,param + t + key + secret 的顺序进行MD5加密,加密后字符串转大写,不用加上“+”号
600您不是合法的用户(即授权Key出错)检查KEY是否填写正确或账号无可用余额,需要充值
601KEY已过期账号无可用余额,需要充值

五、快递信息推送接口

5.1 推送请求地址

由贵司在下单开启订阅功能中通过pollCallBackUrl字段提供

5.2 推送请求类型

post

5.3 推送输入参数

请求参数(header)

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

请求参数(body)

名称类型示例值描述
signString 订阅参数salt值不为null时,推送数据将包含该加密签名,加密方式:md5(param+salt)。注意: salt值为空串时,推送的数据也会包含sign。
Θparam 由其他字段拼接
└ statusStringpolling监控状态:polling:监控中,shutdown:结束,abort:中止,updateall:重新推送。其中当快递单为已签收时status=shutdown,当message为“3天查询无记录”或“60天无变化时”status= abort ,对于status=abort的状态,需要增加额外的处理逻辑
└ billstatusStringgot包括got、sending、check三个状态,由于意义不大,已弃用,请忽略
└ messageString 监控状态相关消息,如:3天查询无记录,60天无变化
└ autoCheckString1快递公司编码是否出错,0为本推送信息对应的是贵司提交的原始快递公司编码,1为本推送信息对应的是我方纠正后的新的快递公司编码。一个单如果我们连续3天都查不到结果,我方会(1)判断一次贵司提交的快递公司编码是否正确,如果正确,给贵司的回调接口(callbackurl)推送带有如下字段的信息:autoCheck=0、comOld与comNew都为空;(2)如果贵司提交的快递公司编码出错,我们会帮忙用正确的快递公司编码+原来的运单号重新提交订阅并开启监控(后续如果监控到单号有更新就给贵司的回调接口(callbackurl)推送带有如下字段的信息:autoCheck=1、comOld=原来的公司编码、comNew=新的公司编码);并且给贵方的回调接口(callbackurl)推送一条含有如下字段的信息:status=abort、autoCheck=0、comOld为空、comNew=纠正后的快递公司编码。
└ comOldStringyuantong贵司提交的原始的快递公司编码。详细见autoCheck后说明。若开启了国际版(即在订阅请求中增加字段interCom=1),则回调请求中暂无此字段
└ comNewStringems我司纠正后的新的快递公司编码。详细见autoCheck后说明。若开启了国际版(即在订阅请求中增加字段interCom=1),则回调请求中暂无此字段
ΘlastResultlastResult 最新查询结果,若在订阅报文中通过interCom字段开通了国际版,则此lastResult表示出发国的查询结果,全量,倒序(即时间最新的在最前)
└- messageString 消息体,请忽略
└- stateString0快递单当前状态,默认为0在途,1揽收,2疑难,3签收,4退签,5派件,8清关,14拒签等10个基础物流状态,如需要返回高级物流状态,请参考 resultv2 传值
└- statusString200通讯状态,请忽略
└- conditionStringF00快递单明细状态标记,暂未实现,请忽略
└- ischeckString0是否签收标记,0未签收,1已签收
└- comStringyuantong快递公司编码,一律用小写字母
└- nuStringV030344422单号
└- dataObject 数组,包含多个对象,每个对象字段如展开所示
└-- contextString上海分拨中心/装件入车扫描内容
└-- timeString2012-08-28 16:33:19时间,原始格式
└-- ftimeString2012-08-28 16:33:19格式化后时间
└-- statusString在途物流状态名称或者高级状态名称,提交resultv2=1或者resultv2=4标记后才会出现
└-- statusCodeString1002本数据元对应的高级物流状态值,提交resultv2=4标记后才会出现
└-- areaCodeString310000000000本数据元对应的行政区域的编码,提交resultv2=1或者resultv2=4标记后才会出现
└-- areaNameString上海市本数据元对应的行政区域的名称,提交resultv2=1或者resultv2=4标记后才会出现
└--areaCenterString17.200983,39.084158本数据元对应的行政区域经纬度,提交resultv2=4标记后才会出现
└--locationString深圳中心本数据元对应的快件当前位置,提交resultv2=4标记后才会出现
└--areaPinYinStringtianjin本数据元对应的行政区域拼音,提交resultv2=4标记后才会出现
Θ destResultdestResult 表示最新的目的国家的查询结果,只有在订阅报文中通过interCom=1字段开通了国际版才会显示此数据元,全量,倒序(即时间最新的在最前)
└- messageString 消息体,请忽略
└- stateString0快递单当前状态,默认为0在途,1揽收,2疑难,3签收,4退签,5派件,8清关,14拒签等10个基础物流状态,如需要返回高级物流状态,请参考 resultv2 传值
└- statusString200通讯状态,请忽略
└- conditionStringF00快递单明细状态标记,暂未实现,请忽略
└- ischeckString0是否签收标记,0未签收,1已签收
└- comStringyuantong快递公司编码,一律用小写字母
└- nuStringV030344422单号
Θ datadata 数组,包含多个对象,每个对象字段如展开所示
└-- contextString上海分拨中心/装件入车扫描内容
└-- timeString2012-08-28 16:33:19时间,原始格式
└-- ftimeString2012-08-28 16:33:19格式化后时间
└-- statusString在途本数据元对应的物流状态名称或者高级状态名称,提交resultv2=1或者resultv2=4标记后才会出现
└-- areaCodeString310000000000本数据元对应的行政区域的编码,提交resultv2=1或者resultv2=4标记后才会出现
└-- areaNameString上海市本数据元对应的行政区域的名称,提交resultv2=1或者resultv2=4标记后才会出现
└--areaCenterString17.200983,39.084158本数据元对应的行政区域经纬度,提交resultv2=4标记后才会出现
└--locationString深圳中心本数据元对应的快件当前位置,提交resultv2=4标记后才会出现
└--areaPinYinStringtianjin本数据元对应的行政区域拼音,提交resultv2=4标记后才会出现

5.4 推送输入参数示例

{
	"status": "polling",
	"billstatus": "got",
	"message": "寄件",
	"lastResult": {
		"message": "ok",
		"nu": "YT6186594166532",
		"ischeck": "0",
		"com": "yuantong",
		"status": "200",
		"data": [{
				"time": "2021-12-15 20:15:14",
				"context": "【苏州转运中心】 已发出 下一站 【无锡转运中心公司】",
				"ftime": "2021-12-15 20:15:14",
				"areaCode": "CN320500000000",
				"areaName": "江苏,苏州市",
				"status": "干线",
				"location": "",
				"areaCenter": "120.585315,31.298886",
				"areaPinYin": "su zhou shi",
				"statusCode": "1002"
			},
			{
				"time": "2021-12-15 20:11:25",
				"context": "【苏州转运中心公司】 已收入",
				"ftime": "2021-12-15 20:11:25",
				"areaCode": "CN320500000000",
				"areaName": "江苏,苏州市",
				"status": "干线",
				"location": "",
				"areaCenter": "120.585315,31.298886",
				"areaPinYin": "su zhou shi",
				"statusCode": "1002"
			},
			{
				"time": "2021-12-15 19:18:27",
				"context": "【江苏省无锡市锡新开发区公司】 已收入",
				"ftime": "2021-12-15 19:18:27",
				"areaCode": "CN320200000000",
				"areaName": "江苏,无锡市",
				"status": "在途",
				"location": "",
				"areaCenter": "120.31191,31.491169",
				"areaPinYin": "wu xi shi",
				"statusCode": "0"
			},
			{
				"time": "2021-12-15 17:10:09",
				"context": "【江苏省苏州市北桥公司】 已揽收",
				"ftime": "2021-12-15 17:10:09",
				"areaCode": "CN320507004000",
				"areaName": "江苏,苏州市,相城区,北桥",
				"status": "揽收",
				"location": "",
				"areaCenter": "120.606531,31.505825",
				"areaPinYin": "bei qiao jie dao",
				"statusCode": "1"
			}
		],
		"state": "0",
		"condition": "F00",
		"routeInfo": {
			"from": {
				"number": "CN320507004000",
				"name": "江苏,苏州市,相城区,北桥"
			},
			"cur": {
				"number": "CN320200000000",
				"name": "江苏,无锡市"
			},
			"to": null
		},
		"isLoop": false
	}
}

5.5 运单签收状态服务说明

物流状态值 物流状态名称 高级物流状态值 高级物流状态名称 含义
1 揽收 1 揽收 快件揽件
101 已下单 已经下快件单
102 待揽收 待快递公司揽收
103 已揽收 快递公司已经揽收
0 在途 0 在途 快件在途中
1001 到达派件城市 快件到达收件人城市
1002 干线 快件处于运输过程中
1003 转递 快件发往到新的收件地址
5 派件 5 派件 快件正在派件
501 投柜或驿站 快件已经投递到快递柜或者快递驿站
3 签收 3 签收 快件已签收
301 本人签收 收件人正常签收
302 派件异常后签收 快件显示派件异常,但后续正常签收
303 代签 快件已被代签
304 投柜或驿站签收 快件已由快递柜或者驿站签收
6 退回 6 退回 快件正处于返回发货人的途中
4 退签 4 退签 此快件单已退签
401 已销单 此快件单已撤销
14 拒签 收件人拒签快件
7 转投 7 转投 快件转给其他快递公司邮寄
2 疑难 2 疑难 快件存在疑难
201 超时未签收 快件长时间派件后未签收
202 超时未更新 快件长时间没有派件或签收
203 拒收 收件人发起拒收快递,待发货方确认
204 派件异常 快件派件时遇到异常情况
205 柜或驿站超时未取 快件在快递柜或者驿站长时间未取
206 无法联系 无法联系到收件人
207 超区 超出快递公司的服务区范围
208 滞留 快件滞留在网点,没有派送
209 破损 快件破损
8 清关 8 清关 快件清关
10 待清关 快件等待清关
11 清关中 快件正在清关流程中
12 已清关 快件已完成清关流程
13 清关异常 货物在清关过程中出现异常
14 拒签 \ \ 收件人拒签快件

注:如需物流状态高级状态名称及状态值需要 resultv2 传 “4” 返回

5.6 推送响应报文及错误码解释

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

5.7 推送返回示例

当我方调用贵方的回调接口(pollCallBackUrl)时,贵方需要先将我方提交的数据保存至贵方的数据库,接着向我方返回是否成功接收的响应报文及代码,即贵公司直接在回调接口的地址的response中填写如下内容:

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

注意:对于status= abort(message中包含“3天查询无记录”或者“60天无变化”)的快递单,也需要返回成功接收的响应报文及代码。

六、快递公司编码

快递公司编码快递类型
京东物流jd官方
德邦快递debangkuaidi官方
顺丰速运shunfeng官方
中通快递zhongtong官方
顺丰快运shunfengkuaiyun官方
顺心捷达sxjdfreight官方