logistics.addOrder

本接口应在服务器端调用,详细说明参见服务端API

本接口支持云调用。需开发者工具版本 >= 1.02.1904090(最新稳定版下载),wx-server-sdk >= 0.4.0

生成运单

调用方式:

HTTPS 调用

请求地址

  1. POST https://api.weixin.qq.com/cgi-bin/express/business/order/add?access_token=ACCESS_TOKEN

请求参数

属性类型默认值必填说明
access_tokenstring接口调用凭证
add_sourcenumber订单来源,0为小程序订单,2为App或H5订单,填2则不发送物流服务通知
wx_appidstringApp或H5的appid,add_source=2时必填,需和开通了物流助手的小程序绑定同一open帐号
order_idstring订单ID,须保证全局唯一,不超过512字节
openidstring用户openid,当add_source=2时无需填写(不发送物流服务通知)
delivery_idstring快递公司ID,参见getAllDelivery
biz_idstring快递客户编码或者现付编码
custom_remarkstring快递备注信息,比如”易碎物品”,不超过1024字节
tagidnumber订单标签id,用于平台型小程序区分平台上的入驻方,tagid须与入驻方账号一一对应,非平台型小程序无需填写该字段
senderObject发件人信息
receiverObject收件人信息
cargoObject包裹信息,将传递给快递公司
shopObject商品信息,会展示到物流服务通知和电子面单中
insuredObject保价信息
serviceObject服务类型
expect_timenumberUnix 时间戳, 单位秒,顺丰必须传。 预期的上门揽件时间,0表示已事先约定取件时间;否则请传预期揽件时间戳,需大于当前时间,收件员会在预期时间附近上门。例如expect_time为“1557989929”,表示希望收件员将在2019年05月16日14:58:49-15:58:49内上门取货。说明:若选择 了预期揽件时间,请不要自己打单,由上门揽件的时候打印。如果是下顺丰散单,则必传此字段,否则不会有收件员上门揽件。

sender 的结构

属性类型默认值必填说明
namestring发件人姓名,不超过64字节
telstring发件人座机号码,若不填写则必须填写 mobile,不超过32字节
mobilestring发件人手机号码,若不填写则必须填写 tel,不超过32字节
companystring发件人公司名称,不超过64字节
post_codestring发件人邮编,不超过10字节
countrystring发件人国家,不超过64字节
provincestring发件人省份,比如:”广东省”,不超过64字节
citystring发件人市/地区,比如:”广州市”,不超过64字节
areastring发件人区/县,比如:”海珠区”,不超过64字节
addressstring发件人详细地址,比如:”XX路XX号XX大厦XX”,不超过512字节

receiver 的结构

属性类型默认值必填说明
namestring收件人姓名,不超过64字节
telstring收件人座机号码,若不填写则必须填写 mobile,不超过32字节
mobilestring收件人手机号码,若不填写则必须填写 tel,不超过32字节
companystring收件人公司名,不超过64字节
post_codestring收件人邮编,不超过10字节
countrystring收件人所在国家,不超过64字节
provincestring收件人省份,比如:”广东省”,不超过64字节
citystring收件人地区/市,比如:”广州市”,不超过64字节
areastring收件人区/县,比如:”天河区”,不超过64字节
addressstring收件人详细地址,比如:”XX路XX号XX大厦XX”,不超过512字节

cargo 的结构

属性类型默认值必填说明
countnumber包裹数量, 需要和detail_list size保持一致
weightnumber包裹总重量,单位是千克(kg)
space_xnumber包裹长度,单位厘米(cm)
space_ynumber包裹宽度,单位厘米(cm)
space_znumber包裹高度,单位厘米(cm)
detail_listArray.<Object>包裹中商品详情列表

cargo.detail_list 的结构

属性类型默认值必填说明
namestring商品名,不超过128字节
countnumber商品数量

shop 的结构

属性类型默认值必填说明
wxa_pathstring商家小程序的路径,建议为订单页面
img_urlstring商品缩略图 url
goods_namestring商品名称, 不超过128字节
goods_countnumber商品数量

insured 的结构

属性类型默认值必填说明
use_insurednumber是否保价,0 表示不保价,1 表示保价
insured_valuenumber保价金额,单位是分,比如: 10000 表示 100 元

service 的结构

属性类型默认值必填说明
service_typenumber服务类型ID,详见已经支持的快递公司基本信息
service_namestring服务名称,详见已经支持的快递公司基本信息

