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

同城配送接口文档

一、同城配送预下单接口

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

1.1 接口格式

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

1.2 请求地址

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

请求参数：

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

param数据结构：

参数名是否必填类型说明
kuaidicom是string快递公司的编码，一律用小写字母，见参数字典
lbsType否Int坐标类型(1：百度坐标，2：高德坐标 ,默认2)
recManName是string收件人姓名，长度最大20
recManMobile是string收件人的手机号（有手机号和固话正则校验）
recManProvince是string收件人所在的省，长度最大20
recManCity是string收件人所在的市，长度最大20
recManDistrict是string收件人所在的区，长度最大20
recManAddr是string收件人所在完整地址，如广东深圳市深圳市南山区科技南十二路2号金蝶软件园，长度最大100
recManLat是string收件人地址纬度，默认高德坐标，长度最大10
recManLng是string收件人地址经度，默认高德坐标，长度最大10
sendManName是string寄件人姓名，长度最大20
sendManMobile是string寄件人的手机号（有手机号和固话正则校验）
sendManProvince是string寄件人所在的省，长度最大20
sendManCity是string寄件人所在的市，长度最大20
sendManDistrict是string寄件人所在的区，长度最大20
sendManAddr是string寄件人所在完整地址，如广东深圳市深圳市南山区科技南十二路2号金蝶软件园，长度最大100
sendManLat是string寄件人地址纬度，默认高德坐标，长度最大10
sendManLng是string寄件人地址经度，默认高德坐标，长度最大10
weight是string物品总重量，例：1.5，单位kg
remark否string备注，例：测试寄件，长度最大255
orderType否Int0：无需预约； 1：预约单送达时间； 2：预约单上门时间。 默认为0
expectPickupTime否string期望取货时间，orderType=2时必填，例：2020-02-02 22:00
expectFinishTime否string期望送达时间，orderType=1时必填，例：2020-02-02 22:00
insurance否string保价物品金额
price是string物品总金额，例：100.23，单位：元
directDelivery否Int是否为专人直送订单，0：否，1：是
goods是List商品详情

goods数据结构：

参数名是否必填类型说明
name否String商品名称
type是String物品类型，详见参数字典：三、物品类型对照表
count是Int商品数量

1.3 返回结果

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

data数据结构

字段类型说明备注
taskIdstring任务ID32位随机字符串，用于记录订单整个生命周期
deliveryDistancestring配送距离单位：米
discountFeestring配送费（折扣价）单位：元
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

请求参数：

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

param数据结构：

参数名是否必填类型说明
kuaidicom是string快递公司的编码，一律用小写字母，见参数字典
lbsType否Int坐标类型(1：百度坐标，2：高德坐标 ,默认2)
recManName是string收件人姓名，长度最大20
recManMobile是string收件人的手机号（有手机号和固话正则校验）
recManProvince是string收件人所在的省，长度最大20
recManCity是string收件人所在的市，长度最大20
recManDistrict是string收件人所在的区，长度最大20
recManAddr是string收件人所在完整地址，如广东深圳市深圳市南山区科技南十二路2号金蝶软件园，长度最大100
recManLat是string收件人地址纬度，默认高德坐标，长度最大10
recManLng是string收件人地址经度，默认高德坐标，长度最大10
sendManName是string寄件人姓名，长度最大20
sendManMobile是string寄件人的手机号（有手机号和固话正则校验）
sendManProvince是string寄件人所在的省，长度最大20
sendManCity是string寄件人所在的市，长度最大20
sendManDistrict是string寄件人所在的区，长度最大20
sendManAddr是string寄件人所在完整地址，如广东深圳市深圳市南山区科技南十二路2号金蝶软件园，长度最大100
sendManLat是string寄件人地址纬度，默认高德坐标，长度最大10
sendManLng是string寄件人地址经度，默认高德坐标，长度最大10
weight是string物品总重量，例：1.5，单位kg
remark否string备注，例：测试寄件，长度最大255
volume否string体积，单位：cm3，长度最大20
salt否string签名用随机字符串，长度最多20
callbackUrl否stringcallBackUrl订单信息回调，长度最大50
orderType否Int0：无需预约； 1：预约单送达时间； 2：预约单上门时间。 默认为0
expectPickupTime否string期望取货时间，orderType=2时必填，例：2020-02-02 22:00
expectFinishTime否string期望送达时间，orderType=1时必填，例：2020-02-02 22:00
insurance否string保价物品金额
price是string物品总金额，例：100.23，单位：元
directDelivery否Int是否为专人直送订单，0：否，1：是
goods是List商品详情

goods数据结构：

参数名是否必填类型说明
name否String商品名称
type是String物品类型，详见参数字典：三、物品类型对照表
count是Int商品数量

2.3 返回结果

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

data数据结构

字段类型说明备注
taskIdstring任务ID32位随机字符串，用于记录订单整个生命周期
orderIdstring同城寄件订单号快递100订单号
kuaidinumstring快递单号
deliveryDistancestring配送距离单位：米
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

请求参数：

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

param数据结构：

参数名是否必填类型说明
taskId是string下单时返回的taskId
orderId是string订单ID
cancelMsgType是Int取消原因编码，详见参数字典：四、取消原因类型对照表
cancelMsg否string取消原因

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

请求参数：

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

param数据结构：

参数名是否必填类型说明
taskId是string下单时返回的taskId
orderId是string订单ID
cancelMsgType是Int取消原因类型，详见参数字典：四、取消原因类型对照表
cancelMsg否string取消原因

4.3 返回结果

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

data数据结构

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

4.4 提供数据内容

请求参数示例

method = cancel
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

请求参数：

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

param数据结构：

参数名是否必填类型说明
taskId是string下单时返回的taskId
orderId是string订单ID
tips是string小费金额，单位：元
remark否string备注

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会忽略。

在线客服

一对一咨询

  • 电话图标

    电话咨询

    0755-86719032

    专业客服团队为您服务

  • 二维码图标

    联系商务

    二维码

    扫码添加工作人员

  • 小程序图标

    小程序

    小程序

    扫码进入企业助手

快递100-AI助手
暂无访问权限，请完成网站配置后刷新重试前往千帆AppBuilder