VibeFox GLS ParcelShop for OpenCart — 帮助
系统要求
OpenCart：3.0.x（已在 3.0.5.0 上测试）或 4.0.2 及更高版本（已在 4.1.0.3 上测试），使用默认主题及其单页结账。
PHP：8.0 或更高版本。
GLS：本扩展不使用、也不需要 GLS 账户或 API 密钥。ParcelShop 地图是公开的。您需要与 GLS 签订合同，才能将包裹发往所选 ParcelShop。
内容安全策略：如果您的店铺发送了内容安全策略（Content Security Policy），请允许 map.gls-croatia.com，GLS 地图脚本即从该域名加载。
VibeFox 许可证密钥：在 vibefox.net 购买。一个密钥仅适用于一个域名。
安装
下载文件是一个 zip 压缩包，包含两个 OpenCart 版本的安装包。请先在您的电脑上解压。压缩包中包括 README.txt、OpenCart 3 安装包 vfd_gls_parcelshop-oc3-(version).ocmod.zip 和 OpenCart 4 安装包 vfd_gls_parcelshop.ocmod.zip。只安装与您的 OpenCart 版本对应的安装包。两个版本的许可证密钥相同。
OpenCart 3
1. 在后台进入 Extensions > Installer，点击 Upload，然后选择文件 vfd_gls_parcelshop-oc3-(version).ocmod.zip。本扩展不添加任何 OCMOD 修改，因此无需刷新 Extensions > Modifications。您也可以不使用安装器，直接将本安装包中 upload 文件夹的内容复制到店铺的根目录。
2. 进入 Extensions > Extensions，扩展类型选择 Shipping。找到 VibeFox GLS ParcelShop，点击 Install（绿色 + 按钮）。
3. 点击 Edit（铅笔按钮）打开设置页面。
4. 在 Edit 页面顶部的许可证区块中，将 VibeFox 许可证密钥输入 License key，然后点击 Activate（参见 License key）。
5. 设置价格：至少添加一行 Country prices（例如 * Default），或设置 Fallback cost（参见配置）。开启 Enable/Disable 并点击 Save。
OpenCart 4
1. 在后台进入 Extensions > Installer，点击 Upload，然后选择文件 vfd_gls_parcelshop.ocmod.zip。请勿重命名该文件：OpenCart 4 从文件名获取扩展代码，重命名后的安装包无法使用。
2. 安装包会出现在同一页面的已安装扩展列表中。点击其旁边的 Install（绿色 + 按钮）。
3. 进入 Extensions > Extensions，扩展类型选择 Shipping。找到 VibeFox GLS ParcelShop，点击 Install（绿色 + 按钮），然后点击 Edit（铅笔按钮）。
4. 按 OpenCart 3 步骤 4 和 5 的方式输入许可证密钥和设置。两个版本的设置页面及其字段相同。
安装后，在您开启 Enable/Disable 并保存之前，该配送方式处于关闭状态。如果您卸载后重新安装扩展，之前保留的设置将再次生效。
配置
所有设置都在扩展页面中：Extensions > Extensions > Shipping > VibeFox GLS ParcelShop > Edit。各部分列在左侧。页面底部的一个 Save 按钮可保存整个页面，无需重新加载。只有拥有本扩展修改权限的管理员用户才能保存设置。
页面顶部以及每次保存后的警告会指出配置问题：未设置任何价格；所选的 Countries (ignore zones mode) 中有部分或全部不在 GLS 地图覆盖范围内；或者店铺的重量单位不被扩展识别，且没有以千克（kg）为单位的重量等级（请在 System > Localisation > Weight Classes 中添加）。无效或负数的值会被拒绝，并显示指明该字段的消息，例如 Fallback cost: "abc" is not a valid number of 0 or more - the previous value was kept. 其他字段仍会保存。无效的 Name、排序、税类或地理区域同样会被拒绝。
常规
本部分列出 GLS 地图覆盖的国家/地区：奥地利、比利时、保加利亚、克罗地亚、捷克共和国、丹麦、芬兰、法国、德国、希腊、匈牙利、意大利、卢森堡、荷兰、波兰、葡萄牙、罗马尼亚、塞尔维亚、斯洛伐克、斯洛文尼亚和西班牙。其他目的地国家/地区不提供该配送方式。
Enable/Disable：在结账时显示或隐藏 GLS ParcelShop。默认：关闭。
Name：向顾客显示的配送方式名称。默认：GLS ParcelShop。必填，最多 64 个字符，不得包含字符 < > ; = # { }。
Tax status：None (shipping is not taxed)，或在配送需要纳税时应用的税类。
Sort order：结账时该配送方式在各配送方式中的位置。整数。
价格
价格以您店铺的默认货币输入，不含税。小数可以使用逗号或句点（4,99 或 4.99）。顾客看到的价格以其自身货币显示。
Calculation type：价格的计算方式。
Country prices：一个表格，每个目的地国家/地区一行。点击 Add country 添加一行。每行包含 Country、Price 以及五个重量列：XS 最多 1 kg，S 1–2 kg，M 2–3 kg，L 3–5 kg，XL 超过 5 kg。系统使用与购物车重量对应的列。重量列保持 0 时，将使用 Price 列。* Default 行用于没有自身单独行的国家/地区。所有价格均为 0 的行表示免费配送，因此保存前请选择国家/地区并填写价格。如果表格中的某个值不是 0 或更大的有效数字，则整个表格都不会保存，消息会列出错误的值。
Fallback cost：当表格中没有目的地国家/地区的行，也没有 * Default 行时使用的价格。留空则对这些国家/地区隐藏该配送方式。
Free shipping from：购物车小计（折扣后、不含税）达到此金额时，GLS ParcelShop 配送免费。如果配送永远不免费，请留空。
可用性
Minimum weight (kg)：购物车重量低于此值时隐藏该配送方式。重量根据商品的重量等级换算。留空或为 0 表示无限制。
Maximum weight (kg)：购物车重量高于此值时隐藏该配送方式。默认：20。GLS ParcelShop 通常接受最大 20 kg 的包裹，请对照您的 GLS 合同确认。留空或为 0 表示无限制。如果最小值大于最大值，两个重量都会被拒绝并显示消息，保留之前的值。
Minimum cart subtotal：仅当购物车小计（折扣后、不含税）达到此金额时才提供该配送方式。留空表示没有最低限额。
Geo zone：仅对该地理区域内的地址提供该配送方式。All zones 表示无限制。开启 Ignore shipping zones 时不使用此项。地理区域在 System > Localisation > Geo Zones 中管理。
Ignore shipping zones：开启时，无论地理区域如何，都会为下方所选的国家/地区提供该配送方式（如果列表为空，则为所有 GLS 地图国家/地区）。关闭时，仅在上方的地理区域中提供。默认：关闭。
Countries (ignore zones mode)：该模式下的目的地国家/地区。留空则使用所有 GLS 地图国家/地区。不在 GLS 地图覆盖范围内的国家/地区将被跳过。该字段仅在 Ignore shipping zones 开启时使用。
高级
Debug log：将运费计算和 ParcelShop 选择记录到 storage/logs/vfd_glps_debug.log.php（OpenCart 4 为 system/storage/logs/vfd_glps_debug.log.php）。该文件无法通过网页读取。错误始终会被记录。不会记录任何顾客个人数据。使用完毕后请关闭日志。当文件达到 5 MB 时，它会被移动到 vfd_glps_debug.old.log.php，并开始新的日志。
Log：显示调试日志的大小和最新条目。点击 Clear log 可清空日志。
Remove data on uninstall：开启时，卸载扩展会删除设置和日志。关闭时，所有内容都会保留，以便重新安装。订单中保存的 ParcelShop 始终保留。
导入 / 导出
Export：点击 Download JSON，将设置保存为 JSON 文件。
Import：粘贴之前导出的 JSON，然后点击 Import 恢复设置，例如在另一家店铺中使用。无效的值会被报告，且不会被导入。
结账时的工作方式
OpenCart 显示配送方式时，会向扩展请求 GLS ParcelShop 的价格。如果设置了 Geo zone（且 Ignore shipping zones 关闭），并且地址位于该区域之外，则不提供该配送方式。只有 Requires Shipping 设为 Yes 的商品才计入：其他商品不增加重量，也不计入购物车小计。小计是这些商品在优惠券折扣之后、不含税的价格。随后扩展检查各项条件：配送国家/地区属于 GLS 地图覆盖范围（并且在该模式开启时已在 Countries (ignore zones mode) 中选中）、购物车重量以及购物车最小小计。如果购物车小计达到 Free shipping from，则免费配送。否则，价格取自该国家/地区的行（或 * Default 行）及对应的重量列，或取自 Fallback cost。如果找不到价格，则隐藏该配送方式。价格会按默认货币的小数位数四舍五入，并按所选 Tax status 的税率显示。
顾客选择 GLS ParcelShop 后，配送方式下方会出现一个 GLS ParcelShop 框，其中有一个 Select GLS ParcelShop 按钮。点击后会打开该配送国家/地区的官方 GLS ParcelShop 地图。位于其他国家/地区的 ParcelShop 会被立即拒绝。选定 ParcelShop 后，会显示其名称和地址，按钮变为 Change ParcelShop。该选择保存在顾客的会话中，因此重新加载配送步骤时仍会保留。如果收货地址改为另一个国家/地区，顾客必须重新选择 ParcelShop。
顾客在配送方式步骤中点击 Continue 时，扩展会检查是否已选择 ParcelShop，以及该 ParcelShop 是否位于配送国家/地区。否则，顾客会看到 Please select a GLS ParcelShop. 或 The selected GLS ParcelShop is not in your shipping country. Please choose a ParcelShop again.，并停留在该步骤。如果无法保存 ParcelShop，顾客会看到 The ParcelShop could not be saved. Please try again. 如果无法加载 GLS 地图脚本，顾客会看到 The GLS ParcelShop map could not be loaded. Please reload the page or choose another shipping method.
在 OpenCart 4 中，顾客在结账页面的配送方式区块中点击 Choose，然后在 Shipping method options 窗口中选择 GLS ParcelShop。GLS ParcelShop 框（含 Select GLS ParcelShop 按钮）会在该窗口中显示在配送方式下方，GLS 地图则在窗口上方打开。窗口中的 Continue 按钮在没有有效 ParcelShop 时不会继续，显示的消息相同。OpenCart 4 为结账保留一个订单，并在顾客每次重新确认时更新该订单，订单中的 ParcelShop 也会随之更新。
GLS 地图在顾客的浏览器中运行。在结账页面上，扩展会从 map.gls-croatia.com 加载 GLS 地图脚本，地图则从 GLS 加载 ParcelShop 数据和地图图块。GLS 会接收访问者通常的请求数据（IP 地址、浏览器）。您的服务器不会向 GLS 发送任何内容。扩展中的错误绝不会中断其他配送方式的结账，而是会被写入日志。
本扩展不获取 GLS 的实时运费，不创建 GLS 运单，不打印标签，也不追踪包裹。您的服务器上没有 ParcelShop 列表，因此无法对照 GLS 验证 ParcelShop ID。请按您平常的方式将订单中的 ParcelShop ID 提供给 GLS（MyGLS、您的 GLS 软件或其他扩展）。
取件点
下单时，结账时所选的 ParcelShop 会与订单一起保存：其 ID、名称及地址，以及国家/地区。订单完成后，该选择会被清除，因此下一个购物车将不带 ParcelShop 开始。
Shipping method name：ParcelShop 会被添加到订单的配送方式名称中，例如 GLS ParcelShop: name, address（先是配送方式名称，然后是 ParcelShop）（OpenCart 3 最多保留其中 128 个字符，OpenCart 4 最多保留 255 个字符）。因此 ParcelShop 会出现在发给顾客的订单确认邮件中、顾客 Order History 中的订单页面以及 Sales > Orders 中。OpenCart 不会在订单成功页面上显示配送方式。
Admin order page：在 Sales > Orders 中，GLS ParcelShop 面板会显示 ParcelShop 的名称和地址，以及 ParcelShop ID 和国家/地区。如果某个 GLS ParcelShop 订单没有 ParcelShop，该面板会显示 No ParcelShop was selected for this order. 该面板仅显示 ParcelShop，无法在此处更改。
商家邮件：发送给店铺的新订单提醒邮件会在备注区块中包含 ParcelShop 及其 ParcelShop ID。
许可证密钥
本扩展使用来自 vibefox.net 的 VibeFox 许可证密钥。许可证区块 License — VibeFox GLS ParcelShop 是 Extensions > Extensions > Shipping > VibeFox GLS ParcelShop > Edit 页面中的第一个区块，位于设置上方。将密钥粘贴到 License key 中，然后点击 Activate。之后，该区块会以隐藏方式显示密钥、状态（例如许可证有效期截止日期和您的域名），以及按钮 Check now（重新检查状态）、Change key（输入其他密钥）和 Remove key（从此店铺中移除密钥）。其下方是 Product: opencart-shipping-gls-parcelshop 一行和链接 Manage licenses and domains in your account，点击后将打开您的 vibefox.net 账户。只有拥有本扩展修改权限的管理员用户才能更改密钥。该区块的文字跟随后台语言（包括英文和俄文）。
如果密钥未被接受，区块会说明原因，例如 Key not found、This key belongs to another product、Domain limit reached 或 License expired on 加某个日期。更改店铺地址后，或在您的账户中释放一个域名名额后，请点击 Check now。如果无法连接许可证服务器，扩展将继续使用最后已知的状态运行。
一个密钥仅适用于一个域名：即 OpenCart 配置中的店铺地址。从店铺中移除密钥并不会释放其域名名额。请在您的 vibefox.net 账户中释放该名额。
如果没有有效的密钥，结账时不会向顾客显示 GLS ParcelShop 配送方式，也不会计算运费。在同一浏览器中登录后台的管理员仍会在店铺中看到该配送方式，并标注 (unlicensed — visible to admins only)，因此您可以在购买密钥前完成扩展的设置和测试。OpenCart 4 不提供此预览功能：店铺看不到后台登录状态，因此没有有效密钥时，该配送方式对所有人都隐藏。打开一次 Edit 页面后，后台的 Dashboard 会显示一条提醒。点击 × 可将其关闭，7 天内不再显示。现有订单不受影响。
许可证到期后，扩展仍会继续工作，但更新和支持需要续费。在您打开后台的 Dashboard 或 Edit 页面时会自动再次检查状态：输入密钥后的前 14 天每天一次，之后每周一次。无需 cron 任务。卸载扩展时始终会删除许可证密钥和许可证状态。
故障排除
结账时未显示 GLS ParcelShop：请检查许可证是否有效，以及 Enable/Disable 是否已开启。检查 Geo zone，或 Ignore shipping zones 与 Countries (ignore zones mode)。检查目的地国家/地区是否属于 GLS 地图国家/地区，并且有价格（国家/地区行、* Default 行或 Fallback cost）。检查重量限制和 Minimum cart subtotal，并确认商品的 Requires Shipping 设为 Yes。开启 Debug log，并查看 Log 字段以了解原因。
地图无法打开：当 GLS 脚本被广告或隐私拦截器、内容安全策略阻止，或 GLS 服务中断时，顾客会看到 "The GLS ParcelShop map could not be loaded..."。请在您的内容安全策略中允许 map.gls-croatia.com。
ParcelShop 框未显示在配送方式下方：本扩展已在 OpenCart 默认主题及其结账页面下测试。若某个主题或结账扩展替换了配送方式步骤，则可能不会显示该框。
某个国家/地区的配送被错误地设为免费：请检查 Country prices 中该国家/地区的行。若 Price 及所有重量列均为 0，则表示免费配送。
表格或某个字段未保存：某个值不是 0 或更大的有效数字。页面顶部的消息会指出该值。请使用数字，并以逗号或句点作为小数分隔符。
订单显示 No ParcelShop was selected for this order：该订单是在没有配送国家/地区 ParcelShop 的情况下下单的。原因已写入日志。请向顾客索取 ParcelShop，并手动提供给 GLS。
页面显示 "Warning: You do not have permission to modify VibeFox GLS ParcelShop!"：您的管理员用户组可能只能查看设置。请在 System > Users > User Groups 中为该组授予 extension/shipping/vfd_gls_parcelshop（OpenCart 3）或 extension/vfd_gls_parcelshop/shipping/vfd_gls_parcelshop（OpenCart 4）的修改权限。
对开发人员：GLS 地图脚本的地址可以通过设置 vfd_glps_widget_url 替换；该设置在设置页面上没有对应字段。
卸载
进入 Extensions > Extensions，选择类型 Shipping，然后点击 VibeFox GLS ParcelShop 旁边的 Uninstall（红色 − 按钮）。该扩展的许可证密钥和许可证状态总会被删除。OpenCart 总会重置 Enable/Disable、Sort order、Tax status 和 Geo zone。扩展总会删除其事件。如果开启了 Remove data on uninstall，其他设置和调试日志也会被删除；如果关闭，它们会被保留，并在您重新安装扩展时再次使用。顾客在未结账的购物车中选择的 ParcelShop 会保留在其会话中直至过期。订单中保存的 ParcelShop 始终保留，现有订单的配送方式和费用保持不变。
在 OpenCart 4 中，如需同时删除扩展文件，请在卸载后进入 Extensions > Installer，在已安装扩展列表中点击 VibeFox GLS ParcelShop 旁边的 Uninstall（橙色 − 按钮），然后点击 Delete（红色垃圾桶按钮）删除已上传的安装包。
GLS 是其各自所有者的商标。本扩展与 GLS 无关联，也未获得 GLS 的认可。