VibeFox Correos CityPaq for PrestaShop — 帮助

系统要求

PrestaShop：8.0 至 9.x。

PHP：8.0 或更高版本。模块会拒绝在更旧的 PHP 版本上安装。

西班牙境内配送：CityPaq 取件柜仅在西班牙境内提供，因此该承运商仅会针对西班牙境内的收货地址显示。

Correos API 凭据（仅用于实时取件柜列表）：Correos CityPaq 列表从 Correos "terminals" API 读取有效取件柜。在 Correos 开发者门户中打开 "terminals" API，并为您的应用点击 Request access。Correos 会批准其企业客户的申请，并发送 client ID 和 client secret。它们也会显示在门户的 My applications 下。如果顾客自行输入取件柜或从您自己的列表中选择，则无需 API 凭据。

VibeFox 许可证密钥：在 vibefox.net 购买。一个密钥对应一个域名。

安装

1. 在后台进入 Modules > Module Manager，点击 Upload a module。选择模块的 ZIP 文件。

2. 上传完成后，点击 Configure；或者之后在模块列表中找到 VibeFox Correos CityPaq 并点击 Configure。

3. 在 Configure 页面顶部的许可证区块中，将您的 VibeFox 许可证密钥输入 License key，然后点击 Activate（参见许可证密钥）。

4. 填写价格表，选择顾客如何选择取件柜（见配置），然后点击 Save。

安装时，模块会创建 Correos CityPaq 承运商，配送时间文本为 Delivery to a Correos CityPaq parcel locker。该承运商会分配给所有客户群组和西班牙区域。您可以在 Shipping > Carriers 中更改区域、客户群组、配送时间、徽标和尺寸限制。请勿在那里设置价格：价格始终来自模块。

配置

所有设置都位于模块页面：Modules > Module Manager > VibeFox Correos CityPaq > Configure。每个部分都有自己的 Save 按钮，它会保存整个页面。价格和金额接受小数点或小数逗号。

设置上方的警告会告诉您：未找到承运商；价格表中没有西班牙的行，也没有默认行；所选的取件柜选择方式无法工作（您的列表中没有取件柜，没有 API 凭据）；Correos API 的最后一个错误是什么；以及模块无法识别您的商店重量单位（此时商品重量按 kg 读取；请在 International > Localization 中设置 kg、g、lb 或 oz）。如果名称为空、无效或超过 64 个字符；如果重量或金额不是 0 或更大的有效数字；或者 Min weight (kg) 大于 Max weight (kg)，页面会显示错误，并且不会保存任何内容。价格表中的无效价格，以及 My lockers 中无效或重复的行，会以警告形式提示，其余内容照常保存。

常规

CityPaq 取件柜仅在西班牙提供，因此该承运商绝不会针对其他国家显示。

Enable/Disable:开启或关闭 Correos CityPaq 配送。这与 Shipping > Carriers 中的承运商状态是同一个开关。

Name:结账时顾客看到的配送方式名称。它也是承运商名称。默认：Correos CityPaq。必填，最多 64 个字符。

Tax:承运商的税务规则。PrestaShop 会在价格表的价格之上加收此税。No tax 表示价格为最终价格。

价格（部分标题显示您的商店默认货币）

Correos 没有为 CityPaq 发布运费 API，因此价格来自此表。请以商店默认货币、不含税填写您与 Correos 合同中的价格。

Price table:一行用于 Spain (ES)，和/或一行默认行 * Default。每行都有基础 Price，以及包裹尺寸 XS（1 kg 以内）、S（2 kg 以内）、M（3 kg 以内）、L（5 kg 以内）和 XL（5 kg 以上）的可选价格。尺寸价格为 0 或留空时，使用基础价格。点击 + Add row 添加一行，点击垃圾桶图标删除一行。没有匹配的行时，承运商会被隐藏。如果某个国家出现两次，则只使用第一行。

Calculation type:如何确定包裹尺寸。

商品重量会根据您商店的重量单位（例如 kg、g、lb 或 oz）换算为 kg。

条件

Min weight (kg):购物车低于此重量时隐藏承运商。0 表示无限制。

Max weight (kg):购物车高于此重量时隐藏承运商。默认：30，因为 CityPaq 接受最大 30 kg 的包裹。0 表示无限制。

Minimum order amount:仅当购物车小计（需要配送的商品，折扣之后，税前）达到此金额时才显示承运商。留空则始终显示。

