快递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：开通行政解析功能以及物流轨迹增加物流高级状态名称、状态值并且返回出发、目的及当前城市信息(详见：快递信息推送接口文档)
thirdOrderId	否	string	平台订单号，最大32位。若此参数与之前的重复，48小时内返回第一次下单内容，否则会重新下单。

1.3 返回结果

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

data数据结构

字段	类型	说明	备注
taskId	string	任务ID
orderId	string	订单ID
kuaidinum	string	快递单号	中通、顺心捷达返回null，需在下单回调接口状态10获取
pollToken	string	查询密钥	调用实时快递查询接口时入参此字段可免费查询该快递单号，一个快递单号对应一个密钥

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：'订单已取消'；101：'运输中'；200：'已出单'；201：'出单失败'；610：'下单失败'；155：'修改重量'(注意需要在工单系统中发起异常反馈并由快递100服务人员确认调重后才会有此状态回调，回调内容包含修改重量后的重量、运费、费用明细、业务类型)；166：订单复活（订单被取消，但是实际包裹已经发出，正常计费）；400：派送中
courierName	否	string	快递员姓名
courierMobile	否	string	快递员电话
weight	否	string	重量
freight	否	string	运费
pollToken	是	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已过期	账号无可用余额，需要充值

五、实时快递查询接口

下单后可携带pollToken请求该接口实时查询物流轨迹信息。

注意：请控制每一单查询频率至少在半小时以上，否则会造成锁单。

5.1 请求地址

https://poll.kuaidi100.com/poll/query.do

5.2 请求类型

post

5.3 输入参数

请求参数（header）

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

请求参数（body）

名称	类型	是否必需	示例值	描述
customer	String	是		授权码，请申请企业版获取
sign	String	是		签名，用于验证身份，按param + key + customer 的顺序进行MD5加密（注意加密后字符串一定要转32位大写），不需要加上“+”号
pollToken	string	否		查询密钥，仅通过C端寄件下单后调用实时快递查询时入参该字段可免扣费查询
Θparam	Object	是		由其他字段拼接
└ com	string	是	yuantong	查询的快递公司的编码
└ num	string	是	12345678	查询的快递单号，单号的最小长度6个字符，最大长度32个字符
└ phone	string	否	13888888888	收、寄件人的电话号码（手机和固定电话均可，只能填写一个，顺丰速运、顺丰快运必填，其他快递公司选填。如座机号码有分机号，分机号无需传入；如号码是电商虚拟号码需传入“-“后的后四位。查看详情）
└ from	string	否	广东深圳	出发地城市
└ to	string	否	北京朝阳	目的地城市，到达目的地后会加大监控频率
└ resultv2	string	否	1	添加此字段表示开通行政区域解析功能。空：关闭（默认），1：开通行政区域解析功能以及物流轨迹增加物流状态名称 4: 开通行政解析功能以及物流轨迹增加物流高级状态名称、状态值并且返回出发、目的及当前城市信息
└show	String	否	0	返回格式：0：json格式（默认），1：xml，2：html，3：text
└order	String	否	desc	返回结果排序:desc降序（默认）,asc 升序

5.4 请求参数示例

    customer = **********
    sign = ******************
    pollToken = ******************
    param = {
        "com": "ems",
        "num": "em263999513jp",
        "phone": "13868688888",
        "from": "广东省深圳市南山区",
        "to": "北京市朝阳区",
        "resultv2": "4",
        "show": "0",
        "order": "desc"
    }

5.5 返回结果

