快递100C端寄件接口文档

一、C端寄件下单接口

选择快递公司进行下单。

1.1 接口格式

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

1.2 请求地址

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

请求参数：

参数名	是否必填	类型	说明
method	是	string	业务类型（默认：cOrder）
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	物品名称,例：文件
payment	否	string	支付方式，SHIPPER: 寄方付（默认），CONSIGNEE: 到付
weight	否	string	物品总重量KG，不需带单位，例：1.5
remark	否	string	备注
dayType	否	string	预约日期，例如：今天/明天/后天
pickupStartTime	否	string	预约起始时间，24小时制（HH:mm），例如：09:00
pickupEndTime	否	string	预约截止时间，24小时制（HH:mm），例如：10:00
salt	否	string	签名用随机字符串
op	否	string	是否开启订阅功能 0：不开启(默认) 1：开启说明开启订阅功能时：pollCallBackUrl必须填入此功能只针对有快递单号的单
pollCallBackUrl	否	string	如果op设置为1时，pollCallBackUrl必须填入，用于跟踪回调。此为免费服务，回调内容通过五、快递信息推送接口返回（免费服务）
resultv2	否	string	添加此字段表示开通行政区域解析功能。 0：关闭（默认） 1：开通行政区域解析功能以及物流轨迹增加物流状态名称 4：开通行政解析功能以及物流轨迹增加物流高级状态名称、状态值并且返回出发、目的及当前城市信息(详见：快递信息推送接口文档)

1.3 返回结果

字段	类型	说明	备注
result	boolean	提交结果	true提交成功，false失败
returnCode	string	返回编码
message	string	返回报文描述
data	data

data数据结构

字段	类型	说明	备注
taskId	string	任务ID
orderId	string	订单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是否填写正确或账号无可用单量，需要充值
601	KEY已过期	账号无可用单量，需要充值
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>

请求参数：

字段	类型	说明	备注
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	是	int	订单状态，0：'下单成功'；1：'已接单'；2：'收件中'；9：'用户主动取消'；10：'已取件'；101：'运输中'；11：'揽货失败'；12：'已退回'；13：'已签收'；14：'异常签收'；99：'订单已取消'
courierName	否	string	快递员姓名
courierMobile	否	string	快递员电话
weight	否	string	重量
freight	否	string	运费

2.3 返回结果

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

2.4 返回结果示例

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

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

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

其他信息快递100会忽略。

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

对下完的单进行取消操作

3.1 接口格式

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

3.2 请求地址

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

请求参数：

参数名	是否必填	类型	说明
method	是	string	业务类型（默认：cancel）
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	取消原因，例：暂时不寄件了，最大长度不超过30字符

3.3 返回结果

字段	类型	说明	备注
result	boolean	提交结果	true提交成功，false失败
returnCode	string	返回编码
message	string	返回报文描述
data	data		这里默认为空

3.4 返回结果示例

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

3.5 信息代码含义

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

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

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

4.1 接口格式

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

4.2 请求地址

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

请求参数：

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

param数据结构：

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

4.3 返回结果

字段	类型	说明	备注
result	boolean	提交结果	true提交成功，false失败
returnCode	string	返回编码
message	string	返回报文描述
data	data	运力对象

data数据结构：

参数名	类型	说明
price	string	运费，单位：元

4.4 提供数据内容

返回结果示例

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

说明：

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

五、快递信息推送接口

5.1 推送请求地址

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

5.2 推送请求类型

post

5.3 推送输入参数

请求参数（header）

名称	类型	默认值
Content-Type	string	application/x-www-form-urlencoded

请求参数（body）

