VibeFox The Courier Guy for PrestaShop — 帮助
系统要求
PrestaShop：8.0 至 9.x。
PHP：8.0 或更高版本。模块拒绝在更旧的 PHP 版本上安装。
ShipLogic API 密钥（用于实时运费和快递柜）：The Courier Guy 运行在 ShipLogic 平台上。请在 The Courier Guy 快递门户的 Settings > API Keys 下创建 API 密钥（企业账户）。没有该密钥时，仅使用价格表，且不提供快递柜承运商。
配送至南非：实时运费和快递柜仅适用于南非地址。南非必须是店铺中已启用的国家（International > Locations > Countries）。
VibeFox 许可证密钥：在 vibefox.net 购买。一个密钥只能用于一个域名。
安装
1. 进入后台，前往 Modules > Module Manager，点击 Upload a module。选择模块的 ZIP 文件。
2. 上传完成后，点击 Configure；或之后在模块列表中找到 VibeFox The Courier Guy，再点击 Configure。
3. 将您的 VibeFox 许可证密钥粘贴到 Configure 页面顶部许可证区块中的 License key 字段，然后点击 Activate（参见许可证密钥）。
4. 输入 ShipLogic 的 API key。若要使用实时运费，请填写发货地址（街道、城市、省份、邮政编码）；如果店铺货币不是 ZAR，还需填写 ZAR conversion rate。
5. 填写价格表和/或备用运费，然后点击 Save。
6. 若要使用实时快递运费，如果页面提示南非地址没有省份，请在 Advanced 部分点击 Add South African provinces。
安装时，模块会创建两种承运商：The Courier Guy（配送时间文本 The Courier Guy courier delivery to your door）和 The Courier Guy locker（Delivery to a TCG locker of your choice）。两者均已启用，并关联南非区域和所有客户群组。您可以在 Shipping > Carriers 中修改区域、客户群组、配送时间、Logo 和尺寸限制。请勿在那里设置价格：价格始终由模块提供。
配置
所有设置都位于模块页面：Modules > Module Manager > VibeFox The Courier Guy > Configure。每个部分都有各自的 Save 按钮，点击后会保存整个页面。每次保存都会清除缓存的运费、快递柜以及最近一次 ShipLogic 错误。页面顶部的警告会提示：南非不是店铺中已启用的国家、缺少 API 密钥、缺少 ZAR 汇率或发货地址、没有价格表也没有备用运费、南非地址没有省份、模块无法识别店铺的重量或尺寸单位，或最近一次 ShipLogic 请求失败（附日期和错误信息）。无效数字（例如负数）不会被保存：页面会指出对应字段并保留之前的值。
常规
Courier to the door：启用或停用快递上门承运商。这与 Shipping > Carriers 中承运商状态使用的是同一开关。
Courier carrier name：结账时显示的快递承运商名称。默认值：The Courier Guy。必填。
TCG locker：启用或停用快递柜承运商。客户在结账时选择快递柜。仅对南非地址提供，并且仅在配置了 ShipLogic API 密钥时提供。
Locker carrier name：结账时显示的快递柜承运商名称。默认值：The Courier Guy locker。必填。
Tax status：两个承运商的税务规则。Taxable: <tax rule>：实时运费采用不含增值税的价格，PrestaShop 会添加所选规则的运费税。None：实时运费采用含增值税的价格。
ShipLogic API（实时运费和快递柜）
API key：您在 The Courier Guy 门户中获取的 ShipLogic API 密钥。它绝不会显示给客户，也不会写入日志。保存后，该字段保持为空，并显示 Saved - leave empty to keep it. 只有在需要更改时才输入新值。勾选 Remove the saved API key 并保存，即可删除已保存的密钥。
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 表示不限制，留空表示 30 kg。若 Min weight (kg) 大于 Max weight (kg)，页面会显示警告，两个限制都保留之前的值。
Minimum order amount：仅当购物车小计达到此金额时才显示承运商（需要配送的商品，不含税，折扣后）。留空则始终显示。
Free shipping from：购物车小计达到此金额即免运费。留空则从不提供免运费。小计达到该值时，承运商会以 0 元价格显示，并且不会向 ShipLogic 请求运费。
无配送区域时的可用性
通常，承运商会在其在 Shipping > Carriers 中关联的配送区域内提供。
Ignore shipping zones：即使承运商的区域不包含下列国家，也为下列国家提供下方所选配送类型的承运商。承运商会关联到每个已启用的区域，包括之后创建的区域。重新关闭该选项后，承运商会恢复之前拥有的区域。
Delivery type without zones：Courier to the door 或 TCG locker (customer chooses a locker)。仅与 Ignore shipping zones 一起使用。
Countries：该模式的目的地国家。留空则允许所有国家。快递柜仅在南非提供。
高级
South African provinces：PrestaShop 没有南非省份，但实时快递运费需要地址的省份。Add South African provinces 会将 9 个省份（EC、FS、GP、KZN、LP、MP、NC、NW、WC）添加为南非的州/省，并在南非地址中显示州/省字段。已存在的省份不会重复添加。在此之前，快递承运商会获取价格表中的价格。
Debug log：将调试信息写入模块文件夹中的 logs/vfd_tcgr_debug.log.php。该文件无法通过网页打开。即使此选项关闭，API 错误也始终会记录。API 密钥和客户数据绝不会被记录。
Log：显示日志的大小和最新条目。点击 Clear log 可清空日志。
Remove data on uninstall：启用时，卸载模块会删除其设置和承运商。禁用时，卸载只会关闭承运商。已保存在订单中的快递柜信息始终保留。
结账时的运作方式
在配送步骤中，PrestaShop 会向模块请求每个承运商的运费。仅实体商品计算在内：虚拟商品不增加重量，也不计入订单金额。模块会先检查条件：购物车重量和最低订单金额。若适用免运费，则价格为 0。
Courier to the door：模块会向 ShipLogic 请求从发货地址到客户地址的最便宜服务。地址必须包含街道、城市、省份和邮政编码。在此之前使用价格表。
TCG locker：实时运费是从门到快递柜的最便宜服务，目的地为离客户所在城市最近的快递柜。它不会针对客户所选的快递柜重新计算。快递柜承运商仅对南非地址显示，并且仅在配置了 API 密钥时显示。
整个订单按一个包裹计算：总重量、最长长度和宽度，以及叠加后的高度。没有尺寸的商品按 10 cm 立方体计算。重量和尺寸会从店铺单位换算。兰特金额会换算为默认货币，然后以客户购物车货币显示。
ShipLogic 请求 12 秒后超时。运费缓存 1 小时，快递柜缓存 6 小时，失败结果缓存 10 分钟，以免 API 变慢时每次结账刷新都变慢。若没有实时运费，则使用价格表中的价格，再否则使用 Fallback cost。如果两者都不适用，承运商会被隐藏。API 错误绝不会显示给客户。
承运商适用于 Classic 和 Hummingbird 主题。如果您在订单产生后，在 Shipping > Carriers 中编辑承运商，PrestaShop 会将其保存为新的承运商版本。模块会自动使用新版本。
模块不会创建托运单、运单或面单，也不会自动更新物流信息。没有快递柜地图：快递柜从列表中选择。实时运费和快递柜仅适用于南非。其他国家使用价格表。每个承运商仅显示一种运费（最便宜的服务级别），结账时无法选择服务级别、保险或附加服务。
自提点
客户选择快递柜承运商后，其下方会出现快递柜选择器。它会列出 ShipLogic 针对收货地址所在城市返回的快递柜，最近的排在最前。客户可以输入其他城市、郊区或邮政编码，然后点击 Search。客户必须先选择一个快递柜才能继续，否则配送步骤会显示 Please choose a The Courier Guy locker.
下单时，服务器还会再次将快递柜与 ShipLogic 的列表进行核对。快递柜名称和服务商均取自 ShipLogic，绝不取自浏览器。该选择会保存在购物车中，并在收货地址更改时重置。
如果无法连接 ShipLogic，选择器会提示快递柜无法加载，并说明店铺会就快递柜与客户联系。此时可以在不选择快递柜的情况下下单。该订单会在后台订单页面标记：Not chosen - ShipLogic was unavailable at checkout. Agree the locker with the customer.
订单
所选快递柜（名称、ID 和服务商）会与订单一起保存。它会显示在后台订单页面的 The Courier Guy 区块、订单确认页面、客户的订单详情以及订单确认邮件中。店铺的“新订单”邮件（Mail alerts 模块）也会显示快递柜 ID；如果因 ShipLogic 不可用而未选择快递柜，邮件会注明这一点。
The Courier Guy 追踪编号：在您的 The Courier Guy 门户中预订包裹，然后将运单号作为订单 Shipping 区块（Edit）中的发货追踪编号填写。The Courier Guy 区块会显示该编号。客户可在订单详情中看到它，并会收到 PrestaShop 发出的“运输中”邮件。
许可证密钥
本模块使用来自 vibefox.net 的 VibeFox 许可证密钥。许可证区块 License — VibeFox The Courier Guy 是 Modules > Module Manager > VibeFox The Courier Guy > Configure 页面的第一个区块，位于设置上方。将密钥粘贴到 License key，然后点击 Activate。之后，该区块会以掩码形式显示密钥、状态（例如许可证有效期截止日期以及您的域名），并提供以下按钮：Check now（重新检查状态）、Change key（输入其他密钥）和 Remove key（从本店移除密钥）。其下方是一行 Product: presta-shipping-the-courier-guy 以及链接 Manage licenses and domains in your account，点击后会打开您的 vibefox.net 账户。只有拥有本模块 Configure 权限的员工可以更改密钥。该区块的文字随后台语言显示（包括英语和俄语）。
如果密钥未被接受，该区块会说明原因，例如 Key not found、This key belongs to another product、Domain limit reached，或 License expired on 加上一个日期。店铺地址更改后，或在您的账户中释放了一个域名名额后，点击 Check now。如果无法连接许可证服务器，模块将继续按最后已知的状态运行。
一个密钥只能用于一个域名：即主店铺的域名，多店铺设置中也是如此。从店铺中移除密钥不会释放其域名名额。请在您的 vibefox.net 账户中释放名额。
没有有效密钥时，The Courier Guy 承运商（courier to the door 或 TCG locker）都不会在结账时显示给客户，也不会计算运费。PrestaShop 前台无法识别您已登录后台，因此承运商对您也会隐藏：您可以在购买密钥之前设置模块，但无法在结账时测试。Modules > Module Manager 的 Alerts 选项卡中会出现提醒。现有订单不受影响。
许可证到期后，模块仍会继续运行，但更新和支持需要续订。在您使用后台时，状态会自动重新检查：输入密钥后的前 14 天每天一次，之后每周一次。无需 cron 任务。卸载模块时始终会删除许可证密钥和许可证状态。本模块的 Reset 不会删除数据，因此密钥和状态会保留。
故障排除
结账时没有显示 The Courier Guy：请检查许可证是否有效，以及承运商是否已启用（Courier to the door 或 TCG locker）。在 Shipping > Carriers 中，检查该承运商是否覆盖客户所在国家的区域和客户群组（或者 Ignore shipping zones 已启用且该国家被允许）。检查重量限制和 Minimum order amount。检查价格表或 Fallback cost 中是否有价格。快递柜承运商仅对南非地址且配置了 API 密钥时显示。此外，产品页面可能将商品限制为特定承运商。
客户看不到快递柜列表：快递柜需要 API 密钥、已启用的 TCG locker 承运商以及南非收货地址。设置页面会显示最近一次 ShipLogic 错误（如有），例如密钥被拒绝。
运费始终是价格表中的价格：请检查设置页面上的警告。实时运费需要 API 密钥、完整的发货地址，以及对于非兰特货币的店铺，需要 ZAR 汇率。对于快递上门配送，客户地址需要街道、城市、省份和邮政编码：请在 Advanced 部分添加南非省份。对于快递柜，ShipLogic 必须在客户所在城市附近找到快递柜。请开启 Debug log，重新加载结账页面，然后查看模块页面上的 Log 字段。
ShipLogic 无法使用：显示价格表或备用运费。快递柜订单可以不选快递柜下单，并会在订单上标记。
更改后运费似乎过时：在模块页面点击 Save。这会清除缓存的运费和快递柜。
页面提示找不到 The Courier Guy 承运商：该承运商已在 Shipping > Carriers 中被删除。请在 Modules > Module Manager 中重置模块以重新创建。重置会保留您的设置以及现有承运商的启用状态。
卸载
前往 Modules > Module Manager，打开 VibeFox The Courier Guy 旁边的菜单，然后选择 Uninstall。许可证密钥和许可证状态始终会被删除。缓存的运费和快递柜以及最近一次 ShipLogic 错误始终会被删除。如果 Remove data on uninstall 已启用，承运商会被删除（订单保留其历史记录），并且设置、日志以及没有订单的购物车中的快递柜会被删除。如果已禁用，承运商只会被关闭，所有设置都会保留。重新安装模块后，承运商会恢复之前的状态。已保存在订单中的快递柜绝不会被删除。
The Courier Guy 和 ShipLogic 是其各自所有者的商标。本模块与 The Courier Guy 或 ShipLogic 没有关联，也未获其认可。