# 电子面单取号
# 接口说明
可通过该接口发起电子面单取号
# 注意事项
- 如果使用代发模式,填ewaybill_order_code和ewaybill_order_appid即可,不能填ec_order_id字段;
- ewaybill_order_code可从小店订单详情接口获取;
- 代发模式下,例如店铺A打印店铺B的订单,只有订单字段ewaybill_order_code和ewaybill_order_appid是店铺B的,其他参数(网点,模版等)均是店铺A的;
- 增值服务在使用之前,请先和快递公司或者网点确认可用。
- 目前支持子母单的快递公司有顺丰速运、德邦快递、京东快递
- 子母单打印必须安装最新的微信小店打印组件,可在组件内更新或者前往打印组件内下载。打印组件指南
# 接口调用请求说明
POST https://api.weixin.qq.com/channels/ec/logistics/ewaybill/biz/order/create?access_token=ACCESS_TOKEN
# 请求参数说明
| 参数 | 类型 | 是否必填 | 描述 |
|---|---|---|---|
| ewaybill_order_id | String | 是 | 电子面单订单id,全局唯一id(从预取号接口获取或者自定义),注意该字段类型用String传递,但是数据内容要求是Uint64 |
| delivery_id | String | 是 | 快递公司id |
| site_code | String | 否 | 网点编码 |
| ewaybill_acct_id | String | 是 | 电子面单账号id (从查询开通账号信息接口获取) |
| sender | Address | 是 | 寄件人,传明文,结构体详情请参考Address |
| receiver | Address | 是 | 收件人,传小店订单内的用户收件人的信息文本即可。注:此字段只做非空参数校验,实际使用的收件人地址是小店订单内的用户地址,若收件人地址有误,可以联系用户修改订单收件地址或者调用修改地址接口,结构体详情请参考Address |
| ec_order_list | array[EcOrderInfo] | 是 | 订单信息,结构体详情请参考EcOrderInfo |
| remark | String | 否 | 备注 |
| shop_id | String | 是 | 店铺id(从查询开通账号信息接口获取) |
| return_address | Address | 否 | 退货地址,结构体详情请参考Address |
| template_id | String | 否 | 如果需要获取打印报文,则填该字段。回包返回print_info。 如无需使用后台模板,可直接传递template_type做为默认模板, 如‘single’ |
| order_type | number | 否 | 支持的类型,陆续更新中,枚举值详情请参考order_type,默认为1,加盟型可以不填 |
| order_vas_list | array[OrderVas] | 否 | 保价等增值服务,结构体详情请参考OrderVas |
| ext_info | EWaybillOrderInfoExt | 否 | 温层等补充字段,枚举值详情请参考EWaybillOrderInfoExt |
| delivery_info | DeliveryInfo | 否 | 预约上门取件、子母件等发货信息字段,详情查看DeliveryInfo |
# 请求参数示例
{
"ewaybill_order_id": "1111",
"delivery_id": "xxxx",
"site_code": "1111",
"ewaybill_acct_id": "1111",
"template_id": "xxx", // 如果需要获取打印报文,则填该字段。回包会返回 print_info。 如无需使用后台模板,可直接传递 template_type做为默认模板, 如‘single’
"sender": {
"name": "test",
"mobile": "1111",
"province": "静安区",
"city": "上海市",
"county": "静安区",
"street": "xxxxx",
"address": "xxxxxx"
},
"receiver": {
"name": "test",
"mobile": "11111",
"province": "上海市",
"city": "上海市",
"county": "青浦区",
"street": "xxxx",
"address": "xxxxxxx"
},
"ec_order_list": [{
"ec_order_id": 1111,
"goods_list": [{
"good_name": "电子资料书,",
"good_count": 1,
"product_id": 111,
"sku_id": 11
}]
}],
"remark": "test",
"shop_id": "xxxx",
"return_address": {
"name": "test",
"mobile": "13212778355",
"province": "上海市",
"city": "上海市",
"county": "青浦区",
"street": "xxxx",
"address": "xxxxx"
}
}
# 返回参数说明
| 参数 | 类型 | 是否必填 | 描述 |
|---|---|---|---|
| errcode | number | 是 | 错误码 |
| errmsg | string | 是 | 错误信息 |
| ewaybill_order_id | String | 是 | 电子面单订单id |
| waybill_id | String | 是 | 快递单号 |
| delivery_error_msg | String | 是 | 快递公司错误码 |
| print_info | String | 否 | 如果请求参数填了template_id,则返回打印报文信息,可以传给打印组件打印面单。 |
| waybill_id_list | SubWaybillIdInfo | 否 | 子母单号列表,定义详见SubWaybillIdInfo |
# SubWaybillIdInfo
| 参数 | 类型 | 描述 |
|---|---|---|
| waybill_id | String | 快递单号 |
| waybill_type | uint32 | 快递单号类型,1:母单号,2:子单号 |
| create_time | uint32 | 单号创建时间,秒级时间戳 |
# 返回参数示例
{
"errcode": 0,
"errmsg": "ok",
"ewaybill_order_id":"111",
"waybill_id":"1212xzcxz",
"delivery_error_msg":"xxxx",
"waybill_id_list":[{
"waybill_id":"xxxxxx",
"waybill_type":1,
"create_time":1732515904,
"print_info":"xxxx"
},{
"waybill_id":"xxxxxx",
"waybill_type":2,
"create_time":1732515904,
"print_info":"xxxx"
}
]
}
# 错误码
| 错误码 | 错误描述 |
|---|---|
| 公共错误码 | - |
| 10025005 | 下单失败,具体原因参考delivery_error_msg字段 |
| 10025012 | delivery_id错误 |
| 10025013 | 网点信息错误 |
| 10025014 | 网点账号编码错误 |
| 10025015 | 寄件人信息错误 |
| 10025016 | 收件人信息错误 |
| 10025017 | 小店订单信息错误 |
| 10025018 | 店铺id信息错误 |
| 10025019 | 面单已存在 |
| 10025029 | 快递公司不支持该功能(预约上门取件等) |
| 10025030 | 取号请求快递公司接口超时,可稍后重试 |
| 10025031 | 快递公司取号接口异常,可稍后重试 |
| 10025032 | 快递公司的取号接口异常,可能存在故障,可稍后重试或者更换其他快递公司取号 |
| 10025033 | 快递公司取号接口繁忙,可稍后重试或者更换其他快递公司取号 |
| 10025035 | 快递公司的取号接口不可用,可稍后重试或者更换其他快递公司取号 |
# 结构体
# Address
寄件人,收件人,退货地址
| 参数 | 类型 | 是否必填 | 描述 |
|---|---|---|---|
| name | String | 是 | 人名 |
| mobile | String | 是 | 联系电话 |
| province | String | 是 | 省 |
| city | String | 是 | 市 |
| county | String | 是 | 区 |
| street | String | 是 | 街道(收件人非必填) |
| address | String | 是 | 详细地址 |
# EcOrderInfo
订单信息
| 参数 | 类型 | 是否必填 | 描述 |
|---|---|---|---|
| ec_order_id | Uint64 | 是 | 订单id |
| goods_list | array[GoodsInfo] | 是 | 订单商品信息,结构体详情请参考GoodsInfo |
| ewaybill_order_code | string | 否 | 代发的订单密文 |
| ewaybill_order_appid | string | 否 | 代发的订单所属店铺appid |
# DeliveryInfo
发货信息
| 参数 | 类型 | 是否必填 | 描述 |
|---|---|---|---|
| delivery_type | uint32 | 否 | 发货方式,0:仓库发货,1:门店预约发货 |
| collected_time_begin | uint32 | 否 | 预约上门开始时间,秒级时间戳,delivery_type=1时必填 |
| collected_time_end | uint32 | 否 | 预约上门结束时间,秒级时间戳,delivery_type=1时必填 |
| package_quantity | uint32 | 否 | 子母件包裹的数量,要求 2 <= package_quantity <= 300 |
| subpackage_list | EWaybillSubPackage | 否 | 包裹的体积和重量信息,顺丰支持该字段,结构体详情参考EWaybillSubPackage |
- 门店发货说明
delivery_type不传默认的发货方式是仓库发货,取件地址和取件联系人商家是和快递公司线下签约商定的地址;门店预约发货的取件地址以sender字段传入的地址为准,目前支持门店预约发货的快递公司有:顺丰速运
- 子母件说明
package_quantity不传默认是普通件,package_quantity>=2则生成子母件
# EWaybillSubPackage
包裹信息
| 参数 | 类型 | 是否必填 | 描述 |
|---|---|---|---|
| weight_g | uint64 | 否 | 商品重量,单位克 |
| space_x | uint64 | 否 | 商品长度,单位厘米 |
| space_y | uint64 | 否 | 商品宽度,单位厘米 |
| space_z | uint64 | 否 | 商品高度,单位厘米 |
| package_no | string | 否 | 包裹编号 |
# GoodsInfo
订单商品信息
| 参数 | 类型 | 是否必填 | 描述 |
|---|---|---|---|
| good_name | String | 是 | 商品名 |
| good_count | Uint32 | 是 | 商品个数 |
| product_id | Uint64 | 否 | 商品product id |
| sku_id | Uint64 | 否 | 商品sku id |
| out_product_id | String | 否 | 商家自定义spu id |
| out_sku_id | String | 否 | 商家自定义sku id |
| out_goods_info | String | 否 | 商家自定义商品详情(如果不传平台的商品id的话,会展示该字段在面单商品区域) |
# OrderVas
保价等增值服务
| 参数 | 类型 | 是否必填 | 描述 |
|---|---|---|---|
| vas_type | String | 是 | 增值服务类型 |
| vas_detail | String | 否 | 增值服务描述 |
| vas_value | String | 否 | 增值服务值, 涉及金额单位一律为分 |
目前支持的增值服务,OrderVas结构体参数对应填写以下值即可。
| 快递公司 | vas_type | vas_detail | vas_value |
|---|---|---|---|
| SF | INSURE | 基础保 | {"value":"500"} |
| SF | IN160 | 定额保 | {"value":"500"} |
| SF | IN159 | 足额保 | {"value":"500"} |
| SF | IN67 | 纸箱 | - |
| CNSD | VA002 | 标准保价 | 保价金额,单位:分 |
| DBKD | insuranceValue | 保价 | 保价金额,单位:分 |
| STO | INSURE_SERVICE | 保价业务 | 保价金额,单位:分 |
| JD | 1 | 普通保价-快递 | 保价金额,单位:分 |
| JD | 2 | 包装 | - |
# EWaybillOrderInfoExt
温层等补充字段
| 参数 | 参数类型 | 是否必填 | 描述 | 使用条件 |
|---|---|---|---|---|
| temperature_range | Uint32 | 否 | 0或不传则为月结账号的默认温层信息 1:普通/常温 5:鲜活 6:控温 7:冷藏 8:冷冻 9:深冷 | 温层信息,京东专用 |
| package_weight_g | Uint32 | 否 | 包裹总重量:单位 g | 包裹信息字段仅支持与与菜鸟互有信任协议商家使用 |
| package_space_x | Uint32 | 否 | 包裹长度:单位 cm | |
| package_space_y | Uint32 | 否 | 包裹宽度:单位 cm | |
| package_space_z | Uint32 | 否 | 包裹高度:单位 cm | |
| package_volume_ccm | Uint32 | 否 | 包裹体积:单位 cm3 |
# 枚举值
# order_type
支持的类型
| 快递公司 | 枚举值 | 描述 |
|---|---|---|
| JD | - | - |
| JD | 1 | 京东标快 |
| JD | 2 | 京东特快 |
| JD | 3 | 生鲜标快 |
| JD | 4 | 生鲜特快 |
| JD | 5 | 电商特惠 |
| JD | 6 | 特惠包裹 |
| JD | 7 | 特惠小件 |
| JD | 8 | 函速达 |
| JD | 11 | 特快零担 |
| JD | 12 | 特快重货 |
| JD | 17 | 特惠专配 |
| SF | - | 顺丰产品详情 |
| SF | 1 | 顺丰特快 |
| SF | 2 | 顺丰标快 |
| SF | 6 | 顺丰即日 |
| SF | 10 | 国际小包 |
| SF | 23 | 顺丰国际特惠(文件) |
| SF | 24 | 顺丰国际特惠(包裹) |
| SF | 60 | 顺丰特快(文件) |
| SF | 144 | 当日配-门(80CM/1KG以内) |
| SF | 199 | 特快包裹 |
| SF | 201 | 冷运标快 |
| SF | 231 | 陆运包裹 |
| SF | 242 | 丰网速运 |
| SF | 247 | 电商标快 |
| SF | 249 | 丰礼遇 |
| SF | 255 | 顺丰卡航 |
| SF | 263 | 同城半日达 |
| SF | 266 | 顺丰空配(新) |
| SF | 283 | 填仓标快 |
| SF | 285 | 填舱电标 |
| SF | 303 | 专享急件 |
| SF | 304 | 特早达 |
| SF | 323 | 电商微小件 |
| SF | 325 | 温控包裹 |
| EMS | - | - |
| EMS | 1 | 特快专递(EMS) |
| EMS | 2 | 快递包裹(youzhengguonei) |
| EMS | 3 | 邮政电商标快(yzdsbk) |
| DBKD | - | - |
| DBKD | 1 | 大件快递3.60 |
| DBKD | 2 | 标准快递 |
| DBKD | 3 | 特快专递 |
| DBKD | 4 | 航空大件隔日达 |
| DBKD | 5 | 特快次日 |
| DBKD | 6 | 重包入户 |
| DBKD | 7 | 精准卡航(新) |
| DBKD | 8 | 精准重货(新) |
| DBKD | 9 | 精准汽运(新) |
| KYSY | - | - |
| KYSY | 1 | 当天达 |
| KYSY | 2 | 次日达 |
| KYSY | 3 | 隔日件 |
| KYSY | 4 | 陆运件 |
| KYSY | 5 | 空运 |
| KYSY | 6 | 专运 |
| KYSY | 7 | 省内次日 |
| KYSY | 8 | 省内即日 |
| KYSY | 9 | 同城次日 |
| KYSY | 10 | 同城即日 |
| CNSD | - | - |
| CNSD | 1 | 默认 |
| CNSD | 2 | 菜鸟电商标快 |
| CNSD | 3 | 菜鸟标快 |
| CNSD | 4 | 同城半日达 |