名称	类型	示例值	描述
sign	String		订阅参数salt值不为null时，推送数据将包含该加密签名，加密方式：md5(param+salt)。注意： salt值为空串时，推送的数据也会包含sign。
Θparam			由其他字段拼接
└ status	String	polling	监控状态:polling:监控中，shutdown:结束，abort:中止，updateall：重新推送。其中当快递单为已签收时status=shutdown，当message为“3天查询无记录”或“60天无变化时”status= abort ，对于status=abort的状态，需要增加额外的处理逻辑
└ billstatus	String	got	包括got、sending、check三个状态，由于意义不大，已弃用，请忽略
└ message	String		监控状态相关消息，如:3天查询无记录，60天无变化
└ autoCheck	String	1	快递公司编码是否出错，0为本推送信息对应的是贵司提交的原始快递公司编码，1为本推送信息对应的是我方纠正后的新的快递公司编码。一个单如果我们连续3天都查不到结果，我方会（1）判断一次贵司提交的快递公司编码是否正确，如果正确，给贵司的回调接口（callbackurl）推送带有如下字段的信息：autoCheck=0、comOld与comNew都为空；（2）如果贵司提交的快递公司编码出错，我们会帮忙用正确的快递公司编码+原来的运单号重新提交订阅并开启监控（后续如果监控到单号有更新就给贵司的回调接口（callbackurl）推送带有如下字段的信息：autoCheck=1、comOld=原来的公司编码、comNew=新的公司编码）；并且给贵方的回调接口（callbackurl）推送一条含有如下字段的信息：status=abort、autoCheck=0、comOld为空、comNew=纠正后的快递公司编码。
└ comOld	String	yuantong	贵司提交的原始的快递公司编码。详细见autoCheck后说明。若开启了国际版（即在订阅请求中增加字段interCom=1），则回调请求中暂无此字段
└ comNew	String	ems	我司纠正后的新的快递公司编码。详细见autoCheck后说明。若开启了国际版（即在订阅请求中增加字段interCom=1），则回调请求中暂无此字段
ΘlastResult	lastResult		最新查询结果，若在订阅报文中通过interCom字段开通了国际版，则此lastResult表示出发国的查询结果，全量，倒序（即时间最新的在最前）
└- message	String		消息体，请忽略
└- state	String	0	快递单当前状态，默认为0在途，1揽收，2疑难，3签收，4退签，5派件，8清关，14拒签等10个基础物流状态，如需要返回高级物流状态，请参考 resultv2 传值
└- status	String	200	通讯状态，请忽略
└- condition	String	F00	快递单明细状态标记，暂未实现，请忽略
└- ischeck	String	0	是否签收标记，0未签收，1已签收
└- com	String	yuantong	快递公司编码,一律用小写字母
└- nu	String	V030344422	单号
└- data	Object		数组，包含多个对象，每个对象字段如展开所示
└-- context	String	上海分拨中心/装件入车扫描	内容
└-- time	String	2012-08-28 16:33:19	时间，原始格式
└-- ftime	String	2012-08-28 16:33:19	格式化后时间
└-- status	String	在途	物流状态名称或者高级状态名称，提交resultv2=1或者resultv2=4标记后才会出现
└-- statusCode	String	1002	本数据元对应的高级物流状态值，提交resultv2=4标记后才会出现
└-- areaCode	String	310000000000	本数据元对应的行政区域的编码，提交resultv2=1或者resultv2=4标记后才会出现
└-- areaName	String	上海市	本数据元对应的行政区域的名称，提交resultv2=1或者resultv2=4标记后才会出现
└--areaCenter	String	17.200983,39.084158	本数据元对应的行政区域经纬度，提交resultv2=4标记后才会出现
└--location	String	深圳中心	本数据元对应的快件当前位置，提交resultv2=4标记后才会出现
└--areaPinYin	String	tianjin	本数据元对应的行政区域拼音，提交resultv2=4标记后才会出现
Θ destResult	destResult		表示最新的目的国家的查询结果，只有在订阅报文中通过interCom=1字段开通了国际版才会显示此数据元，全量，倒序（即时间最新的在最前）
└- message	String		消息体，请忽略
└- state	String	0	快递单当前状态，默认为0在途，1揽收，2疑难，3签收，4退签，5派件，8清关，14拒签等10个基础物流状态，如需要返回高级物流状态，请参考 resultv2 传值
└- status	String	200	通讯状态，请忽略
└- condition	String	F00	快递单明细状态标记，暂未实现，请忽略
└- ischeck	String	0	是否签收标记，0未签收，1已签收
└- com	String	yuantong	快递公司编码,一律用小写字母
└- nu	String	V030344422	单号
Θ data	data		数组，包含多个对象，每个对象字段如展开所示
└-- context	String	上海分拨中心/装件入车扫描	内容
└-- time	String	2012-08-28 16:33:19	时间，原始格式
└-- ftime	String	2012-08-28 16:33:19	格式化后时间
└-- status	String	在途	本数据元对应的物流状态名称或者高级状态名称，提交resultv2=1或者resultv2=4标记后才会出现
└-- areaCode	String	310000000000	本数据元对应的行政区域的编码，提交resultv2=1或者resultv2=4标记后才会出现
└-- areaName	String	上海市	本数据元对应的行政区域的名称，提交resultv2=1或者resultv2=4标记后才会出现
└--areaCenter	String	17.200983,39.084158	本数据元对应的行政区域经纬度，提交resultv2=4标记后才会出现
└--location	String	深圳中心	本数据元对应的快件当前位置，提交resultv2=4标记后才会出现
└--areaPinYin	String	tianjin	本数据元对应的行政区域拼音，提交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	派件	快件正在派件
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 推送响应报文及错误码解释

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

5.7 推送返回示例

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

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

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

六、快递公司编码

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

一、C端寄件下单接口

1.1 接口格式

1.2 请求地址

1.3 返回结果

1.4 返回结果示例

1.5 信息代码含义

二、下单回调接口

2.1 接口格式

2.2 请求地址

2.3 返回结果

2.4 返回结果示例

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

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

3.1 接口格式

3.2 请求地址

3.3 返回结果

3.4 返回结果示例

3.5 信息代码含义

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

4.1 接口格式

4.2 请求地址

4.3 返回结果

4.4 提供数据内容

五、快递信息推送接口

5.1 推送请求地址

5.2 推送请求类型

5.3 推送输入参数

5.4 推送输入参数示例

5.5 运单签收状态服务说明

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

5.7 推送返回示例

六、快递公司编码

扫码添加工作人员

扫码进入企业助手