VibeFox CTT for OpenCart — 帮助

系统要求

OpenCart：3.0.x（已在 3.0.5.0 上测试）或 4.0.2 及更高版本（已在 4.1.0.3 上测试）。

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 购买。一个密钥可用于一个域名。

安装

下载文件为一个 zip 压缩包，内含两个 OpenCart 版本的安装包。请先在电脑上解压。其中包含 README.txt、OpenCart 3 的安装包 vfd_ctt-oc3-(version).ocmod.zip 以及 OpenCart 4 的安装包 vfd_ctt.ocmod.zip。只安装与您的 OpenCart 版本对应的安装包。两个版本的许可证密钥相同。

OpenCart 3

1. 在后台进入 Extensions > Installer，点击 Upload，选择文件 vfd_ctt-oc3-(version).ocmod.zip。该扩展不添加任何 OCMOD 修改，因此无需刷新 Extensions > Modifications。您也可以不使用安装程序，而是将本安装包中 upload 文件夹的内容复制到商店的根目录。

2. 进入 Extensions > Extensions，选择扩展类型 Shipping。找到 VibeFox CTT，点击 Install（绿色 + 按钮）。

3. 点击 Edit（铅笔按钮）打开设置页面。

4. 在许可证区块中（位于 Edit 页面顶部）将您的 VibeFox 许可证密钥粘贴到 License key，然后点击 Activate（参见许可证密钥）。

5. 填写运费表（至少包含一行 Portugal 或 * Default），开启 Enable/Disable 和/或 Enable CTT point option，然后点击 Save。可选：填写 CTT API 密钥、App ID 和 Carrier ID，并开启 Live rates（参见配置）。

OpenCart 4

1. 在后台进入 Extensions > Installer，点击 Upload，选择文件 vfd_ctt.ocmod.zip。请勿重命名该文件：OpenCart 4 从文件名中获取扩展代码，重命名后的安装包将无法工作。

2. 安装包会出现在同一页面的已安装扩展列表中。点击其旁边的 Install（绿色 + 按钮）。

3. 进入 Extensions > Extensions，选择扩展类型 Shipping。找到 VibeFox CTT，点击 Install（绿色 + 按钮），然后点击 Edit（铅笔按钮）。

4. 与 OpenCart 3 的步骤 4 和 5 一样，输入许可证密钥并完成设置。两个版本的设置页面及其字段相同。

首次安装后，两个配送选项均处于关闭状态，直到您开启其中一个并保存。如果您卸载后未删除数据便重新安装扩展，则会重新使用保留的设置；若其中任一选项曾处于开启状态，扩展将再次启用。

配置

所有设置都在扩展页面中：Extensions > Extensions > Shipping > VibeFox CTT > Edit。各分区列在左侧。页面底部的单个 Save 按钮可保存整个页面，无需重新加载。价格和条件适用于两个 CTT 选项。每次保存都会清除缓存的 CTT 响应：API 令牌、承运商、价格和 CTT 网点列表。只有拥有该扩展修改权限的管理员用户才能保存设置。

页面顶部的警告会提示：运费表为空、缺少葡萄牙的价格、开启实时运费或 CTT 网点选项时 API 密钥不完整、缺少 Carrier ID、商店货币不是 EUR 且未设置汇率、CTT API 连接失败，以及商店没有单位为 kg 的重量类别或单位为 cm 的长度类别（此时将按单位名称转换商品单位；请检查 System > Localisation > Weight Classes 和 Length Classes）。如果名称为空、无效或超过 64 个字符，Min weight (kg) 大于 Max weight (kg)，或 Sort Order、税类或地理区域无效，页面会显示错误，且不会保存任何内容。其他无效值会以警告形式提示，其余内容仍会保存：无效数字不保存，汇率为 0 或更小则被清除，无效的商品尺寸恢复为默认值，未知目的地或运费表中的重复行会被删除，无效的表格价格留空。

常规

该扩展在结账时最多提供两个选项：配送到客户地址的 CTT 配送，以及配送到 CTT 网点或自提柜。价格和条件适用于两者。

Enable/Disable:开启或关闭配送到客户地址的 CTT 配送。

Name:结账时显示给客户的配送方式名称，例如 "CTT Expresso"。默认：CTT。最多 64 个字符。

Tax class:配送费用的税类。OpenCart 会在价格之上加上该税（例如 IVA）。--- None --- 表示价格为最终价格。两个选项均使用此设置。

Sort Order:结账时 CTT 在各配送方式中的排列位置。整数。

配送到 CTT 网点或自提柜

第二个 CTT 选项。客户按邮政编码或城市搜索 CTT 网点（会自动搜索配送地址），并且必须先选择一个网点才能继续。该选项需要 CTT API 密钥和 Carrier ID。若没有这些，则为不含网点选择的选项。

