# 同城配送简介

微信同城配送是整合了多家运力公司后提供的聚合配送服务。商家通过微信充值并对接同城配送接口后即可下配送单，解决外卖配送需求。

# 1. 业务模式

#60%

# 2. 服务优势

充值即可拥有多家运力公司的服务。
配送价格优惠，1公里起送价¥4.32起。
配送状态通过微信服务通知实时下发给用户，提升收货体验。

# 3. 用户端流程（配送状态实时通知，提升收货体验）

#70%

# 4. 商家端流程（MP/接口两种方式，提升接入灵活性）

# 4.1 小程序MP后台开通服务（小程序MP后台-功能-物流服务-同城配送）

#70%

# 4.2 查看详情并签署协议

#70%

# 4.3 添加门店（门店名称/电话/地址）

#70%

# 4.4 充值门店运费（支持API充值）

如选择接口充值，则需商家传入门店id、运力、金额，平台返回充值url。充值后有效期30天，到期未使用余额自动原路退回。充值运力后可设置运力偏好：价格优先（优先下单低价运力）；运力优先（优先下单某个运力）。

# 4.5 查看门店列表（门店名称/地址/运力余额）

#70%

# 4.6 管理门店信息（门店/配送偏好/运力余额/交易记录）

#70%

# 同城配送开发文档

# 1. API调用规范

# 1.1. 请求方式

文档所有接口请求方式均为HTTPS-POST，小程序调用后台接口需要获取access_token授权；服务商代商家调用接口需要获取接口权限集授权，本文档中所列举的接口权限集ID为51，服务商调用接口使用authorizer_access_token授权。

# 1.2. 数据格式

UTF-8编码，请求和响应参数仅支持JSON数据格式，请_st设置HTTP Header的Content-Type为application/json

Content-Type: application/json;charset=utf-8
Accept: application/json

# 1.3. 数据签名和加密

商家需要通过数字签名来保证求的真实性和数据的完整性，签名和加密的参考，微信服务端api签名指南。使用加密和签名之前请确认小程序已经配置了签名秘钥和加密秘钥，配置路径：小程序管理后台->开发管理->开发设置->API安全注意：小程序管理后台配置了签名秘钥和加密用的对称秘钥后，如果商家确定不需要全局使用接口加密和签名，可以不开启api加密，如下图为没有开启加密的状态！！！ #70%

对于服务商开发者，可前往开放平台-管理中心-第三方平台-详情-开发配置-开发资料-API安全配置-查看详情配置密钥和公钥。 #70%

# 2. API列表

# 2.0 充值&扣费主体说明

同城配送支持以服务商/小程序/门店维度进行充值，充值后名下所有门店都可以统一使充值的运费。

服务商：小程序服务商。
小程序：商家或品牌。
门店：商家或品牌在不同地区的线下门店。该主体也是配送单发单主体。

# 2.1. 开通门店权限

接口简介:

在使用门店相关接口前需要先开通门店权限，开通门店权限前可以使用页面或者使用下面的API开通门店（无加密，可直接调用）。