免运费

Free shipping:开启后，从下方所示金额起提供免费的 CityPaq 配送。

Free shipping from:购物车小计（折扣之后，税前）达到该金额时，此承运商免费。仅在 Free shipping 开启时使用。

CityPaq 取件柜选择

本部分包含指向 Correos CityPaq 官方查询页面的链接。

Locker selection:顾客在下单前如何选择取件柜。默认：顾客输入取件柜。

如果您在没有 API 凭据的情况下选择 Correos 列表，或者在 My lockers 为空时选择您自己的列表，顾客会被要求输入取件柜。

My lockers:当 Locker selection 设为您的列表时使用。每行一个取件柜：CODE | Name | Address | Postal code | City。代码和名称为必填项。如果某个代码列出两次，则只使用第一行。

Correos CityPaq 列表（API）（仅与 Correos CityPaq 列表一起使用）

本部分包含指向 Correos 开发者门户上 "terminals" API 页面的链接。仅读取取件柜列表。价格始终来自价格表。

API client ID:您在 Correos 开发者门户上的应用的 client_id。

API client secret:您在 Correos 开发者门户上的应用的 client_secret。

保存后，这两个字段保持为空，并显示 Saved - leave empty to keep it。只有在需要更改时才输入新值。勾选 Remove the saved client ID and client secret 并点击 Save 即可将其删除。未保存任何内容时，本部分显示 No credentials saved。更改凭据或取件柜选择时，缓存的取件柜列表会被清除。

无配送区域时的可用性

Ignore shipping zones:即使地址所在区域未关联该承运商，也为所有西班牙地址提供 CityPaq。开启后，承运商会关联到所有有效区域，包括之后创建的区域。再次关闭时，承运商会恢复其之前拥有的区域。关闭（推荐）表示使用 Shipping > Carriers 中设置的区域。

高级

Debug log:将调试信息写入模块文件夹中的 logs/vfd_cpq_debug.log.php。该文件无法通过网页打开。即使此项关闭，Correos API 错误也始终会写入。凭据和个人数据绝不会写入日志。

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

Remove data on uninstall:开启后，卸载模块会删除设置、承运商、缓存的列表和日志。保存在订单中的取件柜会保留。关闭时，所有内容都会保留，以便重新安装。

结账时的工作方式

在配送步骤中，PrestaShop 会向模块请求 CityPaq 价格。只有实体商品才计入：虚拟商品不增加重量，也不计入订单金额。模块会检查收货地址是否位于西班牙、购物车重量和最低订单金额，找到西班牙的价格行（或 * 行）以及包裹尺寸，然后返回价格。如果适用免运费，价格为 0。价格以您商店的默认货币计算，然后以顾客购物车的货币显示。税费由承运商的税务规则添加。

当顾客选择 CityPaq 时，承运商下方会出现 CityPaq locker 框。顾客一做出选择，该选择就会保存到购物车中。不可接受的取件柜会被拒绝并显示提示，之前的选择保持不变。使用 Correos 列表时，只有当 Correos 为所搜索的邮政编码提供了该取件柜代码，才会接受该代码，其名称和地址取自 Correos。每个购物车最多可搜索 30 个不同的邮政编码。超过此数量后，顾客会看到 Too many searches. Please enter the CityPaq locker you found on the Correos map. 提示。

配送步骤中的 Continue 按钮在没有有效取件柜时无法继续。服务器端也会进行检查。顾客会看到例如 Please choose the CityPaq locker where you want to collect your parcel. 下单时，购物车中的取件柜会保存到订单中。

只有当顾客选择 CityPaq 时才会请求 Correos 列表，而不是为配送步骤的每位访客都请求。列表按邮政编码缓存 12 小时。失败的请求会缓存 10 分钟，因此结账不会在每次刷新时都等待 Correos。API 超时时间为 12 秒。顾客永远看不到技术错误，只会看到简短提示和手动输入框。取件柜框适用于 Classic 和 Hummingbird 主题。

模块不会从 Correos 获取实时运费、不显示地图、不预先登记运单、不打印面单、不预约取件，也不跟踪包裹。请使用订单中保存的取件柜，在您的 Correos 账户中创建运单。

取件点

所选取件柜会保存在订单中。顾客会在订单确认页面以及其客户账户中的订单详情页面上看到 CityPaq locker:。在订单确认电子邮件以及 Mail alerts 模块的新订单电子邮件中，取件柜会添加到承运商行中，例如 Correos CityPaq - CityPaq locker: ...。