Enable CTT point option:提供配送到 CTT 网点或自提柜的选项。默认：关闭。

CTT point option name:该选项在结账时的名称。默认：CTT point / parcel locker。最多 64 个字符。

CTT 电子商务 API（实时运费、CTT 网点）（可选；未配置密钥时使用运费表）

Public key:CTT 电子商务账户密钥管理页面中的公钥。

Private key:用于签署每个请求的私钥（HMAC-SHA256）。该密钥从不发送给 CTT，也不写入日志。

保存后，两个密钥都不会再次显示。此时字段说明会显示 Saved - leave empty to keep it. 仅在需要更改时输入新值。勾选 Remove the saved public and private key 并保存即可删除两个密钥。未保存任何密钥时，该部分显示 No keys saved.

App ID (X-APPID):由 CTT 签发的应用密钥，通过 X-APPID 请求头发送。

Carrier ID:您账户中 CTT 承运商的 ID，用于实时运费和 CTT 网点搜索。保存密钥和 App ID 后，您账户中的承运商会列在该字段下方（Carriers of your CTT account:），支持 CTT 网点的承运商标有 CTT points。仅限数字。

Live rates:客户输入街道、邮政编码和城市后，向 CTT 请求价格（费用估算）。在地址不完整以及 CTT 未返回价格时，使用运费表。CTT 将此价格称为估算价格。默认：关闭。

Service ID:可选。当 CTT 返回多种服务时，使用具有此 ServiceId 的服务。留空则使用最便宜的服务。

Exchange rate:CTT 价格以欧元计。如果您商店的默认货币不同，请输入 1 个 CTT 货币单位等于多少个商店货币单位。若未设置，则不使用其他货币的实时运费，而是应用运费表。

Default product size (cm):没有尺寸的商品发送给 CTT 时使用的长 x 宽 x 高。默认：30x20x15。有尺寸的商品使用自身尺寸。尺寸会根据商品的长度和重量类别转换为 cm，重量转换为克。

运费（分区标题显示您商店的默认货币）

请按商店默认货币、不含税，输入您 CTT 合同中的价格，或 ctt.pt 上 CTT 公开价目表中的价格。在实时运费关闭时，此表决定价格；开启时，它作为备用价格。

Price table:每个目的地一行。选择一个国家，Portugal - Azores、Portugal - Madeira 或 * Default (other destinations)。每行都有一个基础 Price，以及可选的 XS（最多 1 kg）、S（最多 2 kg）、M（最多 3 kg）、L（最多 5 kg）和 XL（超过 5 kg）尺寸价格。尺寸价格为空（或 0）时使用基础价格。两者都为空的行会隐藏该配送方式。Azores 行用于葡萄牙邮政编码 9500-9999，Madeira 行用于 9000-9499。若没有这些行，则使用 Portugal 行。点击 Add destination 添加一行，点击 × 按钮删除。价格可接受小数点或逗号。安装后该表为空。

Calculation:运费表价格的计算方式。

CTT 实时价格始终针对整个货件。

条件

Min weight (kg):显示 CTT 选项所需的最低购物车重量。0 表示不限制。

Max weight (kg):购物车重量超过此值时隐藏 CTT 选项。默认：30（CTT 包裹最重可达 30 kg）。0 表示不限制。Min weight (kg) 不能大于 Max weight (kg)。

Minimum order amount:仅当需要配送的商品小计（扣除优惠券后、税前）达到此金额时才显示 CTT 选项。留空则始终显示。

免运费

Free shipping:开启后，达到下方金额即可享受 CTT 免费配送。

Free shipping from:需要配送的商品小计（扣除优惠券后、税前）达到此金额时，CTT 选项费用为 0。仅适用于有价格的目的地。仅在 Free shipping 开启时使用。

可用性

通常，CTT 选项会在下方所选的地理区域内提供。All Zones 表示所有地区。开启 Ignore shipping zones 后，不检查地理区域，改由 Countries 决定。

Geo Zone:配送地址所属的地理区域。地理区域在 System > Localisation > Geo Zones 中管理。

Ignore shipping zones:不检查地理区域；在下方国家中提供 CTT。

Countries:该模式下的目的国家。默认：Portugal。留空则允许所有国家。仅在开启 Ignore shipping zones 时使用。

高级

Debug log:将运费计算和 CTT API 调用记录到 storage/logs/vfd_ctt_debug.log.php（OpenCart 4 中为 system/storage/logs/vfd_ctt_debug.log.php）。该文件无法通过网页读取。即使此选项关闭，CTT API 错误也始终会被记录。密钥、令牌和客户地址从不记录。当文件达到 5 MB 时，会移至 vfd_ctt_debug.old.log.php，并开始新的日志。

Log:显示日志的大小和最新条目。点击 Clear log 可清空日志。