返回值

Object

属性类型说明
order_idstring订单ID,下单成功时返回
waybill_idstring运单ID,下单成功时返回
waybill_dataArray.<Object>运单信息,下单成功时返回
errcodenumber微信侧错误码,下单失败时返回
errmsgstring微信侧错误信息,下单失败时返回
delivery_resultcodenumber快递侧错误码,下单失败时返回
delivery_resultmsgstring快递侧错误信息,下单失败时返回

waybill_data 的结构

属性类型说明
keystring运单信息 key
valuestring运单信息 value

errcode 的合法值

说明最低版本
-1系统失败
47001格式错误
40003openid无效
9300502快递公司系统错误
9300501快递侧逻辑错误,详细原因需要看 delivery_resultcode, 请先确认一下编码方式,python建议 json.dumps(b, ensure_ascii=False),php建议 json_encode($arr, JSON_UNESCAPED_UNICODE)
9300503delivery_id 不存在
9300510service_type 不存在
9300526字段长度不正确
930561参数错误
9300525bizid未绑定
9300534add_source=2时,wx_appid和当前小程序不同主体
9300535shop字段商品缩略图 url、商品名称为空或者非法,或者商品数量为0
9300536add_source=2时,wx_appid无效
9300531bizid无效
930564沙盒环境调用无配额
930559沙盒环境openid无效

请求示例

  1. {
  2. "add_source": 0,
  3. "order_id": "01234567890123456789",
  4. "openid": "oABC123456",
  5. "delivery_id": "SF",
  6. "biz_id": "xyz",
  7. "custom_remark": "易碎物品",
  8. "sender": {
  9. "name": "张三",
  10. "tel": "020-88888888",
  11. "mobile": "18666666666",
  12. "company": "公司名",
  13. "post_code": "123456",
  14. "country": "中国",
  15. "province": "广东省",
  16. "city": "广州市",
  17. "area": "海珠区",
  18. "address": "XX路XX号XX大厦XX栋XX"
  19. },
  20. "receiver": {
  21. "name": "王小蒙",
  22. "tel": "020-77777777",
  23. "mobile": "18610000000",
  24. "company": "公司名",
  25. "post_code": "654321",
  26. "country": "中国",
  27. "province": "广东省",
  28. "city": "广州市",
  29. "area": "天河区",
  30. "address": "XX路XX号XX大厦XX栋XX"
  31. },
  32. "shop": {
  33. "wxa_path": "/index/index?from=waybill&id=01234567890123456789",
  34. "img_url": "https://mmbiz.qpic.cn/mmbiz_png/OiaFLUqewuIDNQnTiaCInIG8ibdosYHhQHPbXJUrqYSNIcBL60vo4LIjlcoNG1QPkeH5GWWEB41Ny895CokeAah8A/640",
  35. "goods_name": "微信气泡狗抱枕&微信气泡狗钥匙扣",
  36. "goods_count": 2
  37. },
  38. "cargo": {
  39. "count": 2,
  40. "weight": 5.5,
  41. "space_x": 30.5,
  42. "space_y": 20,
  43. "space_z": 20,
  44. "detail_list": [
  45. {
  46. "name": "微信气泡狗抱枕",
  47. "count": 1
  48. },
  49. {
  50. "name": "微信气泡狗钥匙扣",
  51. "count": 1
  52. }
  53. ]
  54. },
  55. "insured": {
  56. "use_insured": 1,
  57. "insured_value": 10000
  58. },
  59. "service": {
  60. "service_type": 0,
  61. "service_name": "标准快递"
  62. }
  63. }

返回示例

下单成功

  1. {
  2. "order_id": "01234567890123456789",
  3. "waybill_id": "123456789",
  4. "waybill_data": [
  5. {
  6. "key": "SF_bagAddr",
  7. "value": "广州"
  8. },
  9. {
  10. "key": "SF_mark",
  11. "value": "101- 07-03 509"
  12. }
  13. ]
  14. }

下单失败

  1. {
  2. "errcode": 9300501,
  3. "errmsg": "delivery logic fail",
  4. "delivery_resultcode": 10002,
  5. "delivery_resultmsg": "客户密码不正确"
  6. }

云调用

云调用是小程序·云开发提供的在云函数中调用微信开放接口的能力,需要在云函数中通过 wx-server-sdk 使用。

接口方法

  1. openapi.logistics.addOrder

