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_appidstring否App或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_timenumber否顺丰必须传。 预期的上门揽件时间，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是商品名称
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系统失败
9300501快递侧逻辑错误，详细原因需要看 delivery_resultcode
9300503delivery_id 不存在
9300510service_type 不存在
9300526字段长度不正确
9300535shop字段商品缩略图 url、商品名称为空或者非法，或者商品数量为0

请求示例

  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则不发送物流服务通知
wxAppidstring否App或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是服务类型
expectTimenumber否顺丰必须传。 预期的上门揽件时间，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是商品名称
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系统失败
9300501快递侧逻辑错误，详细原因需要看 delivery_resultcode
9300503delivery_id 不存在
9300510service_type 不存在
9300526字段长度不正确
9300535shop字段商品缩略图 url、商品名称为空或者非法，或者商品数量为0

请求示例

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