VibeFox CTT for WooCommerce — 帮助
系统要求
WordPress：5.8 或更高版本。
WooCommerce：7.0 或更高版本，已安装并启用。没有 WooCommerce 时插件无法激活。
PHP：8.0 或更高版本。
CTT 电子商务账户（仅用于实时费率和 CTT 网点）：实时费率和 CTT 网点配送使用 CTT 电子商务 API。您需要在 enviosecommerce.ctt.pt 注册 CTT 电子商务账户（适用于 CTT Expresso 合同客户，或向 CTT 索取报价）。在该账户的密钥管理页面中，创建一对公钥和私钥。App ID（X-APPID）由 CTT 为您的集成签发：请咨询您的 CTT 电子商务联系人。CTT 还会决定您的 App ID 可以使用哪些 API 功能（运费估算、CTT 网点）。最后，您需要账户中的 CTT Carrier ID。保存密钥后，设置页面会列出您账户中的承运商。如果您只使用价格表和送货上门，则无需 API 密钥。
VibeFox 许可证密钥：在 vibefox.net 购买。一个密钥对应一个域名。
安装
1. 在 WordPress 中进入 Plugins > Add New > Upload Plugin，选择插件 ZIP 文件并点击 Install Now。您也可以通过 FTP 将 vfd_ctt 文件夹上传到 /wp-content/plugins/。
2. 点击 Activate。
3. 打开设置：WooCommerce > Settings > Shipping > VibeFox CTT，或在插件页面点击插件名称下方的 Settings。
4. 在页面顶部的许可证区块中输入您的 VibeFox 许可证密钥，然后点击 Activate。
5. 填写价格表（至少一行 Portugal 或 * Default）。可选填写 CTT API 密钥和 Carrier ID，并开启 Live rates（参见配置）。
6. 在 WooCommerce > Settings > Shipping > Shipping zones 中，打开或创建葡萄牙的配送区域，并添加 VibeFox CTT。在方法设置中选择标题和配送类型。或者开启 Ignore shipping zones 并选择国家。
配置
价格、API 密钥和条件都位于同一页面：WooCommerce > Settings > Shipping > VibeFox CTT。它们适用于所有配送区域。将该方式添加到某个区域时，区域窗口包含两个字段：
Title (zone)：该区域结账时此选项的名称。留空则使用全局 Name。
Delivery：To the customer's address（默认）或 To a CTT point or parcel locker chosen at checkout。CTT 网点需要在全局设置中填写 CTT API 密钥和 Carrier ID。在同一区域中添加两次该方式，即可并排提供送货上门和 CTT 网点配送。
设置上方的警告会提示：缺少葡萄牙的价格、API 密钥不完整、缺少 Carrier ID、店铺货币没有汇率，以及 CTT API 连接失败。每次保存设置时，缓存的 CTT 响应都会被清除。
通用
Enable/Disable：一次性在所有区域中启用或禁用该方式。
Name：结账时显示的配送方式名称，例如 "CTT Expresso"。默认：CTT。区域的 Title 会覆盖此名称。
Tax status：Taxable 会在价格上加收 WooCommerce 配送税（例如 IVA）；None 表示价格即为最终价格。
CTT 电子商务 API（实时费率、CTT 网点）（可选；不填写密钥时使用价格表）
Public key：CTT 电子商务账户密钥管理页面中的公钥。
Private key：用于签署每个请求的密钥（HMAC-SHA256）。它从不发送给 CTT，也不会写入日志。
App ID (X-APPID)：CTT 为您的集成签发的应用密钥。
Carrier ID：您账户中 CTT 承运商的 ID，用于实时费率和 CTT 网点搜索。保存密钥后，您账户的承运商会列在该字段下方，其中支持 CTT 网点的承运商会被标记。
Live rates：顾客输入街道、邮政编码和城市后，向 CTT 请求运费（成本估算）。地址不完整时，以及 CTT 未返回价格时，使用价格表。CTT 将该价格称为估算。默认：关闭。
Service ID：可选。当 CTT 返回多种服务时，使用具有此 ServiceId 的服务。留空则使用最便宜的服务。
Exchange rate：CTT 价格以欧元计。如果您的店铺货币不同，请填写 1 个 CTT 货币单位等于多少个店铺货币单位。不填写的话，非欧元的实时费率将不被使用，改用价格表。
Default product size (cm)：发送给 CTT 的、没有尺寸的商品所使用的长 x 宽 x 高。默认：30x20x15。有尺寸的商品使用其自身尺寸。尺寸会换算为厘米，重量会根据店铺单位换算为克。
价格（章节标题会显示您的店铺货币）
以店铺货币输入您 CTT 合同或 CTT 公开价目表中的价格。关闭实时费率时，此价格表决定运费。开启实时费率时，它作为备用价格。
Price table：每个目的地一行。选择国家，Portugal - Azores (PT-AC)、Portugal - Madeira (PT-MA) 或 * Default (other destinations)。每行包含基础价格（Price），以及可选的 XS（最多 1 kg）、S（最多 2 kg）、M（最多 3 kg）、L（最多 5 kg）和 XL（超过 5 kg）尺寸价格。尺寸价格为空（或 0）时使用基础价格。两者都为空的行会隐藏该方式。亚速尔群岛行适用于葡萄牙邮政编码 9500-9999，马德拉群岛行（包括 Porto Santo）适用于 9000-9499。没有这些行时，适用 Portugal 行。点击 + Add destination 添加一行，点击叉号删除一行。价格可使用小数点或逗号。保存时会提示无效的行。
Calculation：表中价格的计算方式。
CTT 实时运费始终针对整个运单。
条件
Min weight (kg)：方式出现所需的购物车最小重量。0 表示不限制。
Max weight (kg)：购物车重量超过此值时隐藏该方式。默认：30（CTT 包裹最重 30 kg）。0 表示不限制。
Minimum order amount：仅当购物车小计（扣除折扣后、税前）达到此金额时才显示该方式。留空则始终显示。
Excluded shipping classes：当购物车中任一商品属于这些 WooCommerce 配送类别时，隐藏该方式。
免运费
Free shipping：开启后，满足下方金额时免除 CTT 配送费。
Free shipping from：购物车小计（扣除折扣后、税前）达到此金额时，该方式免费。仅适用于该方式设有价格的情况。仅在 Free shipping 开启时使用。
无配送区域时的可用性
Ignore shipping zones：当顾客所在区域不包含该方式时，在下方国家中提供该方式。
Countries：该模式下的目的地国家。默认：Portugal。留空则使用您配送的所有国家。此字段仅在 Ignore shipping zones 开启时使用。
高级
Debug log：在 WooCommerce > Status > Logs 中记录运费计算和 CTT API 调用，来源为 vfd-ctt。即使此项关闭，CTT API 错误仍会始终记录。密钥、令牌和顾客地址从不记录。
Remove data on uninstall：开启时，删除插件会移除其设置和区域方式。停用插件从不删除数据。订单从不会被更改。
结账时的工作方式
当顾客输入配送地址时，WooCommerce 会向插件请求运费。插件首先检查购物车重量、最低订单金额和排除的配送类别。开启 Live rates 且地址完整时，插件会将配送地址以及每个购物车行的数量、以克为单位的重量和以厘米为单位的尺寸发送给 CTT，并显示返回的价格。否则，或者当 CTT 未返回价格时（API 错误、超时、无覆盖范围、该功能未对您的 App ID 启用），价格来自价格表。如果适用免运费，则价格为 0。
CTT 价格缓存 1 小时，因此同一购物车不会触发新请求。失败的请求会记住 5 分钟，因此结账页面不会在每次刷新时都等待 CTT。API 超时时间为 12 秒。
该方式适用于经典结账以及购物车与结账区块。它兼容 WooCommerce 高性能订单存储（HPOS）。
填写 API 密钥后，插件会将配送地址、商品重量和尺寸以及您的店铺 URL 发送给 CTT，以获取价格或最近的 CTT 网点。
插件不会创建运单、打印面单、预约取件、提供物流单号，也不会显示 CTT 网点地图。整个店铺只有一个价格表和一组 API 设置。各区域的区别仅在于标题和配送类型。
取件点
对于将 Delivery 设为 CTT 网点的区域方式，结账时该方式下方会出现搜索框和列表。配送地址会被自动搜索。顾客可按邮政编码或城市搜索其他 CTT 网点，并须在下单前选择一个。服务器端也会进行此项检查。CTT 网点列表缓存 6 小时。如果无法连接 CTT，顾客会看到提示，可稍后重试或选择其他配送方式。
所选网点会保存到订单中。它会显示在订单管理页面的配送地址下方、订单接收页面、My account > Orders 中，以及订单邮件（HTML 和纯文本）中，标签为 CTT point。
在订单管理页面，点击 CTT 网点旁的 Change，按邮政编码或城市搜索，然后选择另一个网点。更改会立即保存，并添加一条订单备注。
许可证密钥
本插件需要一个来自 vibefox.net 的 VibeFox 许可证密钥。许可证区块位于 WooCommerce > Settings > Shipping > VibeFox CTT 页面顶部。将密钥粘贴到 License key 中，然后点击 Activate。该区块会显示状态，例如许可证有效期截止日期和您的域名。使用 Check now 重新检查状态，使用 Change key 输入另一个密钥，使用 Remove key 将其从本站点移除。Manage licenses and domains in your account 链接会打开您的 vibefox.net 账户。
一个密钥只能用于一个域名。从站点移除密钥并不会释放域名名额。请在您的 vibefox.net 账户中释放该名额。
没有有效密钥时，结账页面不会向顾客显示 CTT。已登录的店铺管理员仍可看到，并会标注 (unlicensed — visible to admins only)，以便您在购买密钥之前设置和测试插件。插件页面和 WooCommerce 页面会显示提醒。现有订单不受影响。
许可证到期后，插件仍可继续工作，但更新和支持需要续费。状态会在后台自动重新检查。
故障排除
结账时没有显示 CTT：请检查许可证是否有效、Enable/Disable 是否开启、该方式是否已添加到顾客所在国家的区域中（或 Ignore shipping zones 已开启且该国家被允许）。检查目的地在价格表中是否有对应行（或 * Default 行）、购物车重量是否在 Min weight 和 Max weight 之间、是否达到 Minimum order amount，以及是否没有商品属于被排除的配送类别。
顾客无法选择 CTT 网点：只有当区域方式的 Delivery 设为 CTT 网点，并且公钥、私钥、App ID 和 Carrier ID 都已填写时，选择器才会出现。请开启 Debug log，并检查 WooCommerce > Status > Logs。
实时费率没有显示：在顾客输入街道、邮政编码和城市之前，使用价格表。请检查设置上方的警告和日志。返回"405"表示该功能未对您的 App ID 启用：请咨询 CTT。在非欧元店铺中，请填写 Exchange rate。
CTT API 连接失败：设置上方的警告会显示错误。请检查密钥和 App ID。插件会在几分钟后自动重试。
含税或不含税价格：当 Tax status 为 Taxable 时，WooCommerce 会在价格上加收配送税。当为 None 时，价格即为最终价格。
许可证区块显示错误：请按照区块中的提示操作。例如，如果该密钥已在其他域名上使用，请在您的 vibefox.net 账户中释放一个名额，然后点击 Check now。如果站点地址已更改，请点击 Check now，为新域名激活该密钥。如果无法连接许可证服务器，插件将按最后已知状态继续工作。
卸载
停用插件会保留所有数据。如需删除，请先停用，然后在 Plugins 页面中删除。本插件的许可证密钥和许可证状态始终会被删除，缓存的 CTT 响应和 API 令牌也会一并删除。只有在开启 Remove data on uninstall 的情况下，设置和区域方式才会被删除；否则它们会保留，供日后重新安装使用。订单（包括所选的 CTT 网点）永远不会被更改，现有订单也会保留其配送项。
CTT 是其各自所有者的商标。本插件与 CTT 无关联，也未获得 CTT 的认可。