# 同城配送简介
微信同城配送是整合了多家运力公司后提供的聚合配送服务。商家通过微信充值并对接同城配送接口后即可下配送单,解决外卖配送需求。
# 1. 业务模式
# 2. 服务优势
- 充值即可拥有多家运力公司的服务。
- 配送价格优惠,1公里起送价¥4.32起。
- 配送状态通过微信服务通知实时下发给用户,提升收货体验。
# 3. 用户端流程(配送状态实时通知,提升收货体验)
# 4. 商家端流程(MP/接口两种方式,提升接入灵活性)
# 4.1 小程序MP后台开通服务(小程序MP后台-功能-物流服务-同城配送)
# 4.2 查看详情并签署协议
# 4.3 添加门店(门店名称/电话/地址)
# 4.4 充值门店运费(支持API充值)
如选择接口充值,则需商家传入门店id、运力、金额,平台返回充值url。 充值后有效期30天,到期未使用余额自动原路退回。 充值运力后可设置运力偏好:价格优先(优先下单低价运力);运力优先(优先下单某个运力)。
# 4.5 查看门店列表(门店名称/地址/运力余额)
# 4.6 管理门店信息(门店/配送偏好/运力余额/交易记录)
# 同城配送开发文档
# 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加密,如下图为没有开启加密的状态!!!
对于服务商开发者,可前往开放平台-管理中心-第三方平台-详情-开发配置-开发资料-API安全配置-查看详情 配置密钥和公钥。
# 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:充值流水,
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×tamp=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层