Remove data on uninstall:开启后，卸载扩展会删除设置、日志以及未完成结账的 CTT 网点。关闭时（默认），设置会保留，以便重新安装。订单（包括所选的 CTT 网点）永远不会被更改。

导入 / 导出

Export:点击 Download JSON 将设置保存为 JSON 文件。公钥和私钥不会被导出。

Import:粘贴之前导出的 JSON，然后点击 Import 恢复设置，例如在另一家商店中使用。系统会像正常保存一样检查这些值。已保存的密钥会被保留。

结账时的工作方式

当 OpenCart 显示配送方式时，会向扩展请求 CTT 价格。开启 Ignore shipping zones 时，仅对 Countries 中的国家提供 CTT（留空 = 所有国家）；否则，若设置了 Geo Zone，则仅对该区域内的地址提供。只有 Requires Shipping 设为 Yes 的商品才会计算在内：其他商品不增加重量，也不计入订单金额。扩展会检查购物车重量和最低订单金额。开启 Live rates 且地址完整时，它会将配送地址发送给 CTT，并针对每个购物车行发送数量、以克为单位的重量和以 cm 为单位的尺寸，然后使用返回的价格。否则，或当 CTT 未返回价格时（API 错误、超时、无覆盖范围、您的 App ID 未启用某项功能），价格取自运费表。如适用免运费，价格为 0。两个选项获得相同的价格。价格以商店的默认货币计算，按其小数位数取整，并以客户的货币显示，同时包含所选 Tax class 的税费。

CTT 价格缓存 1 小时，因此相同的购物车不会触发新的请求。失败的请求会记住 5 分钟，因此结账页面在每次刷新时都不必等待 CTT。API 令牌、承运商列表和 CTT 网点列表也会被缓存，最长为 OpenCart 缓存的有效期（默认 1 小时）。API 错误绝不会显示给客户：会使用运费表价格，若目的地没有价格，则隐藏该配送方式。

填写 API 密钥后，扩展会将配送地址、商品重量和尺寸以及您的商店网址发送给 CTT，以获取价格或最近的 CTT 网点。

该扩展不创建运单、不打印面单、不预约取件、不提供追踪号码，也不显示 CTT 网点地图。两个选项共用一个运费表和一组 API 设置。

在 OpenCart 4 中，客户在结账页面的配送方式区块中点击 Choose，然后在 Shipping method options 窗口中选择一个 CTT 选项。价格与 OpenCart 3 相同。

取件点

当客户在配送方式步骤中选择 CTT 网点选项时，其下方会出现搜索框和列表。配送地址的邮政编码会被自动填入并搜索。客户可以按邮政编码或城市搜索其他 CTT 网点（Search 按钮），并从列表中选择一个。选择会立即保存。只接受该次搜索结果中 CTT 列表里的网点。

客户必须先选择一个网点才能继续。当客户点击 Continue 时，扩展会在服务器上验证该网点。若未选择网点，客户会看到 Please select a CTT point.；若网点不在 CTT 列表中，则会看到 The selected CTT point is not in the CTT list for this search. Please choose the CTT point again. 若无法连接 CTT，客户会看到 CTT points cannot be loaded right now. Please try again in a few minutes or choose another shipping method.

只有在公钥、私钥、App ID 和 Carrier ID 都已填写时，网点选择才会生效。它是为 OpenCart 默认主题及其结账页面设计的；其他主题可能需要修改。

在 OpenCart 4 中，搜索框和列表会出现在 Shipping method options 窗口中，位于 CTT 网点选项下方。窗口中的 Continue 按钮在没有有效网点时无法继续，并显示相同的提示。OpenCart 4 会为结账保留一个订单，每次客户重新确认时都会更新该订单，订单中的 CTT 网点也会随之更新。

所选网点会添加到订单的配送方式中，例如 CTT point / parcel locker: ...。因此，客户可在其账户的订单历史和订单电子邮件中看到该信息，它也会打印在发票上，并显示在 Sales > Orders 中。OpenCart 订单成功页面不显示配送方式。

在后台订单页面，历史记录上方的 CTT point 面板会显示网点名称和 ID。若要更改，请在 Change CTT point 下输入邮政编码或城市，点击 Search，选择一个网点，然后点击 Save。页面会显示 CTT point updated.，订单的配送方式文本会更新，并在订单历史中添加 CTT point changed to: ... 记录，且不会通知客户。更改网点需要订单修改权限（sale/order）和 API 设置。即使扩展已禁用，CTT 订单仍会显示该面板。

许可证密钥

