VibeFox CTT for PrestaShop — 帮助
系统要求
PrestaShop：8.0 至 9.x。
PHP：8.0 或更高版本。模块拒绝安装在更早的 PHP 版本上。
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. 在后台进入 Modules > Module Manager，点击 Upload a module。选择模块的 ZIP 文件。
2. 上传完成后，点击 Configure；或之后在模块列表中找到 VibeFox CTT，并点击 Configure。
3. 在 Configure 页面顶部的许可证区块中，将您的 VibeFox 许可证密钥粘贴到 License key 中，然后点击 Activate（参见许可证密钥）。
4. 填写价格表（至少一行 Portugal 或 * Default），然后点击 Save。可选填写 CTT API 密钥和 Carrier ID，并开启 Live rates 和 Enable CTT point carrier（参见配置）。
安装时，模块会创建两个承运商。CTT（送货至顾客地址，配送时间文本为 CTT delivery to your address）默认开启。CTT point / parcel locker（配送时间文本为 Pickup at a CTT point or parcel locker）默认关闭，直到您将其开启。两者都关联葡萄牙区域和所有客户组。您可以在 Shipping > Carriers 中修改区域、客户组、配送时间、图标和尺寸限制。请勿在那里设置价格：价格始终来自模块。
配置
所有设置都在模块页面中：Modules > Module Manager > VibeFox CTT > Configure。每个部分都有自己的 Save 按钮，会保存整个页面。价格和条件适用于两个 CTT 承运商。每次保存都会清除缓存的 CTT 响应，包括 API 令牌和 CTT 网点列表。
设置上方的警告会提示：价格表为空、缺少葡萄牙价格、API 密钥不完整、缺少 Carrier ID、店铺货币不是 EUR 且没有汇率、无法连接 CTT API，以及 CTT 承运商已被删除。无效值会在保存时报告：无效数字不会被保存，未知目的地或价格表中的重复行会被删除。如果模块无法识别店铺的重量或尺寸单位，警告会要求您在 International > Localization（Local units）中设置单位。
常规
Enable/Disable：开启或关闭送货至顾客地址的 CTT 配送。这与 Shipping > Carriers 中承运商的状态是同一个开关。
Name：结账时顾客看到的承运商名称，例如 "CTT Expresso"。默认：CTT。必填，最多 64 个字符。
Tax status：None 表示价格为最终价格。Taxable 并配合税务规则表示 PrestaShop 会在价格之上加上该运费税（例如 IVA）。该选择会保存到两个 CTT 承运商。
送至 CTT 网点或自提柜
第二个 CTT 承运商。顾客按邮政编码或城市搜索 CTT 网点，并须先选择一个才能继续。需要 CTT API 密钥和 Carrier ID。没有它们时，该承运商不提供网点选择。
Enable CTT point carrier：开启或关闭 CTT 网点承运商。这与 Shipping > Carriers 中的状态是同一个开关。默认：关闭。
CTT point carrier 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 并保存，即可删除两个密钥。
App ID (X-APPID)：CTT 签发的应用密钥，在 X-APPID 请求头中发送。
Carrier ID：您账户中 CTT 承运商的 ID，用于实时费率和 CTT 网点搜索。保存密钥和 App ID 后，您账户中的承运商会列在该字段下方，支持 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 (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）时使用基础价格。两个字段都留空的行会隐藏该承运商。Azores 行用于葡萄牙邮政编码 9500-9999，Madeira 行（包括 Porto Santo）用于 9000-9499。没有这些行时，适用 Portugal 行。点击 Add destination 添加一行，点击垃圾桶图标删除一行。价格可使用小数点或逗号。安装后表格为空。
Calculation：价格表中价格的计算方式。
CTT 实时价格始终针对整个包裹。
条件
Min weight (kg)：承运商显示所需的最低购物车重量。0 表示无限制。
Max weight (kg)：购物车重量超过此值时隐藏承运商。默认：30（CTT 包裹最大 30 kg）。0 表示无限制。Min weight (kg) 不能大于 Max weight (kg)：设置将不会保存。
Minimum order amount：仅当购物车小计（需要配送的商品、扣除折扣后、税前）达到此金额时才显示承运商。留空则始终显示。
免运费
Free shipping：开启后，达到下方金额即可享受 CTT 免费配送。
Free shipping from：购物车小计（扣除折扣后、税前）达到此金额时，承运商费用为 0。仅适用于有价格的目的地。仅在 Free shipping 开启时使用。
无配送区域时的可用性
通常，承运商会在其在 Shipping > Carriers 中关联的配送区域内提供。
Ignore shipping zones：在下方国家中提供承运商，但不将其关联到区域。开启后，两个承运商都会关联到所有已启用的区域（包括您之后创建的区域）。关闭后，它们会恢复为之前的区域。
Countries：此模式下的目的地国家。默认：Portugal。留空则允许所有国家。仅在 Ignore shipping zones 开启时使用。承运商之前所关联区域中的顾客始终可以使用服务。
高级
Debug log：将价格计算和 CTT API 调用记录到模块文件夹中的 logs/vfd_ctt_debug.log.php。该文件无法通过网页访问。即使此选项关闭，CTT API 错误也始终会被记录。密钥、令牌和顾客地址绝不记录。
Log：显示日志的大小和最新条目。点击 Clear log 可清空。
Remove data on uninstall：开启时，卸载模块会删除模块设置和承运商。关闭时，卸载仅会关闭承运商。订单（包括所选的 CTT 网点）绝不会被更改。
结账时的工作方式
在配送步骤，PrestaShop 会向模块询问每个 CTT 承运商的价格。只有实物商品计入：虚拟商品不增加重量，也不计入订单金额。模块首先检查 Ignore shipping zones 及其国家、购物车重量和最低订单金额。开启 Live rates 且地址完整时，模块会向 CTT 发送收货地址，以及每个购物车行的数量、以克为单位的重量和以 cm 为单位的尺寸，并使用返回的价格。否则，或当 CTT 未返回价格时（API 错误、超时、无覆盖范围、功能未对您的 App ID 启用），价格来自价格表。如果适用免运费，价格为 0。价格以店铺默认货币计算，然后以顾客的购物车货币显示。
CTT 价格缓存 1 小时，因此同一购物车不会触发新的请求。失败的请求会记住 5 分钟，因此结账页面在每次刷新时都不必等待 CTT。API 超时时间为 12 秒。API 错误永远不会传递给顾客：使用价格表，或者如果目的地没有价格，则隐藏该承运商。
如果在 Shipping > Carriers 中编辑已有订单的承运商，PrestaShop 会将其保存为新版本的承运商。模块会自动跟随新版本。
填写 API 密钥后，模块会将配送地址、商品重量和尺寸以及店铺 URL 发送给 CTT，以获取价格或最近的 CTT 网点。
模块不创建运单、不打印面单、不预约取件、不提供物流单号，也不显示 CTT 网点地图。两个承运商共用一个价格表和一组 API 设置。
取件点
当顾客选择 CTT 网点承运商时，其下方会出现搜索框和列表。配送地址的邮政编码会自动填入并搜索。顾客可以按邮政编码或城市搜索其他 CTT 网点（按钮 Search 或 Enter 键），并从列表中选择一个。选择会立即保存到购物车中。只接受该次搜索的 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 网点列表缓存 6 小时。若无法连接 CTT，顾客会看到 CTT points cannot be loaded right now. Please try again in a few minutes or choose another shipping method.
网点选择适用于 Classic 和 Hummingbird 主题。只有在公钥、私钥、App ID 和 Carrier ID 都已填写时才会启用。
所选网点会保存到订单中。它会显示在后台订单页面的 CTT point 区块（名称和 ID）中，显示在订单确认页、顾客账户中的订单详情中，以及订单确认邮件中，位于承运商名称旁边的 CTT point: 处。Mail alerts 模块的新订单邮件也会显示网点 ID。
在后台订单页面，在 Change CTT point 下输入邮政编码或城市，点击 Search，选择一个网点，然后点击 Save。页面会显示 CTT point updated.，并添加一条私密订单留言 CTT point changed to: 及新网点。更改网点需要编辑订单的权限。
许可证密钥
模块需要使用来自 vibefox.net 的 VibeFox 许可证密钥。许可证区块 License — VibeFox CTT 是 Modules > Module Manager > VibeFox CTT > Configure 页面中位于设置上方的第一个区块。请将密钥粘贴到 License key 中，然后点击 Activate。之后，该区块会以掩码形式显示密钥、状态（例如许可证有效期截止日期和您的域名），以及以下按钮：Check now（再次检查状态）、Change key（输入其他密钥）和 Remove key（从此店铺中移除密钥）。其下方是 Product: presta-shipping-ctt 一行和 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 账户中释放该名额。
没有有效密钥时，结账时不会向顾客显示任何一个 CTT 承运商（送货至地址或送至 CTT 网点），也不会计算运费。PrestaShop 前台无法得知您已登录后台，因此承运商对您也会被隐藏：您可以在购买密钥之前设置模块，但无法在结账时测试。Modules > Module Manager 的 Alerts 选项卡中会显示提醒。现有订单不受影响。
许可证到期后，模块仍会继续运行，但更新和支持需要续期。您在后台工作时会自动重新检查状态：输入密钥后的前 14 天每天一次，之后每周一次。无需 cron 任务。卸载或重置模块时，总会删除许可证密钥和许可证状态。
故障排除
结账时没有显示 CTT：请检查许可证是否有效，以及 Enable/Disable（或 Enable CTT point carrier）是否已开启。在 Shipping > Carriers 中，检查承运商是否覆盖顾客所在国家的区域和顾客的客户组，或者 Ignore shipping zones 是否已开启且该国家被允许。检查目的地在价格表中是否有对应行（或 * Default 行），购物车重量是否在 Min weight 和 Max weight 之间，以及是否达到 Minimum order amount。商品也可能在商品页面中被限制为特定承运商。
顾客无法选择 CTT 网点：选择器只会出现在 CTT 网点承运商下方，并且仅在公钥、私钥、App ID 和 Carrier ID 都已填写时出现。请检查设置上方的警告，开启 Debug log，并查看模块页面上的 Log 字段。
实时费率没有显示：在顾客输入街道、邮政编码和城市之前，使用价格表。请检查设置上方的警告和日志。回复 "405" 表示该功能未对您的 App ID 启用：请咨询 CTT。在非欧元店铺中，请填写 Exchange rate。
连接 CTT API 失败：设置上方的警告会显示错误。请检查密钥和 App ID。模块会在几分钟后自动重试。
含税或不含税的价格：当 Tax status 设置为 Taxable 规则时，PrestaShop 会在价格之上加上运费税。选择 None 时，价格为最终价格。
更改后价格看起来过时：点击模块页面上的 Save。这会清除缓存的 CTT 响应。
页面提示找不到 CTT 承运商：该承运商已在 Shipping > Carriers 中被删除。请在 Modules > Module Manager 中重置模块以重新创建。重置会保留设置以及两个承运商的开启/关闭状态。
面向开发者：CTT API 地址可通过配置键 vfd_ctt_API_URL 更改。
卸载
进入 Modules > Module Manager，打开 VibeFox CTT 旁边的菜单，选择 Uninstall。许可证密钥、许可证状态、缓存的 CTT 响应和 API 令牌始终会被删除。如果 Remove data on uninstall 已开启，两个承运商都会被删除（订单保留其历史记录），并且设置、日志以及从未成为订单的购物车中的 CTT 网点都会被删除。如果已关闭，承运商仅会被关闭，所有设置都会保留。重新安装模块会让每个承运商恢复其之前的开启/关闭状态。订单中保存的 CTT 网点始终会保留。
CTT 是其各自所有者的商标。本模块与 CTT 没有关联，也未获得 CTT 的认可。