WooCommerce 聚水潭同步快速入门

本教程帮助你完成插件安装、聚水潭凭据配置、回调地址配置，并验证第一笔 WooCommerce 订单能够同步到聚水潭。

使用前准备

• WordPress 站点已安装并启用 WooCommerce。
• 服务器使用 PHP 7.4 或更高版本。
• 已在聚水潭开放平台创建应用，并取得 APP Key、App Secret 和 Shop ID。
• 站点有可从公网访问的 HTTPS 地址。
• WooCommerce 商品已设置正确且唯一的 SKU；未设置 SKU 时，插件会使用商品 ID 作为上传值，但建议生产环境始终使用与聚水潭一致的 SKU。

第一步：安装并启用插件

1. 登录 WordPress 后台，进入“插件 → 安装插件”。
2. 点击“上传插件”，选择 WooCommerce Jushuitan Sync 安装包。
3. 安装完成后点击“启用插件”。
4. 进入“WooCommerce → 聚水潭”，确认可以看到“聚水潭设置”。

启用插件时会注册同步回调路由。如果回调地址返回 404，请进入“设置 → 固定链接”，直接点击一次“保存更改”以刷新路由规则。

第二步：填写聚水潭设置

进入“WooCommerce → 聚水潭”，填写以下内容：

• 沙箱环境：正式环境保持关闭；需要连接聚水潭沙箱接口时再启用。
• Shop ID：填写需要接收 WooCommerce 订单的聚水潭店铺 ID。
• APP Key：填写当前环境使用的应用 Key。
• App Secret：填写当前环境使用的应用 Secret。
• 发货后订单状态：聚水潭回传发货信息后，WooCommerce 订单要切换到的状态；默认可选择“已完成”。

当前版本进行接口签名时读取的是 APP Key 和 App Secret。即使启用了沙箱环境，也应把沙箱凭据填写在这两个字段中；不要只填写页面上的 Sandbox APP Key 和 Sandbox App Secret。

完成后点击“保存更改”。APP Key、App Secret 和 Token 都属于敏感信息，不要出现在公开截图、工单或代码仓库中。

第三步：获取初始 Token

1. 确认 APP Key 和 App Secret 已保存。
2. 点击设置页中的“获取初始Token”。
3. 请求成功后，插件会保存 Access Token 和 Refresh Token。
4. 返回“WooCommerce → 聚水潭”，确认两个 Token 字段已有内容，再保存一次设置。

如果获取完成后跳转到了不存在的后台页面，请手动返回“WooCommerce → 聚水潭”检查 Token；这不会影响已经成功保存的结果。插件通过 WordPress 定时任务每周尝试刷新一次 Token，因此站点的 WP-Cron 需要正常运行。

第四步：配置消息回调

在聚水潭开放平台为当前应用配置下列 HTTPS 地址，把 example.com 替换成你的站点域名：

Topic/Tag 名称以聚水潭开放平台当前提供的选项为准。回调地址必须能够被聚水潭服务器直接访问，不应经过登录页、维护页或额外的人机验证。

第五步：验证第一笔订单

1. 选择一个已经正确设置 SKU 的 WooCommerce 商品创建测试订单。
2. 完成订单付款。插件会在 WooCommerce 触发“付款完成”时自动上传订单。
3. 在聚水潭后台确认对应订单已出现。
4. 如果支付方式不会立即触发付款完成，进入“WooCommerce → 订单”，选中该订单，在“批量操作”中选择“同步到聚水潭”，然后点击“应用”。
5. 检查页面顶部的同步结果提示，确认成功、跳过和失败数量。

批量同步成功的订单会被标记，之后再次执行相同批量操作时会跳过，以减少重复上传。

第六步：验证回传结果

• 发货通知：订单会保存承运商、运单号和发货时间，并切换为设置的“发货后订单状态”。
• 售后通知：订单详情中会新增包含售后类型、状态、售后单号和备注的订单备注。
• 库存同步：插件按聚水潭传入的 SKU 查找商品并更新库存数量。

建议先使用测试订单和测试 SKU 验证整个链路，再让正式订单进入自动同步。