该扩展需要来自 vibefox.net 的 VibeFox 许可证密钥。License — VibeFox CTT 许可证区块位于扩展 Extensions > Extensions > Shipping > VibeFox CTT > Edit 页面的最上方，位于设置之上。将密钥粘贴到 License key 并点击 Activate。之后，该区块会以掩码形式显示密钥、状态（例如许可证有效期截止日期和您的域名），以及以下按钮：Check now（重新检查状态）、Change key（输入其他密钥）和 Remove key（从此商店中移除密钥）。其下方是 Product: opencart-shipping-ctt 一行，以及 Manage licenses and domains in your account 链接，该链接会打开您的 vibefox.net 账户。只有拥有该扩展 Modify 权限的管理员用户才能更改密钥。该区块的文本跟随管理后台语言（包括英文和俄文）。

如果密钥未被接受，区块会说明原因，例如 Key not found、This key belongs to another product、Domain limit reached，或 License expired on 加某个日期。商店地址更改后，或在您的 vibefox.net 账户中释放了域名名额后，请点击 Check now。如果无法连接许可证服务器，扩展会继续使用上次已知的状态运行。

一个密钥只能用于一个域名：即 OpenCart 配置中的商店地址。从商店中移除密钥不会释放其域名名额。请在您的 vibefox.net 账户中释放该名额。

没有有效的密钥时，CTT 不会在结账时显示给客户，也不会计算任何运费。在同一浏览器中登录后台的管理员用户仍能在商店中看到该配送方式，并标有 (unlicensed — visible to admins only)，因此您可以在购买密钥前进行设置和测试。在 OpenCart 4 中此预览不可用：商店看不到后台登录状态，因此没有有效密钥时，该配送方式对所有人都隐藏。您打开过一次 Edit 页面后，后台 Dashboard 上会出现提醒。点击 × 可将其关闭，关闭后 7 天内不再显示。现有订单不受影响。

许可证到期后，扩展仍可继续工作，但更新和支持需要续费。当您打开后台 Dashboard 或 Edit 页面时，系统会自动重新检查状态：密钥输入后的前 14 天每天一次，之后每周一次。无需 cron 任务。卸载扩展时，始终会删除许可证密钥和许可证状态。

故障排除

CTT 未出现在结账页面中：请检查许可证是否有效，并确认 Enable/Disable（或 Enable CTT point option）已开启。检查 Geo Zone，或 Ignore shipping zones 与 Countries。确认目的地在运费表中有对应行（或 * Default 行），购物车重量在 Min weight 和 Max weight 之间，已达到 Minimum order amount，并且商品的 Requires Shipping 设为 Yes。

客户无法选择 CTT 网点：选择器仅在 CTT 网点选项下方显示，且仅当公钥、私钥、App ID 和 Carrier ID 均已填写时才会显示。请检查设置页面顶部的警告，开启 Debug log，并查看扩展页面上的 Log 字段。

实时运费未显示：在客户输入街道、邮政编码和城市之前，使用的是运费表。请检查警告和日志。回复 "405" 表示您的 App ID 未启用该功能：请咨询 CTT。在非欧元商店中，请填写 Exchange rate。

与 CTT API 的连接失败：设置页面顶部的警告会显示错误信息。请检查密钥和 App ID。扩展会在几分钟后自动重试。

价格含税或不含税：选择 Tax class 后，OpenCart 会在价格之上加上该税。若选择 --- None ---，则价格为最终价格。

修改后价格看起来过时：请在扩展页面点击 Save。这会清除缓存的 CTT 响应。

页面显示 "Warning: You do not have permission to modify VibeFox CTT!"：您的管理员用户组可能只有查看设置的权限。请在 System > Users > User Groups 中为该组授予 extension/shipping/vfd_ctt（OpenCart 3）或 extension/vfd_ctt/shipping/vfd_ctt（OpenCart 4）的修改权限。

开发人员：CTT API 地址可以通过设置 vfd_ctt_api_url 替换（用于测试）；设置页面上没有该字段。

卸载

进入 Extensions > Extensions，选择类型 Shipping，然后点击 VibeFox CTT 旁边的 Uninstall（红色 − 按钮）。该扩展的许可证密钥和许可证状态始终会被删除。OpenCart 始终会重置扩展状态、Sort Order、Tax class 和 Geo Zone。缓存的 CTT 响应和 API 令牌始终会被删除。如果开启了 Remove data on uninstall，设置、日志以及从未成为订单的结账 CTT 网点也会被删除。如果关闭，其他设置会保留，并在您重新安装扩展时再次使用。保存在订单中的 CTT 网点始终保留，现有订单保留其配送方式和费用。

在 OpenCart 4 中，若还要删除扩展的文件，请在卸载后进入 Extensions > Installer，在已安装扩展列表中点击 VibeFox CTT 旁边的 Uninstall（橙色 − 按钮），然后点击 Delete（红色垃圾桶按钮）删除已上传的安装包。

CTT 是其各自所有者的商标。本扩展与 CTT 无关联，也未获得 CTT 的认可。