文档中心
一、同城配送预下单接口 二、同城配送下单接口 三、同城配送预取消接口 四、同城配送取消接口 五、同城配送加小费接口 六、同城配送订单状态回调接口

同城配送接口文档

一、同城配送预下单接口

该接口并非真正发单,是用来验证是否可以发单并在成功时返回时效、计价等信息,也可用来验证地址以及时间是否在快递公司的配送范围内。

1.1 接口格式

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

1.2 请求地址

https://api.kuaidi100.com/bsamecity/order

请求参数:

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

param数据结构:

参数名是否必填类型说明
kuaidicomstring快递公司的编码,一律用小写字母,见参数字典
lbsTypeInt坐标类型(1:百度坐标,2:高德坐标 ,默认2)
recManNamestring收件人姓名,长度最大20
recManMobilestring收件人的手机号(有手机号和固话正则校验)
recManProvincestring收件人所在的省,长度最大20
recManCitystring收件人所在的市,长度最大20
recManDistrictstring收件人所在的区,长度最大20
recManAddrstring收件人所在完整地址,如广东深圳市深圳市南山区科技南十二路2号金蝶软件园,长度最大100
recManLatstring收件人地址纬度,默认高德坐标,长度最大10
recManLngstring收件人地址经度,默认高德坐标,长度最大10
sendManNamestring寄件人姓名,长度最大20
sendManMobilestring寄件人的手机号(有手机号和固话正则校验)
sendManProvincestring寄件人所在的省,长度最大20
sendManCitystring寄件人所在的市,长度最大20
sendManDistrictstring寄件人所在的区,长度最大20
sendManAddrstring寄件人所在完整地址,如广东深圳市深圳市南山区科技南十二路2号金蝶软件园,长度最大100
sendManLatstring寄件人地址纬度,默认高德坐标,长度最大10
sendManLngstring寄件人地址经度,默认高德坐标,长度最大10
weightstring物品总重量,例:1.5,单位kg
remarkstring备注,例:测试寄件,长度最大255
orderTypeInt0:无需预约; 1:预约单送达时间; 2:预约单上门时间。 默认为0
expectPickupTimestring期望取货时间,orderType=2时必填,例:2020-02-02 22:00
expectFinishTimestring期望送达时间,orderType=1时必填,例:2020-02-02 22:00
insurancestring保价物品金额
pricestring物品总金额,例:100.23,单位:元
directDeliveryInt是否为专人直送订单,0:否,1:是
goodsList商品详情

goods数据结构:

参数名是否必填类型说明
nameString商品名称
typeInt物品类型,详见参数字典:三、物品类型对照表
countInt商品数量

1.3 返回结果

字段类型说明备注
successboolean提交结果true提交成功,false失败
codeInt返回编码200为成功
messagestring返回报文描述
dataObject

data数据结构

字段类型说明备注
taskIdstring任务ID32位随机字符串,用于记录订单整个生命周期
deliveryDistancestring配送距离单位:米
deliverFeestring配送费(原价)单位:元
discountFeestring配送费(折扣价)单位:元
estimateDeliveryTimestring预计配送时间单位:秒
otherFeeList其他费用明细详见参数字典:二、费用类型对照表

FeeDetail参数

字段说明备注
feeType费用类型详见参数字典:二、费用类型对照表
amount费用明细金额单位:元

1.4 提供数据内容

请求参数示例

method = order
key = *******
sign = 4 BBDE07660E5EFF90873642CFAE9A8DD
t = 1470304729724
param = {
	"recManAddr": "学清嘉创大厦A座15层",
	"insurance": "1000",
	"orderType": 1,
	"sendManProvince": "北京市",
	"sendManAddr": "北京航空航天大学",
	"recManCity": "北京市",
	"goods": [{
		"name": "狗粮",
		"count": 1,
		"type": "食品"
	}],
	"remark": "备注信息,过来的时候打电话",
	"sendManLng": "116.347304",
	"lbsType": 2,
	"sendManLat": "39.981804",
	"sendManName": "马大萌",
	"expectFinishTime": "2023-03-09 15:10:00",
	"recManLng": "116.352637",
	"recManName": "顺丰同城",
	"kuaidicom": "shunfengtongcheng",
	"recManProvince": "北京市",
	"price": "1500",
	"recManDistrict": "海淀区",

	"recManLat": "40.014846",
	"sendManMobile": "13203559287",
	"salt": "12312313",
	"expectPickupTime": "2023-03-09 19:50:00",
	"weight": "1.5",
	"recManMobile": "13881979410",
	"volume": "0.03",
	"directDelivery": 1,
	"sendManCity": "北京市",
	"sendManDistrict": "海淀区"
}

