WooCommerce 中通下单插件使用指南

本插件用于从 WooCommerce 订单后台提交中通订单、保存运单号，并接收发货回调更新订单物流信息。

1. 使用前准备

请先确认：

• WordPress 6.4 或更高版本。
• PHP 7.2 或更高版本。
• WooCommerce 已安装并启用。
• 已从中通开放平台获得 Shop key、AppKey 和 AppSecret。
• 当前操作账号拥有编辑 WooCommerce 订单的权限。

2. 安装插件

1. 在 WordPress 后台进入“插件 > 安装插件 > 上传插件”。
2. 上传正式发布的插件 ZIP。
3. 点击“现在安装”，完成后启用插件。
4. 请使用购买页面提供的正式插件 ZIP。

如果是覆盖升级，建议先备份网站数据库。插件升级不会主动删除已有设置和订单物流信息。

3. 配置店铺发件信息

进入“WooCommerce > 设置 > 常规”，填写以下信息：

• Store name：店铺或公司名称。
• Store contact name：发件联系人姓名。
• Store contact phone：发件联系人电话。
• Store state/province：发件省份。
• Store county/district：发件区县。

同时确认 WooCommerce 原有的店铺城市、邮编和详细地址已经填写完整。上述信息会作为中通订单的发件地址。

4. 配置中通接口

进入“WooCommerce > 设置 > 配送”，找到“ZTO express Shipping options”：

• Shop key：中通云打印店铺 Key。
• AppKey：中通开放平台应用 Key。
• AppSecret：中通开放平台应用密钥。
• Callback token：可选的发货回调令牌，建议正式站点配置。

保存设置后即可在订单后台发起中通下单。

测试环境

插件沿用 WooCommerce 的配送调试模式：

• 开启配送调试模式时，请求中通测试接口。
• 关闭配送调试模式时，请求中通正式接口。

正式发货前，建议先使用测试订单验证地址、商品数量和接口凭据。

5. 从订单后台提交中通订单

1. 进入“WooCommerce > 订单”。
2. 打开需要发货的订单。
3. 检查订单收件人、电话、省市和详细地址。
4. 在订单商品操作区域点击“中通下单”。
5. 等待页面返回中通接口结果。

提交成功后，插件会保存快递公司名称和运单号。再次打开订单时，可在订单商品区域查看物流信息。

如果订单包含变体商品，插件会将变体说明一并发送到中通商品信息中。

6. 配置发货回调

发货系统可向以下 WordPress AJAX 地址发送 POST 请求：

https://你的域名/wp-admin/admin-ajax.php?action=zto_cloud_return

请求字段：

• orderCode：WooCommerce 订单 ID。
• billNo：快递运单号。
• expressCompany：快递公司名称。
• callback_token：已配置 Callback token 时可通过此字段传递；也可以使用 X-ZTO-Callback-Token 请求头。

回调成功后，插件会：

• 保存快递公司名称和运单号。
• 将订单更新为“已发货”状态。
• 同步微信小程序物流字段。
• 在检测到兼容数据表时同步快递鸟物流字段。

如果 Callback token 留空，插件会保留旧版公开回调行为。正式站点建议配置令牌，并在回调系统中同步设置。

7. 插件更新

新版本发布后，WordPress 后台会像普通插件一样显示更新通知。拥有插件更新权限的管理员可以在“插件”或“更新”页面完成升级。

插件启用后会自动检查已发布的新版本，无需额外配置。更新前建议：

1. 备份数据库和当前插件文件。
2. 查看版本更新日志。
3. 在维护窗口执行更新。
4. 更新后使用测试订单验证中通下单和发货回调。