在后台订单页面，CityPaq locker 区块会显示取件柜；如果是从列表中选择的，还会显示 Locker code:。如需更改，请使用 Change CityPaq locker 字段并点击 Save：使用您的列表时，从下拉列表中选择另一个取件柜；使用 Correos 列表时，输入取件柜代码（将在 Correos 中查询）或地址；其他情况下，输入新的代码或地址。将字段留空即可保留当前取件柜。每次更改都会为订单添加一条私密订单消息：CityPaq 取件柜已更改为：...。更改取件柜需要编辑订单的权限，不需要访问 Modules 页面。

许可证密钥

本模块使用来自 vibefox.net 的 VibeFox 许可证密钥。许可证区块 License — VibeFox Correos CityPaq 是 Modules > Module Manager > VibeFox Correos CityPaq > Configure 页面中位于设置上方的第一个区块。将密钥输入 License key 并点击 Activate。之后，该区块会显示隐藏部分字符的密钥、状态（例如许可证有效期截止日期和您的域名），以及以下按钮：Check now（重新检查状态）、Change key（输入其他密钥）和 Remove key（从此商店中移除密钥）。其下方是一行 Product: presta-shipping-correos-citypaq 以及链接 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 账户中释放名额。

没有有效的密钥时，结账时不会向顾客显示 Correos CityPaq 承运商，也不会计算运费。PrestaShop 前台无法得知您已登录后台，因此该承运商对您也是隐藏的：您可以在购买密钥之前设置模块，但无法在结账时测试。Modules > Module Manager 的 Alerts 选项卡中会出现提醒。现有订单不受影响。

许可证到期后，模块仍会继续工作，但更新和支持需要续费。在您使用后台期间会自动重新检查状态：输入密钥后的前 14 天每天一次，之后每周一次。无需 cron 任务。卸载或重置模块时，始终会删除许可证密钥和许可证状态。

故障排除

Correos CityPaq 未出现在结账页面：请检查许可证是否有效、Enable/Disable 是否开启，以及收货地址是否位于西班牙。在 Shipping > Carriers 中，检查承运商是否覆盖西班牙区域和顾客所属的群组（或开启 Ignore shipping zones）。检查价格表中是否有西班牙的行或 * 行，以及购物车是否在重量限制和 Minimum order amount 范围内。此外，商品页面上的设置也可能将商品限制为某些承运商。

即使选择了 Correos 列表，顾客仍需手动输入取件柜：请检查 API client ID 和 API client secret 是否已保存，并查看设置上方的警告。警告会显示最后一次 Correos API 错误。HTTP 401/403 表示 Correos 拒绝了凭据：请检查凭据，并确认您的应用有权访问 "terminals" API。出现错误后，下一次尝试会在 10 分钟后进行。

某个邮政编码没有取件柜：Correos 未找到该邮政编码、其所在地区或省份中的有效取件柜。顾客可以搜索另一个邮政编码，或输入在 Correos CityPaq 查询页面上找到的取件柜。

我的取件柜下拉列表没有出现：My lockers 为空或其行无效。每行至少需要 CODE | Name。

顾客在哪里找到取件柜代码：在取件柜字段下方链接的 Correos CityPaq 查询页面上。

页面提示未找到承运商，或无法更新承运商：承运商已在 Shipping > Carriers 中被删除。请在 Modules > Module Manager 中重置模块以重新创建。重置会保留设置和承运商状态。

开发者说明：购物车和订单的取件柜存储在表 vfd_cpq_locker 中（带有您的数据库前缀）。模块使用 Correos "terminals" 的正式 API。

卸载

进入 Modules > Module Manager，打开 VibeFox Correos CityPaq 旁边的菜单，然后选择 Uninstall。许可证密钥、许可证状态、缓存的 Correos 取件柜列表和最后一次 API 错误始终会被删除。如果 Remove data on uninstall 开启，承运商会被删除（订单保留其历史记录），并删除设置、日志以及没有订单的购物车中的取件柜。如果关闭，承运商仅会被停用，所有设置都会保留。重新安装模块会恢复承运商之前的状态。保存在订单中的取件柜绝不会被删除。

Correos 和 CityPaq 是其各自所有者的商标。本模块与 Correos 无关联，也未获得 Correos 的认可。