# 生成运单

接口应在服务器端调用，不可在前端（小程序、网页、APP等）直接调用，具体可参考接口调用指南

接口英文名：addOrder

该接口用于生成运单。

# 1. 调用方式

# HTTPS 调用

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

# 云调用

调用方法：logistics.addOrder
出入参和 HTTPS 调用相同，调用方式可查看云调用说明文档

# 第三方调用

本接口支持第三方平台代商家调用。
该接口所属的权限集 id 为：45、71
服务商获得其中之一权限集授权后，可通过使用 authorizer_access_token 代商家进行调用，具体可查看第三方调用说明文档。

# 2. 请求参数

# 查询参数 `Query String parameters`

参数名	类型	必填	说明
access_token	string	是	接口调用凭证，可使用 access_token、authorizer_access_token

# 请求体 `Request Payload`

参数名	类型	必填	说明
order_id	string	是	订单ID，须保证全局唯一，不超过512字节
openid	string	是	用户openid，当add_source=2时无需填写（不发送物流服务通知）
delivery_id	string	是	快递公司ID，参见getAllDelivery
biz_id	string	是	快递客户编码或者现付编码
custom_remark	string	否	快递备注信息，比如"易碎物品"，不超过1024字节
tagid	number	否	订单标签id，用于平台型小程序区分平台上的入驻方，tagid须与入驻方账号一一对应，非平台型小程序无需填写该字段
add_source	number	是	订单来源，0为小程序订单，2为App或H5订单，填2则不发送物流服务通知
wx_appid	string	否	App或H5的appid，add_source=2时必填，需和开通了物流助手的小程序绑定同一open帐号
sender	object	是	发件人信息
receiver	object	是	收件人信息
cargo	object	是	包裹信息，将传递给快递公司
shop	object	是	商品信息，会展示到物流服务通知和电子面单中
insured	object	是	保价信息
service	object	是	服务类型
expect_time	number	否	Unix 时间戳, 单位秒，顺丰必须传。预期的上门揽件时间，0表示已事先约定取件时间；否则请传预期揽件时间戳，需大于当前时间，收件员会在预期时间附近上门。例如expect_time为“1557989929”，表示希望收件员将在2019年05月16日14:58:49-15:58:49内上门取货。说明：若选择了预期揽件时间，请不要自己打单，由上门揽件的时候打印。如果是下顺丰散单，则必传此字段，否则不会有收件员上门揽件。
take_mode	number	否	分单策略，【0：线下网点签约，1：总部签约结算】，不传默认线下网点签约。目前支持圆通。

# Body.sender `Object Payload`

发件人信息

参数名	类型	必填	说明
name	string	否	发/收件人姓名，不超过64字节
tel	string	否	发/收件人座机号码，若不填写则必须填写 mobile，不超过32字节
mobile	string	否	发/收件人手机号码，若不填写则必须填写 tel，不超过32字节
company	string	否	发/收件人公司名称，不超过64字节
post_code	string	否	发/收件人邮编，不超过10字节
country	string	否	发/收件人国家，不超过64字节
province	string	否	发/收件人省份，比如："广东省"，不超过64字节
city	string	否	发/收件人市/地区，比如："广州市"，不超过64字节
area	string	否	发/收件人区/县，比如："海珠区"，不超过64字节
address	string	否	发/收件人详细地址，比如："XX路XX号XX大厦XX"，不超过512字节

# Body.receiver `Object Payload`

收件人信息

参数名	类型	必填	说明
name	string	否	发/收件人姓名，不超过64字节
tel	string	否	发/收件人座机号码，若不填写则必须填写 mobile，不超过32字节
mobile	string	否	发/收件人手机号码，若不填写则必须填写 tel，不超过32字节
company	string	否	发/收件人公司名称，不超过64字节
post_code	string	否	发/收件人邮编，不超过10字节
country	string	否	发/收件人国家，不超过64字节
province	string	否	发/收件人省份，比如："广东省"，不超过64字节
city	string	否	发/收件人市/地区，比如："广州市"，不超过64字节
area	string	否	发/收件人区/县，比如："海珠区"，不超过64字节
address	string	否	发/收件人详细地址，比如："XX路XX号XX大厦XX"，不超过512字节

# Body.cargo `Object Payload`

包裹信息，将传递给快递公司

