VibeFox UPS for PrestaShop — 帮助
系统要求
PrestaShop：8.0 至 9.x。
PHP：8.0 或更高版本，并启用 cURL 扩展。PHP 版本较旧或未启用 cURL 时，模块无法安装。
UPS Developer Portal 应用（仅用于实时运费）：登录 UPS Developer Portal（developer.ups.com），创建包含「Rating」产品的应用，关联您的 UPS 账号，并复制 Client ID 和 Client Secret。模块使用 OAuth 2.0，无需 Access Key、用户名或密码。若要获取协议运费，还需要您 6 位的 UPS 账号号码。没有凭据时，仅使用固定价格。
VibeFox 许可证密钥：在 vibefox.net 购买。一个密钥只能用于一个域名。
安装
1. 在后台进入 Modules > Module Manager，点击 Upload a module。选择模块的 ZIP 文件。
2. 上传完成后，点击 Configure；或者稍后在模块列表中找到 VibeFox UPS，再点击 Configure。
3. 在 Configure 页面顶部的许可证区块中的 License key 字段输入您的 VibeFox 许可证密钥，然后点击 Activate（参见「许可证密钥」）。
4. 输入 Client ID 和 Client Secret、您的 UPS 账号号码（用于协议运费），以及 Ship from 地址：邮政编码；美国和加拿大还需填写 2 位字母的州/省代码。
5. 若您的 UPS 账号货币与商店默认货币不同，请输入 UPS account currency 和 Exchange rate。
6. 可选：输入固定价格作为备用，然后点击 Save。
安装时，模块会创建 UPS 承运商，配送时间文本为 UPS delivery。该承运商分配给所有配送区域和所有客户组。您可以在 Shipping > Carriers 中修改配送区域、客户组、配送时间、Logo 和尺寸限制。请不要在那里设置价格：价格始终由模块提供。
配置
所有设置都在模块页面中：Modules > Module Manager > VibeFox UPS > Configure。设置适用于承运商的每个配送区域。每个部分都有自己的 Save 按钮，点击后会保存整个页面。每次保存都会清除缓存的 UPS 令牌和运费。您也可以在 UPS API 部分点击 Clear cached UPS token and rates。
设置上方的警告会提示：Client ID 和 Client Secret 只填写了其中一项；没有凭据也没有固定价格（此时承运商永远不会显示）；缺少发货地邮政编码或州/省；选择了协议运费却没有账号号码；缺少汇率；或模块无法识别商店的重量或尺寸单位。无效的数字、错误的箱子尺寸，以及高于 Max weight 的 Min weight，会在保存时报错，并保留旧值。
常规
Enable UPS shipping：开启或关闭该承运商。这与 Shipping > Carriers 中的承运商状态是同一个开关。
Name：结账时显示给顾客的承运商名称。默认值：UPS。必填，最多 64 个字符。
Tax status：承运商的税务规则，或 None。UPS 运费按不含税报价。设置税务规则后，商店会在此基础上加收运费税。
UPS API（实时运费）
Test mode：使用 UPS 测试环境。测试运费不是真实价格。如需实时运费，请关闭。默认值：off。
Client ID：您在 UPS Developer Portal 中为应用获取的 Client ID。清空该字段也会删除已保存的 Client Secret。
Client Secret：同一应用的 Client Secret。保存后该字段保持为空，并显示 Saved — leave empty to keep it. 只有需要更改时才输入新值。
UPS account number：您的 6 位 UPS 托运人号码，例如 A1B2C3。协议（议定）运费必须填写，公开运价可选。
Rates：使用哪种 UPS 价格。
Measurement units：发送给 UPS 的单位。商店的重量和尺寸会被换算。
Residential delivery：将顾客地址按住宅地址计算，并加收 UPS 住宅附加费。如果您主要寄送给企业，请关闭。默认值：on。
Box size：可选的箱子尺寸，使用商店的尺寸单位，例如 30x20x15。UPS 会据此应用体积重量。留空则仅按重量报价。
UPS account currency：UPS 以发货账号所在国家的货币报价，例如美国为 USD、加拿大为 CAD、欧元区为 EUR。默认值：USD。
Exchange rate：仅当 UPS 账号货币与商店默认货币不同时需要填写。输入 1 单位账号货币等于多少商店默认货币，例如 0.92。未填写时，这类运费不会被使用，将采用固定价格。汇率不会自动更新。
发货地址（UPS 取件或您投递包裹的地址；用于实时运费）
Country：您的发货国家。默认是商店所在国家。
State / province code：2 位字母代码，美国和加拿大必填，例如 NY、CA 或 ON。
City：您的发货城市。
ZIP / postal code：您的发货邮政编码。UPS 需要它来计算运费。
固定价格（未输入 API 凭据时使用，并在 UPS 未返回运费时作为备用；若两项都留空，则在这种情况下隐藏该承运商）
Country prices：按目的国家设置的价格，以商店默认货币计，不含税。点击 Add country 添加一行，点击删除按钮可删除一行。国家 * 适用于其他所有国家。重量列（XS 为 1 kg 以下，S 为 1–2 kg，M 为 2–3 kg，L 为 3–5 kg，XL 为 5 kg 以上）会针对该重量覆盖 Price。空白单元格则使用 Price。0 表示免运费。保存时会删除没有任何价格的行，非数字的值会被拒绝并给出提示。
Fallback cost：当没有匹配的国家价格时使用的固定运费，以商店默认货币计。留空则在这种情况下隐藏该承运商。
Fixed price is：Per order 按整个购物车的重量收取一次价格。Per item (each item priced by its own weight x quantity) 按每件商品自身的重量（无重量则用默认重量）计价，再乘以数量。如果某个商品没有固定价格，则隐藏该承运商。UPS 实时运费始终按整个购物车的重量报价。
条件
Free shipping from：购物车小计（需要配送的商品，折扣后、税前）达到该金额即免运费。此时不会向 UPS 发送请求。留空则从不提供免运费。
Minimum subtotal：仅当购物车小计至少达到该金额时才显示此承运商。留空则始终显示。
Min weight：此承运商显示所需的最低购物车重量（kg）。0 表示无限制。
Max weight：购物车重量超过此值（kg）时隐藏该承运商。默认值：70，即 UPS 单件包裹的限制（70 kg / 150 lbs）。0 表示无限制，留空表示 70。Min weight 不能高于 Max weight。
Default product weight：用于没有重量的商品的重量（kg），用于 UPS 运费、重量列和重量限制。默认值：0.5。
无配送区域时的可用性
通常，承运商会在 Shipping > Carriers 中分配到的配送区域内提供。
Ignore shipping zones：无论匹配哪个配送区域，都为下方列出的国家提供该承运商。保存时，该承运商会添加到所有配送区域，也会添加到之后创建的配送区域。关闭此项后，这些配送区域会再次被删除。
Countries：该模式下的目的国家。留空则使用商店所有启用的国家。此字段仅在 Ignore shipping zones 开启时使用。
高级
Debug log：将 API 请求和运费计算记录到模块文件夹中的 logs/vfd_upsx_debug.log.php。该文件无法通过网页打开。即使此选项关闭，API 错误也始终会记录。凭据、令牌和顾客地址永远不会被记录。
Log：显示日志的大小和最新条目。点击 Clear log 可清空。
Remove data on uninstall：开启时，卸载模块会删除设置、承运商、缓存的令牌和运费、日志，以及随订单保存的 UPS 服务。订单本身会保留。关闭时，所有内容都会保留，以便重新安装。
结账时的工作方式
在配送步骤，PrestaShop 会向模块请求 UPS 价格。只有实物商品计入：虚拟商品不增加重量，也不计入小计。模块首先检查条件：Ignore shipping zones 的国家、购物车重量和最低小计。如果适用免运费，价格为 0，且不会向 UPS 发送请求。
模块从 UPS 获取 OAuth 令牌，并在过期前保留。被 UPS 拒绝的令牌会自动更新。随后，模块向 UPS Rating API 请求从您的发货地址到顾客地址的所有服务，购物车视为一个包裹。对于有邮政编码的国家，请求会等待顾客输入邮政编码。从美国发往加拿大或波多黎各的货物，会按 UPS 的要求发送货物价值。
顾客只会看到一个选项，即最便宜的 UPS 服务。价格先以商店默认货币计算，然后以顾客购物车的货币显示。由于模块不收集 Access Point 地址，因此不报 UPS Access Point Economy 的价格。
每次报价缓存 1 小时。失败的请求会记录 10 分钟，失败的令牌请求记录 5 分钟，这样故障不会拖慢每次结账更新。HTTP 超时时间为 15 秒。
如果 UPS 未返回运费（API 不可用、凭据错误、没有服务、没有汇率的其他货币），价格将依次取自 Country prices、Fallback cost。两者都不适用时，承运商会被隐藏。顾客永远看不到 UPS 的错误信息。
如果在承运商已有订单后，您在 Shipping > Carriers 中编辑了该承运商，PrestaShop 会将其保存为新的承运商版本。模块会自动跟随新版本。
模块仅计算运费。它不提供 UPS Access Point 选择，不创建运单或 UPS 运输单，不预约取件，也不追踪包裹。它只显示一个选项，而不是多个 UPS 服务。不进行装箱：购物车按一个包裹报价。汇率不会自动更新。
订单
使用实时 UPS 运费下单时，UPS 服务会与订单一同保存。后台订单页面会显示一个 UPS 区块，包含 UPS service（例如 UPS Ground）和 Live rate (excl. tax)。之后在后台修改购物车不会改变它。使用固定价格或免运费的订单没有此区块。
许可证密钥
模块需要使用 vibefox.net 提供的 VibeFox 许可证密钥。许可证区块 License — VibeFox UPS 是 Modules > Module Manager > VibeFox UPS > Configure 页面中的第一个区块，位于设置上方。请将密钥输入 License key，然后点击 Activate。此后，该区块会以掩码形式显示密钥、状态（例如许可证的有效截止日期和您的域名），以及以下按钮：Check now（重新检查状态）、Change key（输入其他密钥）和 Remove key（从本商店移除密钥）。其下方有一行 Product: presta-shipping-ups，以及链接 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 账户中释放该名额。
没有有效密钥时，结账时不会向顾客显示 UPS 承运商，也不会计算运费。PrestaShop 前台无法得知您已登录后台，因此承运商对您也是隐藏的：您可以在购买密钥之前设置模块，但无法在结账时测试。Modules > Module Manager 的 Alerts 选项卡中会出现提醒。现有订单不受影响。
许可证过期后，模块仍会继续运行，但更新和支持需要续费。在后台工作时，系统会自动重新检查状态：输入密钥后的前 14 天每天一次，之后每周一次。无需 cron 任务。卸载或重置模块时，始终会删除许可证密钥和许可证状态。
故障排除
结账时不显示 UPS：请检查许可证是否有效，Enable UPS shipping 是否开启。在 Shipping > Carriers 中，检查该承运商是否覆盖顾客所在国家的配送区域和顾客组；或开启 Ignore shipping zones 并检查 Countries。检查重量限制和 Minimum subtotal。没有可用的 UPS 凭据时，承运商需要固定价格（Country prices 或 Fallback cost）。此外，还可以在商品页面将商品限定为特定承运商。
实时运费不显示：请查看 Configure 页面顶部的警告。开启 Debug log，重新加载结账页面，然后查看模块页面上的 Log 字段。其中会显示 OAuth 错误（请检查 Client ID、Client Secret 和 Test mode）、UPS 错误信息以及货币问题。
运费为 USD，但商店不是：UPS 以发货账号的货币返回运费。请设置 UPS account currency 和 Exchange rate。没有汇率时，这类运费会被忽略，并使用固定价格。
「This measurement system is not valid for the selected country」：请将 Measurement units 保持为 Automatic，或选择 UPS 对您发货国家所要求的单位。
页面提示商店的重量或尺寸单位未知：此时重量按 kg、箱子尺寸按 cm 读取。请在 International > Localization 的 Local units 部分设置标准单位（kg、g、lb 或 oz；cm、mm、m 或 in）。
修改后运费看起来过时：请点击模块页面上的 Save，或点击 Clear cached UPS token and rates。
页面提示未找到 UPS 承运商：该承运商已在 Shipping > Carriers 中被删除。请在 Modules > Module Manager 中重置模块，以重新创建它。
开发者相关：钩子 actionVfdUpsxAllowedServices 和 actionVfdUpsxExcludedServices 用于限制可显示的 UPS 服务。actionVfdUpsxRateRequest 用于修改运费请求，actionVfdUpsxApiBaseUrl 用于修改 API 地址，actionVfdUpsxCurrencyCodes 用于映射 UPS 返回的货币代码。
卸载
进入 Modules > Module Manager，打开 VibeFox UPS 旁边的菜单，选择 Uninstall。许可证密钥和许可证状态始终会被删除。缓存的 UPS 令牌和运费始终会被删除。如果 Remove data on uninstall 已开启，承运商会被删除（订单会保留其历史记录），设置、日志以及随订单保存的 UPS 服务也会被删除。如果已关闭，承运商仅会被禁用，设置会保留。重新安装模块或执行重置，会让承运商恢复之前的状态。
UPS 是其各自所有者的商标。本模块与 UPS 无关联，也未获得 UPS 的认可。