字段名称	类型	字段含义
message	String	消息体，请忽略
state	String	快递单当前状态，默认为0在途，1揽收，2疑难，3签收，4退签，5派件，8清关，14拒签等10个基础物流状态，如需要返回高级物流状态，请参考 resultv2 传值
status	String	通讯状态，请忽略
condition	String	快递单明细状态标记，暂未实现，请忽略
ischeck	String	是否签收标记，0未签收，1已签收，请忽略，明细状态请参考state字段
com	String	快递公司编码,一律用小写字母
nu	String	单号
Θdata	data	最新查询结果，数组，包含多项，全量，倒序（即时间最新的在最前），每项都是对象，对象包含字段请展开
└ context	String	内容
└ time	String	时间，原始格式
└ ftime	String	格式化后时间
└status	String	本数据元对应的物流状态名称或者高级状态名称，实时查询接口中提交resultv2=1或者resultv2=4标记后才会出现
└statusCode	String	本数据元对应的高级物流状态值，实时查询接口中提交resultv2=4标记后才会出现
└areaCode	String	本数据元对应的行政区域的编码，实时查询接口中提交resultv2=1或者resultv2=4标记后才会出现
└areaName	String	本数据元对应的行政区域的名称，实时查询接口中提交resultv2=1或者resultv2=4标记后才会出现
└areaCenter	String	本数据元对应的行政区域经纬度，实时查询接口中提交resultv2=4标记后才会出现
└location	String	本数据元对应的快件当前地点，实时查询接口中提交resultv2=4标记后才会出现
└areaPinYin	String	本数据元对应的行政区域拼音，实时查询接口中提交resultv2=4标记后才会出现

5.6 运单快递状态（state)说明

物流状态值	物流状态名称	高级物流状态值	高级物流状态名称	含义

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	破损	快件破损
		210	销单	寄件人申请撤销寄件
8	清关	8	清关	快件清关
		10	待清关	快件等待清关
		11	清关中	快件正在清关流程中
		12	已清关	快件已完成清关流程
		13	清关异常	货物在清关过程中出现异常
14	拒签	\	\	收件人拒签快件

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

5.7 正确返回示例

JSON格式

