同城急送接口文档

一、同城急送价格查询接口

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

1.1 接口格式

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

1.2 请求地址

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

请求参数：

param数据结构：

goods数据结构：

1.3 返回结果

data数据结构

FeeDetail参数

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",
	"sendManCity": "北京市",
	"sendManDistrict": "海淀区"
}

​

返回结果示例

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

1.5 信息代码含义

二、同城急送下单接口

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

2.1 接口格式

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

2.2 请求地址

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

请求参数：

param数据结构：

goods数据结构：

2.3 返回结果

data数据结构

FeeDetail参数

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,
	}]
}

​

返回结果示例

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

2.5 信息代码含义

三、同城急送取消接口

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

3.1 接口格式

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

3.2 请求地址

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

请求参数：

param数据结构：

3.3 返回结果

data数据结构

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

3.5 信息代码含义

四、同城急送加小费接口

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

4.1 接口格式

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

4.2 请求地址

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

请求参数：

param数据结构：

4.3 返回结果

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

4.5 信息代码含义

五、同城急送订单状态回调接口

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

5.1 接口格式

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

5.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>

请求参数

param数据结构：

5.3 返回结果

5.4 提供数据内容

请求结果示例

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

​

返回结果示例

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

说明：

其他信息快递100会忽略。

六、同城急送获取骑手位置信息接口

订单创建且骑手接单后，通过该接口获取骑手位置信息。

6.1 接口格式

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

6.2 请求地址

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

请求参数（header）

请求参数（body）

param数据结构：

6.3 返回结果

6.4 请求参数示例

key = xxx
sign = 4BBDE07660******0873642CFAE9A8DD
t = 1470304729724
param = {
"orderId": "xxxx",
}

6.5 返回结果示例

成功示例

{
    "code": 200,
    "data": {
        "lbsType": 2,
        "courierLat": "31.26731662",
        "courierLng": "120.63341715"
    },
    "message": "success",
    "time": 0,
    "success": true
}

6.6 返回信息代码含义

同时向多家同城快递公司发起价格查询，返回各公司的预估配送距离及折扣价格。该接口不会产生实际费用。请注意，仅部分同城快递公司支持批量查价，调用前请和快递100技术支持人员确认。

7.1 接口格式

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

7.2 请求地址

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

7.3 请求参数

7.4 param 数据结构

goods 数据结构：

7.5 请求示例

method = batchPrice
key = ******
sign = ******
t = 1576123932000

{
    "salt": "abc",
    "callbackUrl": "http://test..kuaidi100.com/test/callback/mock",
    "kuaidiComList": [
        "shunfengtongcheng",
        "dadatongcheng"
    ],
    "lbsType": 2,
    "recManName": "王晓祺",
    "recManMobile": "13557554568",
    "recManProvince": "北京",
    "recManCity": "北京市",
    "recManDistrict": "海淀区",
    "recManAddr": "学清嘉创大厦A座",
    "recManLat": "40.014844",
    "recManLng": "116.352637",
    "sendManName": "王",
    "sendManMobile": "19128686044",
    "sendManProvince": "北京",
    "sendManCity": "北京市",
    "sendManDistrict": "西城区",
    "sendManAddr": "广安门南街60号荣宁园小区1",
    "sendManLat": "39.873819",
    "sendManLng": "116.351928",
    "weight": "5",
    "remark": "",
    "orderType": 0,
    "expectPickupTime": "2026-05-30 11:00:00",
    "expectFinishTime": "2026-05-30 14:00:00",
    "price": 0,
    "goods": [
        {
            "name": "数码",
            "type": "数码",
            "count": 1
        }
    ]
}

7.6 返回结果

data 数据结构：

FeeDetail 数据结构：

7.7 响应示例

{
    "code": 200,
    "data": {
        "taskId": "4E032A9BF98848B7B7B0CD3EDDDAB3D2",
        "feeDetail": [
            {
                "kuaidiCom": "meituantongcheng",
                "distance": "16473",
                "discountFee": "37.18"
            },
            {
                "kuaidiCom": "fengniaotongcheng",
                "distance": "16611",
                "discountFee": "36.19"
            },
            {
                "kuaidiCom": "dadatongcheng",
                "distance": "16080",
                "discountFee": "35.97"
            },
            {
                "kuaidiCom": "shunfengtongcheng",
                "distance": "16080",
                "discountFee": "31.07"
            }
        ]
    },
    "message": "success",
    "time": 0,
    "success": true
}

八、同城急送并呼下单接口

同时向多家同城快递公司发起下单请求，抢单成功后，自动取消其他同城快递公司订单。

8.1 接口格式

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

8.2 请求地址

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

8.3 请求参数

8.4 param 数据结构

goods 数据结构：

8.5 请求示例

method = batchorder
key = ******
sign = ******
t = 1576123932000

{
    "salt": "",
    "callbackUrl": "http://test.kuaidi100.com/test/callback/mock",
    "kuaidiComList": [
        "shunfengtongcheng",
        "meituantongcheng",
        "fengniaotongcheng",
        "dadatongcheng"
    ],
    "lbsType": 2,
    "recManName": "王晓祺",
    "recManMobile": "13557554568",
    "recManProvince": "北京",
    "recManCity": "北京市",
    "recManDistrict": "海淀区",
    "recManAddr": "学清嘉创大厦A座",
    "recManLat": "40.014844",
    "recManLng": "116.352637",
    "sendManName": "王",
    "sendManMobile": "19128686044",
    "sendManProvince": "北京",
    "sendManCity": "北京市",
    "sendManDistrict": "西城区",
    "sendManAddr": "广安门南街60号荣宁园小区1",
    "sendManLat": "39.873819",
    "sendManLng": "116.351928",
    "weight": "5",
    "remark": "",
    "volume": "",
    "orderType": 0,
    "expectPickupTime": "2026-06-02 11:00:00",
    "expectFinishTime": "2026-06-02 14:00:00",
    "price": "0",
    "goods": [
        {
            "name": "数码",
            "type": "数码",
            "count": 1
        }
    ]
}

8.6 返回结果

data 数据结构：

FeeItem 数据结构：

8.7 响应示例

{
    "code": 200,
    "data": {
        "taskId": "4C2F566CD54640668FC89B0D4416D480",
        "orderId": "300948167",
        "fee": [
            {
                "kuaidiCom": "meituantongcheng",
                "deliveryDistance": "16473",
                "discountFee": "37.18"
            },
            {
                "kuaidiCom": "fengniaotongcheng",
                "deliveryDistance": "16611",
                "discountFee": "36.19"
            },
            {
                "kuaidiCom": "dadatongcheng",
                "deliveryDistance": "16080",
                "discountFee": "35.64"
            },
            {
                "kuaidiCom": "shunfengtongcheng",
                "deliveryDistance": "16080",
                "discountFee": "31.07"
            }
        ]
    },
    "message": "success",
    "time": 0,
    "success": true
}