VibeFox UPS for OpenCart — 帮助
系统要求
OpenCart：3.0.x（已在 3.0.5.0 上测试），或 4.0.2 及更高版本（已在 4.1.0.3 上测试）。
PHP：8.0 或更高版本，并启用 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 购买。一个密钥只能用于一个域名。
安装
下载文件是一个 zip 压缩包，内含适用于两个 OpenCart 版本的安装包。请将其解压到您的计算机上。其中包含 README.txt、OpenCart 3 安装包 vfd_ups-oc3-(version).ocmod.zip，以及 OpenCart 4 安装包 vfd_ups.ocmod.zip。请只安装与您的 OpenCart 版本对应的安装包。两个版本使用相同的许可证密钥。
OpenCart 3
1. 在后台进入 Extensions > Installer，点击 Upload，然后选择文件 vfd_ups-oc3-(version).ocmod.zip。本扩展不添加任何 OCMOD 修改，因此无需刷新 Extensions > Modifications。您也可以不使用 Installer，而是将本安装包中 upload 文件夹的内容复制到店铺的根目录。
2. 进入 Extensions > Extensions，选择扩展类型 Shipping。找到 VibeFox UPS，点击 Install（绿色 + 按钮）。
3. 点击 Edit（铅笔按钮）打开设置页面。
4. 在 Edit 页面顶部的许可证区块中，将 VibeFox 许可证密钥输入到 License key 字段，然后点击 Activate（见 License key）。
5. 输入 Client ID 和 Client Secret、您的 UPS 账户号（用于协商费率），以及 Ship from 发货地址：邮政编码，若为美国或加拿大，还需填写两位字母的州代码。
6. 如果您的 UPS 账户货币与店铺默认货币不同，请输入 UPS account currency 和 Exchange rate。
7. 可选择输入固定价格作为备用，开启 Enable UPS shipping，然后点击 Save。
OpenCart 4
1. 在后台进入 Extensions > Installer，点击 Upload，然后选择文件 vfd_ups.ocmod.zip。请不要重命名该文件：OpenCart 4 会从文件名获取扩展代码，重命名后的安装包无法使用。
2. 安装包会出现在同一页面的已安装扩展列表中。点击其旁边的 Install（绿色 + 按钮）。
3. 进入 Extensions > Extensions，选择扩展类型 Shipping。找到 VibeFox UPS，点击 Install（绿色 + 按钮），然后点击 Edit（铅笔按钮）。
4. 许可证密钥和设置请按 OpenCart 3 的第 4 至 7 步操作。两个版本的设置页面及其字段相同。
安装后，该方式保持关闭，直到您开启 Enable UPS shipping 并保存。Ship from 的国家最初与店铺所在国家相同。如果您在卸载后重新安装扩展，之前保留的 UPS 设置将再次被使用。
配置
所有设置都位于扩展页面：Extensions > Extensions > Shipping > VibeFox UPS > Edit。各分区列在左侧。页面底部的一个 Save 按钮会保存整个页面，无需重新加载。每次保存都会清除缓存的 UPS 令牌和费率。只有拥有本扩展修改权限的管理员用户才能保存设置、清除缓存或清空日志。
如果名称、税率类别、排序或地理区域无效，则不会保存任何内容，页面会显示原因，例如 Enter a valid name (64 characters max, without < > ; = # { }). Nothing was saved. 无效的数字（例如负数）、错误的箱子尺寸、大于 Max weight (kg) 的 Min weight (kg)，以及不是数字的价格单元格，都会在保存时报告：该字段保留原值，其余设置仍会保存。设置上方的警告会提示：Client ID 和 Client Secret 只填了一个、没有凭据也没有固定价格（此时该方式永远不会显示）、发货地的邮政编码或州缺失、选择了账户费率却没有账户号、缺少汇率，或店铺的重量或长度单位无法被本扩展识别。
常规
这些设置适用于所有地理区域。UPS 在结账时作为一个配送选项提供。
Enable UPS shipping：在结账时显示或隐藏 UPS。默认：关闭。
Name：结账时显示给顾客的配送方式名称。默认：UPS。必填，最多 64 个字符，不得包含 < > ; = # { }。
Tax class：配送费的税率类别，或 None（默认）。UPS 费率以不含税价格报价。设置税率类别后，OpenCart 会在其上加收配送税。
Sort order：结账时 UPS 在配送方式中的位置。整数。
UPS API（实时运费）
Test mode：使用 UPS 测试环境。测试费率不是真实价格。获取实时费率时请关闭。默认：关闭。
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 住宅附加费。如果您主要发货给企业，请关闭。默认：开启。
Box size (L x W x H)：可选的箱子尺寸，单位为店铺的长度单位（显示在字段名称中），例如 30x20x15。UPS 会据此应用体积重量。留空则仅按重量报价。
UPS account currency：UPS 以发货人账户所在国家的货币报价，例如美国为 USD，加拿大为 CAD，欧元区为 EUR。默认：USD。
Exchange rate：仅当 UPS 账户货币与店铺默认货币不同时需要。请输入 1 个账户货币单位等于多少店铺默认货币，例如 0.92。没有它，此类费率将不被使用，改用固定价格。汇率不会自动更新。
Cache：UPS 令牌缓存至过期（最长不超过 OpenCart 的缓存时长），费率缓存 1 小时，失败的请求缓存 5 至 10 分钟。点击 Clear cached UPS token and rates 可立即清空缓存。
Ship from（UPS 取件的地址或您寄送包裹的地址；用于实时运费）
Country：您发货的国家。默认为店铺所在国家。
State / province code：两位字母的州代码，美国和加拿大必填，例如 NY、CA 或 ON。仅对这两个国家会发送给 UPS。
City：您发货的城市。
ZIP / postal code：您发货的邮政编码。UPS 报价时需要它。OpenCart 没有店铺邮政编码，因此请在此输入。
固定价格（未填写 API 凭据时使用，并在 UPS 未返回费率时作为备用；如果两者都留空，则在这种情况下隐藏该方式）
Country prices：以店铺默认货币表示、不含税的价格，按目的国家设定。点击 Add country 添加一行，点击删除按钮删除一行。* Default (all other countries) 适用于所有其他国家。某个重量列（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。
Default product weight (kg)：用于没有重量的商品的重量，适用于 UPS 费率、重量列和重量限制。默认：0.5。留空也表示 0.5。
Geo zone：仅向此地理区域内的地址提供 UPS。All zones（默认）表示无限制。地理区域在 System > Localisation > Geo Zones 中管理。使用 Ignore shipping zones 时不适用。
无配送区域时的可用性
Ignore shipping zones：不检查地理区域。该方式将在下列国家提供。
Countries：该模式的目标国家。留空则使用店铺所有已启用的国家。仅当 Ignore shipping zones 开启时才使用此字段。
高级
Debug log：将 API 请求和费率计算记录到 storage/logs/vfd_upsx_debug.log.php（在 OpenCart 4 中为 system/storage/logs/vfd_upsx_debug.log.php）。该文件无法通过网页读取。即使此选项关闭，API 错误仍会始终被记录。凭据、令牌和顾客地址绝不会被记录。文件达到 5 MB 时，会被移动到 vfd_upsx_debug.old.log.php，并开始新的日志。
Log：显示日志的大小和最新条目。点击 Clear log 可清空日志。
Remove data on uninstall：开启后，卸载扩展会删除 UPS 设置、缓存的令牌和费率以及日志。随订单保存的 UPS 服务始终保留。关闭时，所有内容都会保留，以便重新安装。
导入 / 导出
Export：点击 Download JSON，将设置保存为 JSON 文件。Client Secret 不会被导出。
Import：粘贴之前导出的 JSON，然后点击 Import，即可恢复设置，例如在另一家店铺中使用。这些值会像普通保存一样进行检查。已保存的 Client Secret 会被保留。
结账时的运作方式
OpenCart 显示配送方式时，会向扩展请求 UPS 的价格。如果设置了 Geo zone 且地址位于其之外，则不提供 UPS（使用 Ignore shipping zones 时，则由国家列表决定）。只有 Requires Shipping 设为 Yes 的商品才会计入：其他商品不增加重量，也不计入小计。小计是这些商品经优惠券折扣后、税前的价格。礼品卡、奖励积分和店铺余额不计入在内。然后扩展会检查条件：购物车重量和最低小计。如果适用免运费，价格为 0，且不会向 UPS 发送请求。
扩展会从 UPS 获取 OAuth 令牌，并在其过期前持续使用。被 UPS 拒绝的令牌会自动更新，并重试一次请求。然后，它会向 UPS Rating API 请求从您的发货地址到顾客地址之间的所有服务，购物车作为一个包裹计算。对于 OpenCart 要求邮政编码的国家，请求会等待顾客输入邮政编码后再发送。对于从美国发往加拿大或波多黎各的货件，会按 UPS 的要求发送商品价值。
顾客只会看到一个包含最便宜 UPS 服务的选项。价格以店铺默认货币计算，并按其小数位数取整，然后以顾客的货币显示，同时包含所选 Tax class 的税费。UPS Access Point Economy 不会报价，因为本扩展不收集 Access Point 地址。
每个报价缓存 1 小时。失败的请求会记住 10 分钟，失败的令牌请求记住 5 分钟，因此服务中断不会拖慢每次结账页面的更新。HTTP 超时时间为 15 秒。
如果 UPS 没有返回费率（API 不可用、凭据错误、没有可用服务、使用无汇率的其他货币），价格将依次取自 Country prices 和 Fallback cost。如果两者都不适用，该方式将被隐藏。顾客永远不会看到 UPS 的错误文本，原因会写入调试日志。
本扩展只计算费率。它不提供 UPS Access Point 选择，不创建运输标签或 UPS 运单，不预约取件，也不跟踪包裹。它只显示一个选项，而非多个 UPS 服务。没有装箱功能：购物车作为一个包裹报价。汇率不是自动的。
在 OpenCart 4 中，顾客在结账页面的配送方式区块中点击 Choose，并在 Shipping method options 窗口中选择 UPS。该方式的工作方式与 OpenCart 3 相同。
订单
使用实时 UPS 费率下单时，UPS 服务会与订单一同保存。Sales > Orders 中的订单页面会显示一个 UPS 面板，包含 UPS service（例如 UPS Ground）和 Live rate (excl. tax)。这些值在下单时保存。固定价格或免运费的订单没有此面板。
OpenCart 4 为结账保留一个订单，每次顾客重新确认时都会更新该订单。已保存的 UPS 服务会随之更新。如果顾客改选其他配送方式，或价格变为固定价格或免运费，已保存的服务将从订单中移除。在 OpenCart 4 中，UPS 面板显示在 History 部分上方。
许可证密钥
本扩展需要使用来自 vibefox.net 的 VibeFox 许可证密钥。License — VibeFox UPS 许可证区块是 Extensions > Extensions > Shipping > VibeFox UPS > Edit 页面中位于设置上方的第一个区块。请将密钥输入 License key 字段，然后点击 Activate。之后，该区块会以掩码形式显示密钥、状态（例如许可证有效期截止日期和您的域名），并提供以下按钮：Check now（重新检查状态）、Change key（输入其他密钥）和 Remove key（从本店铺移除密钥）。其下方是 Product: opencart-shipping-ups 一行，以及打开您 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。如果无法连接许可证服务器，扩展会继续使用最后已知的状态运行。
一个密钥只能用于一个域名。您可以在 vibefox.net 账户中管理您的许可证和域名。
没有有效的密钥，UPS 不会在结账时显示给顾客，也不会计算任何费率。在同一浏览器中登录后台的管理员用户，仍会在店铺中看到该方式，并标有 (unlicensed — visible to admins only)，因此您可以在购买密钥之前设置和测试本扩展。在 OpenCart 4 中此预览不可用：店铺看不到后台登录状态，因此没有有效密钥时，该方式对所有人都隐藏。打开一次 Edit 页面后，后台 Dashboard 上会出现提醒。点击 × 可将其隐藏 7 天。现有订单不受影响。
许可证到期后，扩展会继续运行，但更新和支持需要续费。当您打开后台的 Dashboard 或 Edit 页面时，状态会自动重新检查：输入密钥后的前 14 天每天一次，之后每周一次。无需 cron 任务。卸载扩展时，始终会删除许可证密钥和许可证状态。
故障排除
UPS does not appear at checkout：请检查许可证是否有效，以及 Enable UPS shipping 是否已开启。检查 Geo zone，或开启 Ignore shipping zones 并检查 Countries。检查重量限制和 Minimum subtotal。没有可用的 UPS 凭据时，该方式需要固定价格（Country prices 或 Fallback cost）。检查商品的 Requires Shipping 是否设为 Yes。
Live rates do not appear：请检查 Edit 页面顶部的警告。开启 Debug log，重新加载结账页面，然后查看扩展页面上的 Log 字段。它会显示 OAuth 错误（请检查 Client ID、Client Secret 和 Test mode）、UPS 错误信息以及货币问题。
The rate is in USD but the store is not：UPS 以发货人账户的货币返回费率。请设置 UPS account currency 和 Exchange rate。没有汇率的话，此类费率会被忽略，并使用固定价格。
"This measurement system is not valid for the selected country"：请将 Measurement units 保持为 Automatic (by ship-from country)，或选择 UPS 对您发货国家所要求的单位。
The page warns about the weight or length unit：如果没有以 kg 为单位的重量类别，未知的重量单位将按 kg 计算。请在 System > Localisation > Weight Classes 中添加一个 kg 重量类别。店铺的长度单位未知时，Box size 会按 cm 计算。请将 cm、mm、m 或 in 用作店铺的长度类别（System > Settings，选项卡 Option）。
Rates look outdated after a change：在扩展页面点击 Save，或点击 Clear cached UPS token and rates。
The page says "Warning: You do not have permission to modify VibeFox UPS!"：您的管理员用户组可能只有查看设置的权限。请在 System > Users > User Groups 中，为该组授予 extension/shipping/vfd_ups（OpenCart 3）或 extension/vfd_ups/shipping/vfd_ups（OpenCart 4） 的修改权限。
For developers：本扩展会触发 OpenCart 事件，其他扩展可以监听这些事件：vfd_ups/allowed_services 和 vfd_ups/excluded_services 限制可显示的 UPS 服务，vfd_ups/rate_request 修改费率请求，vfd_ups/api_base_url 修改 API 地址，vfd_ups/currency_codes 映射 UPS 返回的货币代码。
卸载
进入 Extensions > Extensions，选择 Shipping 类型，然后点击 VibeFox UPS 旁边的 Uninstall（红色 − 按钮）。OpenCart 总会重置 Enable UPS shipping、Sort order、Tax class 和 Geo zone。缓存的 UPS 令牌和费率总会被清除。如果 Remove data on uninstall 已开启，UPS 设置和调试日志也会被删除。如果未开启，其他设置会被保留，并在您重新安装扩展时再次使用。随订单保存的 UPS 服务永远不会被删除，现有订单也会保留其配送方式和费用。
在 OpenCart 4 中，如要同时删除扩展文件，请在卸载后进入 Extensions > Installer，在已安装扩展列表中点击 VibeFox UPS 旁边的 Uninstall（橙色 − 按钮），然后点击 Delete（红色垃圾桶按钮）删除已上传的安装包。
UPS 是其所有者的商标。本扩展与 UPS 没有关联，也未获得 UPS 的认可或背书。