WooCommerce Buffalo Shipping 使用指南

WooCommerce Buffalo Shipping 用于把 WooCommerce 订单发送到 Buffalo Express，并在结账、后台订单和客户账户中提供相关配送与物流功能。

1. 使用要求

• WordPress 6.4 或更高版本。
• PHP 8.3 或更高版本，并启用 OpenSSL 扩展。
• 已安装并启用 WooCommerce。
• 已从 Buffalo Express 获得有效的 App ID 和 RSA Private Key。
• 服务器能够访问 Buffalo Express 接口。

建议先在测试站点或测试订单中完成配置和下单验证，再用于正式订单。

2. 安装与启用

1. 备份网站数据库和插件文件。
2. 在 WordPress 后台进入“插件 > 安装插件 > 上传插件”。
3. 选择 WooCommerce Buffalo Shipping ZIP 文件并安装。
4. 安装完成后点击“启用”。
5. 确认 WooCommerce 仍处于启用状态。

插件启用后会增加 Buffalo Express 接口设置、店铺发件信息字段、配送方式、商品 HS Code 和订单物流操作。

3. 配置 Buffalo Express 接口

1. 进入“WooCommerce > 设置”。
2. 打开“BuffaloShipping API”选项卡。
3. 在“App ID”中填写 Buffalo Express 提供的应用 ID。
4. 在“Private Key”中粘贴 RSA 私钥正文。
5. 点击“保存更改”。

Private Key 字段只填写 BEGIN RSA PRIVATE KEY 与 END RSA PRIVATE KEY 之间的正文。不要把接口凭据发送给无关人员，也不要粘贴到公开工单、截图或日志中。

WooCommerce 的“调试模式”启用时，插件会使用 Buffalo Express 测试接口；关闭时使用正式接口。切换模式后，请重新验证报价和运单创建。

4. 完善店铺发件信息

进入“WooCommerce > 设置 > 常规”，检查并填写以下字段：

• Store name：店铺或公司名称。
• Store contact name：发件联系人。
• Store contact phone：联系电话。
• Store state/province：省或州。
• Store county/district：区县。
• WooCommerce 原有的地址、城市、邮编和邮箱字段。

这些内容会随订单一起发送给 Buffalo Express。缺少联系人、电话或地址时，运单可能被接口拒绝。

5. 添加 Buffalo Express 配送方式

1. 进入“WooCommerce > 设置 > 配送 > 配送区域”。
2. 编辑需要提供 Buffalo Express 的配送区域。
3. 点击“添加配送方式”，选择“Buffalo Express”。
4. 编辑该配送方式并确认已启用。
5. 设置顾客在结账页看到的配送方式名称。
6. 选择运费模式并保存。

只有客户地址匹配该配送区域时，结账页才会显示 Buffalo Express。

固定阶梯运费

未启用 Buffalo Express 动态报价时，当前版本按订单商品项数量使用以下内置运费：

• 1 个商品项：149
• 2 个商品项：199
• 3 个商品项：299
• 4 个或更多商品项：399

这里统计的是购物车商品项数量，不是每个商品的购买件数。配送方式中的“Shipping Fee”字段当前不会覆盖以上阶梯值。

Buffalo Express 动态报价

启用“Calculate Shipping Fee From Buffalo Express”后，插件会使用客户地址中的 City 和 Postcode 请求 Buffalo Express 报价。

测试时请确认：

• 城市与邮编匹配。
• 接口凭据有效。
• 服务器可以连接 Buffalo Express。
• 返回的运费在结账页显示为数值。

如果动态报价异常，可先关闭该选项，确认固定阶梯运费和配送区域是否正常，再检查接口响应。

6. 配置商品重量与 HS Code

创建运单前，逐个检查待发货商品：

1. 进入“商品”，编辑商品。
2. 在“商品数据 > 配送”中填写重量。
3. 在同一区域填写“HS Code”。
4. 更新商品。

商品未填写重量时，插件会使用 0.01 作为接口数据；未填写 HS Code 时会使用默认值 7326909000。这些默认值不一定符合真实商品和申报要求，请以 Buffalo Express 和目的地海关要求为准填写准确数据。

