VibeFox UPS for WooCommerce — 帮助
系统要求
WordPress：5.8 或更高版本。
WooCommerce：7.0 或更高版本，须已安装并启用。未安装时插件无法激活。
PHP：8.0 或更高版本。
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. 在 WordPress 中进入 Plugins > Add New > Upload Plugin，选择插件的 ZIP 文件，然后点击 Install Now。您也可以通过 FTP 将 vfd_ups 文件夹上传到 /wp-content/plugins/。
2. 点击 Activate。
3. 打开设置：WooCommerce > Settings > Shipping > VibeFox UPS，或在插件列表页点击插件名称下方的 Settings。
4. 在页面顶部的许可证区块中输入您的 VibeFox 许可证密钥，然后点击 Activate。
5. 输入 Client ID 和 Client Secret、您的 UPS 账户号码（用于协议运费），以及 Ship from 地址：邮政编码，对于美国和加拿大还需填写两位字母的州代码。
6. 如果您的 UPS 账户货币与店铺货币不同，请输入 UPS account currency 和 Exchange rate。
7. 在 WooCommerce > Settings > Shipping > Shipping zones 中，将 VibeFox UPS 添加到配送区域；或开启 Ignore shipping zones 并选择国家。
8. 可选：输入固定价格作为备用。
配置
所有设置都位于同一页面：WooCommerce > Settings > Shipping > VibeFox UPS。它们适用于所有配送区域。将该方式添加到某个区域时，区域窗口只有一个字段：
Title (zone)：此选项在结账时显示的名称。留空则使用全局的 Name。
每次保存设置时，缓存的 UPS 令牌和运费都会被清除。您也可以在 UPS API 部分点击 Clear cached UPS token and rates。设置上方的警告会提示：Client ID 与 Client Secret 只填写了一个、没有凭据也没有固定价格、缺少发货邮政编码或州、选择了账户运费却未填写账户号码，或缺少汇率。
General
Enable/Disable：一次性在所有区域中开启或关闭此方式。
Name：结账时显示的配送方式名称。默认：UPS。
Tax status：Taxable 允许 WooCommerce 在运费上另加配送税，None 则不加。UPS 运费报价不含税，因此不会重复征税。
UPS API（实时运费）
Test mode：使用 UPS 测试环境。测试运费不是真实价格。要获取实时运费，请关闭此选项。默认：关闭。
Client ID：您在 UPS Developer Portal 中应用的 Client ID。
Client Secret：同一应用的 Client Secret。
UPS account number：您 6 位的 UPS 托运人号码，例如 A1B2C3。获取账户（协议）运费时需要，获取公开运价时可选。
Rates：使用哪种 UPS 价格。
Measurement units：发送给 UPS 的计量单位。店铺中的重量和尺寸会被换算。
Residential delivery：将顾客地址按住宅地址计算，并加收 UPS 住宅附加费。如果您主要寄送给企业，请关闭。默认：开启。
Box size：可选的包裹尺寸，使用店铺的尺寸单位，例如 30x20x15。启用后，UPS 将应用体积重量。留空则仅按重量计算。
UPS account currency：UPS 以发货人账户所在国家的货币报价，例如美国为 USD、加拿大为 CAD、欧元区为 EUR。默认：USD。
Exchange rate：仅当 UPS 账户货币与店铺货币不同时需要。请输入 1 个账户货币单位对应的店铺货币价格，例如 0.92。若不填写，此类运费将不会被使用，并改用固定价格。汇率不会自动更新。
发货地址（UPS 取件或您交寄包裹的地址；用于实时运费）
Country：您的发货国家。默认为店铺所在国家。
State / province code：两位字母的州或省代码，美国和加拿大必填，例如 NY、CA 或 ON。
City：您的发货城市。
ZIP / postal code：您的发货邮政编码。UPS 需要它来计算运费。
固定价格（未填写 API 凭据时使用，UPS 未返回运费时作为备用；两者都留空则在此情况下隐藏该方式）
Country prices：按目的国家设置的店铺货币价格。点击 + Add country 添加一行，点击叉号删除。* Default 行适用于其他所有国家。重量列（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：购物车小计达到此金额时该方式免运费。顾客会看到带有「(Free)」的方式名称，且不会向 UPS 发送请求。留空则从不提供免运费。
Minimum subtotal：仅当购物车小计至少达到此金额时才显示该方式。留空则始终显示。
Min weight (kg)：该方式出现所需的最低购物车重量。0 表示不限制。
Max weight (kg)：购物车重量超过此值时隐藏该方式。默认：70，即 UPS 单个包裹的限制（70 kg / 150 lbs）。0 表示不限制。
Default product weight (kg)：用于没有重量的商品，适用于 UPS 运费、重量列和重量限制。默认：0.5。
Excluded shipping classes：如果购物车中包含任一所选 WooCommerce 配送类别的商品，则隐藏该方式。
无配送区域时的可用性
Ignore shipping zones：即使未将该方式添加到配送区域，也会为下方所列国家提供此方式。
Countries：此模式下的目的国家。留空则使用店铺的所有配送国家。仅当 Ignore shipping zones 开启时才会使用此字段。
高级
Debug log：将 API 请求和运费计算记录到 WooCommerce > Status > Logs 中，来源为 vfd-ups。即使此选项关闭，API 错误也始终会被记录。凭据、令牌和顾客地址从不记录。
Remove data on uninstall：开启后，删除插件时将移除所有插件设置和区域方式。停用插件从不删除设置。
结账时的工作流程
当顾客输入配送地址时，WooCommerce 会向插件请求运费。插件首先检查条件：购物车重量、最低小计和排除的配送类别。如果适用免运费，该方式将显示为免费，且不会向 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 的错误信息。
该方式适用于经典结账以及购物车和结账区块。它兼容 WooCommerce 高性能订单存储（HPOS）。
插件仅计算运费。它不提供 UPS Access Point 选择，不创建配送标签或 UPS 运单，不预约取件，也不追踪包裹。它只显示一个选项，而不是多个 UPS 服务。不提供装箱功能：购物车将被视为一个包裹进行报价。汇率不是自动的。
订单
对于实时运费，订单的配送行会保存 UPS service，例如 UPS Ground。店铺管理员可以在后台的订单页面看到该信息。
许可证密钥
插件需要一个来自 vibefox.net 的 VibeFox 许可证密钥。许可证区块位于 WooCommerce > Settings > Shipping > VibeFox UPS 页面顶部。将密钥粘贴到 License key 中并点击 Activate。该区块会显示状态，例如许可证有效期截止日期以及您的域名。使用 Check now 重新检查状态，使用 Change key 输入其他密钥，使用 Remove key 从本站点移除密钥。链接 Manage licenses and domains in your account 会打开您的 vibefox.net 账户。
一个密钥只能用于一个域名。从站点移除密钥并不会释放其域名名额，请在您的 vibefox.net 账户中释放该名额。
如果没有有效的密钥，结账时 UPS 不会显示给顾客。已登录的店铺管理员仍可看到它，并标有 (unlicensed — visible to admins only)，以便您在购买密钥前进行设置和测试。插件列表页和 WooCommerce 页面上会出现提醒。现有订单不受影响。
许可证过期后，插件仍可继续工作，但更新和支持需要续费。状态会在后台自动重新检查。
故障排除
结账时没有显示 UPS：请检查许可证是否有效、Enable/Disable 是否开启，以及该方式是否已添加到顾客所在国家的区域（或已开启 Ignore shipping zones 且该国家被允许）。检查重量限制、Minimum subtotal 和 Excluded shipping classes。如果 UPS 凭据无效，该方式需要固定价格（Country prices 或 Fallback cost）。
实时运费不显示：请查看设置页面顶部的警告。开启 Debug log，然后打开 WooCommerce > Status > Logs，选择来源 vfd-ups。其中会显示 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 对您发货国家所要求的单位。
更改后运费似乎过时：保存设置页面，或点击 Clear cached UPS token and rates。
面向开发者：过滤器 vfd_upsx_allowed_services 和 vfd_upsx_excluded_services 用于限制可显示的 UPS 服务。vfd_upsx_rate_request 用于修改运费请求，vfd_upsx_api_base_url 用于修改 API 地址，vfd_upsx_currency_codes 用于映射 UPS 返回的货币代码。
许可证区块显示错误：请按照区块中的提示操作。例如，如果该密钥已在其他域名上使用，请在您的 vibefox.net 账户中释放一个名额，然后点击 Check now。如果站点地址已更改，请点击 Check now，为新域名激活密钥。如果无法连接许可证服务器，插件将继续使用最后已知的状态运行。
卸载
停用插件会保留设置，仅清除缓存的令牌和运费。要删除插件，请先停用，然后在 Plugins 页面将其删除。本插件的许可证密钥和许可证状态，以及缓存的令牌和运费，始终会被删除。只有在 Remove data on uninstall 已开启时，设置和区域方式才会被删除；否则它们会保留，以便日后重新安装时使用。现有订单会保留其配送行。
UPS 是其各自所有者的商标。本插件与 UPS 无关联，也未获得 UPS 认可。