VibeFox GIG Logistics for OpenCart — 帮助
系统要求
OpenCart：3.0.x（已在 3.0.5.0 上测试）或 4.0.2 及更高版本（已在 4.1.0.3 上测试）。
PHP：8.0 或更高版本。
GIG Logistics API 凭据（仅用于实时价格）：实时价格使用 GIG Logistics 第三方 API。GIG Logistics 会向企业客户提供 API 用户名（通常是电子邮件地址）和密码。请在 GIG Logistics 开发者页面（giglogistics.com/developer）申请。测试凭据仅适用于测试 API。如果您只使用价格表和备用费用，则无需 API 凭据。
商店中的尼日利亚：实时价格仅针对尼日利亚的送货地址请求。OpenCart 已包含尼日利亚国家及其 37 个州；该国家必须在 System > Localisation > Countries 中启用。
VibeFox 许可证密钥：在 vibefox.net 购买。一个密钥只能用于一个域名。
安装
下载的是一个压缩包，其中包含两个 OpenCart 版本的安装包。请将其解压到您的电脑上。压缩包包含 README.txt、OpenCart 3 安装包 vfd_gig_logistics-oc3-(version).ocmod.zip，以及 OpenCart 4 安装包 vfd_gig_logistics.ocmod.zip。只安装与您的 OpenCart 版本对应的安装包。两个版本使用相同的许可证密钥。
OpenCart 3
1. 在后台进入 Extensions > Installer，点击 Upload，然后选择文件 vfd_gig_logistics-oc3-(version).ocmod.zip。该扩展不添加任何 OCMOD 修改，因此您无需刷新 Extensions > Modifications。您也可以不使用安装器，而是将本安装包中 upload 文件夹的内容复制到商店的根目录。
2. 进入 Extensions > Extensions，选择扩展类型 Shipping。找到 VibeFox GIG Logistics，点击 Install（绿色的 + 按钮）。
3. 点击 Edit（铅笔按钮）打开设置页面。
4. 将您的 VibeFox 许可证密钥粘贴到 Edit 页面顶部许可证区块的 License key 中，然后点击 Activate（参见许可证密钥）。
5. 填写价格表和/或备用费用。对于实时价格，还需输入 API 用户名和密码、取件电话、街道、城市和州，以及如果默认货币不是 NGN 的换算汇率（参见配置）。启用 Enable/Disable，然后点击 Save。
OpenCart 4
1. 在后台进入 Extensions > Installer，点击 Upload，然后选择文件 vfd_gig_logistics.ocmod.zip。请勿重命名该文件：OpenCart 4 从文件名获取扩展代码，重命名后的安装包无法使用。
2. 该安装包会出现在同一页面的已安装扩展列表中。点击其旁边的 Install（绿色的 + 按钮）。
3. 进入 Extensions > Extensions，选择扩展类型 Shipping。找到 VibeFox GIG Logistics，点击 Install（绿色的 + 按钮），然后点击 Edit（铅笔按钮）。
4. 按照 OpenCart 3 步骤 4 和 5 的方式输入许可证密钥和设置。两个版本的设置页面及其字段相同。
安装后，在您启用 Enable/Disable 并保存之前，该方式保持关闭。如果您卸载后重新安装该扩展，将重新使用您保留的设置。
配置
所有设置均位于扩展页面：Extensions > Extensions > Shipping > VibeFox GIG Logistics > Edit。各分区列在左侧。页面底部的一个 Save 按钮可在不重新加载页面的情况下保存整个页面。每次保存还会清除缓存的 GIG Logistics 价格、API 令牌和地址坐标。只有具备该扩展修改权限的管理员用户才能保存设置。
在页面顶部以及每次保存后，当实时价格无法使用时，扩展会显示警告：仅填写了 API 用户名或密码之一，Sender phone 或取件城市和州缺失，或者默认货币不是 NGN 且未设置 Currency conversion rate。如果您的商店没有单位为 kg 的重量类别（System > Localisation > Weight Classes），它也会发出警告；此时，商品重量将按其单位名称（kg、g、lb、oz）换算，其他单位按 kg 处理。保存时，如果数值有误（负金额、Currency conversion rate 为 0、纬度不在 -90 到 90 之间、经度不在 -180 到 180 之间），Min weight (kg) 大于 Max weight (kg)，Method title 为空或无效，排序值不是整数，或税类或地理区域未知，系统都会报告，并且不会保存任何内容。
常规
该方式会针对 Conditions 中选定的地理区域提供，或针对 Ignore shipping zones 中的国家提供。此页面上的设置适用于所有区域。
Enable/Disable：在结账时显示或隐藏 GIG Logistics（即本扩展的状态）。默认：关闭。
Method title：在购物车和结账时显示的配送方式名称。默认：GIG Logistics。必填，1 至 64 个字符，且不能包含字符 < > ; = # { }。
Tax class：配送费用的税类，或 No tax。税类会在费用之上加上您的配送税。如果 GIG 价格已包含您想收取的全部费用，请选择 No tax。
Sort order：该方式在各配送方式中的位置。一个整数。
GIG Logistics API（实时价格）（可选）
设置 API 凭据后，系统会为每个尼日利亚地址向 GIG Logistics 请求价格，并缓存 1 小时。如果没有凭据，或 API 未返回价格，则使用价格表和备用费用。该分区包含一个指向 GIG Logistics 开发者页面的链接。
API username：您的 GIG Logistics 第三方 API 用户名，通常是您的电子邮件地址。
API password：您的 GIG Logistics 第三方 API 密码。它仅用于登录 API，且绝不会被记录。保存后，该字段保持为空，并显示 Saved — leave empty to keep it. To remove it, clear the API username and save. 只有在要更改时才输入新值。
Test mode：使用 GIG Logistics 测试（dev）API。测试凭据仅适用于测试 API。如需真实价格，请关闭。默认：关闭。
Currency conversion rate：GIG Logistics 以 NGN 返回价格。如果您商店的默认货币不是 NGN，请输入 1 NGN 相当于您默认货币的金额（1 NGN = ? 您的货币，例如 0.0006）。汇率必须大于 0。没有该汇率，则不使用 GIG 实时价格。如果您的默认货币是 NGN，该字段会说明这一点，且无需填写。
取件（发件人）地址
GIG Logistics 在尼日利亚取件的地点。OpenCart 没有结构化的商店地址，因此请在此处输入街道和城市。当您商店所在国家为尼日利亚时，留空的 State 会使用 System > Settings > Store > Local 中的商店地区。
Sender name：发送给 GIG Logistics 的发件人名称。留空则使用商店名称。
Sender phone：您的电话号码，例如 08030000000。实时价格需要 GIG Logistics 提供此信息。
Street address：取件街道地址，例如 1 Adeola Odeku Street。
City / area：取件城市或区域，例如 Victoria Island。实时价格时必填。
State：取件地址所在的尼日利亚州，从 37 个州中选择。默认选项 Store region (System > Settings > Store > Local) 在您的商店位于尼日利亚时使用商店所在地区。实时价格时必填。
Pickup latitude：取件点的可选地图纬度，例如 6.4281。GIG Logistics 按距离计算价格。留空则根据地址查找坐标。
Pickup longitude：取件点的可选地图经度，例如 3.4219。
Address lookup：借助 OpenStreetMap（Nominatim）查找地址的地图坐标。GIG Logistics 根据取件和送货坐标计算价格。客户的街道、城市和州会被发送至 nominatim.openstreetmap.org，结果缓存 30 天。若不开启，则只发送地址文本，GIG Logistics 可能不返回价格。默认：开启。
价格表与备用费用
用于其他国家、未配置实时价格时，或 GIG Logistics 未返回价格时。价格以您商店的默认货币计，不含税。
Country prices：一个按国家设置基础价格的表格。点击 Add country 添加一行。对于没有单独一行的所有国家，请选择 * Any other country。XS ≤1 kg、S ≤2 kg、M ≤3 kg、L ≤5 kg 和 XL >5 kg 列是可选的重量段价格：大于 0 的段价格会替代该段购物车的基础价格。价格为 0 表示免运费。空白或无效的价格单元格会保存为 0，因此请为您添加的每一行填写基础价格。保存后，更正的值会列在以 Country prices: 开头的警告中。没有对应行的国家（当没有 * 行时）不会获得表格价格。
Fallback cost：在 GIG Logistics 和价格表都不提供价格时使用。留空表示此时隐藏该方式。
Table / fallback price is：Per order 只收取一次价格。Per item (multiplied by the number of items) 则将价格乘以购物车中的商品数量。GIG 实时价格始终针对整个订单。
条件
Free shipping from：购物车小计（需要配送的商品，优惠券折扣后，不含税）达到此金额后免运费。留空表示永不免运费。
Minimum subtotal：仅当购物车小计达到此金额时才显示该方式。留空表示始终显示。
Min weight (kg)：购物车的最小重量（kg）。商品重量按其重量类别换算。0 表示无限制。
Max weight (kg)：购物车的最大重量（kg）。默认：30。0 表示无限制。
Geo zone：仅向此地理区域内的地址提供该方式。All zones 表示无限制。与 Ignore shipping zones 一起使用时无效。地理区域在 System > Localisation > Geo Zones 中管理。
不使用配送区域时的可用性
Ignore shipping zones：无论地理区域如何，都为下列国家提供该方式。此时不会检查 Conditions 中的 Geo zone。
Countries：该模式下的目的地国家，从您商店中已启用的国家中选择。留空表示您配送的所有国家。仅在 Ignore shipping zones 开启时使用。
高级
Debug log：将价格计算记录到 storage/logs/vfd_gigl_debug.log.php（OpenCart 4 中为 system/storage/logs/vfd_gigl_debug.log.php）。该文件无法通过网页读取。即使日志关闭，API 和地址查找错误也始终会被记录。密码、令牌和客户地址绝不会被写入。当文件达到 5 MB 时，它会被移动到 vfd_gigl_debug.old.log.php，并开始新的日志。
Log：显示调试日志的大小和最新条目。点击 Clear log 可清空日志。
Remove data on uninstall：开启时，卸载扩展会删除设置和日志。关闭时，所有内容都会保留，以便重新安装。缓存的价格始终会被删除。订单始终会被保留。
导入 / 导出
Export：点击 Download JSON，将设置保存为 JSON 文件。API 密码不会被导出。
Import：粘贴之前导出的 JSON，然后点击 Import，即可恢复设置，例如在另一家商店中。这些值会像正常保存一样进行检查。已保存的 API 密码会被保留。
结账时的工作方式
OpenCart 显示配送方式时，会向扩展请求 GIG Logistics 价格。如果设置了 Geo zone（并且 Ignore shipping zones 处于关闭状态），而地址不在该区域内，则不提供该方式。只有 Requires Shipping 设为 Yes 的商品会被计算：其他商品不增加重量，也不计入小计。小计是这些商品在扣除优惠券折扣后、不含税的价格。礼品卡、积分和商店余额不计入在内。扩展首先检查条件：配送国家（使用 Ignore shipping zones 时）、购物车重量以及最低小计。如果小计达到 Free shipping from，价格为 0，且不会向 GIG Logistics 发出请求。
然后，价格取自第一个能提供价格的来源。首先是 GIG Logistics 实时价格，前提是已输入 API 凭据、地址位于尼日利亚、地址有城市或州、取件电话、城市和州已设置，并且对于默认货币不是 NGN 的商店已设置换算汇率。扩展会登录 GIG Logistics API，并发送取件和送货地址及坐标，以及购物车商品的名称、数量、重量和价值。没有重量的商品按 1 kg 发送。价格按自行车配送请求。其次是 Country prices 价格表。第三是 Fallback cost。如果都不能提供价格，则该购物车隐藏此方式。价格以默认货币计算，按其小数位数舍入，并以客户的货币显示，同时附加所选 Tax class 的税费。
每个 GIG 响应缓存 1 小时，因此同一购物车不会触发新的请求。失败的请求或失败的登录缓存 10 分钟，使结账在每次刷新时都不必等待 GIG Logistics。登录令牌保留 30 分钟，GIG 拒绝时会自动更新。地址坐标保留 30 天，未找到的地址保留 1 天。API 超时时间为 10 秒，地址查找超时时间为 5 秒。
如果 GIG Logistics 返回错误或零价格，客户不会看到任何错误。将使用价格表或备用费用，并将错误写入调试日志。
扩展仅计算价格。它不创建 GIG Logistics 发货单、运单或标签，不预约取件，不跟踪包裹，也不允许客户选择服务中心。它不会向订单添加任何内容：订单显示配送方式名称和运费，与其他任何 OpenCart 配送方式相同。实时价格仅针对尼日利亚地址请求。对于其他国家，请使用价格表。
在 OpenCart 4 中，客户在结账页面的配送方式区块中点击 Choose，然后在 Shipping method options 窗口中选择 GIG Logistics。该选项会显示方式名称和价格，例如 GIG Logistics - $4.50。该方式的工作方式与 OpenCart 3 相同。
许可证密钥
本扩展需要配合一个来自 vibefox.net 的 VibeFox 许可证密钥使用。许可证区块 License — VibeFox GIG Logistics 是 Extensions > Extensions > Shipping > VibeFox GIG Logistics > Edit 页面中位于设置上方的第一个区块。将密钥粘贴到 License key 中并点击 Activate。之后，该区块会以隐藏形式显示密钥、状态（例如许可证有效期至的日期和您的域名），以及以下按钮：Check now（重新检查状态）、Change key（输入其他密钥）和 Remove key（将密钥从此商店中移除）。它们下方是 Product: opencart-shipping-gig-logistics 一行，以及打开您 vibefox.net 账户的链接 Manage licenses and domains in your account。只有拥有该扩展 Modify 权限的管理员用户才能更改密钥。该区块的文字跟随后台语言显示（包含英语和俄语）。
如果密钥未被接受，区块会说明原因，例如 Key not found、This key belongs to another product、Domain limit reached，或 License expired on 加上日期。更改商店地址后，或在您的账户中释放一个域名名额后，请点击 Check now。如果无法连接许可证服务器，扩展会继续使用最后已知的状态工作。
一个密钥只能用于一个域名：即 OpenCart 配置中的商店地址。从商店中移除密钥并不会释放其域名名额。请在您的 vibefox.net 账户中释放该名额。
没有有效密钥时，GIG Logistics 不会在结账时显示给客户，也不会计算价格。在同一浏览器中已登录后台的管理员用户，仍会在商店中看到该配送方式，并标记为 (unlicensed — visible to admins only)，因此您可以在购买密钥之前设置和测试扩展。OpenCart 4 中没有此预览功能：商店无法看到后台登录状态，因此没有有效密钥时，该方式对所有人隐藏。打开一次 Edit 页面后，后台 Dashboard 上会出现提醒。点击 × 可将其隐藏 7 天。现有订单不受影响。
许可证到期后，扩展仍会继续工作，但更新和支持需要续费。当您打开后台的 Dashboard 或 Edit 页面时，状态会自动重新检查：输入密钥后的前 14 天每天一次，之后每周一次。无需 cron 任务。卸载扩展时始终会删除许可证密钥和许可证状态。
故障排除
GIG Logistics 没有出现在结账页面：请检查许可证是否有效，以及 Enable/Disable 是否已开启。检查 Geo zone，或 Ignore shipping zones 和 Countries、重量限制以及 Minimum subtotal。检查价格表（国家或 *）或 Fallback cost 是否为该国家提供了价格。请检查商品的 Requires Shipping 是否设为 Yes。
价格来自价格表，而不是 GIG Logistics：实时价格需要 API 用户名和密码、Sender phone、取件城市和州、带有城市或州的尼日利亚送货地址，以及对于默认货币不是 NGN 的商店，还需要 Currency conversion rate。请查看 Edit 页面顶部的警告。开启 Debug log，刷新结账页面，然后查看扩展页面上的 Log 字段以了解原因。失败的请求将在 10 分钟后重试。
日志中登录失败：GIG Logistics 拒绝了 API 用户名或密码。请检查它们，并检查 Test mode：测试凭据仅适用于测试 API。保存设置可立即重试。
GIG Logistics 不返回价格：GIG 按距离计算价格。请保持 Address lookup 开启，或输入 Pickup latitude 和 Pickup longitude。正式上线前，请与您的 GIG Logistics 账户确认价格。
取件城市和州的警告仍然存在：请在 State 中选择一个州，并填写 City / area。只有当 System > Settings > Store > Local 中的商店国家为尼日利亚时，才会使用商店地区。
GIG 价格之上又收取了税费：如果 GIG 价格已包含您想收取的全部费用，请将 Tax class 设为 No tax。
更改后的价格看起来过时了：在扩展页面点击 Save。这会清除缓存的价格、令牌和坐标。
页面显示 "Warning: You do not have permission to modify VibeFox GIG Logistics!"：您的管理员用户组可能只能查看设置。请在 System > Users > User Groups 中，授予该用户组对 extension/shipping/vfd_gig_logistics（OpenCart 3）或 extension/vfd_gig_logistics/shipping/vfd_gig_logistics（OpenCart 4）的修改权限。
面向开发人员：GIG Logistics API 地址和地址查找地址可以通过设置 vfd_gigl_api_base_url 和 vfd_gigl_geocode_url 进行替换（用于测试）；设置页面上没有这些字段。
卸载
进入 Extensions > Extensions，选择 Shipping 类型，然后点击 VibeFox GIG Logistics 旁边的 Uninstall（红色 − 按钮）。本扩展的许可证密钥和许可证状态始终会被删除。OpenCart 始终会重置 Enable/Disable、Sort order、Tax class 和 Geo zone。缓存的价格、令牌和地址坐标始终会被删除。如果开启了 Remove data on uninstall，其他设置和调试日志也会被删除。如果关闭，它们会被保留，并在您重新安装该扩展时再次使用。现有订单会保留其配送方式和费用。
在 OpenCart 4 中，如需同时删除扩展文件，请在卸载后进入 Extensions > Installer，在已安装扩展列表中点击 VibeFox GIG Logistics 旁边的 Uninstall（橙色 − 按钮），然后点击 Delete（红色垃圾桶按钮）删除已上传的安装包。
GIG Logistics 是其各自所有者的商标。本扩展与 GIG Logistics 没有关联，也未获得 GIG Logistics 的认可或背书。