参数名	类型	必填	说明
count	number	是	包裹数量, 默认为1
weight	number	是	货物总重量，比如1.2，单位是千克(kg)
space_x	number	是	货物长度，比如20.0，单位是厘米(cm)
space_y	number	是	货物宽度，比如15.0，单位是厘米(cm)
space_z	number	是	货物高度，比如10.0，单位是厘米(cm)
detail_list	objarray	是	货物总重量，单位是千克(kg)

# Body.shop `Object Payload`

商品信息，会展示到物流服务通知和电子面单中

参数名	类型	必填	说明
wxa_path	string	否	商家小程序的路径，建议为订单页面
img_url	string	否	商品缩略图 url；shop.detail_list为空则必传，shop.detail_list非空可不传。
goods_name	string	否	商品名称, 不超过128字节；shop.detail_list为空则必传，shop.detail_list非空可不传。
goods_count	number	否	商品数量；shop.detail_list为空则必传。shop.detail_list非空可不传，默认取shop.detail_list的size
detail_list	object	否	商品详情列表，适配多商品场景，用以消息落地页展示。（新规范，新接入商家建议用此字段）

# Body.insured `Object Payload`

保价信息

参数名	类型	必填	说明
use_insured	number	否	是否保价，0 表示不保价，1 表示保价
insured_value	number	否	保价金额，单位是分，比如: 10000 表示 100 元

# Body.service `Object Payload`

服务类型

参数名	类型	必填	说明
service_type	number	是	服务类型ID，详见已经支持的快递公司基本信息
service_name	string	是	服务名称，详见已经支持的快递公司基本信息

# Body.cargo.detail_list(Array) `Object Payload`

货物总重量，单位是千克(kg)

参数名	类型	必填	说明
name	string	是	商品名，不超过128字节
count	number	是	商品数量

# Body.shop.detail_list `Object Payload`

商品详情列表，适配多商品场景，用以消息落地页展示。（新规范，新接入商家建议用此字段）

参数名	类型	必填	说明
goods_name	string	是	商品名称
goods_img_url	string	是	商品图片url
goods_desc	string	是	商品详情

# 3. 返回参数

# 返回体 `Response Payload`

参数名	类型	说明
errcode	number	微信侧错误码，下单失败时返回
errmsg	string	微信侧错误信息，下单失败时返回
order_id	string	订单ID，下单成功时返回
waybill_id	string	运单ID，下单成功时返回
delivery_resultcode	number	快递侧错误码，下单失败时返回
delivery_resultmsg	string	快递侧错误信息，下单失败时返回
waybill_data	objarray	运单信息，下单成功时返回

# Res.waybill_data(Array) `Object Payload`

运单信息，下单成功时返回

参数名	类型	说明
key	string	运单信息 key
value	string	运单信息 value

# 4. 注意事项

本接口无特殊注意事项

# 5. 代码示例

# 5.1 下单成功的例子

请求示例

{
  "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": "中国",
    "province": "广东省",
    "city": "广州市",
    "area": "海珠区",
    "address": "XX路XX号XX大厦XX栋XX"
  },
  "receiver": {
    "name": "王小蒙",
    "tel": "020-77777777",
    "mobile": "18610000000",
    "company": "公司名",
    "post_code": "654321",
    "country": "中国",
    "province": "广东省",
    "city": "广州市",
    "area": "天河区",
    "address": "XX路XX号XX大厦XX栋XX"
  },
  "shop": {
    "wxa_path": "/index/index?from=waybill&id=01234567890123456789",
    "detail_list": [
      {
        "goods_name": "微信气泡狗抱枕（小号）",
        "goods_img_url": "https://mmbiz.qpic.cn/mmbiz_png/OiaFLUqewuIDNQnTiaCInIG8ibdosYHhQHPbXJUrqYSNIcBL60vo4LIjlcoNG1QPkeH5GWWEB41Ny895CokeAah8A/640",
        "goods_desc": "40cm * 40cm尺寸"
      },
      {
        "goods_name": "微信气泡狗抱枕（中号）",
        "goods_img_url": "https://mmbiz.qpic.cn/mmbiz_png/OiaFLUqewuIDNQnTiaCInIG8ibdosYHhQHPbXJUrqYSNIcBL60vo4LIjlcoNG1QPkeH5GWWEB41Ny895CokeAah8A/640",
        "goods_desc": "50cm * 50cm尺寸"
      }
    ]
  },
  "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": "标准快递"
  }
}