变量商品应同时检查实际下单变体的数据和商品名称。提交前还应确认商品数量、订单金额、收件地址和电话准确。

7. 结账地址建议

结账页的 City/Suburb 字段会根据插件内置的南非地点数据提供建议。顾客选择建议项后，插件会尝试自动填写对应邮编。

如果没有建议或邮编不正确：

• 允许顾客手动填写并核对 City/Suburb 与 Postcode。
• 清理页面缓存和脚本优化缓存后重试。
• 检查主题或结账插件是否替换了标准 billing_city 与 billing_postcode 字段。

8. 创建 Buffalo Express 运单

1. 在 WooCommerce 后台打开需要发货的订单。
2. 检查收件人姓名、国家、城市、地址、电话、邮箱和邮编。
3. 检查订单内每个商品的重量与 HS Code。
4. 在订单商品区域点击“Send to Buffalo Express”。
5. 等待操作完成，不要重复点击。
6. 成功后检查提示、订单备注和保存的 Tracking Number。

每个订单商品项会作为一箱发送，箱号按商品项顺序生成。创建成功后，插件在订单中保存发送标记和跟踪号。

当前后台按钮依赖经典 WooCommerce 订单编辑界面。如果启用了 High-Performance Order Storage（HPOS）后看不到按钮或物流框，请先在测试环境切换到兼容模式验证，并联系技术支持确认当前站点适配情况。

9. 查看物流状态

订单成功发送后，可以在以下位置查看物流信息：

• 后台订单侧边的 Buffalo Express status。
• 客户“我的账户 > 订单”列表的 Shipping Status 列。
• 客户打开单个订单后的 Shipping Status 区域。

物流查询结果会缓存约 30 分钟，因此 Buffalo Express 已更新轨迹后，站点页面可能不会立即变化。新运单尚未扫描时也可能暂时没有记录。

10. 取消订单

当 WooCommerce 订单状态变为“已取消”时，插件会尝试通知 Buffalo Express 取消对应物流订单。成功时会在订单中添加备注。

取消后请同时登录 Buffalo Express 管理端确认状态。网络故障、凭据错误或接口拒绝都可能导致同步失败，不能只依赖 WooCommerce 状态判断承运端是否已取消。

常见问题

结账页为什么没有 Buffalo Express？

确认插件与 WooCommerce 均已启用，相应配送区域已经添加并启用 Buffalo Express，而且客户地址匹配该区域。若使用结账编辑器或第三方结账插件，请用 WooCommerce 标准结账流程对比测试。

动态运费为什么无法显示？

先核对 App ID、Private Key、City 和 Postcode，再检查服务器是否可以访问 Buffalo Express 接口。关闭动态报价后若固定阶梯运费正常，问题通常位于接口请求或响应。

点击发送按钮后提示下单错误怎么办？

检查订单收件信息、商品重量与 HS Code，以及 Buffalo Express 接口凭据。查看 WooCommerce 日志、PHP 错误日志和浏览器网络响应，并向技术支持提供插件版本、订单号、发生时间和已脱敏的错误内容。

为什么没有保存 Tracking Number？

只有 Buffalo Express 返回成功状态时插件才会保存 Tracking Number。不要连续重复提交同一订单；先在 Buffalo Express 管理端确认是否已经创建运单，再排查接口响应。

为什么物流状态长时间不更新？

轨迹会缓存约 30 分钟，且新运单需要等待承运商首次扫描。稍后重试；若 Buffalo Express 管理端已有轨迹但网站仍无结果，请清理对象缓存并检查接口日志。

订单取消后 Buffalo Express 仍显示未取消怎么办？

WooCommerce 取消动作只会尝试同步一次。请在 Buffalo Express 管理端核对运单，必要时手动取消，并检查当时的服务器网络与错误日志。

更新后出现异常怎么办？

先清理对象缓存、页面缓存和 CDN 缓存，确认 PHP、WordPress 与 WooCommerce 满足要求，再复测一个结账订单和一个已发货订单。如果问题仍存在，可恢复更新前备份，并向技术支持提供复现步骤和相关错误日志。