# 物流发货

## 开发前准备

- **功能了解**：开发前建议先阅读以下运营文档了解完整业务流程：
  - [订单发货不用愁，三步轻松搞定！](https://store.weixin.qq.com/chengzhang/webdoc/wiki/9144/9856d41269780faf/growth_center_lesson_for_store/5)
  - [微信小店「快递地址」使用指南](https://store.weixin.qq.com/chengzhang/webdoc/wiki/9096/656b0873f92ca0f9/growth_center_manual_for_store/3)
  - [微信小店「电子面单操作」使用指南](https://store.weixin.qq.com/chengzhang/webdoc/wiki/540/8928bda6d81898f4/growth_center_manual_for_store)
- **权限与凭证**：商家自研可直接调用，使用小店 access_token；第三方服务商需获得商家对 `权限集 ID：131` 的授权，使用 authorizer_access_token。电子面单接口还需额外授权 `权限集 ID：130 / 159 / 192`（三选一）
- **消息推送配置**：需配置消息推送回调 URL，详见 [消息通知（回调）说明](/doc/store/shop/dev_before/message_push)
- **电子面单开通**：需先在[微信小店管理后台](https://store.weixin.qq.com/shop/home)开通电子面单服务并绑定快递公司网点/月结账号

## 接入流程

本模块接口分布在三个路径前缀下：`/channels/ec/merchant/`（地址、运费模板）、`/channels/ec/logistics/`（电子面单）、`/channels/ec/order/`（发货）。

### 阶段一：基础配置（地址 + 运费模板）

地址和运费模板是发货的前置依赖。电子面单取号时需要寄件人地址，发货失败的常见原因之一就是没有设置默认退货地址（错误码 `606003`）。

```mermaid
%%{init: {'theme': 'base', 'themeVariables': {'primaryColor': '#0ab8a6', 'primaryTextColor': '#ffffff', 'primaryBorderColor': '#089e8d', 'lineColor': '#0ab8a6', 'secondaryColor': '#07827a', 'secondaryTextColor': '#ffffff', 'secondaryBorderColor': '#055f59', 'tertiaryColor': '#0ab8a6', 'tertiaryTextColor': '#ffffff', 'tertiaryBorderColor': '#089e8d', 'edgeLabelBackground': '#888888', 'fontColor': '#888888'}}}%%
flowchart LR
  A["[API] 添加地址<br/>addaddress"] -->|"设 default_send/default_recv=true"| B[默认地址生效]
  C["[API] 增加运费模版<br/>addfreighttemplate"] -->|"返回 freight_template_id"| D[商品上架时传入模板 ID]
  style B fill:#ffffff,stroke:#0ab8a6,color:#666666
  style D fill:#ffffff,stroke:#0ab8a6,color:#666666
```

#### 地址管理

调用 [API] [添加地址 / addaddress](/doc/store/shop/API/channels-shop-delivery/address/api_addaddress) 创建地址后，通过 `send_addr` / `recv_addr` 标记用途（发货地址 / 退货地址），一个地址可同时兼任两种角色。设置 `default_send=true` / `default_recv=true` 可将其指定为默认地址，电子面单取号时会自动使用默认发货地址作为寄件人。

还支持两种特殊配送类型：
- **同城配送**（`same_city=1`）：适用于生鲜外卖场景
- **用户自提**（`pickup=1`）：适用于门店自提场景

#### 运费模板

调用 [API] [增加运费模版 / addfreighttemplate](/doc/store/shop/API/channels-shop-delivery/merchant/api_addfreighttemplate) 创建模板后，接口返回 `freight_template_id`。**商品上架时必须关联一个运费模板**，在商品管理模块的添加/更新商品接口中传入 `freight_template_id` 即可完成关联。

核心字段说明：

| 字段 | 说明 | 可选值 |
|------|------|--------|
| `shipping_method` | 计费方式 | `FREE` 全国包邮 / `CONDITION_FREE` 条件包邮 / `NO_FREE` 不包邮 |
| `valuation_type` | 计费类型 | `PIECE` 按件数 / `WEIGHT` 按重量 |
| `send_time` | 发货时限 | `SendTime_TWENTYFOUR_HOUR` 24 小时内 / `SendTime_FOUTYEIGHT_HOUR` 48 小时内 |
| `not_send_area` | 不发货区域 | 指定不配送的偏远地区 |
| `all_condition_free_detail` | 条件包邮规则 | 最低件数/重量/金额 + 适用地区 |
| `all_freight_calc_method` | 运费计算规则 | 首重/首件价格 + 续重/续件价格 + 地区差异化 |
### 阶段二：电子面单取号与打印（核心链路）

这是本模块最核心的能力。整个链路涉及 6 次 API 调用 + 1 次打印组件交互：

```mermaid
%%{init: {'theme': 'base', 'themeVariables': {'primaryColor': '#0ab8a6', 'primaryTextColor': '#ffffff', 'primaryBorderColor': '#089e8d', 'lineColor': '#0ab8a6', 'secondaryColor': '#07827a', 'secondaryTextColor': '#ffffff', 'secondaryBorderColor': '#055f59', 'tertiaryColor': '#0ab8a6', 'tertiaryTextColor': '#ffffff', 'tertiaryBorderColor': '#089e8d', 'edgeLabelBackground': '#888888', 'fontColor': '#888888'}}}%%
flowchart LR
  A["[API] 查询开通的电子面单网点/账号信息<br/>ewaybill_getacct"] --> B["[API] 电子面单预取号<br/>ewaybill_precreateorder"]
  B --> C["[API] 电子面单取号<br/>ewaybill_createorder"]
  C --> D["[API] 获取打印报文<br/>get_print_content"]
  C -->|子母单| E["[API] 电子面单子件追加<br/>ewaybill_addsuborder"]
  E --> D
  D --> F["打印组件出单"]
  F --> G["[API] 打印成功通知<br/>ewaybill_printorder"]
  style F fill:#ffffff,stroke:#0ab8a6,color:#666666
```

**Step 1 — 查询面单账号**

调用 [API] [查询开通的电子面单网点/账号信息 / ewaybill_getacct](/doc/store/shop/API/channels-shop-delivery/ewaybill/api_ewaybill_getacct)，获取 `shop_id`、`ewaybill_acct_id`、`delivery_id` 三个取号必需参数，并通过 `available` 确认面单库存充足。

**Step 2 — 预取号**

调用 [API] [电子面单预取号 / ewaybill_precreateorder](/doc/store/shop/API/channels-shop-delivery/ewaybill/api_ewaybill_precreateorder)，传入寄件人、收件人、订单商品信息，返回 `ewaybill_order_id`。此步仅做参数校验，**不扣面单库存**。

**Step 3 — 正式取号**

调用 [API] [电子面单取号 / ewaybill_createorder](/doc/store/shop/API/channels-shop-delivery/ewaybill/api_ewaybill_createorder)，传入 `ewaybill_order_id`，返回快递单号 `waybill_id`，**此步扣减面单库存**。如同时传入 `template_id`，可直接返回 `print_info`，省去 Step 4。

**Step 4 — 获取打印报文**

调用 [API] [获取打印报文 / get_print_content](/doc/store/shop/API/channels-shop-delivery/ewaybill/api_get_print_content_supplier)，获取 `print_info` 字符串。若 Step 3 已返回 `print_info`，**此步可跳过**。`print_info` 无需解析，原样透传给打印组件即可。

**Step 5 — 打印组件出单**

将 `print_info` 通过 WebSocket 传给本地打印组件完成面单打印，详见[电子面单打印组件 - 开发指南](ewaybill)。

**Step 6 — 通知平台出单结果**

打印成功后**必须**调用 [API] [打印成功通知 / ewaybill_printorder](/doc/store/shop/API/channels-shop-delivery/ewaybill/api_ewaybill_printorder)（批量场景用 [API] [批量打印通知 / ewaybill_batchprintorder](/doc/store/shop/API/channels-shop-delivery/ewaybill/api_ewaybill_batchprintorder)），否则平台无法感知面单已出单。

**子母单（大件拆包场景）**

当一个大件商品需拆分多个包裹时使用子母单。支持子母单的快递公司、打印样式等详情见[电子面单打印组件 - 开发指南](ewaybill)。

两种获取方式：
1. **一次性获取**：取号时（Step 3）传入 `package_quantity`（2~300），一次返回母单号 + N 个子单号
2. **逐步追加**：先正常取号得母单，再调用 [API] [电子面单子件追加 / ewaybill_addsuborder](/doc/store/shop/API/channels-shop-delivery/ewaybill/api_ewaybill_addsuborder) 逐个追加

**面单辅助管理**

除核心取号打印链路外，还支持面单模板管理（获取标准模板、新增/更新/删除自定义模板）、查询已开通快递公司列表、取消面单（回收库存）、查询面单详情等能力，详见接口全览 - 电子面单。
### 阶段三：订单发货

面单打印完成后，调用发货接口将 `waybill_id` 绑定到订单上，完成履约闭环。

```mermaid
%%{init: {'theme': 'base', 'themeVariables': {'primaryColor': '#0ab8a6', 'primaryTextColor': '#ffffff', 'primaryBorderColor': '#089e8d', 'lineColor': '#0ab8a6', 'secondaryColor': '#07827a', 'secondaryTextColor': '#ffffff', 'secondaryBorderColor': '#055f59', 'tertiaryColor': '#0ab8a6', 'tertiaryTextColor': '#ffffff', 'tertiaryBorderColor': '#089e8d', 'edgeLabelBackground': '#888888', 'fontColor': '#888888'}}}%%
flowchart LR
  A[面单打印完成] --> B["[API] 订单发货<br/>senddelivery"]
  B -->|部分发货 finish_delivery=0| C[继续取号打印剩余]
  C --> B
  B -->|全部发货 finish_delivery=1| D[订单状态: 待收货]
  B -->|漏发/拆包/赠品| E["[API] 订单补发货<br/>delivery_compensation"]
  style A fill:#ffffff,stroke:#0ab8a6,color:#666666
  style C fill:#ffffff,stroke:#0ab8a6,color:#666666
  style D fill:#ffffff,stroke:#0ab8a6,color:#666666
```

调用 [API] [订单发货 / senddelivery](/doc/store/shop/API/channels-shop-delivery/delivery/api_senddelivery) 时，核心参数：`deliver_type=1`（快递，需传 `waybill_id` + `delivery_id`）或 `3`（虚拟商品，无需物流）；`product_infos` 指定本次发货的商品 SKU 和数量；`finish_delivery=0` 表示部分发货，`=1` 表示全部发货完成。

发货前可先调用 [API] [获取快递公司列表 / getdeliverycompanylistnew](/doc/store/shop/API/channels-shop-delivery/delivery/api_getdeliverycompanylistnew) 获取平台支持的快递公司编码（即 `delivery_id`）。

漏发、拆分包裹、坏损补发、赠品等补救场景，调用 [API] [订单补发货 / delivery_compensation](/doc/store/shop/API/channels-shop-delivery/delivery/api_delivery_compensation)，最多补发 10 次。
#### 多包裹分批发货

当一个订单需要拆成多个包裹发货时：
1. 每个包裹分别执行阶段二的取号+打印流程，得到各自的 `waybill_id`
2. 分别调用 `senddelivery`，每次传入对应的 `waybill_id` 和该包裹的 `product_infos`
3. 前 N-1 次设 `finish_delivery=0`（部分发货），最后一次设 `finish_delivery=1`（全部发货）

#### 发货后如需修改物流信息

调用**订单管理模块**的 [API] [修改物流信息 / changedeliveryinfo](/doc/store/shop/API/channels-shop-order/api_changedeliveryinfo)，用于更换快递公司或更正快递单号。

### 阶段四：物流轨迹追踪

当快递轨迹变化时（揽收、运输中、派件、签收等），通过 [事件] [物流轨迹推送通知 / ewaybill_push_path](/doc/store/shop/notify/merchant_callback/ewaybill_push_path) 实时推送。
## 前端对接说明

本模块唯一涉及前端对接的是**电子面单打印组件**。打印组件运行在商家本地电脑上，应用端通过 WebSocket（`ws://127.0.0.1:12705`）与之通信。详见[电子面单打印组件 - 开发指南](ewaybill)。

## 接口全览

### API 接口

#### 地址管理

| 中文名 / 英文名 | 请求方式 | 功能说明 |
|----------------|---------|---------|
| [添加地址](/doc/store/shop/API/channels-shop-delivery/address/api_addaddress) / addaddress | `POST /channels/ec/merchant/address/add` | 添加发货/退货地址 |
| [获取地址列表](/doc/store/shop/API/channels-shop-delivery/address/api_getaddresslist) / getaddresslist | `POST /channels/ec/merchant/address/list` | 分页获取地址 ID 列表 |
| [获取地址详情](/doc/store/shop/API/channels-shop-delivery/address/api_getaddress) / getaddress | `POST /channels/ec/merchant/address/get` | 按 ID 获取地址详情 |
| [更新地址](/doc/store/shop/API/channels-shop-delivery/address/api_updateaddress) / updateaddress | `POST /channels/ec/merchant/address/update` | 更新已有地址 |
| [删除地址](/doc/store/shop/API/channels-shop-delivery/address/api_deleteaddress) / deleteaddress | `POST /channels/ec/merchant/address/delete` | 删除指定地址 |

#### 运费模板

| 中文名 / 英文名 | 请求方式 | 功能说明 |
|----------------|---------|---------|
| [增加运费模版](/doc/store/shop/API/channels-shop-delivery/merchant/api_addfreighttemplate) / addfreighttemplate | `POST /channels/ec/merchant/addfreighttemplate` | 创建运费模板 |
| [查询运费模版](/doc/store/shop/API/channels-shop-delivery/merchant/api_getfreighttemplatedetail) / getfreighttemplatedetail | `POST /channels/ec/merchant/getfreighttemplatedetail` | 查询模板详情 |
| [获取运费模板列表](/doc/store/shop/API/channels-shop-delivery/merchant/api_getfreighttemplatelist) / getfreighttemplatelist | `POST /channels/ec/merchant/getfreighttemplatelist` | 分页获取模板 ID 列表 |
| [更新运费模版](/doc/store/shop/API/channels-shop-delivery/merchant/api_updatefreighttemplate) / updatefreighttemplate | `POST /channels/ec/merchant/updatefreighttemplate` | 更新已有模板 |

#### 电子面单

| 中文名 / 英文名 | 请求方式 | 功能说明 |
|----------------|---------|---------|
| [查询开通的电子面单网点/账号信息](/doc/store/shop/API/channels-shop-delivery/ewaybill/api_ewaybill_getacct) / ewaybill_getacct | `POST /channels/ec/logistics/ewaybill/biz/account/get` | 查询面单账号和库存 |
| [电子面单预取号](/doc/store/shop/API/channels-shop-delivery/ewaybill/api_ewaybill_precreateorder) / ewaybill_precreateorder | `POST /channels/ec/logistics/ewaybill/biz/order/precreate` | 校验参数并获取 ewaybill_order_id |
| [电子面单取号](/doc/store/shop/API/channels-shop-delivery/ewaybill/api_ewaybill_createorder) / ewaybill_createorder | `POST /channels/ec/logistics/ewaybill/biz/order/create` | 正式取号获取快递单号 |
| [电子面单子件追加](/doc/store/shop/API/channels-shop-delivery/ewaybill/api_ewaybill_addsuborder) / ewaybill_addsuborder | `POST /channels/ec/logistics/ewaybill/biz/order/addsuborder` | 追加子母单子件 |
| [获取打印报文](/doc/store/shop/API/channels-shop-delivery/ewaybill/api_get_print_content_supplier) / get_print_content | `POST /channels/ec/logistics/ewaybill/biz/print/get` | 获取面单打印内容 |
| [打印成功通知](/doc/store/shop/API/channels-shop-delivery/ewaybill/api_ewaybill_printorder) / ewaybill_printorder | `POST /channels/ec/logistics/ewaybill/biz/order/print` | 通知平台面单已打印 |
| [批量打印通知](/doc/store/shop/API/channels-shop-delivery/ewaybill/api_ewaybill_batchprintorder) / ewaybill_batchprintorder | `POST /channels/ec/logistics/ewaybill/biz/order/batchprint` | 批量通知出单结果 |
| [电子面单取消下单](/doc/store/shop/API/channels-shop-delivery/ewaybill/api_ewaybill_cancelorder) / ewaybill_cancelorder | `POST /channels/ec/logistics/ewaybill/biz/order/cancel` | 取消已取号的面单 |
| [查询面单详情](/doc/store/shop/API/channels-shop-delivery/ewaybill/api_ewaybill_getorder) / ewaybill_getorder | `POST /channels/ec/logistics/ewaybill/biz/order/get` | 查询面单状态详情 |
| [查询开通的快递公司列表](/doc/store/shop/API/channels-shop-delivery/ewaybill/api_ewaybill_getdeliverylist) / ewaybill_getdeliverylist | `POST /channels/ec/logistics/ewaybill/biz/delivery/get` | 查询已开通电子面单的快递公司 |
| [获取面单标准模板](/doc/store/shop/API/channels-shop-delivery/ewaybill/api_ewaybill_get_template_config) / ewaybill_get_template_config | `POST /channels/ec/logistics/ewaybill/biz/template/config` | 获取标准面单模板 |
| [新增面单模板](/doc/store/shop/API/channels-shop-delivery/ewaybill/api_ewaybill_createtemplate) / ewaybill_createtemplate | `POST /channels/ec/logistics/ewaybill/biz/template/create` | 创建自定义面单模板 |
| [更新面单模版](/doc/store/shop/API/channels-shop-delivery/ewaybill/api_ewaybill_updatetemplate) / ewaybill_updatetemplate | `POST /channels/ec/logistics/ewaybill/biz/template/update` | 更新自定义模板 |
| [删除面单模版](/doc/store/shop/API/channels-shop-delivery/ewaybill/api_ewaybill_deltemplate) / ewaybill_deltemplate | `POST /channels/ec/logistics/ewaybill/biz/template/delete` | 删除面单模板 |
| [获取面单模板信息](/doc/store/shop/API/channels-shop-delivery/ewaybill/api_ewaybill_gettemplate) / ewaybill_gettemplate | `POST /channels/ec/logistics/ewaybill/biz/template/get` | 查询面单模板信息 |
| [根据模板ID获取面单模板信息](/doc/store/shop/API/channels-shop-delivery/ewaybill/api_ewaybill_gettemplatebyid) / ewaybill_gettemplatebyid | `POST /channels/ec/logistics/ewaybill/biz/template/getbyid` | 按 ID 查询模板 |

#### 发货

| 中文名 / 英文名 | 请求方式 | 功能说明 |
|----------------|---------|---------|
| [订单发货](/doc/store/shop/API/channels-shop-delivery/delivery/api_senddelivery) / senddelivery | `POST /channels/ec/order/delivery/send` | 传入面单号完成订单发货 |
| [订单补发货](/doc/store/shop/API/channels-shop-delivery/delivery/api_delivery_compensation) / delivery_compensation | `POST /channels/ec/order/delivery/compensation` | 漏发/拆包/赠品补发，最多 10 次 |
| [获取快递公司列表](/doc/store/shop/API/channels-shop-delivery/delivery/api_getdeliverycompanylistnew) / getdeliverycompanylistnew | `POST /channels/ec/order/deliverycompanylist/new/get` | 获取平台支持的快递公司编码 |

### 事件通知
| 中文名 / 英文名 | 事件标识 | 功能说明 |
|----------------|---------|---------|
| [物流轨迹推送通知](/doc/store/shop/notify/merchant_callback/ewaybill_push_path) / ewaybill_push_path | `Event: ewaybill_push_path` | 快递轨迹变化时推送，包含 9 种状态枚举 |

## 常见问题 FAQ

**Q：为什么调用 senddelivery 报错 606046「请使用电子面单发货」？**
A：微信小店要求必须通过平台电子面单取号后发货，不支持手动填写快递单号。需先完成阶段二的电子面单取号流程获取 `waybill_id`。

**Q：订单发货后发现快递单号填错了怎么办？**
A：调用订单管理模块的 [API] [修改物流信息 / changedeliveryinfo](/doc/store/shop/API/channels-shop-order/api_changedeliveryinfo)，该接口属于**订单管理模块**而非本模块。

**Q：print_info 是什么格式，需要解析吗？**
A：不需要。`print_info` 是一段不透明字符串，服务端拿到后原样透传给前端，前端放入打印组件的 `taskList[].printInfo` 字段即可。详见[电子面单打印组件 - 开发指南](ewaybill)。

![](https://res8.wxqcloud.qq.com.cn/wxdoc/56617deb-b17d-4cf1-bccd-71d2c41ccc76.svg)文档变更日志（1条）
2026 年 04 月 17 日新增 物流发货 开发指南