VibeFox The Courier Guy for WooCommerce — 帮助
系统要求
WordPress：5.8 或更高版本。
WooCommerce：7.0 或更高版本，且已安装并启用。没有它，插件无法启用。
PHP：8.0 或更高版本。
ShipLogic API 密钥（用于实时运费和快递柜）：The Courier Guy 运行在 ShipLogic 平台上。请在您的 The Courier Guy 快递门户中，于 Settings > API Keys 下创建 API 密钥（企业账户）。没有该密钥时，只能使用价格表，无法提供快递柜配送。
配送至南非：实时运费和快递柜仅适用于南非地址。您的店铺必须支持配送至南非（WooCommerce > Settings > General > Shipping location(s)）。
VibeFox 许可证密钥：在 vibefox.net 购买。一个密钥只能用于一个域名。
安装
1. 在 WordPress 中进入 Plugins > Add New > Upload Plugin，选择插件的 ZIP 文件，然后点击 Install Now。您也可以通过 FTP 将 vfd_the_courier_guy 文件夹上传到 /wp-content/plugins/。
2. 点击 Activate。
3. 打开设置：WooCommerce > Settings > Shipping > VibeFox The Courier Guy，或在插件页面中点击插件名称下方的 Settings。
4. 在页面顶部的许可证区块中输入您的 VibeFox 许可证密钥，然后点击 Activate。
5. 输入 ShipLogic 的 API key。若要使用实时运费，请填写发件地址（街道、城市、省份、邮政编码）；如果店铺货币不是 ZAR，还需填写 ZAR conversion rate。
6. 填写价格表和/或备用运费。
7. 在 WooCommerce > Settings > Shipping > Shipping zones 中，将 VibeFox The Courier Guy 添加到南非的配送区域，选择 Delivery type（courier 或 TCG locker），并可选填标题。再次添加该方式即可提供另一种配送类型。
配置
主要设置位于同一页面：WooCommerce > Settings > Shipping > VibeFox The Courier Guy。这些设置适用于所有配送区域。将该方式添加到某个区域时，区域窗口中有两个字段：
Title (zone)：该区域中结账时显示的此运费名称。留空则使用全局的 Method name。
Delivery type (zone)：Courier to the door（默认）或 TCG locker (customer chooses a locker)。添加两次即可同时提供两者。快递柜需要 ShipLogic API 密钥，且仅在南非可用。
每次保存设置时，缓存的运费和快递柜都会被清除。设置上方的提示会在以下情况显示：店铺不配送至南非、缺少 API 密钥、缺少 ZAR 汇率或发件地址、既没有价格表也没有备用运费，或上一次 ShipLogic 请求失败（并附带日期和错误信息）。
常规
Enable/Disable：在所有地方关闭该方式，包括配送区域。
Method name：结账时显示的名称。快递柜配送时会在名称后加上“locker”，例如“The Courier Guy locker”。某个区域可用自己的标题覆盖它。默认：The Courier Guy。
Tax status：Taxable：实时运费不含增值税，WooCommerce 会另外添加自己的税费。None：实时运费含增值税。
ShipLogic API（实时运费与快递柜）
API key：您在 The Courier Guy 门户中获取的 ShipLogic API 密钥。
Account ID：可选。ShipLogic 数字账户 ID，仅当您的密钥可访问多个账户时才需要。
实时运费（适用于南非地址；如果没有实时运费，则使用价格表）
Price source：运费来源。
ZAR conversion rate：ShipLogic 以南非兰特（ZAR）报价。如果店铺货币不是 ZAR，请填写 1 ZAR 等于多少店铺货币，例如 0.05。未填写时，不使用实时运费，而是采用价格表。如果店铺货币是 ZAR，请留空。该汇率不会自动更新。
发件地址（用于实时运费）（The Courier Guy 在南非取件的地址；实时运费需要街道、城市、省份和邮政编码）
Sender company：您的公司名称。
Sender street address：例如 12 My Road。
Sender suburb：发件地址所在的郊区。
Sender city：发件地址所在的城市。
Sender province：从列表中选择南非省份。
Sender postal code：发件地址的邮政编码。
价格表（以店铺货币设置您自己的价格：与 Price table only 一起使用、用于南非以外地区，以及在没有实时运费时使用；可接受小数点或小数逗号）
Calculation type：仅适用于价格表。实时运费始终针对整个订单。
Prices by weight：国家表格，包含 Price 列以及重量区间 XS（最多 1 kg）、S（最多 2 kg）、M（最多 3 kg）、L（最多 5 kg）和 XL（超过 5 kg）。点击 + Add row 可添加一行（新行默认从南非开始），点击叉号可删除。区间为空或为 0 时使用 Price 列。价格为 0 表示免运费。* Any country 行适用于没有自己行的国家，以及没有任何价格的国家行。
Fallback cost：在既没有实时运费也没有表格价格时使用。留空则在这种情况下隐藏该方式。
条件
Min weight (kg)：购物车重量低于此值时隐藏该方式。0 表示不限制。
Max weight (kg)：购物车重量高于此值时隐藏该方式。默认：30。0 表示不限制。
Minimum order amount：仅当购物车小计达到此金额时才显示该方式。留空则始终显示。
Free shipping from：购物车小计达到此金额后，该方式免运费。只有当该方式对目的地有价格时才会提供免运费：实时运费、表格价格或 Fallback cost。如果表格或 Fallback cost 有价格，则不会向 ShipLogic 发送运费请求。留空则从不提供免运费。
Excluded shipping classes：如果购物车中包含这些 WooCommerce 配送类别的商品，则隐藏该方式。
无配送区域时的可用性
Ignore shipping zones：即使没有任何区域包含该方式，也会为下面列出的国家提供该方式。
Delivery type without zones：该模式下使用 courier 或 TCG locker。仅与 Ignore shipping zones 一起使用。
Countries：该模式的目的地国家。留空则使用您所有配送国家。快递柜仅在南非提供。
高级
Debug log：将调试信息写入 WooCommerce > Status > Logs，来源为 vfd-the-courier-guy。即使关闭此选项，API 错误也始终会被记录。API 密钥和客户数据绝不会被记录。
Remove data on uninstall：开启后，删除插件时会移除该方式的设置和区域运费。停用插件从不会删除设置。订单中保存的快递柜和追踪信息会保留。
结账时的工作方式
当顾客输入配送地址时，WooCommerce 会向插件请求运费。插件首先检查各项条件：购物车重量、最低订单金额和排除的配送类别。如果适用免运费且目的地有价格，则以 0 元显示该方式。
Courier to the door：插件向 ShipLogic 请求从您的发件地址到顾客地址的最便宜服务。必须先填写顾客的街道、城市、省份和邮政编码。在此之前，显示价格表中的价格。
TCG locker：实时运费是从上门取件到快递柜的最便宜服务，目的地为离顾客城市最近的快递柜。它不会因顾客选择的快递柜而重新计算。
整个订单按一个包裹报价：总重量、最大长度和宽度，以及叠放后的高度。没有尺寸的商品按 10 厘米见方的立方体计算。兰特金额会转换为您的店铺货币。服务等级（例如 ECO）会保存在配送行中。
ShipLogic 请求 12 秒后超时。运费缓存 1 小时，快递柜缓存 6 小时，失败结果缓存 10 分钟，以免响应缓慢的 API 拖慢每次结账页面的刷新。如果没有实时运费，则依次使用价格表中的价格和 Fallback cost。如果都不适用，则隐藏该方式。
该方式适用于经典结账以及购物车和结账区块。它兼容 WooCommerce 高性能订单存储（HPOS）。
插件不会创建运单、托运单或标签，也不会自动更新物流追踪信息。没有快递柜地图：快递柜需从列表中选择。实时运费和快递柜仅适用于南非。其他国家使用价格表。每个区域实例只显示一个运费（最便宜的服务等级），结账时不提供服务等级、保险或附加服务的选择。
取件点
当顾客在经典结账或区块结账中选择 TCG locker 运费时，其下方会出现快递柜选择器。它会按距离由近到远列出 ShipLogic 为配送地址所在城市返回的快递柜。顾客可以输入其他城市、郊区或邮政编码，然后点击 Search。必须选择一个快递柜后才能下单。
服务器会再次根据 ShipLogic 的列表验证快递柜。快递柜的名称和提供商均取自 ShipLogic，而非浏览器。该选择在结账页面刷新后仍会保留，地址更改时会被重置。
如果无法连接 ShipLogic，选择器会提示快递柜无法加载，订单可以在没有快递柜的情况下提交。此时订单会被标记：“Not chosen — ShipLogic was unavailable at checkout. Agree the locker with the customer.”（未选择：结账时 ShipLogic 不可用。请与顾客确定快递柜。）
订单
所选快递柜（名称、ID 和提供商）会保存到订单中。它会显示在管理员订单页面、“感谢购买”和“我的账户”订单页面，以及订单邮件（HTML 和纯文本）中。管理员邮件还会显示快递柜 ID。
在管理员订单页面，使用此方式的订单会有一个 The Courier Guy tracking reference 字段。请输入您 The Courier Guy 门户中的编号，然后点击 Save。该编号会显示在顾客的订单页面以及之后发送的邮件中。
许可证密钥
插件需要使用从 vibefox.net 获取的 VibeFox 许可证密钥。许可证区块位于 WooCommerce > Settings > Shipping > VibeFox The Courier Guy 的顶部。将密钥粘贴到 License key 中，然后点击 Activate。区块会显示状态，例如许可证有效期截止日期以及您的域名。使用 Check now 重新检查状态，使用 Change key 输入其他密钥，使用 Remove key 将其从本站移除。Manage licenses and domains in your account 链接会打开您的 vibefox.net 账户。
一个密钥只能用于一个域名。从站点移除密钥不会释放其域名名额，请在您的 vibefox.net 账户中释放名额。
没有有效密钥时，顾客在结账时不会看到 The Courier Guy。已登录的店铺管理员仍能看到该方式，并标有 (unlicensed — visible to admins only)，以便您在购买密钥前进行设置和测试。插件页面和 WooCommerce 页面会显示提醒。已有订单不受影响。
许可证到期后，插件仍可继续工作，但更新和支持需要续订。系统会在后台自动重新检查状态。
故障排除
结账时不显示 The Courier Guy：请检查许可证是否有效、Enable/Disable 是否开启、该方式是否已添加到顾客所在国家的配送区域（或 Ignore shipping zones 已开启且允许该国家）。检查重量限制、Minimum order amount 和 Excluded shipping classes。检查价格表或 Fallback cost 是否有价格。快递柜运费仅显示给南非地址。
顾客看不到快递柜列表：快递柜需要 API 密钥、Delivery type 为“TCG locker”的区域方式，以及南非配送地址。设置页面会显示最近一次 ShipLogic 错误（如有），例如密钥被拒绝。
价格始终是价格表中的价格：请查看设置页面上的提示。实时运费需要 API 密钥、完整的发件地址，以及对于非兰特货币的店铺，还需要 ZAR 汇率。快递上门配送需要填写顾客的街道、城市、省份和邮政编码。快递柜需要 ShipLogic 能在顾客城市附近找到快递柜。请开启 Debug log，然后打开 WooCommerce > Status > Logs，来源为 vfd-the-courier-guy。
ShipLogic 无法访问：显示价格表或备用价格。快递柜订单可以在没有快递柜的情况下提交，并会在订单中被标记。
修改后运费似乎过时：请保存设置页面，这会清除缓存的运费和快递柜。
许可证区块显示错误：请按照区块中的提示操作。例如，如果该密钥已在其他域名上使用，请在 vibefox.net 账户中释放一个名额，然后点击 Check now。如果站点地址已更改，请点击 Check now 以便为新域名激活密钥。如果无法连接许可证服务器，插件将继续使用最后已知的状态运行。
卸载
停用插件会保留设置，仅清除缓存的运费和快递柜。若要删除插件，请先停用，然后在 Plugins 页面中删除。本插件的许可证密钥和许可证状态、缓存的运费和快递柜以及最后一次错误始终会被删除。只有在开启 Remove data on uninstall 的情况下，设置和区域运费才会被删除；否则，它们会保留，以便日后重新安装时使用。订单中保存的快递柜和追踪编号永远不会被删除，现有订单也会保留其配送行。
The Courier Guy 和 ShipLogic 是其各自所有者的商标。本插件与 The Courier Guy 或 ShipLogic 没有关联，也未获得它们的认可或背书。