需在 config.json 中配置 logistics.addOrder API 的权限,详情

请求参数

属性类型默认值必填说明
addSourcenumber订单来源,0为小程序订单,2为App或H5订单,填2则不发送物流服务通知
wxAppidstringApp或H5的appid,add_source=2时必填,需和开通了物流助手的小程序绑定同一open帐号
orderIdstring订单ID,须保证全局唯一,不超过512字节
openidstring用户openid,当add_source=2时无需填写(不发送物流服务通知)
deliveryIdstring快递公司ID,参见getAllDelivery
bizIdstring快递客户编码或者现付编码
customRemarkstring快递备注信息,比如”易碎物品”,不超过1024字节
tagidnumber订单标签id,用于平台型小程序区分平台上的入驻方,tagid须与入驻方账号一一对应,非平台型小程序无需填写该字段
senderObject发件人信息
receiverObject收件人信息
cargoObject包裹信息,将传递给快递公司
shopObject商品信息,会展示到物流服务通知和电子面单中
insuredObject保价信息
serviceObject服务类型
expectTimenumberUnix 时间戳, 单位秒,顺丰必须传。 预期的上门揽件时间,0表示已事先约定取件时间;否则请传预期揽件时间戳,需大于当前时间,收件员会在预期时间附近上门。例如expect_time为“1557989929”,表示希望收件员将在2019年05月16日14:58:49-15:58:49内上门取货。说明:若选择 了预期揽件时间,请不要自己打单,由上门揽件的时候打印。如果是下顺丰散单,则必传此字段,否则不会有收件员上门揽件。

sender 的结构

属性类型默认值必填说明
namestring发件人姓名,不超过64字节
telstring发件人座机号码,若不填写则必须填写 mobile,不超过32字节
mobilestring发件人手机号码,若不填写则必须填写 tel,不超过32字节
companystring发件人公司名称,不超过64字节
postCodestring发件人邮编,不超过10字节
countrystring发件人国家,不超过64字节
provincestring发件人省份,比如:”广东省”,不超过64字节
citystring发件人市/地区,比如:”广州市”,不超过64字节
areastring发件人区/县,比如:”海珠区”,不超过64字节
addressstring发件人详细地址,比如:”XX路XX号XX大厦XX”,不超过512字节

receiver 的结构

属性类型默认值必填说明
namestring收件人姓名,不超过64字节
telstring收件人座机号码,若不填写则必须填写 mobile,不超过32字节
mobilestring收件人手机号码,若不填写则必须填写 tel,不超过32字节
companystring收件人公司名,不超过64字节
postCodestring收件人邮编,不超过10字节
countrystring收件人所在国家,不超过64字节
provincestring收件人省份,比如:”广东省”,不超过64字节
citystring收件人地区/市,比如:”广州市”,不超过64字节
areastring收件人区/县,比如:”天河区”,不超过64字节
addressstring收件人详细地址,比如:”XX路XX号XX大厦XX”,不超过512字节

cargo 的结构

属性类型默认值必填说明
countnumber包裹数量, 需要和detail_list size保持一致
weightnumber包裹总重量,单位是千克(kg)
spaceXnumber包裹长度,单位厘米(cm)
spaceYnumber包裹宽度,单位厘米(cm)
spaceZnumber包裹高度,单位厘米(cm)
detailListArray.<Object>包裹中商品详情列表

cargo.detailList 的结构

属性类型默认值必填说明
namestring商品名,不超过128字节
countnumber商品数量

shop 的结构

属性类型默认值必填说明
wxaPathstring商家小程序的路径,建议为订单页面
imgUrlstring商品缩略图 url
goodsNamestring商品名称, 不超过128字节
goodsCountnumber商品数量

insured 的结构

属性类型默认值必填说明
useInsurednumber是否保价,0 表示不保价,1 表示保价
insuredValuenumber保价金额,单位是分,比如: 10000 表示 100 元

service 的结构

属性类型默认值必填说明
serviceTypenumber服务类型ID,详见已经支持的快递公司基本信息
serviceNamestring服务名称,详见已经支持的快递公司基本信息

返回值

Object

属性类型说明
orderIdstring订单ID,下单成功时返回
waybillIdstring运单ID,下单成功时返回
waybillDataArray.<Object>运单信息,下单成功时返回
errCodenumber微信侧错误码,下单失败时返回
errMsgstring微信侧错误信息,下单失败时返回
deliveryResultcodenumber快递侧错误码,下单失败时返回
deliveryResultmsgstring快递侧错误信息,下单失败时返回