{
    "message": "ok",
    "nu": "JT0004301991791",
    "ischeck": "0",
    "com": "jtexpress",
    "status": "200",
    "data": [
        {
            "time": "2021-12-15 17:19:28",
            "context": "【杭州市】您的包裹已存放至【驿站】，记得早点来取它回家！",
            "ftime": "2021-12-15 17:19:28",
            "areaCode": "CN330102000000",//本数据元对应的行政区域编码，resultv2=1或者resultv2=4才会展示
            "areaName": "浙江,杭州市,上城区",//本数据元对应的行政区域名称，resultv2=1或者resultv2=4才会展示
            "status": "投柜或驿站",//本数据元对应的物流状态名称或者高级物流状态名称，resultv2=1或者resultv2=4才会展示
            "location": "浙江省 杭州市 上城区", //本数据元对应的快件当前地点，resultv2=4才会展示
            "areaCenter": "120.184349,30.25446", //本数据元对应的行政区域经纬度，resultv2=4才会展示
            "areaPinYin": "shang cheng qu",//本数据元对应的行政区域拼音，resultv2=4才会展示
            "statusCode": "501"//本数据元对应的高级物流状态值，resultv2=4才会展示
        },
        {
            "time": "2021-12-15 14:17:31",
            "context": "【杭州市】【杭州网点】的极兔小哥正在派件",
            "ftime": "2021-12-15 14:17:31",
            "areaCode": "CN330102000000",
            "areaName": "浙江,杭州市,上城区",
            "status": "派件",
            "location": "浙江省 杭州市 上城区",
            "areaCenter": "120.184349,30.25446",
            "areaPinYin": "shang cheng qu",
            "statusCode": "5"
        },
        {
            "time": "2021-12-15 13:58:18",
            "context": "【杭州市】 快件到达【杭州网点】",
            "ftime": "2021-12-15 13:58:18",
            "areaCode": "CN330102000000",
            "areaName": "浙江,杭州市,上城区",
            "status": "在途",
            "location": "浙江省 杭州市 上城区",
            "areaCenter": "120.184349,30.25446",
            "areaPinYin": "shang cheng qu",
            "statusCode": "0"
        },
        {
            "time": "2021-12-15 04:11:20",
            "context": "【杭州市】快件离开【杭州转运中心】已发往【杭州江干四季青网点】",
            "ftime": "2021-12-15 04:11:20",
            "areaCode": "CN330109000000",
            "areaName": "浙江,杭州市,萧山区",
            "status": "干线",
            "location": "浙江省 杭州市 萧山区",
            "areaCenter": "120.493286,30.28333",
            "areaPinYin": "xiao shan qu",
            "statusCode": "1002"
        },
        {
            "time": "2021-12-15 02:09:52",
            "context": "【杭州市】 快件到达【杭州转运中心】",
            "ftime": "2021-12-15 02:09:52",
            "areaCode": "CN330109000000",
            "areaName": "浙江,杭州市,萧山区",
            "status": "干线",
            "location": "浙江省 杭州市 萧山区",
            "areaCenter": "120.493286,30.28333",
            "areaPinYin": "xiao shan qu",
            "statusCode": "1002"
        },
        {
            "time": "2021-12-14 21:08:34",
            "context": "【上海市】快件离开【上海浦西转运中心】已发往【杭州转运中心】",
            "ftime": "2021-12-14 21:08:34",
            "areaCode": "CN310118000000",
            "areaName": "上海,上海,青浦区",
            "status": "干线",
            "location": "上海 上海市 青浦区",
            "areaCenter": "121.124178,31.150681",
            "areaPinYin": "qing pu qu",
            "statusCode": "1002"
        },
        {
            "time": "2021-12-14 20:54:22",
            "context": "【上海市】 快件到达【上海浦西转运中心】",
            "ftime": "2021-12-14 20:54:22",
            "areaCode": "CN310118000000",
            "areaName": "上海,上海,青浦区",
            "status": "干线",
            "location": "上海 上海市 青浦区",
            "areaCenter": "121.124178,31.150681",
            "areaPinYin": "qing pu qu",
            "statusCode": "1002"
        },
        {
            "time": "2021-12-14 17:25:58",
            "context": "【上海市】快件离开【上海杨浦黄兴路网点】已发往【上海浦西转运中心】",
            "ftime": "2021-12-14 17:25:58",
            "areaCode": "CN310110000000",
            "areaName": "上海,上海,杨浦区",
            "status": "干线",
            "location": "上海 上海市 杨浦区",
            "areaCenter": "121.526077,31.259541",
            "areaPinYin": "yang pu qu",
            "statusCode": "1002"
        },
        {
            "time": "2021-12-14 09:03:58",
            "context": "【上海市】【上海杨浦黄兴路网点】已取件。",
            "ftime": "2021-12-14 09:03:58",
            "areaCode": "CN310110000000",
            "areaName": "上海,上海,杨浦区",
            "status": "揽收",
            "location": "上海 上海市 杨浦区",
            "areaCenter": "121.526077,31.259541",
            "areaPinYin": "yang pu qu",
            "statusCode": "1"
        }  
    ],
    "state": "5",
    "condition": "00",
    "routeInfo": {
        "from": {
            "number": "CN310110000000",
            "name": "上海,上海,杨浦区"
        },//本数据元对应的出发地城市信息，resultv2=4才会展示
        "cur": {
            "number": "CN330102000000",
            "name": "浙江,杭州市,上城区"
        },//本数据元对应的当前城市信息，resultv2=4才会展示
        "to": null
    },//本数据元对应的目的地城市信息，resultv2=4才会展示
    "isLoop": false
}
}

5.8 错误返回示例

JSON格式

{
    "result": false,
    "returnCode": "400",
    "message": "找不到对应公司"
}

5.9 信息代码含义

信息代码	信息内容描述	原因及建议处理方式
200	查询成功	查询成功
400	找不到对应公司	提交数据不完整或者账号未充值, 检查提交的格式是否为x-www-form-urlencoded的post格式
408	快递公司参数异常：验证码错误	电话号码校验不通过，检查是否提交了收、寄件人正确的电话号码
500	查询无结果，请隔段时间再查	表示查询失败，或没有POST提交，或polltoken不正确
501	服务器错误	快递100的服务器出现间歇或临时性异常，有时如果因为不按规范提交请求，比如快递公司参数没有按照文档规定填写等，也会报此错误
502	服务器繁忙	快递100的服务器出现间歇或临时性异常，请联系快递100排查原因
503	验证签名失败	请检查加密方式，param + key + customer 的顺序进行MD5加密，加密后字符串转大写
601	key已过期	没有可用单量，账号需要充值使用

六、快递信息推送接口

6.1 推送请求地址

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

6.2 推送请求类型

post

6.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标记后才会出现

6.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
	}
}

6.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” 返回

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

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

6.7 推送返回示例

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

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

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

七、快递公司编码

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

八、C端寄件详情查询接口文档