返回结果示例

{
	"code": 200,
	"data": {
		"orderId": "100025",
		"deliveryDistance": "4702",
		"deliverFee": "0.10",
		"estimateDeliveryTime": "2400",
		"otherFee": [],
		"taskId": “1221221122121”,
	},
	"message": "success",
	"time": 0,
	"success": true
} 

1.5 信息代码含义

信息代码信息内容描述原因及建议处理方式
200成功成功
-1服务器错误快递100的服务器出现间歇或临时性异常,有时如果因为不按规范提交请求,比如快递公司参数写错等,也会报此错误
30001参数错误请根据技术文档请求,注意参数类型及是否必填
30002验证签名失败检查加密方式,param +t+key+ secret的顺序进行MD5加密,加密后字符串转32位大写,不用加上“+”号
30003账号信息不正确检查key是否正确
30004账号余额不足余额不足需要充值
30005快递公司返回异常按照描述可以自行检查是否参数缺失或者错误
30006参数转换异常按照描述可以自行检查参数的数据类型是否正确

二、同城配送下单接口

真实下发订单到快递公司,下单会产生费用扣减。

2.1 接口格式

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

###2.2 请求地址

https://api.kuaidi100.com/bsamecity/order

请求参数:

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

param数据结构:

参数名是否必填类型说明
kuaidicomstring快递公司的编码,一律用小写字母,见参数字典
lbsTypeInt坐标类型(1:百度坐标,2:高德坐标 ,默认2)
recManNamestring收件人姓名,长度最大20
recManMobilestring收件人的手机号(有手机号和固话正则校验)
recManProvincestring收件人所在的省,长度最大20
recManCitystring收件人所在的市,长度最大20
recManDistrictstring收件人所在的区,长度最大20
recManAddrstring收件人所在完整地址,如广东深圳市深圳市南山区科技南十二路2号金蝶软件园,长度最大100
recManLatstring收件人地址纬度,默认高德坐标,长度最大10
recManLngstring收件人地址经度,默认高德坐标,长度最大10
recManAddrstring寄件人姓名
sendManNamestring寄件人姓名,长度最大20
sendManMobilestring寄件人的手机号(有手机号和固话正则校验)
sendManProvincestring寄件人所在的省,长度最大20
sendManCitystring寄件人所在的市,长度最大20
sendManDistrictstring寄件人所在的区,长度最大20
sendManAddrstring寄件人所在完整地址,如广东深圳市深圳市南山区科技南十二路2号金蝶软件园,长度最大100
sendManLatstring寄件人地址纬度,默认高德坐标,长度最大10
sendManLngstring寄件人地址经度,默认高德坐标,长度最大10
weightstring物品总重量,例:1.5,单位kg
remarkstring备注,例:测试寄件,长度最大255
volumestring体积,单位:cm3,长度最大20
saltstring签名用随机字符串,长度最多20
callbackUrlstringcallBackUrl订单信息回调,长度最大50
orderTypeInt0:无需预约; 1:预约单送达时间; 2:预约单上门时间。 默认为0
expectPickupTimestring期望取货时间,orderType=2时必填,例:2020-02-02 22:00
expectFinishTimestring期望送达时间,orderType=1时必填,例:2020-02-02 22:00
insurancestring保价物品金额
pricestring物品总金额,例:100.23,单位:元
directDeliveryInt是否为专人直送订单,0:否,1:是
goodsList商品详情

goods数据结构:

参数名是否必填类型说明
nameString商品名称
typeInt物品类型,详见参数字典:三、物品类型对照表
countInt商品数量

2.3 返回结果

字段类型说明备注
successboolean提交结果true提交成功,false失败
codeInt返回编码200为成功
messagestring返回报文描述
dataObject

data数据结构

字段类型说明备注
taskIdstring任务ID32位随机字符串,用于记录订单整个生命周期
orderIdstring同城寄件订单号快递100订单号
kuaidinumstring快递单号
deliveryDistancestring配送距离单位:米
deliverFeestring配送费(原价)单位:元
discountFeestring配送费(折扣价)单位:元
estimateDeliveryTimestring预计配送时间单位:秒
otherFeeList其他费用明细详见参数字典:二、费用类型对照表

FeeDetail参数

字段说明备注
feeType费用类型详见参数字典:二、费用类型对照表
amount费用明细金额单位:元