接口地址：[https://api.weixin.qq.com/cgi-bin/express/intracity/apply?access_token={ACCESS_TOKEN}]

请求参数：（不需要请求参数）

返回参数：

字段	字段名	类型	是否必填	说明
errcode	返回码	int	是	0:请求成功，其他：请求失败
errmsg	返回信息	string	是

请求示例：

{}

返回参数：

{
    "errcode":0，
    "errmsg":"ok"
}

# 2.2. 创建门店

接口简介:

创建门店时需要传入自定义的门店编号，自定义的门店编号需要唯一，确保不重复创建门店创建后系统生成全局唯一门店编号wx_store_id，后续创建运力订单时需要该门店编号

接口地址: https://api.weixin.qq.com/cgi-bin/express/intracity/createstore?access_token={ACCESS_TOKEN}

请求参数：

字段	字段名	类型	是否必填	说明
out_store_id	自定义门店编号	string	是
store_name	门店名称	string	是
order_pattern	运力偏好	uint32	否	1：价格优先，2：运力优先, 默认价格优先
service_trans_prefer	优先使用的运力ID	string	否	order_pattern = 2时必填，运力ID见列表
address_info	门店地址信息	object	是	见AddressInfo，务必要传入正确的门店地址作为发货地址

AddressInfo

字段	字段名	类型	是否必填	说明
province	省/自治区/直辖市	string	是	xxx省,xxx自治区,xxx市
city	地级市	string	是	xxx市
area	县/县级市/区	string	是	xxx区, xxx县
street	街道	string	否	xxx街道
house	具体门牌号或详细地址	string	是	xxxx号
lat	门店所在地纬度	double	是
lng	门店所在地经度	double	是
phone	门店联系电话	string	是	11位手机号或11位带区号的固话:020-8080880

返回参数：

字段	字段名	类型	是否必填	说明
errcode	返回码	int	是	0:请求成功，其他：请求失败
errmsg	返回信息	string	是
以下信息在请求成功时返回
wx_store_id	微信门店编号	string	是
appid	小程序appid	string	是
out_store_id	自定义门店ID	string	是

请求示例：

{
    "out_store_id":"123",
    "store_name":"测试门店1",
    "order_pattern":1,
    "address_info":{
      "province":"广东省",
      "city":"深圳市",
      "area":"南山区",
      "street":"南头街道",
      "house":"深南大道10000号",
      "lat":22.540366,
      "lng":113.934559,      
      "phone":"1380000138"
    }
}

返回示例：

{
    "errcode":0，
    "errmsg":"ok",
    "wx_store_id":"4000000000000042001",
    "appid":"wx539e0b4872f196d1",
    "out_store_id":"123"
}

# 2.3. 查询门店

接口简介: 获取本小程序所创建的门店，不传wx_store_id和out_store_id则返回本小程序所有门店信息

接口地址：https://api.weixin.qq.com/cgi-bin/express/intracity/querystore?access_token={ACCESS_TOKEN}

请求参数：

字段	字段名	类型	是否必填	说明
wx_store_id	微信门店编号	string	否
out_store_id	自定义门店编号	string	否

返回参数：

字段	字段名	类型	是否必填	说明
errcode	返回码	int	是	0:请求成功，其他：请求失败
errmsg	返回信息	string	是
以下信息在请求成功时返回
store_list	门店信息列表	Object Array	否	详见 StoreInfo定义
total	符合条件的门店总数	uint32	是
appid	小程序appid	string	是

StoreInfo

字段	字段名	类型	是否必填	说明
wx_store_id	微信门店编号	string	是
out_store_id	自定义门店编号	string	是
city_id	门店所在城市ID	string	是
order_pattern	运力偏好	uint32	否
service_trans_prefer	优先使用的运力ID	string	否
address_info	门店地址信息	Object	是	定义见2.1 AddressInfo

请求示例：

{
    "wx_store_id":"4000000000000042001"
}

返回示例：

{
	"errcode": 0,
	"errmsg": "ok",
	"total": 1,
	"appid": "wx539e0b4872f196d1",
	"store_list": [{
		"wx_store_id": "4000000000000042001",
		"out_store_id": "123",
		"city_id": 440300,
		"address_info": {
			"province": "广东省",
			"city": "深圳市",
			"area": "南山区",
			"street": "南头街道",
			"house": "深南大道10000号",
			"lat": 22.540366,
			"lng": 113.934559,
			"phone": "1380000138"
		},
		"order_pattern": 0,
		"service_trans_prefer": ""
	}]
}

# 2.4. 更新门店

接口简介：更新门店信息

接口地址：https://api.weixin.qq.com/cgi-bin/express/intracity/updatestore?access_token={ACCESS_TOKEN}

请求参数：

字段	字段名	类型	是否必填	说明
keys	门店编号	Object	是	详见KeyInfo
content	更新内容	Object	是	详见UpdateContent

KeyInfo

字段	字段名	类型	是否必填	说明
wx_store_id	微信门店编号	string	否	wx_store_id和out_store_id二选一
out_store_id	自定义门店编号	string	否	wx_store_id和out_store_id二选一

UpdateContent

字段	字段名	类型	是否必填	说明
store_name	门店名称	string	否
order_pattern	运力偏好	string	否
service_trans_prefer	优先使用的运力ID	string	否	order_pattern = 2时必填，运力ID见列表
address_info	门店地址信息	Object	否	定义见2.1 AddressInfo

返回参数：

字段	字段名	类型	是否必填	说明
errcode	返回码	int	是	0:请求成功，其他：请求失败
errmsg	返回信息	string	是

请求示例：

{
	"keys": {
		"wx_store_id": "4000000000000042001"
	},
	"content": {
		"store_name": "测试门店3",
		"address_info": {
			"province": "北京市",
			"city": "北京市",
			"area": "海淀区",
			"street": "西三旗街道",
			"house": "海淀区清河龙岗路51号清润家园小区 永辉",
			"phone": "13800000138",
			"lat": 40.030613,
			"lng": 116.354787
		},
		"order_pattern": 2,
		"service_trans_prefer": "SFTC"
	}

返回示例：

{
    "errcode":0,
    "errmsg":"ok"
}

# 2.5. 门店运费充值

接口简介: 返回微信服务市场的充值页面地址，通过该页面可以为门店充值指定运力的运费，充值后运费有使用有效期，默认有效期为1个月，超期未使用的运费降原路退回。

接口地址：https://api.weixin.qq.com/cgi-bin/express/intracity/storecharge?access_token={ACCESS_TOKEN}

请求参数：

字段	字段名	类型	是否必填	说明
wx_store_id	微信门店编号	string	否	pay_mode = PAY_MODE_STORE时必传，不传pay_mode时必传wx_store_id
service_trans_id	运力ID	string	是
amount	充值金额	uint32	是	单位：分, 50元起充
pay_mode	充值主体	string	否	门店：PAY_MODE_STORE；小程序:PAY_MODE_APP；服务商：PAY_MODE_COMPONENT，不传pay_mode默认pay_mode=PAY_MODE_STORE

返回参数：

字段	字段名	类型	是否必填	说明
errcode	返回码	int	是	0:请求成功，其他：请求失败
errmsg	返回信息	string	是
以下信息在请求成功时返回
payurl	充值页面地址	string	是
appid	小程序appid	string	是
wx_store_id	微信门店编号	string	是

请求示例：

{
    "wx_store_id":"4000000000000042001"，
    "service_trans_id":"SFTC",
    "amount":10000
}

返回示例：

{
    "payurl":"https://fuwu.weixin.qq.com/service/common/buy?orderId=2886882380534202368&hasApply=1",
    "appid":"wx539e0b4872f196d1",
    "wx_store_id":"4000000000000042001"
}

# 2.6. 门店运费退款

接口简介: 该接口可以将门店指定运力的运费余额退还，如果门店有在途的配送订单，需要等配送完成或者取消配送订单之后才可以操作退款；操作退款后，退款金额五分钟内到账。

接口地址：https://api.weixin.qq.com/cgi-bin/express/intracity/storerefund?access_token={ACCESS_TOKEN}

请求参数：

字段	字段名	类型	是否必填	说明
wx_store_id	微信门店编号	string	否	pay_mode = PAY_MODE_STORE时必传，不传pay_mode时必传wx_store_id
pay_mode	充值/扣费主体	string	否	门店：PAY_MODE_STORE；小程序:PAY_MODE_APP；服务商：PAY_MODE_COMPONENT，不传pay_mode默认pay_mode=PAY_MODE_STORE
service_trans_id	运力ID	string	是

返回参数：

字段	字段名	类型	是否必填	说明
errcode	返回码	int	是	0:请求成功，其他：请求失败
errmsg	返回信息	string	是
以下信息在请求成功时返回
appid	小程序appid	string	是
wx_store_id	微信门店编号	string	是
refund_amount	退款金额	uint32	是	单位：分

请求参数示例：

{
    "wx_store_id":"4000000000000042001",
    "service_trans_id":"SFTC"
}

返回参数示例：

{
    "appid":"wx539e0b4872f196d1",
    "wx_store_id":"4000000000000042001"，
    "refund_amount":3000
}

# 2.7. 门店运费流水查询

接口简介：查询门店运力资金流水

接口地址：https://api.weixin.qq.com/cgi-bin/express/intracity/queryflow?access_token={ACCESS_TOKEN}

请求参数：

字段	字段名	类型	是否必填	说明
wx_store_id	微信门店编号	string	是
flow_type	流水类型	uint32	是	1:充值流水， 2:消费流水，3:退款流水
service_trans_id	运力ID	string	否	运力ID
begin_time	开始时间戳	uint32	否	不传默认返回最近90天的数据
end_time	结束时间戳	uint32	否	不传默认返回最近90天的数据

返回参数：

字段	字段名称	类型	是否必填	说明
errcode	返回码	int	是	0:请求成功，其他:请求失败
errmsg	返回信息	string	是
以下信息在请求成功时返回
flow_list	流水数组	Object Array	是	详见FlowRecordInfo的定义
total_pay_amt	总支付金额	int	是
total_refund_amt	总退款金额	int	是
total_deduct_amt	总违约金	int	否	消费流水返回

FlowRecordInfo-充值流水

字段	字段名称	类型	是否必填	说明
flow_type	流水类型	uint32	是	1:充值流水， 2:消费流水， 3:退款流水
appid	appid	string	是
wx_store_id	微信门店ID	string	是
pay_order_id	充值订单号	uint64	是
service_trans_id	运力ID	string	是
pay_amount	支付金额	uint32	是
pay_time	支付时间	uint32	是	时间戳类型
pay_status	支付状态	string	是	FAIL：支付失败 SUCCESS:支付成功
create_time	订单创建时间	uint32	是	时间戳类型
consume_deadline	有效截止日期	uint32	是	时间戳类型

FlowRecordInfo-退款流水

字段	字段名称	类型	是否必填	说明
flow_type	流水类型	uint32	是	1:充值流水， 2:消费流水， 3:退款流水
appid	appid	string	是
wx_store_id	微信门店ID	string	是
pay_order_id	充值订单号	uint64	是
service_trans_id	运力ID	string	是
pay_amount	支付金额	uint32	是
pay_time	支付时间	uint32	是	时间戳类型
create_time	订单创建时间	uint32	是	时间戳类型
consume_deadline	有效截止日期	uint32	是	时间戳类型
refund_time	退款时间	uint32	是	时间戳类型
refund_amount	退款金额	int32	是	单位：分

FlowRecordInfo-消费流水

字段	字段名称	类型	是否必填	说明
flow_type	流水类型	uint32	是	1:充值流水， 2:消费流水， 3:退款流水
appid	appid	string	是
wx_store_id	微信门店ID	string	是
wx_order_id	订单ID	string	是
service_trans_id	运力ID	string	是
openid	用户openid	string	是	下单用户的openid
delivery_status	运单状态	int32	是	取值详见第4节
pay_amount	支付金额	int32	是	单位：分
pay_time	支付时间	int32	是	时间戳类型
pay_status	支付状态	string	是	FAIL:支付失败 SUCCESS:支付成功
refund_status	退款状态	string	否	PROCESSING:退款处理中 SUCCESS:退款成功
refund_amount	退款金额	int32	否	运单被取消后产生的退款，单位：分
refund_time	退款时间	int32	是	时间戳类型
deduct_amount	扣除违约金	int32	否	运单被取消后产生的违约金，单位：分
create_time	创建时间	uint32	是	时间戳类型
bill_id	运单ID	string	是	运力公司的订单ID
delivery_finished_time	运单完成配送的时间	uint32	否	时间戳类型

请求示例

{
    "wx_store_id":"4000000000000042002",
    "flow_type":1,
    "service_trans_id":"SFTC"
}

返回示例：

{
	"total": 1,
	"flow_list": [{
		"flow_type": 1,
		"appid": "wx539e0b4872f196d1",
		"wx_store_id": "4000000000000042002",
		"pay_order_id": 2920020938702667776,
		"service_trans_id": "SFTC",
		"pay_amount": 1,
		"refund_amount": 1,
		"create_time": 1683639082,
		"pay_time": 1683639151,
		"refund_time": 1683653491,
		"consume_deadline": 1686231082,
        "pay_status":"SUCCESS"
	}],
	"errcode": 0,
	"errmsg": "ok",
	"total_pay_amt":1,
	"total_refund_amt":1
}

# 2.8. 门店余额查询

接口简介：查询门店运力余额

接口地址：https://api.weixin.qq.com/cgi-bin/express/intracity/balancequery?access_token={ACCESS_TOKEN}

请求参数：

字段	字段名	类型	是否必填	说明
wx_store_id	微信门店编号	string	否	pay_mode = PAY_MODE_STORE时必传，不传pay_mode时必传wx_store_id
service_trans_id	运力ID	string	否	查询门店在指定运力ID充值的余额，不指定则查询全部
pay_mode	充值/扣费主体	string	否	门店：PAY_MODE_STORE；小程序:PAY_MODE_APP；服务商：PAY_MODE_COMPONENT，不传pay_mode默认pay_mode=PAY_MODE_STORE

返回参数：

字段	字段名称	类型	是否必填	说明
errcode	返回码	int	是	0:请求成功，其他：请求失败
errmsg	返回信息	string	是
以下信息在请求成功时返回
wx_store_id	门店ID	string	是	门店ID
appid	appid	string	是
all_balance	总余额	int32	是
balance_detail	余额详情	JSON ARRAY	是	详见BalanceDetail

BalanceDetail:

字段	字段名	是否必填	说明
balance	余额	是
service_trans_id	运力ID	是
service_trans_name	运力名称	是
order_list	充值订单详情	否	当前生效的充值且余额没有被消费完的充值订单详情，订单充值后，没有被消费完会自动退款。详见OrderDetail

OrderDetail

字段	字段名	类型	是否必填	说明
payorder_id	充值订单号	string	是
charge_amt	充值金额	int32	是
unused_amt	未使用的余额	int32	是
begin_time	充值生效时间	uint32	是	时间戳类型
end_time	失效时间	uint32	是	时间戳类型，超过该时间，余额没有被消费完会退款

请求示例：

{
"wx_store_id":"4000000000000042001",
"service_trans_id":"DADA"
}

返回示例：

{
	"appid": "wx539e0b4872f196d1",
	"wx_store_id": "4000000000000042001",
	"all_balance": 10,
	"balance_detail": [{
		"balance": 10,
		"service_trans_id": "DADA",
		"service_trans_name": "达达快送",
		"order_list": [{
			"payorder_id": "2978080038359269380",
			"unused_amt": 10,
			"charge_amt": 10,
			"begin_time": 1687099701,
			"end_time": 1689691701
		}]
	}],
	"errcode": 0,
	"errmsg": "OK"
}

# 2.9. 查询运费

接口简介:商家通过该接口传入配送单的相关信息，同城配送后台将根据配送信息向运力查询并返回实时的运费和配送距离。同城配送会根据门店设置的运力偏好（价格优先/运力优先）进行预下单，如果没有设置偏好，则默认返回低价运力的预下单结果，商家可以根据该接口的返回价格作为配送的预估价格。（注意：接口返回实时计价结果，可能存在预下单和下单价格不一致的情况，具体费用应以下单接口为准。以达达为例，询价结果一般3分钟内有效，顺丰平台没有做说明）

接口地址：https://api.weixin.qq.com/cgi-bin/express/intracity/preaddorder?access_token={ACCESS_TOKEN}

字段	字段名	类型	是否必填	说明
wx_store_id	微信门店编号	string	是
user_name	收件人姓名	string	是
user_phone	收件人手机号	string	是	11位手机号或11位带区号的固话:020-8080880
user_lng	收件用户位置经度	double	是
user_lat	收件用户位置维度	double	是
user_address	收件用户详细地市	string	是
cargo_name	商品名称	string	是
cargo	商品重量	Cargo	是	详看CargoInfo
use_sandbox	是否使用沙箱	uint32	否

CargoInfo

字段	字段名	类型	是否必填	说明
cargo_name	商品名称	string	是
cargo_weight	商品总重量	uint32	是	单位：克
cargo_price	商品总价格	uint32	是	单位：分
cargo_type	商品类型	uint32	是	详见物品类型列表
cargo_num	商品数量	uint32	是	商品数量

返回参数：

字段	字段名	类型	是否必填	说明
errcode	返回码	int	是	0:请求成功，其他：请求失败
errmsg	返回信息	string	是
以下信息在请求成功时返回
service_trans_id	运力公司ID	string	是
distance	配送距离	int32	是	单位：米
est_fee	预估配送费	int32	是	单位：分
expected_finished_time	商品预计送达时间	uint32	否	时间戳类型，是否返回取决于运力公司，支持该字段的运力公司：SFTC
promise_delivery_time	配送时长（单位：分钟）	uint32	否	从下单到完成配送所需时间，是否返回取决于运力公司，支持该字段的运力公司：SFTC

请求参数示例：

{
	"wx_store_id": "4000000000000042001",
	"user_lng": "116.353093",
	"user_lat": "40.01496",
	"user_address": "北京市海淀区学清嘉创大厦A座15层）",
	"use_sandbox": 1,
	"user_name":"顺丰同城",
	"user_phone":"13800000138",
	"cargo": {
		"cargo_name": "榴莲披萨套餐",
		"cargo_type": 1,
		"cargo_num": 7,
		"cargo_price": 5000,
		"cargo_weight": 500
	}
}

返回参数示例：

{
	"errcode":0,
	"errmsg":"OK",
	"distance":1000,
	"fee":870,
	"service_trans_id":"SFTC",
	"promise_delivery_time":50,
	"expected_finished_time":1692163151
}

# 2.10. 创建配送单

接口简介：创建同城配送单，会根据门店设置的运力偏好来选择运力公司下单。如果没有设置偏好，则默认优先下单低价运力。

接口地址：https://api.weixin.qq.com/cgi-bin/express/intracity/addorder?access_token={ACCESS_TOKEN}

请求参数：

字段	字段名	类型	是否必填	说明
wx_store_id	微信门店编号	string	是
store_order_id	门店订单编号	string	是	同一个门店订单编号要保证唯一，相同的订单号会重入
user_openid	收货用户openid	string	是
user_lng	收货用户地址经度	double	是
user_lat	收货用户地址维度	double	是
user_address	收货用户详细地址	string	是
user_name	收货用户姓名	string	是
user_phone	收货用户电话	string	是	11位手机号或11位带区号的固话:020-8080880
order_seq	订单序号	string	否	用于配送员快速寻找到匹配的商品
verify_code_type	验证码类型	int32	否	0:不生成 1:生成取货码 2:生成收货码 3:两者都生成
order_detail_path	跳转商家订单页面路径	string	是	物流轨迹页面跳转到商家小程序的订单页面路径参数，期望向用户展示商品订单详情
callback_url	订单状态回调地址	string	否	回调协议详细查看第三节
use_sandbox	是否使用沙箱	int32	否	1:使用沙箱环境; 使用测试沙箱环境，不需要充值运费就可以生成测试订单
cargo	商品信息	Object	是	见Cargo

Cargo

字段	字段名	类型	是否必填	说明
cargo_name	商品名称	string	是
cargo_weight	商品重量	uint32	是	单位：克
cargo_type	商品类型	uint32	是	见第6节物品类型列表
cargo_num	商品数量	uint32	是
cargo_price	商品价格	uint32	是	单位：分
item_list	物品列表	object array	是	物品列表，物品的图片和名称等，详见ItemDetail

ItemDetail

字段	字段名	类型	是否必填	说明
item_name	物品名称	string	是	物品名称
item_pic_url	物品图片	string	是	物品的图片
count	物品数量	uint32	是	物品数量

返回参数：

字段	字段名	类型	是否必填	说明
errcode	错误码	int32	是	0:请求成功，其他：请求失败
errmsg	错误信息	string	是
以下字段在请求成功时返回
wx_store_id	微信门店编号	string	是
wx_order_id	微信订单编号	string	是
store_order_id	门店订单编号	string	是
service_trans_id	配送运力	string	是
distance	配送距离	uint32	是	单位：米
trans_order_id	运力订单号	string	是
waybill_id	运力配送单号	string	否	是否返回取决于运力
fee	配送费	uint32	是	单位：分
fetch_code	取货码	string	否
order_seq	取货序号	string	否

请求参数示例：

{
	"wx_store_id": "4000000000000042001",
	"store_order_id": "testorder123",
	"user_openid": "ozMQO0WsxkA3E56SWBGrLGQ4WVZY",
	"user_lng": "116.353093",
	"user_lat": "40.01496",
	"user_address": "北京市海淀区学清嘉创大厦A座15层）",
	"user_name": "顺丰同城",
	"user_phone": "13881979410",
	"callback_url": "https://testcallback.com",
	"use_sandbox": 1,
	"cargo": {
		"cargo_name": "榴莲披萨套餐",
		"cargo_type": 1,
		"cargo_num": 3,
		"cargo_price": 5000,
		"cargo_weight": 500，
        "item_list":[
            {                       
                "item_name":"8寸榴莲",
                "count":1,
                "item_pic_url": "https://www.qq.com"
            },
            {              
                "item_name":"可口可乐",
                "count":2,
                "item_pic_url": "https://www.qq.com"
            }
        ]
	}
}

返回参数示例：

{
	"errcode": 0,
	"errmsg": "ok",
	"service_trans_id": "SFTC",
	"wx_store_id": "1000000000000023002",
	"store_order_id": "testorder123",
	"distance": 2358,
	"fee": 1300,
    "trans_order_id":"JS123143DA"
}

注意：

使用顺丰的沙箱环境环境需要固定的收件人信息（达达没有要求），收件人信息如下
收件人姓名：顺丰同城
收件人手机：13881979410 
收件地址：北京市海淀区学清嘉创大厦A座15层

# 2.11. 查询配送单

接口简介：通过该接口查询订单是否创建成功，以及订单创建后的状态更新

接口地址：https://api.weixin.qq.com/cgi-bin/express/intracity/queryorder?access_token={ACCESS_TOKEN}

请求参数：

字段	字段名	类型	是否必填	说明
wx_store_id	微信门店编号	string	否	wx_store_id和store_order_id需要成对出现
store_order_id	门店订单号	string	否	wx_store_id和store_order_id需要成对出现
wx_order_id	微信订单号	string	否	可以单独使用wx_order_id查询

返回参数：

字段	字段名	类型	是否必填	说明
wx_order_id	微信订单号	string	是
store_order_id	门店订单号	string	是
wx_store_id	微信门店编号	string	是
order_status	订单状态	uint32	是
appid	string	string	是
user_openid	收件用户openid	string	是
service_trans_id	运力ID	string	是
delivery_no	运力订单号	string	是
distance	配送距离	double	是	单位：米
actualfee	实际支付费用	uint32	是	单位：分
deductfee	违约金	uint32	是	单位：分
create_time	发单时间	uint32	是
accept_time	配送员接单时间	uint32	否	时间戳
fetch_time	配送员取货时间	uint32	否	时间戳
finish_time	配送员送达时间	uint32	否	时间戳
cancel_time	取消时间	uint32	否	时间戳
expected_finish_time	预期送达时间	uint32	否	时间戳
fetch_code	取货码	string	否	商家验证
recv_code	收货码	string	否	收货人验证
order_seq	订单序号	string	否	用于配送员识别
transporter_info	配送员信息	Object	否	详见TranspoterInfo
store_info	门店信息	Object	是	详见StoreInfo
receiver_info	收获人信息	Object	是	详见ReceiverInfo
cargo_info	商品信息	Object	是	详见CargoInfo

TranspoterInfo

字段	字段名	类型	是否必填	说明
transporter_name	配送员姓名	string	是
transporter_phone	配送员电话	string	是

StoreInfo

字段	字段名	类型	是否必填
store_name	门店名称	string	是
wx_store_id	门店编号	string	是
address	门店详细地址	string	是
lng	门店经度	double	是
lat	门店维度	double	是
phone_num	门店电话	string	是

ReceiverInfo

字段	字段名	类型	是否必填
receiver_name	收件人姓名	string	是
address	收件人详细地址	string	是
phone_num	收件人电话	string	是
lng	收件地址经度	double	是
lat	收件地址维度	double	是

CargoInfo

字段	字段名	类型	是否必填	说明
cargo_name	商品名称	string	是
cargo_weight	商品总重量	uint32	是	单位：克
cargo_price	商品总价格	uint32	是	单位：分
cargo_type	商品类型	uint32	是	详见物品类型列表
cargo_num	商品数量	uint32	是	商品数量
item_list	商品详情	object array	是	物品列表详情，见ItemDetail

ItemDetail

字段	字段名	类型	是否必填	说明
item_name	物品名称	string	是	物品名称
item_pic_url	物品图片	string	是	物品的图片
num	物品数量	uint32	是	物品数量

请求参数示例：

{
    "wx_store_id":"4000000000000042001"
}

返回参数示例：

{
	"wx_order_id": "2000000000000042007",
	"store_order_id": "testorder12345",
	"order_status": 10000,
	"appid": "wx539e0b4872f196d1",
	"user_openid": "ozMQO0ehr_FBgL5mWa5_duxH71Yw",
	"service_trans_id": "SFTC",
	"delivery_no": "SF6508800795950",
	"distance": 2358,
	"actualfee": 201,
	"deductfee": 0,
	"create_time": 1682318663,
	"expected_finish_time": 1682319663,
	"store_info": {
		"phone_num": "13800000138",
		"address": "北京市海淀区西三旗街道永辉超市",
		"lng": 116.354787,
		"lat": 40.030613,
		"store_name": "测试门店3"
	},
	"receiver_info": {
		"phone_num": "顺丰同城",
		"address": "北京市海淀区学清嘉创大厦A座15层）",
		"lng": 116.353093,
		"lat": 40.01496
	},
	"cargo_info": {
		"cargo_name": "榴莲披萨套餐",
		"cargo_weight": 500,
		"cargo_price": 5000,
		"cargo_num": 3,
		"cargo_type": 1
        "item_list":[
            {            "item_name":"8寸榴莲"，
             "item_num":1,
             "item_pic_url": "https://www.qq.com",
            },
            {            "item_name":"可口可乐"，
             "item_num":2,
             "item_pic_url": "https://www.qq.com",
            },
        ]
	},
	"errcode": 0,
	"errmsg": "ok"
}

# 2.12. 取消配送单

接口简介：通过该接口可以取消已创建的订单，取消配送中的订单需要扣减违约金。顺丰配送员接单后2分钟取消订单，收取¥2违约金；达达配送员接单后1分钟取消订单，收取¥2违约金。

接口地址：https://api.weixin.qq.com/cgi-bin/express/intracity/cancelorder?access_token={ACCESS_TOKEN}

请求参数：

字段	字段名	类型	是否必填	说明
wx_store_id	微信门店编号	string	否	wx_store_id和store_order_id需要成对出现
store_order_id	门店订单号	string	否	wx_store_id和store_order_id需要成对出现
wx_order_id	微信订单号	string	否	可以单独使用wx_order_id取消订单
cancel_reason_id	取消原因	uint32	是	1:不需要了 2：信息填错 3：无人接单 99：其他
cancel_reason	取消原因描述	string	否

返回参数：

字段	字段名	类型	是否必填	说明
errcode	错误码	int32	是	0:请求成功，其他：请求失败
errmsg	错误信息	string	是
以下字段在请求成功时返回
wx_order_id	微信订单号	string	是
store_order_id	门店订单号	string	是
wx_store_id	微信门店编号	string	是
order_status	订单状态	uint32	是	详见第4节
appid	小程序appid	string	是
deductfee	违约金	uint32	是	取消配送途中的订单，需要扣减违约金

请求参数示例：

{
    "wx_store_id":"4000000000000042001",
    "wx_order_id":"2000000000000092001",
    "cancel_reason_id":1,
    "cancel_reason":"不需要了"
}

返回参数示例：

{
	"errcode": 0,
	"errmsg": "ok",
	"wx_order_id": "2000000000000092001",
	"store_order_id": "testorder12345879",
	"wx_store_id": "4000000000000042001",
	"appid": "wx539e0b4872f196d1",
	"order_status": 20000,
	"deductfee": 0
}

# 2.13. 设置扣费主体

接口简介：默认扣费主体和充值主体都是门店，该接口可以让开发者设置门店的扣费主体，接口调用成功后，小程序的管理员会收到模板消息，点击模板消息确认更改门店扣费主体后，修改生效。目前支持的扣费主体有：服务商，小程序和门店，详细说明见2.0节

接口地址：https://api.weixin.qq.com/cgi-bin/express/intracity/setpaymode?access_token={ACCESS_TOKEN}

接口参数：

字段	字段名	类型	是否必填	说明
appid	小程序appid	string	是	必须要和access_token匹配
pay_mode	扣费主体	string	是	门店：PAY_MODE_STORE；小程序:PAY_MODE_APP；服务商：PAY_MODE_COMPONENT

返回参数：

字段	字段名	类型	是否必填	说明
errcode	错误码	int32	是	0:请求成功，其他：请求失败
errmsg	错误信息	string	是

请求参数示例：

{
    "appid":"wx539e0b4872f196d1",
    "pay_mode":"PAY_MODE_APP"
}

返回参数示例：

{
	"errcode": 0,
	"errmsg": "ok"
}

# 2.14. 查询扣费主体

接口简介：查询小程序的扣费主体。

接口地址：https://api.weixin.qq.com/cgi-bin/express/intracity/getpaymode?access_token={ACCESS_TOKEN}

请求参数：

字段	字段名	类型	是否必填	说明
appid	小程序appid	string	是	必须要和access_token匹配

返回参数：

字段	字段名	类型	是否必填	说明
pay_mode	扣费主体	string	是	门店：PAY_MODE_STORE；小程序:PAY_MODE_APP；服务商：PAY_MODE_COMPONENT
pay_appid	扣费appid	string	否	扣费主体为小程序时返回
pay_component_appid	扣费component_appid	string	否	扣费主体为服务商时返回

请求参数示例：

{
    "appid":"wx539e0b4872f196d1"
}

返回参数示例：

{
"pay_mode":"PAY_MODE_APP","pay_appid":"wx539e0b4872f196d1","errcode":0,"errmsg":"ok"
}

# 2.15. 查询支持同城配送的城市

接口简介：用于查询全国可以使用微信同城配送的城市

接口地址：https://api.weixin.qq.com/cgi-bin/express/intracity/getcity?access_token={ACCESS_TOKEN}

请求参数：

字段	字段名	类型	是否必填	说明
service_trans_id	返回指定运力的支持城市信息	string	否	SFTC:顺丰同城，DADA:达达，不传则返回所有结果

返回参数：

字段	字段名	类型	是否必填	说明
errcode	错误码	int32	是	0:请求成功，其他:请求失败
errmsg	错误信息	string	是
support_list	运力支持的城市信息	Array	否	Element的定义详见TransCity

TransCity:

字段	字段名	类型	是否必填	说明
service_trans_id	运力ID	string	是
city_list	城市列表	Array	是	Element定义详见CityInfo

CityInfo:

字段	字段名	类型	是否必填	说明
city_code	城市行政区域编码	uint64	是
city_name	城市名称	string	是

请求示例：

{
	"service_trans_id":"SFTC"
}

返回示例：

{
	"support_list": [{
		"service_trans_id": "SFTC",
		"city_list": [{
				"city_name": "北京市",
				"city_code": 110000
			},
			{
				"city_name": "天津市",
				"city_code": 120000
			}
		]
	}]
}

# 3. 订单状态回调

# 3.1. 回调协议

当订单状态发生变更时，会由微信服回调接入方的回调地址进行状态变更的通知，回调接口地址需要接入方在下单时传入，详见2.8节。

字段	字段名	类型	是否必填	说明
appid	appid	string	是	下单小程序appid
wx_store_id	微信门店id	string	是
wx_order_id	微信订单号	string	是
store_order_id	门店订单号	string	是
order_status	订单状态	uint32	是	详见第四节
status_change_time	订单状态变更时间	uint32	是	秒级时间戳格式
timestamp	消息推送时间	uint32	是	秒级时间戳格式
service_trans_id	运力ID	string	是
sign	签名值	string	是	生成方式详见签名步骤

回调报文示例：

{
    "appid":"wx539e0b4872f19621",
    "order_status":40000,
    "service_trans_id":"DADA",
    "status_change_time":1711458532,
    "store_order_id":"sa5dadada12fd4assdsdad11s",
    "timestamp":1711458532,
    "wx_order_id":"4018734875633256960",
    "wx_store_id":"4000000000000042001",
    "sign":"a85489d9444bdd382e0de0ddca67a8ee"
}

签名步骤: 1.对报文的数据做预处理用=连接key和value组成键值对，按key的ascii码升序排列键值对用&链接,示例如下：

appid=wx539e0b4872f19621&order_status=40000&service_trans_id=DADA&status_change_time=1711458532&store_order_id=sa5dadada12fd4assdsdad11s&timestamp=1711458532&wx_order_id=4018734875633256960&wx_store_id=4000000000000042001

2.拼接小程序的安全token，安全token需要在下单小程序管理后台设置和获取，设置路径：开发管理->开发设置->消息推送->Token

appid=wx539e0b4872f19621&order_status=40000&service_trans_id=DADA&status_change_time=1711458532&store_order_id=sa5dadada12fd4assdsdad11s×tamp=1711458532&wx_order_id=4018734875633256960&wx_store_id=4000000000000042001&token=abcdefghi

3.对第二步中的字符串计算MD5，得到十六进制结果取小写。

to_lower(to_hex(md5(sign_str)))

签名值：a85489d9444bdd382e0de0ddca67a8ee 商家需要回复报文：

{
    "return_code":0,
    "return_msg":"OK"
}

表示应答成功，如果没有接收到正确的请求应答，微信会重试回调。

# 3.2. 模拟回调接口

接口简介：由于测试订单没有快递员接单，不会自动推送订单状态变化回调，为了方便开发者在沙箱环境联调，我们提供了模拟回调接口，针对测试订单开发者可以通过该接口触发3.1的回调。

接口地址：

https://api.weixin.qq.com/cgi-bin/express/intracity/mocknotify?access_token={ACCESS_TOKEN}

请求参数：

字段	字段名	类型	是否必填	说明
wx_order_id	微信订单号	string	否	可以单独使用wx_order_id
wx_store_id	门店ID	string	否	wx_store_id和store_order_id需要成对出现
store_order_id	门店订单号	string	否	wx_store_id和store_order_id需要成对出现
order_status	订单状态	uint32	是	详见订单状态列表

返回参数：

字段	字段名	类型	是否必填	说明
errcode	错误码	int32	是	0:请求成功，其他：请求失败
errmsg	错误信息	string	是

请求参数示例：

{
    "wx_order_id":"2000000000000092001",
    "order_status":30000
}

返回参数示例：

{
    "return_code":0,
    "return_msg":"OK"
}

# 4. 订单状态列表

状态类型	状态名称
10000	订单创建成功
20000	商家取消订单
20001	配送方取消订单
30000	配送员接单
40000	配送员到店
50000	配送中
60000	配送员撤单
70000	配送完成
90000	配送异常

# 5. 物品类型列表

物品类型	类型名称
1	快餐
2	药品
3	百货
6	生鲜
8	酒品
12	文件
13	蛋糕
14	鲜花
15	数码
16	服装
17	汽配
18	珠宝
32	饮料
36	证照
55	宠物用品
56	母婴用品
57	美妆用品
58	家居建材
99	其他

# 6. 运力列表

运力名称	运力ID
达达	DADA
顺丰同城	SFTC

# 7. 错误码列表

错误码	解释
0	请求成功
934000	其他逻辑错误
934001	请求参数有误，详细看错误提示
934002	订单已存在，且订单在处理中,请勿重复添加
934003	运力ID错误
934005	运力预创建订单错误
934006	有在途订单，暂不能退款，请等待配送完成
934007	不是在途订单
934008	门店ID和APPID不匹配
934009	不支持该门店所在城市
934010	重复创建门店，请更换out_store_id
934011	请求签名错误
934012	appid和access_token不匹配
934013	门店余额不足无法下单
934014	运力公司返回了非法金额
934015	余额扣减失败
934016	订单不存在
934017	订单处在不能被取消的状态
934018	订单已取消，请勿重复操作
934019	超出运力支持的配送范围
934020	商品超重
934021	门店不存在
934022	账号类型不可以为个人账号
934023	小程序类型必须为普通小程序
934999	内部系统错误

# 8.常见问题

接口返回48001

{"errcode":48001,"errmsg":"api unauthorized rid: 64a3ce69-21d3dd25-7ce6af58"}

原因是小程序没有获得同城配送接口权限，在小程序管理后台开通【同城配送】后即可

接口返回61007

{"errcode":61007,"errmsg":"api is unauthorized to component rid: 64a3d44c-4d455d2b-6d57b3d3"}

此小程序没有授权当前服务商调用接口权限，服务商需获得小程序的51接口权限集

接口返回934011

{"errcode":934011,"errmsg":"signature is needed, please refer document for help [https://developers.weixin.qq.com/miniprogram/dev/OpenApiDoc/getting_started/api_signature.html] rid: 64dc5f3e-7e245626-0c795d50"}

原因是接口没有带签名验证信息，可以参照微信服务端api签名指南的指引开发，同时社区内也有同行分享的php和java的开发实践经验。

沙箱环境下单接口返回934019 用户超出配送范围解决方法：使用顺丰的沙箱环境环境需要固定的收件人信息（达达没有要求），收件人信息如下

收件人姓名：顺丰同城
收件人手机：13881979410 
收件地址：北京市海淀区学清嘉创大厦A座15层

# 同城配送简介

# 1. 业务模式

# 2. 服务优势

# 3. 用户端流程（配送状态实时通知，提升收货体验）

# 4. 商家端流程（MP/接口两种方式，提升接入灵活性）

# 4.1 小程序MP后台开通服务（小程序MP后台-功能-物流服务-同城配送）

# 4.2 查看详情并签署协议

# 4.3 添加门店（门店名称/电话/地址）

# 4.4 充值门店运费（支持API充值）

# 4.5 查看门店列表（门店名称/地址/运力余额）

# 4.6 管理门店信息（门店/配送偏好/运力余额/交易记录）

# 同城配送开发文档

# 1. API调用规范

# 1.1. 请求方式

# 1.2. 数据格式

# 1.3. 数据签名和加密

# 2. API列表

# 2.0 充值&扣费主体说明

# 2.1. 开通门店权限

# 2.2. 创建门店

# 2.3. 查询门店

# 2.4. 更新门店

# 2.5. 门店运费充值

# 2.6. 门店运费退款

# 2.7. 门店运费流水查询

# 2.8. 门店余额查询

# 2.9. 查询运费

# 2.10. 创建配送单

# 2.11. 查询配送单

# 2.12. 取消配送单

# 2.13. 设置扣费主体

# 2.14. 查询扣费主体

# 2.15. 查询支持同城配送的城市

# 3. 订单状态回调

# 3.1. 回调协议

# 3.2. 模拟回调接口

# 4. 订单状态列表

# 5. 物品类型列表

# 6. 运力列表

# 7. 错误码列表

# 8.常见问题

# 如有开发问题或建议，可前往微信开放社区-微信物流服务 发帖提问讨论，官方工作人员会及时回复。

# 如有开发问题或建议，可前往微信开放社区-微信物流服务发帖提问讨论，官方工作人员会及时回复。