微信小程序 小程序使用·addOrder

2022-05-11 15:09 更新

logistics.addOrder

本接口應(yīng)在服務(wù)器端調(diào)用,詳細(xì)說(shuō)明參見(jiàn)服務(wù)端API。
本接口支持云調(diào)用。需開(kāi)發(fā)者工具版本 >= 1.02.1904090(最新穩(wěn)定版下載
wx-server-sdk >= 0.4.0

生成運(yùn)單

調(diào)用方式:

  • HTTPS 調(diào)用
  • 云調(diào)用

HTTPS 調(diào)用

請(qǐng)求地址

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

請(qǐng)求參數(shù)

屬性 類型 默認(rèn)值 必填 說(shuō)明
access_token string 接口調(diào)用憑證
add_source number 訂單來(lái)源,0為小程序訂單,2為App或H5訂單,填2則不發(fā)送物流服務(wù)通知
wx_appid string App或H5的appid,add_source=2時(shí)必填,需和開(kāi)通了物流助手的小程序綁定同一open帳號(hào)
order_id string 訂單ID,須保證全局唯一,不超過(guò)512字節(jié)
openid string 用戶openid,當(dāng)add_source=2時(shí)無(wú)需填寫(xiě)(不發(fā)送物流服務(wù)通知)
delivery_id string 快遞公司ID,參見(jiàn)getAllDelivery
biz_id string 快遞客戶編碼或者現(xiàn)付編碼
custom_remark string 快遞備注信息,比如"易碎物品",不超過(guò)1024字節(jié)
tagid number 訂單標(biāo)簽id,用于平臺(tái)型小程序區(qū)分平臺(tái)上的入駐方,tagid須與入駐方賬號(hào)一一對(duì)應(yīng),非平臺(tái)型小程序無(wú)需填寫(xiě)該字段
sender Object 發(fā)件人信息
receiver Object 收件人信息
cargo Object 包裹信息,將傳遞給快遞公司
shop Object 商品信息,會(huì)展示到物流服務(wù)通知和電子面單中
insured Object 保價(jià)信息
service Object 服務(wù)類型
expect_time number Unix 時(shí)間戳, 單位秒,順豐必須傳。 預(yù)期的上門(mén)攬件時(shí)間,0表示已事先約定取件時(shí)間;否則請(qǐng)傳預(yù)期攬件時(shí)間戳,需大于當(dāng)前時(shí)間,收件員會(huì)在預(yù)期時(shí)間附近上門(mén)。例如expect_time為“1557989929”,表示希望收件員將在2019年05月16日14:58:49-15:58:49內(nèi)上門(mén)取貨。說(shuō)明:若選擇 了預(yù)期攬件時(shí)間,請(qǐng)不要自己打單,由上門(mén)攬件的時(shí)候打印。如果是下順豐散單,則必傳此字段,否則不會(huì)有收件員上門(mén)攬件。

sender 的結(jié)構(gòu)

屬性 類型 默認(rèn)值 必填 說(shuō)明
name string 發(fā)件人姓名,不超過(guò)64字節(jié)
tel string 發(fā)件人座機(jī)號(hào)碼,若不填寫(xiě)則必須填寫(xiě) mobile,不超過(guò)32字節(jié)
mobile string 發(fā)件人手機(jī)號(hào)碼,若不填寫(xiě)則必須填寫(xiě) tel,不超過(guò)32字節(jié)
company string 發(fā)件人公司名稱,不超過(guò)64字節(jié)
post_code string 發(fā)件人郵編,不超過(guò)10字節(jié)
country string 發(fā)件人國(guó)家,不超過(guò)64字節(jié)
province string 發(fā)件人省份,比如:"廣東省",不超過(guò)64字節(jié)
city string 發(fā)件人市/地區(qū),比如:"廣州市",不超過(guò)64字節(jié)
area string 發(fā)件人區(qū)/縣,比如:"海珠區(qū)",不超過(guò)64字節(jié)
address string 發(fā)件人詳細(xì)地址,比如:"XX路XX號(hào)XX大廈XX",不超過(guò)512字節(jié)

receiver 的結(jié)構(gòu)

屬性 類型 默認(rèn)值 必填 說(shuō)明
name string 收件人姓名,不超過(guò)64字節(jié)
tel string 收件人座機(jī)號(hào)碼,若不填寫(xiě)則必須填寫(xiě) mobile,不超過(guò)32字節(jié)
mobile string 收件人手機(jī)號(hào)碼,若不填寫(xiě)則必須填寫(xiě) tel,不超過(guò)32字節(jié)
company string 收件人公司名,不超過(guò)64字節(jié)
post_code string 收件人郵編,不超過(guò)10字節(jié)
country string 收件人所在國(guó)家,不超過(guò)64字節(jié)
province string 收件人省份,比如:"廣東省",不超過(guò)64字節(jié)
city string 收件人地區(qū)/市,比如:"廣州市",不超過(guò)64字節(jié)
area string 收件人區(qū)/縣,比如:"天河區(qū)",不超過(guò)64字節(jié)
address string 收件人詳細(xì)地址,比如:"XX路XX號(hào)XX大廈XX",不超過(guò)512字節(jié)

cargo 的結(jié)構(gòu)

屬性 類型 默認(rèn)值 必填 說(shuō)明
count number 包裹數(shù)量, 需要和detail_list size保持一致
weight number 包裹總重量,單位是千克(kg)
space_x number 包裹長(zhǎng)度,單位厘米(cm)
space_y number 包裹寬度,單位厘米(cm)
space_z number 包裹高度,單位厘米(cm)
detail_list Array.<Object> 包裹中商品詳情列表

cargo.detail_list 的結(jié)構(gòu)

屬性 類型 默認(rèn)值 必填 說(shuō)明
name string 商品名,不超過(guò)128字節(jié)
count number 商品數(shù)量

shop 的結(jié)構(gòu)

屬性 類型 默認(rèn)值 必填 說(shuō)明
wxa_path string 商家小程序的路徑,建議為訂單頁(yè)面
img_url string 商品縮略圖 url
goods_name string 商品名稱, 不超過(guò)128字節(jié)
goods_count number 商品數(shù)量

insured 的結(jié)構(gòu)

屬性 類型 默認(rèn)值 必填 說(shuō)明
use_insured number 是否保價(jià),0 表示不保價(jià),1 表示保價(jià)
insured_value number 保價(jià)金額,單位是分,比如: 10000 表示 100 元

service 的結(jié)構(gòu)

屬性 類型 默認(rèn)值 必填 說(shuō)明
service_type number 服務(wù)類型ID,詳見(jiàn)已經(jīng)支持的快遞公司基本信息
service_name string 服務(wù)名稱,詳見(jiàn)已經(jīng)支持的快遞公司基本信息

返回值

Object

屬性 類型 說(shuō)明
order_id string 訂單ID,下單成功時(shí)返回
waybill_id string 運(yùn)單ID,下單成功時(shí)返回
waybill_data Array.<Object> 運(yùn)單信息,下單成功時(shí)返回
errcode number 微信側(cè)錯(cuò)誤碼,下單失敗時(shí)返回
errmsg string 微信側(cè)錯(cuò)誤信息,下單失敗時(shí)返回
delivery_resultcode number 快遞側(cè)錯(cuò)誤碼,下單失敗時(shí)返回
delivery_resultmsg string 快遞側(cè)錯(cuò)誤信息,下單失敗時(shí)返回

waybill_data 的結(jié)構(gòu)

屬性 類型 說(shuō)明
key string 運(yùn)單信息 key
value string 運(yùn)單信息 value

errcode 的合法值

說(shuō)明 最低版本
-1 系統(tǒng)失敗
47001 格式錯(cuò)誤
40003 openid無(wú)效
9300502 快遞公司系統(tǒng)錯(cuò)誤
9300501 快遞側(cè)邏輯錯(cuò)誤,詳細(xì)原因需要看 delivery_resultcode, 請(qǐng)先確認(rèn)一下編碼方式,python建議 json.dumps(b, ensure_ascii=False),php建議 json_encode($arr, JSON_UNESCAPED_UNICODE)
9300503 delivery_id 不存在
9300510 service_type 不存在
9300526 字段長(zhǎng)度不正確
930561 參數(shù)錯(cuò)誤
9300525 bizid未綁定
9300534 add_source=2時(shí),wx_appid和當(dāng)前小程序不同主體
9300535 shop字段商品縮略圖 url、商品名稱為空或者非法,或者商品數(shù)量為0
9300536 add_source=2時(shí),wx_appid無(wú)效
9300531 bizid無(wú)效
930564 沙盒環(huán)境調(diào)用無(wú)配額
930559 沙盒環(huán)境openid無(wú)效

請(qǐng)求示例

{
  "add_source": 0,
  "order_id": "01234567890123456789",
  "openid": "oABC123456",
  "delivery_id": "SF",
  "biz_id": "xyz",
  "custom_remark": "易碎物品",
  "sender": {
    "name": "張三",
    "tel": "020-88888888",
    "mobile": "18666666666",
    "company": "公司名",
    "post_code": "123456",
    "country": "中國(guó)",
    "province": "廣東省",
    "city": "廣州市",
    "area": "海珠區(qū)",
    "address": "XX路XX號(hào)XX大廈XX棟XX"
  },
  "receiver": {
    "name": "王小蒙",
    "tel": "020-77777777",
    "mobile": "18610000000",
    "company": "公司名",
    "post_code": "654321",
    "country": "中國(guó)",
    "province": "廣東省",
    "city": "廣州市",
    "area": "天河區(qū)",
    "address": "XX路XX號(hào)XX大廈XX棟XX"
  },
  "shop": {
    "wxa_path": "/index/index?from=waybill&id=01234567890123456789",
    "img_url": "https://mmbiz.qpic.cn/mmbiz_png/OiaFLUqewuIDNQnTiaCInIG8ibdosYHhQHPbXJUrqYSNIcBL60vo4LIjlcoNG1QPkeH5GWWEB41Ny895CokeAah8A/640",
    "goods_name": "微信氣泡狗抱枕&微信氣泡狗鑰匙扣",
    "goods_count": 2
  },
  "cargo": {
    "count": 2,
    "weight": 5.5,
    "space_x": 30.5,
    "space_y": 20,
    "space_z": 20,
    "detail_list": [
      {
        "name": "微信氣泡狗抱枕",
        "count": 1
      },
      {
        "name": "微信氣泡狗鑰匙扣",
        "count": 1
      }
    ]
  },
  "insured": {
    "use_insured": 1,
    "insured_value": 10000
  },
  "service": {
    "service_type": 0,
    "service_name": "標(biāo)準(zhǔn)快遞"
  }
}

返回示例

下單成功

{
  "order_id": "01234567890123456789",
  "waybill_id": "123456789",
  "waybill_data": [
    {
      "key": "SF_bagAddr",
      "value": "廣州"
    },
    {
      "key": "SF_mark",
      "value": "101- 07-03 509"
    }
  ]
}

下單失敗

{
  "errcode": 9300501,
  "errmsg": "delivery logic fail",
  "delivery_resultcode": 10002,
  "delivery_resultmsg": "客戶密碼不正確"
}

云調(diào)用

云調(diào)用是小程序·云開(kāi)發(fā)提供的在云函數(shù)中調(diào)用微信開(kāi)放接口的能力,需要在云函數(shù)中通過(guò) wx-server-sdk 使用。

接口方法

openapi.logistics.addOrder
需在 config.json 中配置 logistics.addOrder API 的權(quán)限,詳情

請(qǐng)求參數(shù)

屬性 類型 默認(rèn)值 必填 說(shuō)明
addSource number 訂單來(lái)源,0為小程序訂單,2為App或H5訂單,填2則不發(fā)送物流服務(wù)通知
wxAppid string App或H5的appid,add_source=2時(shí)必填,需和開(kāi)通了物流助手的小程序綁定同一open帳號(hào)
orderId string 訂單ID,須保證全局唯一,不超過(guò)512字節(jié)
openid string 用戶openid,當(dāng)add_source=2時(shí)無(wú)需填寫(xiě)(不發(fā)送物流服務(wù)通知)
deliveryId string 快遞公司ID,參見(jiàn)getAllDelivery
bizId string 快遞客戶編碼或者現(xiàn)付編碼
customRemark string 快遞備注信息,比如"易碎物品",不超過(guò)1024字節(jié)
tagid number 訂單標(biāo)簽id,用于平臺(tái)型小程序區(qū)分平臺(tái)上的入駐方,tagid須與入駐方賬號(hào)一一對(duì)應(yīng),非平臺(tái)型小程序無(wú)需填寫(xiě)該字段
sender Object 發(fā)件人信息
receiver Object 收件人信息
cargo Object 包裹信息,將傳遞給快遞公司
shop Object 商品信息,會(huì)展示到物流服務(wù)通知和電子面單中
insured Object 保價(jià)信息
service Object 服務(wù)類型
expectTime number Unix 時(shí)間戳, 單位秒,順豐必須傳。 預(yù)期的上門(mén)攬件時(shí)間,0表示已事先約定取件時(shí)間;否則請(qǐng)傳預(yù)期攬件時(shí)間戳,需大于當(dāng)前時(shí)間,收件員會(huì)在預(yù)期時(shí)間附近上門(mén)。例如expect_time為“1557989929”,表示希望收件員將在2019年05月16日14:58:49-15:58:49內(nèi)上門(mén)取貨。說(shuō)明:若選擇 了預(yù)期攬件時(shí)間,請(qǐng)不要自己打單,由上門(mén)攬件的時(shí)候打印。如果是下順豐散單,則必傳此字段,否則不會(huì)有收件員上門(mén)攬件。

sender 的結(jié)構(gòu)

屬性 類型 默認(rèn)值 必填 說(shuō)明
name string 發(fā)件人姓名,不超過(guò)64字節(jié)
tel string 發(fā)件人座機(jī)號(hào)碼,若不填寫(xiě)則必須填寫(xiě) mobile,不超過(guò)32字節(jié)
mobile string 發(fā)件人手機(jī)號(hào)碼,若不填寫(xiě)則必須填寫(xiě) tel,不超過(guò)32字節(jié)
company string 發(fā)件人公司名稱,不超過(guò)64字節(jié)
postCode string 發(fā)件人郵編,不超過(guò)10字節(jié)
country string 發(fā)件人國(guó)家,不超過(guò)64字節(jié)
province string 發(fā)件人省份,比如:"廣東省",不超過(guò)64字節(jié)
city string 發(fā)件人市/地區(qū),比如:"廣州市",不超過(guò)64字節(jié)
area string 發(fā)件人區(qū)/縣,比如:"海珠區(qū)",不超過(guò)64字節(jié)
address string 發(fā)件人詳細(xì)地址,比如:"XX路XX號(hào)XX大廈XX",不超過(guò)512字節(jié)

receiver 的結(jié)構(gòu)

屬性 類型 默認(rèn)值 必填 說(shuō)明
name string 收件人姓名,不超過(guò)64字節(jié)
tel string 收件人座機(jī)號(hào)碼,若不填寫(xiě)則必須填寫(xiě) mobile,不超過(guò)32字節(jié)
mobile string 收件人手機(jī)號(hào)碼,若不填寫(xiě)則必須填寫(xiě) tel,不超過(guò)32字節(jié)
company string 收件人公司名,不超過(guò)64字節(jié)
postCode string 收件人郵編,不超過(guò)10字節(jié)
country string 收件人所在國(guó)家,不超過(guò)64字節(jié)
province string 收件人省份,比如:"廣東省",不超過(guò)64字節(jié)
city string 收件人地區(qū)/市,比如:"廣州市",不超過(guò)64字節(jié)
area string 收件人區(qū)/縣,比如:"天河區(qū)",不超過(guò)64字節(jié)
address string 收件人詳細(xì)地址,比如:"XX路XX號(hào)XX大廈XX",不超過(guò)512字節(jié)

cargo 的結(jié)構(gòu)

屬性 類型 默認(rèn)值 必填 說(shuō)明
count number 包裹數(shù)量, 需要和detail_list size保持一致
weight number 包裹總重量,單位是千克(kg)
spaceX number 包裹長(zhǎng)度,單位厘米(cm)
spaceY number 包裹寬度,單位厘米(cm)
spaceZ number 包裹高度,單位厘米(cm)
detailList Array.<Object> 包裹中商品詳情列表

cargo.detailList 的結(jié)構(gòu)

屬性 類型 默認(rèn)值 必填 說(shuō)明
name string 商品名,不超過(guò)128字節(jié)
count number 商品數(shù)量

shop 的結(jié)構(gòu)

屬性 類型 默認(rèn)值 必填 說(shuō)明
wxaPath string 商家小程序的路徑,建議為訂單頁(yè)面
imgUrl string 商品縮略圖 url
goodsName string 商品名稱, 不超過(guò)128字節(jié)
goodsCount number 商品數(shù)量

insured 的結(jié)構(gòu)

屬性 類型 默認(rèn)值 必填 說(shuō)明
useInsured number 是否保價(jià),0 表示不保價(jià),1 表示保價(jià)
insuredValue number 保價(jià)金額,單位是分,比如: 10000 表示 100 元

service 的結(jié)構(gòu)

屬性 類型 默認(rèn)值 必填 說(shuō)明
serviceType number 服務(wù)類型ID,詳見(jiàn)已經(jīng)支持的快遞公司基本信息
serviceName string 服務(wù)名稱,詳見(jiàn)已經(jīng)支持的快遞公司基本信息

返回值

Object

屬性 類型 說(shuō)明
orderId string 訂單ID,下單成功時(shí)返回
waybillId string 運(yùn)單ID,下單成功時(shí)返回
waybillData Array.<Object> 運(yùn)單信息,下單成功時(shí)返回
errCode number 微信側(cè)錯(cuò)誤碼,下單失敗時(shí)返回
errMsg string 微信側(cè)錯(cuò)誤信息,下單失敗時(shí)返回
deliveryResultcode number 快遞側(cè)錯(cuò)誤碼,下單失敗時(shí)返回
deliveryResultmsg string 快遞側(cè)錯(cuò)誤信息,下單失敗時(shí)返回

waybillData 的結(jié)構(gòu)

屬性 類型 說(shuō)明
key string 運(yùn)單信息 key
value string 運(yùn)單信息 value

errCode 的合法值

說(shuō)明 最低版本
0 成功

異常

Object

拋出的異常

屬性 類型 說(shuō)明
errCode number 微信側(cè)錯(cuò)誤碼,下單失敗時(shí)返回
errMsg string 微信側(cè)錯(cuò)誤信息,下單失敗時(shí)返回

errCode 的合法值

說(shuō)明 最低版本
-1 系統(tǒng)失敗
47001 格式錯(cuò)誤
40003 openid無(wú)效
9300502 快遞公司系統(tǒng)錯(cuò)誤
9300501 快遞側(cè)邏輯錯(cuò)誤,詳細(xì)原因需要看 delivery_resultcode, 請(qǐng)先確認(rèn)一下編碼方式,python建議 json.dumps(b, ensure_ascii=False),php建議 json_encode($arr, JSON_UNESCAPED_UNICODE)
9300503 delivery_id 不存在
9300510 service_type 不存在
9300526 字段長(zhǎng)度不正確
930561 參數(shù)錯(cuò)誤
9300525 bizid未綁定
9300534 add_source=2時(shí),wx_appid和當(dāng)前小程序不同主體
9300535 shop字段商品縮略圖 url、商品名稱為空或者非法,或者商品數(shù)量為0
9300536 add_source=2時(shí),wx_appid無(wú)效
9300531 bizid無(wú)效
930564 沙盒環(huán)境調(diào)用無(wú)配額
930559 沙盒環(huán)境openid無(wú)效

請(qǐng)求示例

const cloud = require('wx-server-sdk')
cloud.init()
exports.main = async (event, context) => {
  try {
    const result = await cloud.openapi.logistics.addOrder({
        openid: 'oABC123456',
        sender: {
          name: '張三',
          tel: '020-88888888',
          mobile: '18666666666',
          company: '公司名',
          country: '中國(guó)',
          province: '廣東省',
          city: '廣州市',
          area: '海珠區(qū)',
          address: 'XX路XX號(hào)XX大廈XX棟XX',
          postCode: '123456'
        },
        receiver: {
          name: '王小蒙',
          tel: '020-77777777',
          mobile: '18610000000',
          company: '公司名',
          country: '中國(guó)',
          province: '廣東省',
          city: '廣州市',
          area: '天河區(qū)',
          address: 'XX路XX號(hào)XX大廈XX棟XX',
          postCode: '654321'
        },
        shop: {
          wxaPath: '/index/index?from=waybill&id=01234567890123456789',
          imgUrl: 'https://mmbiz.qpic.cn/mmbiz_png/OiaFLUqewuIDNQnTiaCInIG8ibdosYHhQHPbXJUrqYSNIcBL60vo4LIjlcoNG1QPkeH5GWWEB41Ny895CokeAah8A/640',
          goodsName: '微信氣泡狗抱枕&微信氣泡狗鑰匙扣',
          goodsCount: 2
        },
        cargo: {
          count: 2,
          weight: 5.5,
          spaceX: 30.5,
          spaceY: 20,
          spaceZ: 20,
          detailList: [
            {
              name: '微信氣泡狗抱枕',
              count: 1
            },
            {
              name: '微信氣泡狗鑰匙扣',
              count: 1
            }
          ]
        },
        insured: {
          useInsured: 1,
          insuredValue: 10000
        },
        service: {
          serviceType: 0,
          serviceName: '標(biāo)準(zhǔn)快遞'
        },
        addSource: 0,
        orderId: '01234567890123456789',
        deliveryId: 'SF',
        bizId: 'xyz',
        customRemark: '易碎物品'
      })
    return result
  } catch (err) {
    return err
  }
}

返回示例

下單成功

{
  "orderId": "01234567890123456789",
  "waybillId": "123456789",
  "waybillData": [
    {
      "key": "SF_bagAddr",
      "value": "廣州"
    },
    {
      "key": "SF_mark",
      "value": "101- 07-03 509"
    }
  ],
  "errMsg": "openapi.logistics.addOrder:ok"
}

下單失敗

{
  "errCode": 9300501,
  "errMsg": "openapi.logistics.addOrder:fail delivery logic fail",
  "deliveryResultcode": 10002,
  "deliveryResultmsg": "客戶密碼不正確"
}


以上內(nèi)容是否對(duì)您有幫助:
在線筆記
App下載
App下載

掃描二維碼

下載編程獅App

公眾號(hào)
微信公眾號(hào)

編程獅公眾號(hào)