返回示例

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

# 5.2 下单失败的例子

请求示例

{
  "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": "中国",
    "province": "广东省",
    "city": "广州市",
    "area": "海珠区",
    "address": "XX路XX号XX大厦XX栋XX"
  },
  "receiver": {
    "name": "王小蒙",
    "tel": "020-77777777",
    "mobile": "18610000000",
    "company": "公司名",
    "post_code": "654321",
    "country": "中国",
    "province": "广东省",
    "city": "广州市",
    "area": "天河区",
    "address": "XX路XX号XX大厦XX栋XX"
  },
  "shop": {
    "wxa_path": "/index/index?from=waybill&id=01234567890123456789",
    "detail_list": [
      {
        "goods_name": "微信气泡狗抱枕（小号）",
        "goods_img_url": "https://mmbiz.qpic.cn/mmbiz_png/OiaFLUqewuIDNQnTiaCInIG8ibdosYHhQHPbXJUrqYSNIcBL60vo4LIjlcoNG1QPkeH5GWWEB41Ny895CokeAah8A/640",
        "goods_desc": "40cm * 40cm尺寸"
      },
      {
        "goods_name": "微信气泡狗抱枕（中号）",
        "goods_img_url": "https://mmbiz.qpic.cn/mmbiz_png/OiaFLUqewuIDNQnTiaCInIG8ibdosYHhQHPbXJUrqYSNIcBL60vo4LIjlcoNG1QPkeH5GWWEB41Ny895CokeAah8A/640",
        "goods_desc": "50cm * 50cm尺寸"
      }
    ]
  },
  "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": "标准快递"
  }
}

返回示例

{
  "errcode": 9300501,
  "errmsg": "delivery logic fail",
  "delivery_resultcode": 10002,
  "delivery_resultmsg": "客户密码不正确"
}

# 6. 错误码

以下是本接口的错误码列表，其他错误码可参考通用错误码；调用接口遇到报错，可使用官方提供的 API 诊断工具辅助定位和分析问题。

错误码	错误描述	解决方案
-1	system error	系统繁忙，此时请开发者稍候再试
40001	invalid credential access_token isinvalid or not latest	获取 access_token 时 AppSecret 错误，或者 access_token 无效。请开发者认真比对 AppSecret 的正确性，或查看是否正在为恰当的公众号调用接口
40003	invalid openid	不合法的 OpenID ，请开发者确认 OpenID （该用户）是否已关注公众号，或是否是其他公众号的 OpenID
47001	data format error	解析 JSON/XML 内容错误;post 数据中参数缺失;检查修正后重试。
930559	invaild openid	沙盒环境openid无效
930561	args error	参数错误
930564	quota run out	沙盒环境调用无配额
9300501	Delivery side error	快递侧逻辑错误，详细原因需要看 delivery_resultcode。请先确认一下编码方式，python建议 json.dumps(b, ensure_ascii=False)，php建议 json_encode($arr, JSON_UNESCAPED_UNICODE)
9300502	Delivery side sys error	快递公司系统错误
9300503	Specified delivery id is not registerred	delivery_id 不存在
9300510	invalid service type	service_type 不存在
9300525	biz id not bind	bizid未绑定
9300526	arg size exceed limit	参数字段长度不正确
9300531	invalid biz_id or password	bizid无效或者密码错误
9300534	invalid shop args	access_token与openid参数不匹配
9300535	invalid shop args	shop字段商品缩略图 url、商品名称为空或者非法，或者商品数量为0
9300536	invalid wxa_appid	add_source=2时，wx_appid无效

# 7. 适用范围

本接口支持「小程序（仅认证）」账号类型调用。其他账号类型如无特殊说明，均不可调用。

# 生成运单

# 1. 调用方式

# HTTPS 调用

# 云调用

# 第三方调用

# 2. 请求参数

# 查询参数 Query String parameters

# 请求体 Request Payload

# Body.sender Object Payload

# Body.receiver Object Payload

# Body.cargo Object Payload

# Body.shop Object Payload

# Body.insured Object Payload

# Body.service Object Payload

# Body.cargo.detail_list(Array) Object Payload

# Body.shop.detail_list Object Payload