2.4 提供数据内容

请求参数示例

method = order
key =******
sign =******
t = 1470304729724
param = {
	"kuaidicom": "shunfengtongcheng",
	"lbsType": 2,
	"recManName": "顺丰同城",
	"recManMobile": "13811112222",
	"recManProvince": "北京市",
	"recManCity": "北京市",
	"recManDistrict": "海淀区",
	"recManAddr": "学清嘉创",
	"recManLat": "40.123456",
	"recManLng": "116.123456",
	"sendManName": "李测试",
	"sendManMobile": "13211112222",
	"sendManProvince": "北京",
	"sendManCity": "北京市",
	"sendManDistrict": "海淀区",
	"sendManAddr": "清华大学",
	"sendManLat": "40.001234",
	"sendManLng": "116.234567",
	"weight": "1",
	"remark": "测试下单",
	"volume": "",
	"salt": "",
	"callbackUrl": "http://www.kuaidi100.cm",
	"orderType": 0,
	"expectPickupTime": "",
	"expectFinishTime": "",
	"insurance": "",
	"price": "0",
	"goods": [{
		"name": "外卖",
		"type": "食品",
		"count": 0,
	}],
	"directDelivery": 0
}

返回结果示例

{
	"code": 200,
	"data": {
		"orderId": "100025",
		"deliveryDistance": "4702",
		"deliverFee": "0.10",
		"estimateDeliveryTime": "2400",
		"otherFee": [],
		"taskId": “1221221122121”,
	},
	"message": "success",
	"time": 0,
	"success": true
}

2.5 信息代码含义

信息代码信息内容描述原因及建议处理方式
200成功成功
-1服务器错误快递100的服务器出现间歇或临时性异常,有时如果因为不按规范提交请求,比如快递公司参数写错等,也会报此错误
30001参数错误请根据技术文档请求,注意参数类型及是否必填
30002验证签名失败检查加密方式,param +t+key+ secret的顺序进行MD5加密,加密后字符串转32位大写,不用加上“+”号
30003账号信息不正确检查key是否正确
30004账号余额不足余额不足需要充值
30005快递公司返回异常按照描述可以自行检查是否参数缺失或者错误
30006参数转换异常按照描述可以自行检查参数的数据类型是否正确

三、同城配送预取消接口

该接口并非真正取消订单,用来验证是否可以取消订单并返回计价等信息。

3.1 接口格式

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

3.2 请求地址

https://api.kuaidi100.com/bsamecity/order

请求参数:

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

param数据结构:

参数名是否必填类型说明
taskIdstring下单时返回的taskId
orderIdstring订单ID
cancelMsgTypeInt取消原因编码,详见参数字典:四、取消原因类型对照表
cancelMsgstring取消原因

3.3 返回结果

字段类型说明备注
successboolean提交结果true提交成功,false失败
codeInt返回编码200为成功
messagestring返回报文描述
dataObject

data数据结构

字段类型说明备注
cancelFeestring取消费用

3.4 提供数据内容

请求参数示例

method = precancel
key = *****
sign = 4BBDE07660E5EFF90873642CFAE9A8DD
t = 1470304729724
param = {
	"orderId": "100094",
	"cancelMsgType": 1,
	"cancelMsg": "测试寄件",
	"taskId": "3B8E825DCCEE4F28B4A93685DA62F7F2"
}

返回结果示例

{
	"code": 200,
	"message": "success",
	"time": 0,
	"data": {
		"cancelFee": "2"
	}
	"success": true
}

3.5 信息代码含义

信息代码信息内容描述原因及建议处理方式
200成功成功
-1服务器错误快递100的服务器出现间歇或临时性异常,有时如果因为不按规范提交请求,比如快递公司参数写错等,也会报此错误
30001参数错误请根据技术文档请求,注意参数类型及是否必填
30002验证签名失败检查加密方式,param +t+key+ secret的顺序进行MD5加密,加密后字符串转32位大写,不用加上“+”号
30003账号信息不正确检查key是否正确
30004账号余额不足余额不足需要充值
30005快递公司返回异常例:订单已取消,照描述可以自行检查参数的数据类型是否正确
30006参数转换异常按照描述可以自行检查参数的数据类型是否正确

四、同城配送取消接口

当商家处发生异常需要取消配送时,可调用此接口对订单进行取消操作,同步返回结果。(注意可能产生费用)

4.1 接口格式

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

4.2 请求地址

https://api.kuaidi100.com/bsamecity/order

请求参数:

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

param数据结构:

