# 物流发货

# 开发前准备

• 功能了解：开发前建议先阅读以下运营文档了解完整业务流程：
  • 订单发货不用愁，三步轻松搞定！
  • 微信小店「快递地址」使用指南
  • 微信小店「电子面单操作」使用指南
• 权限与凭证：商家自研可直接调用，使用小店 access_token；第三方服务商需获得商家对 权限集 ID：131 的授权，使用 authorizer_access_token。电子面单接口还需额外授权 权限集 ID：130 / 159 / 192（三选一）
• 消息推送配置：需配置消息推送回调 URL，详见 消息通知（回调）说明
• 电子面单开通：需先在微信小店管理后台开通电子面单服务并绑定快递公司网点/月结账号

# 接入流程

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

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

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

# 地址管理

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

还支持两种特殊配送类型：

• 同城配送（same_city=1）：适用于生鲜外卖场景
• 用户自提（pickup=1）：适用于门店自提场景

# 运费模板

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

核心字段说明：

# 阶段二：电子面单取号与打印（核心链路）

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

Step 1 — 查询面单账号

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

Step 2 — 预取号

调用 [API] 电子面单预取号 / ewaybill_precreateorder，传入寄件人、收件人、订单商品信息，返回 ewaybill_order_id。此步仅做参数校验，不扣面单库存。

Step 3 — 正式取号

调用 [API] 电子面单取号 / ewaybill_createorder，传入 ewaybill_order_id，返回快递单号 waybill_id，此步扣减面单库存。如同时传入 template_id，可直接返回 print_info，省去 Step 4。

Step 4 — 获取打印报文

调用 [API] 获取打印报文 / get_print_content，获取 print_info 字符串。若 Step 3 已返回 print_info，此步可跳过。print_info 无需解析，原样透传给打印组件即可。

Step 5 — 打印组件出单

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

Step 6 — 通知平台出单结果

打印成功后必须调用 [API] 打印成功通知 / ewaybill_printorder（批量场景用 [API] 批量打印通知 / ewaybill_batchprintorder），否则平台无法感知面单已出单。

子母单（大件拆包场景）

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

两种获取方式：

1. 一次性获取：取号时（Step 3）传入 package_quantity（2~300），一次返回母单号 + N 个子单号
2. 逐步追加：先正常取号得母单，再调用 [API] 电子面单子件追加 / ewaybill_addsuborder 逐个追加

面单辅助管理

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

# 阶段三：订单发货

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

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

发货前可先调用 [API] 获取快递公司列表 / getdeliverycompanylistnew 获取平台支持的快递公司编码（即 delivery_id）。

漏发、拆分包裹、坏损补发、赠品等补救场景，调用 [API] 订单补发货 / delivery_compensation，最多补发 10 次。

# 多包裹分批发货

当一个订单需要拆成多个包裹发货时：

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

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

调用订单管理模块的 [API] 修改物流信息 / changedeliveryinfo，用于更换快递公司或更正快递单号。

# 阶段四：物流轨迹追踪

当快递轨迹变化时（揽收、运输中、派件、签收等），通过 [事件] 物流轨迹推送通知 / ewaybill_push_path 实时推送。

# 前端对接说明

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

# 接口全览

# API 接口

# 地址管理

# 运费模板

# 电子面单

# 发货

# 事件通知

# 常见问题 FAQ

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

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

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

文档变更日志（1条）

2026 年 04 月 17 日

新增 物流发货 开发指南