VibeFox GIG Logistics for WooCommerce — 帮助
系统要求
WordPress：5.8 或更高版本。
WooCommerce：5.0 或更高版本，已安装并启用。未安装时插件无法激活。
PHP：8.0 或更高版本。
GIG Logistics API 凭据（仅用于实时运费）：实时运费使用 GIG Logistics 第三方 API。GIG Logistics 会向企业客户提供 API 用户名（通常为电子邮件地址）和密码。请在 GIG Logistics 开发者页面（giglogistics.com/developer）申请。测试凭据仅适用于测试 API。如果您只使用运费表和备用运费，则无需 API 凭据。
VibeFox 许可证密钥：在 vibefox.net 购买。一个密钥只能用于一个域名。
安装
1. 在 WordPress 中进入 Plugins > Add New > Upload Plugin，选择插件 ZIP 文件，然后点击 Install Now。您也可以通过 FTP 将 vfd_gig_logistics 文件夹上传到 /wp-content/plugins/。
2. 点击 Activate。
3. 打开设置：WooCommerce > Settings > Shipping > VibeFox GIG Logistics，或在插件页面中点击插件名称下方的 Settings。
4. 在页面顶部的许可证区块中输入您的 VibeFox 许可证密钥，然后点击 Activate。
5. 填写运费表和/或备用运费。若要使用实时运费，还需填写 API 用户名和密码、取件电话、城市和州；若您的店铺货币不是 NGN，还需填写货币换算汇率（参见配置）。
6. 在 WooCommerce > Settings > Shipping > Shipping zones 中，将 VibeFox GIG Logistics 添加到尼日利亚的配送区域，或开启 Ignore shipping zones 并选择国家。
配置
所有设置都位于同一页面：WooCommerce > Settings > Shipping > VibeFox GIG Logistics。这些设置适用于所有配送区域。将该方式添加到某个区域时，区域窗口中只有一个字段：
Title (zone)：顾客在该区域看到的名称。留空则使用全局的 Method title。
页面顶部会在无法使用实时运费时显示警告：仅填写了 API 用户名或密码之一、缺少 Sender phone 或取件城市和州，或店铺货币不是 NGN 且未设置 Currency conversion rate。每次保存设置时，缓存的运费和 API 令牌都会被清除。
General
Enable/Disable：一次性在所有区域中启用或禁用该方式。默认：开启。
Method title：显示在购物车和结账页面的配送方式名称。默认：GIG Logistics。区域标题会覆盖它。
Tax status：Taxable 会在运费上加上您店铺的配送税，None 则不加。如果 GIG 运费已包含您想收取的全部费用，请选择 None。
GIG Logistics API（实时运费）（可选）
填写 API 凭据后，每个尼日利亚地址的运费都会向 GIG Logistics 请求。没有凭据，或 API 未返回运费时，则使用运费表和备用运费。
API username：您的 GIG Logistics 第三方 API 用户名，通常为您的电子邮件地址。
API password：您的 GIG Logistics 第三方 API 密码。仅用于登录 API，且绝不会写入日志。
Test mode：使用 GIG Logistics 测试（dev）API。测试凭据仅适用于测试 API。如需真实运费，请关闭。默认：关闭。
Currency conversion rate：GIG Logistics 以 NGN 返回运费。如果您的店铺货币不是 NGN，请填写 1 NGN 相当于多少店铺货币（1 NGN = ? 您的货币，例如 0.0006）。未设置时，不使用 GIG 实时运费。如果店铺货币是 NGN，则无需填写此字段。小数点和逗号均可作为小数分隔符。
取件（发件人）地址
GIG Logistics 在尼日利亚取件的地点。如果您的店铺位于尼日利亚，留空的街道、城市和州字段将使用 WooCommerce > Settings > General 中的店铺地址。
Sender name：发送给 GIG Logistics 的发件人名称。留空则使用网站名称。
Sender phone：您的电话号码，例如 08030000000。实时运费需要 GIG Logistics 提供此信息。
Street address：取件街道地址。
City / area：取件城市或区域，例如 Victoria Island。实时运费必填。
State：取件地址所在的尼日利亚州。默认使用店铺所在州。实时运费必填。
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，因此请为每个添加的行填写基础运费。没有对应行的国家（当没有 * 行时）不获得运费表运费。
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 表示不限。
Excluded shipping classes：如果购物车包含这些 WooCommerce 配送类别的商品，则隐藏该方式。
无配送区域时的可用性
Ignore shipping zones：即使未添加到任何区域，也为下方指定的国家提供该方式。关闭时，该方式只会出现在已添加它的配送区域中。
Countries：该模式下的目的地国家。留空则为您配送的所有国家。仅在开启 Ignore shipping zones 时使用。
高级
Debug log：将运费计算记录到 WooCommerce > Status > Logs，来源为 vfd-gig-logistics。即使日志关闭，API 错误也始终会被记录。不会写入密码、令牌或顾客地址。
Remove data on uninstall：开启后，删除插件时会移除其设置、区域方式和缓存。停用插件不会删除任何内容。
结账时的工作方式
顾客输入配送地址时，WooCommerce 会向插件请求运费。插件首先检查条件：配送国家、购物车重量、最低小计和排除的配送类别。如果小计达到 Free shipping from，该方式将以 0 运费显示，但仅当该国家有运费时才会显示：Country prices 中的一行、Fallback cost，或实时 GIG Logistics 运费。只有当运费表和备用运费都无法提供运费时，才会查询 GIG Logistics。
然后，运费取自第一个能够提供运费的来源。首先是实时 GIG Logistics 运费，前提是已填写 API 凭据、地址位于尼日利亚、顾客已填写城市或州、已设置取件电话、城市和州，并且非 NGN 店铺已设置换算汇率。插件会登录 GIG Logistics API，并发送取件和配送地址及坐标，以及购物车商品的名称、数量、重量和价值。没有重量的商品按 1 kg 发送。运费按 bike 配送方式请求。其次是 Country prices 运费表。第三是 Fallback cost。如果都无法提供运费，则在该购物车中隐藏该方式。
每个 GIG 响应缓存 1 小时，因此同一购物车不会触发新的请求。失败的请求或登录会缓存 10 分钟，使结账页面在每次刷新时都无需等待 GIG Logistics。登录令牌保存 30 分钟，GIG 拒绝时会自动续期。API 超时时间为 10 秒，地址查找超时时间为 5 秒。
如果 GIG Logistics 返回错误或零运费，顾客不会看到任何错误。系统会使用运费表或备用运费，并将错误写入日志。
该方式适用于经典结账以及购物车和结账区块。它兼容 WooCommerce 高性能订单存储（HPOS）。
本插件仅计算运费。它不会创建 GIG Logistics 运单、托运单或标签，不预约取件，不跟踪包裹，也不允许顾客选择服务网点。订单仍照常通过您的 GIG Logistics 账户发运。实时运费仅针对尼日利亚地址请求。其他国家请使用运费表。
许可证密钥
本插件需要一个来自 vibefox.net 的 VibeFox 许可证密钥。许可证区块位于 WooCommerce > Settings > Shipping > VibeFox GIG Logistics 页面顶部。将密钥粘贴到 License key 中，然后点击 Activate。该区块会显示状态，例如许可证有效期截止日期和您的域名。使用 Check now 重新检查状态，使用 Change key 输入其他密钥，使用 Remove key 将密钥从本站点移除。链接 Manage licenses and domains in your account 会打开您的 vibefox.net 账户。
一个密钥只能用于一个域名。从站点移除密钥并不会释放其域名名额。请在您的 vibefox.net 账户中释放名额。
没有有效密钥时，GIG Logistics 不会在结账时显示给顾客。已登录的店铺管理员仍可看到它，并标注 (unlicensed — visible to admins only)，以便您在购买密钥之前设置和测试插件。插件页面和 WooCommerce 页面会显示提醒。现有订单不受影响。
许可证过期后，插件仍可继续工作，但更新和支持需要续费。状态会在后台自动重新检查。
故障排除
GIG Logistics 未出现在结账页面：请检查许可证是否有效、Enable/Disable 是否开启，以及该方式是否已添加到顾客所在国家的区域中（或 Ignore shipping zones 已开启且该国家被允许）。检查重量限制、Minimum subtotal 和 Excluded shipping classes。检查运费表（该国家或 *）或 Fallback cost 是否能为该国家提供运费。
运费来自运费表，而非 GIG Logistics：实时运费需要 API 用户名和密码、Sender phone、取件城市和州、城市或州填写完整的尼日利亚配送地址，以及非 NGN 店铺的 Currency conversion rate。请查看设置页面顶部的警告。开启 Debug log，刷新结账页面，然后打开 WooCommerce > Status > Logs，来源 vfd-gig-logistics，查看原因。失败的请求将在 10 分钟后重试。
日志中出现 Login failed：GIG Logistics 拒绝了 API 用户名或密码。请检查它们，并检查 Test mode：测试凭据仅适用于测试 API。保存设置可立即重试。
GIG Logistics 未返回运费：GIG 按距离计算运费。请保持 Address lookup 开启，或填写 Pickup latitude 和 Pickup longitude。正式上线前，请与您的 GIG Logistics 账户核对运费。
运费之上又加收了税：如果 GIG 运费已包含您想收取的全部费用，请将 Tax status 设为 None。
修改后运费看起来过时：保存设置页面。这将清除缓存的运费和令牌。
自定义地理编码器：开发者可以使用 vfd_gigl_pre_geocode 过滤器提供自己的地址查找功能。
许可证区块显示错误：请按照区块中的提示操作。例如，如果该密钥已在另一个域名上使用，请在 vibefox.net 账户中释放一个名额，然后点击 Check now。如果站点地址已更改，请点击 Check now，为新域名激活密钥。如果无法连接许可证服务器，插件将沿用最后已知的状态继续工作。
卸载
停用插件会保留所有数据。如需移除，请先停用，然后在 Plugins 页面中删除。本插件的许可证密钥和许可证状态始终会被移除。设置、区域方式、缓存的运费、令牌和地址查找，仅在 Remove data on uninstall 开启时才会被移除，否则将保留，以便日后重新安装时使用。现有订单会保留其配送行。
GIG Logistics 是其各自所有者的商标。本插件与 GIG Logistics 无关联，也未获得其认可或背书。