VibeFox GIG Logistics for PrestaShop — 帮助
系统要求
PrestaShop：8.0 至 9.x。
PHP：8.0 或更高版本。在较旧的 PHP 版本上，模块会拒绝安装。
GIG Logistics API 凭据（仅用于实时运费）：实时运费使用 GIG Logistics 第三方 API。GIG Logistics 向企业客户提供 API 用户名（通常是电子邮件地址）和密码。请在 GIG Logistics 开发者页面（giglogistics.com/developer）申请。测试凭据仅适用于测试 API。如果您只使用运费表和备用运费，则无需 API 凭据。
店铺中的尼日利亚：实时运费仅针对尼日利亚的配送地址请求，因此尼日利亚这个国家必须存在并在 International > Locations > Countries 中处于启用状态。
VibeFox 许可证密钥：在 vibefox.net 购买。一个密钥只适用于一个域名。
安装
1. 进入后台，前往 Modules > Module Manager，点击 Upload a module。选择模块的 ZIP 文件。
2. 上传完成后，点击 Configure；或稍后在模块列表中找到 VibeFox GIG Logistics，然后点击 Configure。
3. 将您的 VibeFox 许可证密钥粘贴到配置页面顶部许可证区块中的 License key，然后点击 Activate（参见许可证密钥）。
4. 填写运费表和/或备用运费。若要使用实时运费，还需填写 API 用户名和密码、取件电话、城市和州；如果默认货币不是 NGN，还需填写货币换算汇率（参见配置）。点击 Save。
5. 如果 Nigerian states 字段显示 Add Nigerian states 按钮，请点击该按钮（参见配置）。
安装时，模块会创建 GIG Logistics 承运商，配送时效文字为 Courier delivery。该承运商会关联到尼日利亚区域（在默认店铺中为非洲）以及所有顾客群组。您可以在 Shipping > Carriers 中更改区域、顾客群组、配送时效、徽标和尺寸限制。请勿在那里设置运费：运费始终来自本模块。
配置
所有设置都在模块页面中：Modules > Module Manager > VibeFox GIG Logistics > Configure。每个部分都有自己的 Save 按钮，点击后会保存整个页面。每次保存还会清除缓存的 GIG Logistics 运费、API 令牌和地址坐标。
在各部分上方，当实时运费无法使用时，页面会显示警告：只填写了 API 用户名或密码中的一项，缺少 Sender phone 或取件城市和州，或默认货币不是 NGN 且未设置 Currency conversion rate。如果未找到 GIG Logistics 承运商，或者店铺的重量单位（International > Localization > Local units）不是模块可识别的单位（此时商品重量会按 kg 读取），页面也会显示警告。保存时，如果输入了错误的数值（负数金额、为 0 的 Currency conversion rate、超出 -90 至 90 范围的纬度、超出 -180 至 180 范围的经度），或 Min weight (kg) 大于 Max weight (kg)，或 Method title 为空或无效，或税务规则未知，则会报错，并且不会保存任何内容。
General
此页面上的设置适用于承运商的所有区域。
Enable/Disable：启用或停用承运商。这与 Shipping > Carriers 中的承运商状态是同一个开关。
Method title：在购物车和结账页面中显示的承运商名称。默认：GIG Logistics。必填。
Tax：承运商的税务规则，或 No tax。税务规则会在运费上叠加您的运费税。如果 GIG 运费已包含您希望收取的全部费用，请选择 No tax。
GIG Logistics API (live prices)（可选）
配置 API 凭据后，系统会针对每个尼日利亚地址向 GIG Logistics 请求运费。如果没有凭据，或 API 未返回运费，则使用运费表和备用运费。
API username：您的 GIG Logistics 第三方 API 用户名，通常是您的电子邮件地址。
API password：您的 GIG Logistics 第三方 API 密码。它仅用于登录 API，且绝不会写入日志。保存后，该字段保持为空，并显示 Saved — leave empty to keep it. 只有在需要更改时才输入新值。若要删除密码，请清空 API username 并保存。
Test mode：使用 GIG Logistics 测试（dev）API。测试凭据仅适用于测试 API。若要获取真实运费，请将其关闭。默认：关闭。
Currency conversion rate：GIG Logistics 以 NGN 返回运费。如果您店铺的默认货币不是 NGN，请输入 1 NGN 相当于多少您的默认货币（1 NGN = ? 您的货币，例如 0.0006）。汇率必须大于 0。未设置时，不使用 GIG 实时运费。如果默认货币为 NGN，该字段会说明这一点，且无需填写。小数点和逗号都可作为小数分隔符。
Pickup (sender) address
GIG Logistics 在尼日利亚取件的地址。如果您的店铺位于尼日利亚，留空的街道、城市和州字段将使用 Shop Parameters > Contact > Stores 中的店铺地址。
Sender name：发送给 GIG Logistics 的发件人姓名。留空时使用店铺名称。
Sender phone：您的电话号码，例如 08030000000。实时运费需要 GIG Logistics 提供此信息。
Street address：取件的街道地址。
City / area：取件城市或区域，例如 Victoria Island。实时运费必填。
State：取件地址所在的尼日利亚州，从 37 个州中选择。默认选项 Shop state (Shop parameters > Contact > Stores) 使用店铺地址的州。实时运费必填。
Pickup latitude：取件点的可选地图纬度，例如 6.4281。GIG Logistics 按距离计算运费。留空时，将根据地址查找坐标。
Pickup longitude：取件点的可选地图经度，例如 3.4219。
Address lookup：使用 OpenStreetMap（Nominatim）查找地址的地图坐标。GIG Logistics 根据取件和配送坐标计算运费。顾客的街道、城市和州会发送至 nominatim.openstreetmap.org，结果缓存 30 天。关闭后，仅发送地址文本，GIG Logistics 可能无法返回运费。默认：开启。
Nigerian states：配送地址的州会发送给 GIG Logistics 和地址查找服务。PrestaShop 默认没有尼日利亚的州；没有州信息时，仅使用街道和城市。Add Nigerian states 按钮会添加 37 个州（代码如 LA、FC 等），为尼日利亚开启 Contains states，并在尼日利亚地址表单中添加州字段。已存在的州（按代码或名称判断）不会重复添加。一切就绪后，该字段会显示尼日利亚地址有多少个州。在您点击按钮之前，不会更改任何内容。
Price table and fallback
用于其他国家、未配置实时运费时，或 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，因此请为您添加的每一行填写基础运费。如果同一国家出现两次，则保留后一行。保存后，更正的数值会列在警告中。没有对应行的国家（当不存在 * 行时）不会获得表格运费。
Fallback cost：在 GIG Logistics 和运费表都无法给出运费时使用。留空时，在这种情况下会隐藏承运商。
Table / fallback price is：Per order 表示只收取一次运费。Per item (multiplied by the number of items) 表示将运费乘以购物车中的商品数量。GIG 实时运费始终针对整个订单。
Conditions
Free shipping from：购物车小计（需要配送的商品，扣除折扣后，不含税）达到此金额即免运费。留空表示从不免运费。
Minimum subtotal：仅当购物车小计达到此金额时才显示承运商。留空表示始终显示。
Min weight (kg)：购物车的最低重量（kg）。商品重量会从店铺的重量单位换算。0 表示无限制。
Max weight (kg)：购物车的最高重量（kg）。默认：30。0 表示无限制。
Availability without shipping zones
Ignore shipping zones：即使承运商的区域未包含下列国家，也为这些国家提供该承运商。开启后，承运商会关联到所有启用的区域，之后创建的区域也会自动关联。关闭后，承运商会恢复其之前的区域。
Countries：此模式下的目的地国家。留空表示您发货的所有国家。仅在使用 Ignore shipping zones 时生效。
Advanced
Debug log：将运费计算写入模块文件夹中的 logs/vfd_gigl_debug.log.php。该文件无法通过网页打开。即使关闭日志，API 错误也始终会被记录。不会写入密码、令牌或顾客地址。
Log：显示调试日志的大小和最新条目。点击 Clear log 可清空日志。
Remove data on uninstall：开启后，卸载模块时会删除模块设置、承运商、缓存和日志。关闭后，所有内容都会保留，以便重新安装。订单始终保留。
结账时的工作方式
在配送步骤中，PrestaShop 会向模块请求 GIG Logistics 运费。只有需要配送的商品才计入：虚拟商品不增加重量，也不计入小计。模块首先检查条件：配送国家（结合 Ignore shipping zones）、购物车重量和最低小计。如果小计达到 Free shipping from，运费为 0，并且不会向 GIG Logistics 发送任何请求。
然后，运费取自第一个能提供运费的来源。首先是实时 GIG Logistics 运费，前提是已输入 API 凭据、地址位于尼日利亚、地址包含城市或州、已设置取件电话、城市和州，并且对于默认货币不是 NGN 的店铺，已设置换算汇率。模块会登录 GIG Logistics API，并发送取件和配送地址及坐标，以及购物车商品的名称、数量、重量和价值。没有重量的商品按 1 kg 发送。运费按自行车配送请求。其次是 Country prices 运费表。第三是 Fallback cost。如果都无法得出运费，则对该购物车隐藏此承运商。运费以您的默认货币计算，然后以顾客的购物车货币显示。
每个 GIG 响应缓存 1 小时，因此同一购物车不会触发新的请求。失败的请求或失败的登录缓存 10 分钟，这样结账页面就不会在每次刷新时等待 GIG Logistics。登录令牌保留 30 分钟，GIG 拒绝时会自动续期。API 超时为 10 秒，地址查找超时为 5 秒。
如果 GIG Logistics 返回错误或零运费，顾客不会看到任何错误。系统会使用运费表或备用运费，并将错误写入调试日志。
如果您在 Shipping > Carriers 中编辑已产生订单的承运商，PrestaShop 会将其保存为新的承运商版本。模块会自动跟随新版本。
本模块只计算运费。它不会创建 GIG Logistics 运单、托运单或标签，不预约取件，不跟踪包裹，也不允许顾客选择服务网点。订单照常通过您的 GIG Logistics 账户发货。实时运费仅针对尼日利亚地址请求。对于其他国家，请使用运费表。
许可证密钥
本模块需要 vibefox.net 提供的 VibeFox 许可证密钥。许可证区块 License — VibeFox GIG Logistics 是 Modules > Module Manager > VibeFox GIG Logistics > Configure 中位于设置上方的第一个区块。将密钥粘贴到 License key 中，然后点击 Activate。之后，该区块会以掩码形式显示密钥、状态（例如许可证有效期截止日期和您的域名），以及以下按钮：Check now（重新检查状态）、Change key（输入其他密钥）和 Remove key（从此店铺中移除密钥）。它们下方有一行 Product: presta-shipping-gig-logistics，以及一个链接 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 账户中释放该名额。
如果没有有效的密钥，结账时不会向顾客显示 GIG Logistics 承运商，也不会计算任何运费。PrestaShop 前台无法得知您已登录后台，因此承运商对您也会隐藏：您可以在购买密钥之前设置模块，但无法在结账时测试。Modules > Module Manager 的 Alerts 选项卡中会出现提醒。现有订单不受影响。
许可证到期后，模块仍会继续运行，但更新和支持需要续费。在您使用后台期间，系统会自动重新检查状态：输入密钥后的前 14 天每天一次，之后每周一次。无需设置 cron 任务。卸载或重置模块时，许可证密钥和许可证状态总会被删除。
故障排除
结账时没有显示 GIG Logistics：请检查许可证是否有效，以及 Enable/Disable 是否开启。在 Shipping > Carriers 中，检查承运商是否覆盖顾客所在国家的区域和顾客群组；或开启 Ignore shipping zones 并检查 Countries。检查重量限制和 Minimum subtotal。检查运费表（该国家或 *）或 Fallback cost 是否能为该国家提供运费。也可以在商品页面中将商品限制为特定承运商。
运费来自运费表，而不是 GIG Logistics：实时运费需要 API 用户名和密码、Sender phone、取件城市和州、带城市或州的尼日利亚配送地址；对于默认货币不是 NGN 的店铺，还需要 Currency conversion rate。请查看配置页面顶部的警告。开启 Debug log，重新加载结账页面，然后查看模块页面上的 Log 字段，了解具体原因。失败的请求会在 10 分钟后重试。
日志中出现 Login failed：GIG Logistics 拒绝了 API 用户名或密码。请检查它们，并检查 Test mode：测试凭据仅适用于测试 API。保存设置可立即重试。
GIG Logistics 未返回运费：GIG 按距离计算运费。请保持 Address lookup 开启，或输入 Pickup latitude 和 Pickup longitude。点击 Add Nigerian states，以便同时发送配送州。正式上线前，请先在您的 GIG Logistics 账户中确认运费。
取件城市和州的警告仍然存在：在 State 中选择一个州，并填写 City / area。只有当店铺所在国家为尼日利亚时才会使用店铺地址；而店铺的州只有在添加尼日利亚各州并于 Shop Parameters > Contact > Stores 中选定后才会被识别。
税费叠加在 GIG 运费之上：如果 GIG 运费已包含您希望收取的全部费用，请将 Tax 设置为 No tax。
修改后运费看起来过时：在模块页面上点击 Save。这会清除缓存的运费、令牌和坐标。
页面提示未找到 GIG Logistics 承运商：该承运商已在 Shipping > Carriers 中被删除。请在 Modules > Module Manager 中重置模块，以重新创建它。
卸载
前往 Modules > Module Manager，打开 VibeFox GIG Logistics 旁边的菜单，然后选择 Uninstall。许可证密钥和许可证状态始终会被删除。缓存的运费、令牌和地址坐标始终会被删除。如果 Remove data on uninstall 已开启，承运商会被删除（订单保留其历史记录），设置和日志也会被删除。如果已关闭，承运商仅会被停用，所有设置都会保留。重新安装模块后，已保存的承运商将恢复其之前的状态。无论哪种情况，通过 Add Nigerian states 添加的尼日利亚各州都会保留在您的店铺中。
GIG Logistics 是其各自所有者的商标。本模块与 GIG Logistics 无关联，也未获得 GIG Logistics 的认可。