# 同城配送简介

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

# 1. 业务模式

#60%

# 2. 服务优势

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

# 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 充值&扣费主体说明

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

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

# 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签名指南的指引开发,同时社区内也有同行分享的phpjava的开发实践经验。

  • 沙箱环境下单接口返回934019 用户超出配送范围 解决方法:使用顺丰的沙箱环境环境需要固定的收件人信息(达达没有要求),收件人信息如下
收件人姓名:顺丰同城
收件人手机:13881979410 
收件地址:北京市海淀区学清嘉创大厦A座15层

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