VibeFox FedEx for OpenCart — 帮助
要求
OpenCart：3.0.x（已在 3.0.5.0 上测试）或 4.0.2 及更高版本（已在 4.1.0.3 上测试）。
PHP：8.0 或更高版本，并启用 cURL 扩展。
FedEx 账户和 API 密钥（仅用于实时运费）：在 FedEx 开发者门户（developer.fedex.com）中创建一个启用了 Rate API 的项目，绑定您的 FedEx 发货账户，并复制 API Key 和 Secret Key。您还需要 9 位数字的 FedEx 账户号码。测试密钥只能在开启 Sandbox 时使用，正式密钥只能在关闭时使用。该扩展使用基于 OAuth 2.0 的 FedEx REST API；不需要电表号码（meter number）或 Web 服务密码。如果您只使用固定价格，则无需 FedEx 密钥。
VibeFox 许可证密钥：在 vibefox.net 购买。一个密钥只能用于一个域名。
安装
下载的是一个 zip 文件，内含两个 OpenCart 版本的安装包。请先将其解压到您的电脑上。其中包含 README.txt、OpenCart 3 安装包 vfd_fedex-oc3-(version).ocmod.zip 和 OpenCart 4 安装包 vfd_fedex.ocmod.zip。只安装与您的 OpenCart 版本对应的安装包。两个版本使用相同的许可证密钥。
OpenCart 3
1. 在后台进入 Extensions > Installer，点击 Upload，然后选择文件 vfd_fedex-oc3-(version).ocmod.zip。该扩展不添加 OCMOD 修改，因此无需刷新 Extensions > Modifications。您也可以不使用安装器，而是把此安装包中 upload 文件夹的内容复制到商店的根目录。
2. 进入 Extensions > Extensions，选择扩展类型 Shipping。找到 VibeFox FedEx，点击 Install（绿色的 + 按钮）。
3. 点击 Edit（铅笔按钮）打开设置页面。
4. 在 Edit 页面顶部的许可证区块中，将您的 VibeFox 许可证密钥输入 License key，然后点击 Activate（见许可证密钥）。
5. 输入 API Key、Secret Key、9 位数字的 FedEx 账户号码，以及 Ship from 发货地址（邮编，以及美国和加拿大所需的 2 位州代码）。使用正式密钥时关闭 Sandbox。如需备用方案，可选择输入固定价格。开启 Enable/Disable 并点击 Save。
OpenCart 4
1. 在后台进入 Extensions > Installer，点击 Upload，然后选择文件 vfd_fedex.ocmod.zip。请勿重命名该文件：OpenCart 4 从文件名获取扩展代码，重命名后的安装包将无法工作。
2. 该安装包会出现在同一页面的已安装扩展列表中。点击其旁边的 Install（绿色的 + 按钮）。
3. 进入 Extensions > Extensions，选择扩展类型 Shipping。找到 VibeFox FedEx，点击 Install（绿色的 + 按钮），然后点击 Edit（铅笔按钮）。
4. 按照 OpenCart 3 步骤 4 和 5 的方式输入许可证密钥和设置。两个版本的设置页面及其字段相同。
安装后，该方式保持关闭，直到您开启 Enable/Disable 并保存。如果您卸载后重新安装该扩展，将再次使用您保留的 FedEx 设置。
配置
所有设置都在扩展页面上：Extensions > Extensions > Shipping > VibeFox FedEx > Edit。各分区列在左侧。页面底部的一个 Save 按钮可在不刷新页面的情况下保存整个页面。每次保存还会清除缓存的 FedEx 令牌和运费。只有拥有该扩展修改权限的管理员用户才能保存设置。
页面顶部，扩展会显示以下警告：三个 API 凭据只填了部分；没有 API 密钥也没有固定价格（此时该方式永远不会显示）；没有发货邮编；美国或加拿大没有发货州；店铺货币没有用于 FedEx 账户货币运费的汇率；没有 kg 重量单位时，使用了扩展无法识别的重量单位（请在 System > Localisation > Weight Classes 中添加一个）；或者设置了包裹尺寸但长度单位无法识别。数字字段接受小数点或逗号。保存时，无效的数字或包裹尺寸、汇率为 0、非 3 位字母代码的账户货币、无效的名称或排序会被提示且不会保存；该字段保留之前的值，其他字段仍会保存（The other settings were saved.）。最低重量大于最高重量也会被提示，两个重量都保留之前的值。
常规
这些设置适用于所有地理区域。FedEx 在结账时作为一个配送选项提供：最便宜的 FedEx 服务，或者当 FedEx 未返回运费时使用的固定价格。
Enable/Disable：开启或关闭结账时的 FedEx 配送。默认：关闭。
Name：结账时显示给顾客的配送方式名称，最多 64 个字符，不得包含 < > ; = # { }。默认：FedEx。必填。
Tax class：配送费用的税类，或 No tax（默认）。选择税类后，OpenCart 会在配送费用上加税，因此会使用不含税的 FedEx 费用。选择 No tax 时，直接使用 FedEx 的净费用。
Sort order：FedEx 在结账时配送方式中的位置。一个整数。
FedEx API（实时运费）
该分区链接到 FedEx 开发者门户。没有密钥时使用固定价格。
Sandbox：使用 FedEx 沙盒环境（apis-sandbox.fedex.com）和测试密钥。关闭后使用正式环境（apis.fedex.com）和正式密钥以获取真实运费。默认：开启。
API Key：您的 FedEx 开发者门户项目的 API Key（client_id）。清空它也会删除已保存的 Secret Key。
Secret Key：同一项目的 Secret Key（client_secret）。保存后该字段保持为空，并显示 Saved — leave empty to keep it. Clearing the API Key removes it too. 只有需要更改时才输入新值。
FedEx account number：与项目绑定的 9 位数字 FedEx 发货账户。账户（协商）运费即按此账户报价。
Rates：Account rates (your negotiated FedEx prices)（默认）或 List rates (FedEx published prices)。
Residential delivery：将顾客地址按住宅地址报价（FedEx Home Delivery，住宅附加费）。如果您主要寄送给企业，请关闭。默认：开启。
Box size (L x W x H)：可选的包裹尺寸，单位为字段名中所示的商店长度单位，例如 30x20x15。FedEx 随后会应用体积重量。留空则仅按重量报价。
FedEx account currency：您的 FedEx 账户货币，例如美国账户为 USD，加拿大为 CAD。默认：USD。FedEx 始终也会被要求以商店默认货币报价。
Exchange rate：仅当 FedEx 只返回账户货币的运费，且您的商店默认货币不同时才需要：账户货币 1 个单位折合为您的默认货币的价格，例如 0.92。未设置时，此类运费不会被使用，而且其他货币的金额绝不会显示为您的货币。
Cache：按钮 Clear cached FedEx token and rates 可立即清空缓存。FedEx 令牌缓存至过期，运费缓存 1 小时，失败的请求缓存 5 至 10 分钟。
Ship from
FedEx 取件或您寄送包裹的地址。用于实时运费。
Country：您发货的国家。默认：United States。
State / province code：2 位州或省代码，美国和加拿大必填，例如 TN、CA 或 ON。
City：发货城市。
ZIP / postal code：发货邮编。FedEx 报价需要它。OpenCart 没有商店邮编，因此请在此处输入。
固定价格
在未输入 API 密钥时使用，并在 FedEx 未返回运费时作为备用（API 不可用、密钥错误、没有服务）。在这种情况下，如果要隐藏该方式，请将两个字段都留空。
Country prices：目的地国家和价格列表，价格以商店默认货币计，不含税。点击 Add row 添加一行，点击 × 按钮删除。选择 * Any other country 可设置适用于所有没有单独行的国家的价格。没有有效国家或价格的行会被忽略，并在保存时提示。
Fallback cost：没有任何国家价格匹配时的固定价格。留空则隐藏该方式。
Fixed price is：Per order（默认）只收一次费用。Per item (price x number of items) 则按购物车商品数量相乘。这仅适用于固定价格。FedEx 实时运费始终按整个购物车的重量报价。
条件
Free shipping from：需要配送的商品小计（优惠券折扣后，税前）达到此金额时，该方式免运费。此时不会向 FedEx 发出请求。留空则从不提供免运费。
Minimum subtotal：只有当小计至少达到此金额时才显示该方式。留空则始终显示。
Min weight (kg)：该方式显示所需的最低购物车重量。0 表示不限（默认）。
Max weight (kg)：最高购物车重量。超过时该方式会被隐藏。0 表示不限（默认）。
Default product weight (kg)：用于没有重量的商品的重量，用于 FedEx 运费计算以及上述重量限制。默认：0.5；空字段同样视为 0.5 kg。商品重量根据每个商品的重量单位转换。
Geo zone：仅对该地理区域内的地址提供 FedEx。All zones（默认）表示不限制。地理区域在 System > Localisation > Geo Zones 中管理。开启 Ignore shipping zones 时不使用。
无配送区域时的可用性
Ignore shipping zones：不检查地理区域；为下面的国家提供该方式。默认：关闭。
Countries：该模式下的目的地国家。留空表示所有国家。仅在开启 Ignore shipping zones 时使用。
高级
Debug log：将 API 请求和运费计算写入 storage/logs/vfd_fdx_debug.log.php（OpenCart 4 中为 system/storage/logs/vfd_fdx_debug.log.php）。该文件无法通过网页读取。即使日志关闭，API 错误也始终会记录。密钥、令牌、账户号码和顾客地址绝不会被记录。文件达到 5 MB 时，会移至 vfd_fdx_debug.old.log.php，并开始新的日志。
Log：显示日志的大小和最新条目。点击 Clear log 可清空。
Remove data on uninstall：开启后，卸载扩展会删除 FedEx 设置、缓存的令牌和运费以及日志。关闭时（默认），所有内容都会保留，以便重新安装。已下订单的 FedEx 运费始终保留。
导入 / 导出
Export：点击 Download JSON 可将设置保存为 JSON 文件。Secret Key 不会被导出。
Import：粘贴之前导出的 JSON，然后点击 Import 恢复设置，例如在另一家商店中。这些值会像正常保存一样进行检查。已保存的 Secret Key 会保留。
结账时的工作方式
OpenCart 显示配送方式时，会向扩展请求 FedEx 的价格。如果设置了 Geo zone（且 Ignore shipping zones 关闭），而地址不在该区域内，则不提供 FedEx。只有 Requires Shipping 设为 Yes 的商品才计入：其他商品不增加重量，也不计入小计。小计是这些商品在优惠券折扣之后、税前的价格；礼品卡、积分和商店余额不计入。然后扩展检查允许的国家（启用 Ignore shipping zones 时）、购物车重量和最低小计。如果适用免运费，价格为 0，且不会向 FedEx 发出请求。
否则，如果已设置 API Key、Secret Key 和账户号码，扩展会获取 OAuth 令牌，并向 FedEx Rate API 发送发货地址、收货地址、购物车重量（以 kg 计；若重量单位为 lb 或 oz，则以 lb 计）、包裹尺寸（如已设置），以及您的默认货币作为首选货币。对于在 OpenCart 中启用了 Postcode Required 的国家，只有在顾客输入邮编后才会发出请求。对于国际运输，会发送购物车的报关价值。州代码仅发送给美国和加拿大。
FedEx 返回可用的服务。对于每项服务，扩展会取您选择的账户或列表运费，优先使用默认货币的运费，用您设置的汇率换算 FedEx 账户货币的运费，并舍弃无法换算的运费。使用最便宜的服务。价格按默认货币的小数位数取整，并以顾客的货币显示，同时加上所选 Tax class 的税。
令牌会缓存至过期，并在 FedEx 拒绝时自动重新请求。报价缓存 1 小时。失败的运费请求会记住 10 分钟，失败的令牌请求会记住 5 分钟，因此故障不会拖慢每次结账更新。API 超时时间为 15 秒。如果 FedEx 没有响应，顾客不会看到错误：使用固定价格，或隐藏该方式。原因会写入调试日志。
该扩展仅计算运费。它不会创建 FedEx 运单、打印面单、预约取件、追踪包裹或让顾客选择 FedEx 网点。它只显示一个选项（最便宜的服务），而不是多个，并且没有装箱功能：购物车按一个包裹报价。
在 OpenCart 4 中，顾客在结账页面的配送方式区块点击 Choose，然后在 Shipping method options 窗口中选择 FedEx。该方式的工作方式与 OpenCart 3 相同。
订单
下单使用 FedEx 时，顾客看到的运费会与订单一起保存。在 Sales > Orders 的订单页面中有一个 FedEx shipping 面板，显示运费的 FedEx service（针对实时运费）、Price source（FedEx live rate、Fixed price (no live rate) 或 Free shipping threshold），以及以您的默认货币显示的 Calculated price (excl. tax)。这些值在下单时被固定：之后对设置的更改不会改变它们。在 OpenCart 4 中，结账会保留一个订单，顾客每次重新确认时都会更新该订单：已保存的 FedEx 运费随之更新，顾客切换到其他配送方式时该运费会被删除。
许可证密钥
该扩展需要来自 vibefox.net 的 VibeFox 许可证密钥。许可证区块 License — VibeFox FedEx 是 Extensions > Extensions > Shipping > VibeFox FedEx > Edit 页面上位于设置上方的第一个区块。将密钥输入 License key 并点击 Activate。之后该区块会以掩码形式显示密钥、状态（例如许可证有效期截止日期和您的域名），以及用于重新检查状态的 Check now、输入其他密钥的 Change key，和从本店铺移除密钥的 Remove key 按钮。其下方是 Product: opencart-shipping-fedex 一行，以及打开您 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 账户中释放该名额。
没有有效的许可证密钥时，结账时不会向顾客显示 FedEx 配送方式，也不会计算运费。以同一浏览器登录后台的管理员用户，仍会在店铺中看到该方式，并标有 (unlicensed — visible to admins only)，因此您可以在购买密钥之前完成设置和测试。OpenCart 4 中没有此预览功能：店铺无法识别后台登录，因此没有有效密钥时，该方式对所有人都会隐藏。您打开过一次 Edit 页面后，后台 Dashboard 上会出现提醒。点击 × 可将其关闭，并在 7 天内隐藏。现有订单不受影响。
许可证到期后，扩展会继续运行，但更新和支持需要续费。在您打开后台 Dashboard 或 Edit 页面时会自动再次检查状态：输入密钥后的前 14 天每天一次，之后每周一次。无需 cron 任务。卸载扩展时总会删除许可证密钥和许可证状态。
故障排除
结账时没有显示 FedEx：检查许可证是否有效，以及 Enable/Disable 是否已开启。检查 Geo zone，或者 Ignore shipping zones 和 Countries。检查扩展页面顶部的警告、重量限制和 Minimum subtotal。没有实时运费时，该方式需要一个国家价格、一个 * Any other country 行或一个 Fallback cost。检查商品的 Requires Shipping 是否设为 Yes。
实时运费没有显示：开启 Debug log，刷新结账页面，然后查看扩展页面上的 Log 字段。错误的密钥、错误的环境（关闭 Sandbox 时使用测试密钥，或开启时使用正式密钥）、缺少的收货邮编以及 FedEx 错误代码都会记录在那里。
我的商店不是 USD：系统会要求 FedEx 以您的默认货币报价。如果您的账户只返回其自身货币，请设置 FedEx account currency 和 Exchange rate。没有汇率时，此类运费会被忽略，并使用固定价格，因此美元金额绝不会显示为欧元。
"Per item" 会乘以 FedEx 运费吗？不会。Per item 仅适用于固定价格。
修改后运费看起来过时：保存扩展页面会清空缓存。您也可以点击 Clear cached FedEx token and rates。
页面显示“Warning: You do not have permission to modify VibeFox FedEx!”：您的管理员用户组可能只能查看设置。请在 System > Users > User Groups 中为该组授予 extension/shipping/vfd_fedex（OpenCart 3）或 extension/vfd_fedex/shipping/vfd_fedex（OpenCart 4）的修改权限。
开发者说明：其他扩展可以通过 OpenCart 事件 vfd_fedex/api_base_url、vfd_fedex/allowed_services 和 vfd_fedex/rate_request（注册为 catalog/vfd_fedex/...）更改 API 地址、允许的 FedEx 服务和运费请求；设置 vfd_fdx_api_url 可替换测试用的 API 地址，它在设置页面上没有对应字段。
卸载
进入 Extensions > Extensions，选择类型 Shipping，然后点击 VibeFox FedEx 旁边的 Uninstall（红色 − 按钮）。OpenCart 总是会重置 Enable/Disable、Sort order、Tax class 和 Geo zone。缓存的令牌和运费总会被删除。如果 Remove data on uninstall 已开启，FedEx 设置和调试日志也会被删除。如果已关闭，其他设置会保留，并在您重新安装扩展时再次使用。无论哪种情况，订单中保存的 FedEx 运费都会保留，订单也会保留其配送方式和运费。
在 OpenCart 4 中，若要同时删除扩展文件，请在卸载后进入 Extensions > Installer，在已安装扩展列表中点击 VibeFox FedEx 旁边的 Uninstall（橙色 − 按钮），然后点击 Delete（红色垃圾桶按钮）删除已上传的安装包。
FedEx 是其所有者的商标。本扩展与 FedEx 没有关联，也未获得 FedEx 的认可或支持。