VibeFox FedEx for PrestaShop — 帮助
系统要求
PrestaShop：8.0 至 9.x。
PHP：8.0 或更高版本，并启用 cURL 扩展。缺少这些时模块无法安装。
FedEx 账户和 API 密钥（仅用于实时运费）：在 FedEx Developer Portal（developer.fedex.com）中创建一个开通了 Rate API 的项目，关联您的 FedEx 配送账户，并复制 API Key 和 Secret Key。您还需要 9 位数的 FedEx 账号。测试密钥只能在开启 Sandbox 时使用，正式密钥只能在关闭时使用。模块使用带 OAuth 2.0 的 FedEx REST API，不需要 meter number 或 Web Services 密码。如果您只使用固定价格，则不需要 FedEx 密钥。
VibeFox 许可证密钥：在 vibefox.net 购买。一个密钥只能用于一个域名。
安装
1. 在后台进入 Modules > Module Manager，点击 Upload a module。选择模块的 ZIP 文件。
2. 上传完成后，点击 Configure；或之后在模块列表中找到 VibeFox FedEx，然后点击 Configure。
3. 在 Configure 页面顶部的许可证区块中的 License key 字段输入您的 VibeFox 许可证密钥，然后点击 Activate（见许可证密钥）。
4. 输入 API Key、Secret Key、9 位 FedEx 账号以及 Ship from 地址（邮编；美国和加拿大还需要 2 位字母的州代码）。如果使用正式密钥，请关闭 Sandbox。如需要，可输入固定价格作为备用。点击 Save。
安装时，模块会创建 FedEx 承运商，配送时间文本为 FedEx delivery。该承运商会分配给所有区域和所有客户组。您可以在 Shipping > Carriers 中修改区域、客户组、配送时间、徽标和尺寸限制。请不要在那里设置价格：价格始终由模块提供。
配置
所有设置都位于模块页面：Modules > Module Manager > VibeFox FedEx > Configure。这些设置适用于承运商的所有区域。每个部分都有自己的 Save 按钮，它会保存整个页面。每次保存也会清除缓存的 FedEx 令牌和运费。
页面顶部，模块会显示以下警告：三项 API 凭据只填写了部分；没有 API 密钥且没有固定价格（此时承运商永远不会显示）；没有发货邮编；美国或加拿大缺少发货州代码；店铺货币与 FedEx 账户货币不同且没有汇率；店铺重量单位（或在设置包装箱尺寸时的尺寸单位）模块不支持；或承运商已被删除。数字字段接受小数点或逗号。无效的数字或包装箱尺寸、汇率为 0、不是 3 位字母代码的账户货币以及超过 64 个字符的名称不会被保存，并会给出提示；该字段保留原值，其他字段正常保存。最低重量大于最高重量时也会给出提示，两个重量都保留原值。
常规
Enable/Disable: 开启或关闭 FedEx 配送。这与 Shipping > Carriers 中的承运商状态是同一个开关。
Name: 顾客在结账时看到的配送方式名称（即承运商名称）。默认值：FedEx。必填。
Tax status: 承运商的税则，或 No tax。选择税则时（并且店铺已启用税费），PrestaShop 会在运费上加收税费，因此使用不含税的 FedEx 运费。选择 No tax 时，直接使用 FedEx 的净运费。
FedEx API（实时运费）
未填写密钥时，使用下方的固定价格。本部分包含 Clear cached FedEx token and rates 按钮。
Sandbox：使用带测试密钥的 FedEx 沙盒（apis-sandbox.fedex.com）。如需获取真实运费（apis.fedex.com），请使用正式密钥并关闭此选项。默认值：开启。
API Key：您的 FedEx Developer Portal 项目的 API Key（client_id）。
Secret Key：同一项目的 Secret Key（client_secret）。保存后该字段会保持为空，并显示 Saved — leave empty to keep it. 只有需要修改时才输入新值。清空 API Key 也会删除已保存的 Secret Key。
FedEx account number：与项目关联的 9 位 FedEx 配送账号。账户（协商）运费即按该账号报价。
Rates：Account rates (your negotiated FedEx prices)（默认）或 List rates (FedEx published prices)。
Residential delivery：将顾客地址按住宅地址报价（FedEx Home Delivery，住宅附加费）。如果您主要向企业发货，请关闭。默认值：开启。
Box size：可选的包装箱尺寸，使用您店铺的尺寸单位，例如 30x20x15。设置后 FedEx 会应用体积重量。留空则仅按重量报价。
FedEx account currency：您的 FedEx 账户货币，例如美国账户为 USD，加拿大为 CAD。默认值：USD。FedEx 始终也会被要求以店铺默认货币报价。
Exchange rate：仅当 FedEx 只返回账户货币的运费，并且店铺默认货币不同时才需要：1 个账户货币单位折合为您默认货币的价格，例如 0.92。未设置时，此类运费不会被使用。
发货地址
FedEx 取件或您寄件的地址。用于实时运费。
Country：您发货的国家。默认值：United States。
State / province code：2 位字母的州或省代码，美国和加拿大必填，例如 TN、CA 或 ON。
City：发货城市。
ZIP / postal code：发货邮编。FedEx 报价时需要。
固定价格
未输入 API 密钥时使用，并在 FedEx 未返回运费时作为备用（API 不可用、密钥错误、无可用服务）。如果在这种情况下希望隐藏承运商，请将两个字段都留空。
Country prices：一个表格，包含 2 位字母的目的地国家代码以及以店铺默认货币计、不含税的价格。点击 Add row 添加国家，点击垃圾桶图标删除。使用 * 作为其他所有国家的代码。没有有效国家代码（或 *）或价格的行会被忽略，并在保存时提示。
Fallback cost：没有任何国家价格匹配时使用的固定价格。留空则隐藏承运商。
Fixed price is：Per order 只收取一次价格。Per item (price x number of items) 则按购物车中的商品数量乘以该价格。此设置仅适用于固定价格。FedEx 实时运费始终按整个购物车的重量报价。
条件
Free shipping from：购物车小计（折扣后、税前）达到此金额时，该承运商免运费。留空则从不提供免运费。
Minimum subtotal：仅当购物车小计不低于此金额时才显示该承运商。留空则始终显示。
Min weight：承运商显示所需的最低购物车重量（kg）。0 表示无限制。
Max weight：购物车的最高重量（kg）。超过时承运商会被隐藏。0 表示无限制。
Default product weight：用于没有重量的商品的重量（kg），也用于 FedEx 运费计算和上述重量限制。默认值：0.5。商品重量会从店铺的重量单位（kg、g、lb 或 oz）换算，该单位在 International > Localization（Local units）中设置。
无配送区域时的可用性
Ignore shipping zones：即使下列国家的区域未分配给该承运商，也为这些国家提供该承运商。保存后，承运商会关联到所有区域，包括之后创建的区域。关闭此选项后，承运商将恢复其原有区域。
Countries：此模式下的目的地国家。留空则为店铺的所有国家。仅在开启 Ignore shipping zones 时使用。
高级
Debug log：将 API 请求和运费计算记录到模块文件夹中的 logs/vfd_fdx_debug.log.php。该文件无法通过网页打开。API 错误始终会被记录。密钥、令牌和顾客地址从不记录。
Log：显示日志的大小和最新条目。点击 Clear log 清空。
Remove data on uninstall：开启时，卸载模块会删除所有模块设置、承运商以及订单中保存的 FedEx 服务。关闭时，所有内容都会保留，以便重新安装。
结账时的工作方式
在配送步骤中，PrestaShop 会向模块请求 FedEx 价格。仅实体商品计入：虚拟商品不增加重量，也不计入小计。模块首先检查允许的国家（结合 Ignore shipping zones）、购物车重量和最低小计。如果适用免运费，则价格为 0，且不会向 FedEx 发送请求。
否则，模块会获取 OAuth 令牌，并向 FedEx Rate API 发送发货地址、收货地址、购物车重量（以 kg 计；对于使用 lb 或 oz 的店铺则以 lb 计）、已设置的包装箱尺寸，以及作为首选货币的店铺默认货币。对于需要邮编的国家，只有顾客输入邮编后才会发出请求。国际配送时会发送购物车的海关申报价值。仅在美国和加拿大时才发送州代码。
FedEx 返回可用的服务。对于每项服务，模块会取您所选的账户或列表运费，优先选择店铺默认货币的运费，按您设置的汇率将 FedEx 账户货币的运费换算，并丢弃无法换算的运费。价格以最便宜的服务为准，并以顾客购物车的货币显示。
令牌按环境和密钥进行缓存，并在 FedEx 拒绝时自动重新请求。报价缓存 1 小时。运费请求失败会记录 10 分钟，令牌请求失败会记录 5 分钟，这样故障不会拖慢每次结账更新。API 超时时间为 15 秒。如果 FedEx 没有响应，顾客看不到任何错误：会使用固定价格，或者隐藏承运商。原因会写入调试日志。
如果承运商在 Shipping > Carriers 中已有订单后被编辑，PrestaShop 会将其保存为新的承运商版本。模块会自动跟随新版本。
模块只计算运费。它不会创建 FedEx 运单、打印面单、预约取件、跟踪包裹，也不允许顾客选择 FedEx 网点。它只显示一个选项（最便宜的服务），而不是多个，并且不进行装箱：购物车会作为一个包裹进行报价。
订单
在后台的订单页面，使用 FedEx 承运商的订单会有一个 FedEx shipping 区块。它会显示运费的 FedEx service（适用于实时运费）、Price source（FedEx live rate、Fixed price (no live rate) 或 Free shipping threshold），以及以您默认货币显示的 Calculated price (excl. tax)。这些值在下单时固定：之后对设置的更改不会改变它们。
许可证密钥
模块需要使用从 vibefox.net 获取的 VibeFox 许可证密钥。License — VibeFox FedEx 许可证区块位于 Modules > Module Manager > VibeFox FedEx > Configure 页面中设置上方的第一个区块。在 License key 中输入密钥并点击 Activate。之后，该区块会以隐藏部分字符的方式显示密钥、状态（例如许可证有效期截止日期和您的域名），以及以下按钮：Check now（重新检查状态）、Change key（输入其他密钥）和 Remove key（将密钥从本店铺中移除）。其下方是 Product: presta-shipping-fedex 一行和 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 账户中释放该名额。
没有有效的密钥时，结账时不会向顾客显示 FedEx 承运商，也不会计算任何运费。PrestaShop 前台无法得知您已登录后台，因此该承运商对您也会被隐藏：您可以在购买密钥之前设置模块，但无法在结账时测试它。Modules > Module Manager 中的 Alerts 选项卡会显示提醒。现有订单不受影响。
许可证到期后，模块仍会继续运行，但更新和支持需要续费。您在后台工作时会自动再次检查状态：输入密钥后的前 14 天每天一次，之后每周一次。无需 cron 任务。卸载或重置模块时，总会删除许可证密钥和许可证状态。
故障排除
结账时没有显示 FedEx：请检查许可证是否有效，并确认 Enable/Disable 已开启。在 Shipping > Carriers 中，检查承运商是否覆盖顾客所在国家的区域和顾客所属的客户组（或开启 Ignore shipping zones 并检查 Countries）。查看模块页面顶部的警告、重量限制和 Minimum subtotal。没有实时运费时，承运商需要国家价格、* 行或 Fallback cost。此外，产品页面可能将商品限制为特定承运商。
实时运费没有显示：开启 Debug log，重新加载结账页面，然后查看模块页面上的 Log 字段。这里会记录错误的密钥、错误的环境（关闭 Sandbox 时使用测试密钥，或开启时使用正式密钥）、缺少的收货邮编以及 FedEx 错误代码。
我的店铺不使用 USD：系统会要求 FedEx 以您的默认货币报价。如果您的账户只返回其自身货币，请设置 FedEx account currency 和 Exchange rate。没有汇率时，此类运费会被忽略并使用固定价格，因此美元金额绝不会显示为欧元。
"Per item" 会乘以 FedEx 运费吗？不会。Per item 仅适用于固定价格。
修改后运费似乎过时：保存模块页面会清除缓存。您也可以点击 Clear cached FedEx token and rates。
页面提示未找到 FedEx 承运商：该承运商已在 Shipping > Carriers 中被删除。请在 Modules > Module Manager 中重置模块以重新创建。
只应提供部分服务：开发人员可以使用 actionVfdFdxAllowedServices 钩子限制服务。钩子 actionVfdFdxRateRequest 和 actionVfdFdxApiBaseUrl 用于修改运费请求和 API 地址。
卸载
进入 Modules > Module Manager，打开 VibeFox FedEx 旁边的菜单，然后选择 Uninstall。许可证密钥和许可证状态始终会被删除。缓存的令牌和运费始终会被删除。如果 Remove data on uninstall 已开启，承运商会被删除（订单保留历史记录），并且设置、日志以及订单中保存的 FedEx 服务都会被删除。如果已关闭，承运商仅会被停用，所有设置都会保留。重新安装模块（或使用 Reset）后，已保存的承运商会恢复卸载前的状态。
FedEx 是其各自所有者的商标。本模块与 FedEx 无关联，也未获得 FedEx 的认可。