参数名是否必填类型说明
taskIdstring下单时返回的taskId
orderIdstring订单ID
cancelMsgTypeInt取消原因类型,详见参数字典:四、取消原因类型对照表
cancelMsgstring取消原因

4.3 返回结果

字段类型说明备注
successboolean提交结果true提交成功,false失败
codeInt返回编码200为成功
messagestring返回报文描述
dataObject

data数据结构

字段类型说明备注
cancelFeestring取消费用

4.4 提供数据内容

请求参数示例

method = precancel
key = *****
sign = 4BBDE07660E5EFF90873642CFAE9A8DD
t = 1470304729724
param = {
	"orderId": "100094",
	"cancelMsgType": 1,
	"cancelMsg": "测试寄件",
	"taskId": "3B8E825DCCEE4F28B4A93685DA62F7F2"
}

返回结果示例

{
	"code": 200,
	"message": "success",
	"time": 0,
	"data": {
		"cancelFee": "2"
	}
	"success": true
}

4.5 信息代码含义

信息代码信息内容描述原因及建议处理方式
200成功成功
-1服务器错误快递100的服务器出现间歇或临时性异常,有时如果因为不按规范提交请求,比如快递公司参数写错等,也会报此错误
30001参数错误请根据技术文档请求,注意参数类型及是否必填
30002验证签名失败检查加密方式,param +t+key+ secret的顺序进行MD5加密,加密后字符串转32位大写,不用加上“+”号
30003账号信息不正确检查key是否正确
30004账号余额不足余额不足需要充值
30005快递公司返回异常例:订单已取消,照描述可以自行检查参数的数据类型是否正确
30006参数转换异常按照描述可以自行检查参数的数据类型是否正确

五、同城配送加小费接口

订单创建后,在骑手未接单的情况下通过该接口对订单进行加小费,促进订单接单,截止订单完成前,都可以对订单加小费。

5.1 接口格式

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

5.2 请求地址

https://api.kuaidi100.com/bsamecity/order

请求参数:

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

param数据结构:

参数名是否必填类型说明
taskIdstring下单时返回的taskId
orderIdstring订单ID
tipsstring小费金额,单位:元
remarkstring备注

5.3 返回结果

字段类型说明备注
successboolean提交结果true提交成功,false失败
codeInt返回编码200为成功
messagestring返回报文描述
datastring相应的数据

5.4 提供数据内容

请求参数示例

method = addfee
key = ******
sign = 4 BBDE07660E5EFF90873642CFAE9A8DD
t = 1470304729724
param = {
	"orderId": "100092",
	"remark": "",
	"taskId": "24A38808091C45719167B612738FA559",
	"tips": "10"
}

返回结果示例

{
	"code": 200,
	"message": "success",
	"time": 0,
	"success": true
}

5.5 信息代码含义

信息代码信息内容描述原因及建议处理方式
200成功成功
-1服务器错误快递100的服务器出现间歇或临时性异常,有时如果因为不按规范提交请求,比如快递公司参数写错等,也会报此错误
30001参数错误请根据技术文档请求,注意参数类型及是否必填
30002验证签名失败检查加密方式,param +t+key+ secret的顺序进行MD5加密,加密后字符串转32位大写,不用加上“+”号
30003账号信息不正确检查key是否正确
30005快递公司返回异常例:订单已取消,照描述可以自行检查参数的数据类型是否正确

六、同城配送订单状态回调接口

当订单状态发生变更时,将会通过下单时传入的callbackUrl回推信息。回调后如果没有得到合作方正确返回,会重复回调多2次,即最多回调3次,间隔1分钟。

6.1 接口格式

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

6.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数据结构:

参数名类型说明
orderIdstring订单ID (对应下单时返回的orderId )
kuaidicomparam快递公司编码
statusInt订单状态,0:下单成功;100:已接单;210:待取件;230:已到店;310:配送中;515:转单改派中;510:订单状态异常(非终态);520:已完成;;720:订单取消;710:用户取消订单
statusDescstring订单状态描述
courierNamestring骑手姓名
courierMobilestring骑手电话
expectFinishTimestring预计送达时间(格式 yyyy-MM-dd HH:mm:ss)
updateTimestring状态更新时间

6.3 返回结果

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

6.4 提供数据内容

返回结果示例

{
	"kuaidicom": "shunfengtongcheng",
	"orderId": "100280",
	"status": 720,
	"updateTime": "2023-03-09 16:08:22"
}

返回结果示例

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

说明:

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

其他信息快递100会忽略。