waybillData 的结构

属性类型说明
keystring运单信息 key
valuestring运单信息 value

errCode 的合法值

说明最低版本
0成功

异常

Object

抛出的异常

属性类型说明
errCodenumber微信侧错误码,下单失败时返回
errMsgstring微信侧错误信息,下单失败时返回

errCode 的合法值

说明最低版本
-1系统失败
47001格式错误
40003openid无效
9300502快递公司系统错误
9300501快递侧逻辑错误,详细原因需要看 delivery_resultcode, 请先确认一下编码方式,python建议 json.dumps(b, ensure_ascii=False),php建议 json_encode($arr, JSON_UNESCAPED_UNICODE)
9300503delivery_id 不存在
9300510service_type 不存在
9300526字段长度不正确
930561参数错误
9300525bizid未绑定
9300534add_source=2时,wx_appid和当前小程序不同主体
9300535shop字段商品缩略图 url、商品名称为空或者非法,或者商品数量为0
9300536add_source=2时,wx_appid无效
9300531bizid无效
930564沙盒环境调用无配额
930559沙盒环境openid无效

请求示例

  1. const cloud = require('wx-server-sdk')
  2. cloud.init({
  3. env: cloud.DYNAMIC_CURRENT_ENV,
  4. })
  5. exports.main = async (event, context) => {
  6. try {
  7. const result = await cloud.openapi.logistics.addOrder({
  8. openid: 'oABC123456',
  9. sender: {
  10. name: '张三',
  11. tel: '020-88888888',
  12. mobile: '18666666666',
  13. company: '公司名',
  14. country: '中国',
  15. province: '广东省',
  16. city: '广州市',
  17. area: '海珠区',
  18. address: 'XX路XX号XX大厦XX栋XX',
  19. postCode: '123456'
  20. },
  21. receiver: {
  22. name: '王小蒙',
  23. tel: '020-77777777',
  24. mobile: '18610000000',
  25. company: '公司名',
  26. country: '中国',
  27. province: '广东省',
  28. city: '广州市',
  29. area: '天河区',
  30. address: 'XX路XX号XX大厦XX栋XX',
  31. postCode: '654321'
  32. },
  33. shop: {
  34. wxaPath: '/index/index?from=waybill&id=01234567890123456789',
  35. imgUrl: 'https://mmbiz.qpic.cn/mmbiz_png/OiaFLUqewuIDNQnTiaCInIG8ibdosYHhQHPbXJUrqYSNIcBL60vo4LIjlcoNG1QPkeH5GWWEB41Ny895CokeAah8A/640',
  36. goodsName: '微信气泡狗抱枕&微信气泡狗钥匙扣',
  37. goodsCount: 2
  38. },
  39. cargo: {
  40. count: 2,
  41. weight: 5.5,
  42. spaceX: 30.5,
  43. spaceY: 20,
  44. spaceZ: 20,
  45. detailList: [
  46. {
  47. name: '微信气泡狗抱枕',
  48. count: 1
  49. },
  50. {
  51. name: '微信气泡狗钥匙扣',
  52. count: 1
  53. }
  54. ]
  55. },
  56. insured: {
  57. useInsured: 1,
  58. insuredValue: 10000
  59. },
  60. service: {
  61. serviceType: 0,
  62. serviceName: '标准快递'
  63. },
  64. addSource: 0,
  65. orderId: '01234567890123456789',
  66. deliveryId: 'SF',
  67. bizId: 'xyz',
  68. customRemark: '易碎物品'
  69. })
  70. return result
  71. } catch (err) {
  72. return err
  73. }
  74. }

返回示例

下单成功

  1. {
  2. "orderId": "01234567890123456789",
  3. "waybillId": "123456789",
  4. "waybillData": [
  5. {
  6. "key": "SF_bagAddr",
  7. "value": "广州"
  8. },
  9. {
  10. "key": "SF_mark",
  11. "value": "101- 07-03 509"
  12. }
  13. ],
  14. "errMsg": "openapi.logistics.addOrder:ok"
  15. }

下单失败

  1. {
  2. "errCode": 9300501,
  3. "errMsg": "openapi.logistics.addOrder:fail delivery logic fail",
  4. "deliveryResultcode": 10002,
  5. "deliveryResultmsg": "客户密码不正确"
  6. }