查询通过C端寄件下单接口下单的订单详情信息。

8.1 接口格式

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

8.2 请求地址

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

8.3 请求参数

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

param数据结构：

参数名	是否必填	类型	说明
taskId	是	string	下单时返回的任务ID

8.4 返回结果

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

data数据结构

字段	类型	说明
taskId	string	任务ID
createTime	date	下单时间
orderId	string	订单ID
kuaidiCom	string	快递公司
kuaidiNum	string	快递单号
sendName	string	寄件人姓名
sendMobile	string	寄件人联系方式
sendProvince	string	寄件人省份
sendCity	string	寄件人城市
sendDistrict	string	寄件人区
sendAddr	string	寄件人详细地址
recName	string	收件人姓名
recMobile	string	收件人联系方式
recProvince	string	收件人省份
recCity	string	收件人城市
recDistrict	string	收件人区
recAddr	string	收件人详细地址
cargo	string	物品名称
serviceType	string	业务类型
preWeight	string	用户端输入重量，单位：kg
lastWeight	string	快递公司返回最终重量，单位：kg
comment	string	备注内容
dayType	string	预约日期
pickupStartTime	string	预约时间
pickupEndTime	string	预约截止时间
payment	string	支付方式，SHIPPER: 寄付，CONSIGNEE: 到付
defPrice	Int	标准运费，单位：元
courierName	string	快递员姓名
courierMobile	string	快递员联系方式
status	Integer	订单状态： 0：'下单成功'； 1：'已接单'； 2：'收件中'； 9：'用户主动取消'； 10；'已取件'； 11；'揽货失败'； 12；'已退回'； 13；'已签收'； 14；'异常签收'； 99；'订单已取消'101；'运输中'；200：'已出单'201：'出单失败'；610：'下单失败'；155：'修改重量'(注意需要在工单系统中发起异常反馈并由快递100服务人员确认调重后才会有此状态回调，回调内容包含修改重量后的重量、运费、费用明细、业务类型)；166：订单复活（订单被取消，但是实际包裹已经发出，正常计费）；400：派送中

8.5 返回参数示例

成功示例

{
    "data": {
        "cancelMsg9": null,
        "cancelMsg99": null,
        "cargo": "雪允吉赛尔海粼“走转转平台交易，喜欢的话就点！询问购买，私信",
        "comment": null,
        "courierMobile": null,
        "courierName": null,
        "createTime": "2024-07-23 19:16:12",
        "dayType": "明天",
        "defPrice": null,
        "feeDetails": null,
        "freight": null,
        "kuaidiCom": "zhongtong",
        "kuaidiNum": null,
        "lastWeight": null,
        "orderId": "182077473",
        "payStatus": 0,
        "payment": "SHIPPER",
        "pickupEndTime": "11:00",
        "pickupStartTime": "09:00",
        "preWeight": "1.0",
        "recAddr": "高新区棘洪滩街道丰年路领秀珊瑚湾尚院27栋203",
        "recCity": "青岛市",
        "recDistrict": "城阳区",
        "recMobile": "15806565873",
        "recName": "任安琪",
        "recProvince": "山东",
        "sendAddr": "西影路东段阳光小区沁园12号楼",
        "sendCity": "西安市",
        "sendDistrict": "雁塔区",
        "sendMobile": "13152419166",
        "sendName": "sunrise",
        "sendProvince": "陕西",
        "serviceType": "标准快递",
        "status": 0,
        "taskId": "84BE1087B701C7E9EC660D939FEF153B",
        "valins": null
    },
    "message": "成功",
    "result": true,
    "returnCode": "200"
}

失败示例


{"data":null,"message":"KEY已过期","result":false,"returnCode":"601"}

说明：

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

一、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 运单快递状态（state)说明

5.7 正确返回示例

5.8 错误返回示例

5.9 信息代码含义

六、快递信息推送接口

6.1 推送请求地址

6.2 推送请求类型

6.3 推送输入参数

6.4 推送输入参数示例

6.5 运单签收状态服务说明

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

6.7 推送返回示例

七、快递公司编码

8.1 接口格式

8.2 请求地址

8.3 请求参数

8.4 返回结果

8.5 返回参数示例

扫码添加工作人员

扫码进入企业助手