VibeFox Correos CityPaq for OpenCart — 帮助

系统要求

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

PHP：8.0 或更高版本。

配送至西班牙：CityPaq 包裹柜仅存在于西班牙，因此该方式仅提供给西班牙境内的配送地址。

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

VibeFox 许可证密钥：在 vibefox.net 购买。一个密钥只能用于一个域名。

安装

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

OpenCart 3

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

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

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

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

5. 填写价格表，选择顾客选择包裹柜的方式（参见配置），开启 Enable/Disable，然后点击 Save。

OpenCart 4

1. 在管理后台进入 Extensions > Installer，点击 Upload，然后选择文件 vfd_correos_citypaq.ocmod.zip。请勿重命名该文件：OpenCart 4 从文件名中读取扩展代码，重命名后的安装包无法使用。

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

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

4. 按照 OpenCart 3 的第 4 步和第 5 步输入许可证密钥和设置。两个版本的设置页面及其字段相同。

安装后，在您开启 Enable/Disable 并保存之前，该配送方式处于关闭状态。如果卸载后重新安装扩展，之前保留的设置将再次生效。

配置

所有设置都在扩展页面中：Extensions > Extensions > Shipping > VibeFox Correos CityPaq > Edit。各分区列在左侧。页面底部的一个 Save 按钮可在不重新加载页面的情况下保存整个页面。运费和金额可以使用小数逗号或小数点。只有拥有本扩展修改权限的管理员用户才能保存设置。

页面顶部会在以下情况显示警告：价格表中没有西班牙的行也没有默认行；所选包裹柜选择方式无法工作（您的列表中没有包裹柜，没有 API 凭据）；显示最近一次 Correos API 错误；店铺没有单位为 kg 的重量类别（此时商品重量将按单位名称换算：kg、g、lb 或 oz；无法识别的单位按 kg 计算）。请检查 System > Localisation > Weight Classes。如果名称为空、无效或超过 64 个字符，如果重量或金额不是 0 或更大的有效数字，如果 Min weight (kg) 大于 Max weight (kg)，或者 Sort order 不是整数，页面会显示错误，且不会保存任何内容。价格表中的无效价格、重复行以及 My lockers 中无效或重复的行会作为警告提示，其余内容照常保存。

常规

CityPaq 包裹柜仅存在于西班牙，因此该方式绝不会提供给其他国家。

Enable/Disable：开启或关闭 Correos CityPaq 配送。默认：关闭。

Name：顾客在结账时看到的配送方式名称。默认：Correos CityPaq。必填，最多 64 个字符，不得包含 < > ; = # { }。

Tax class：OpenCart 会在价格表的价格之上加上该类别的税。No tax 表示价格即为最终价格。

Sort order：该方式在配送方式列表中的位置。整数。

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

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：如何确定包裹尺寸。

Per order (size by the total cart weight)：整个购物车一个价格，根据总重量选择。这是默认值。

Per item (size by each item weight, multiplied by quantity)：每件商品按其自身尺寸获得价格，再乘以数量，最后相加。

商品重量根据每件商品所属的重量类别换算为 kg。

条件

Min weight (kg)：购物车低于此重量时隐藏该方式。0 表示不限制。

Max weight (kg)：购物车超过此重量时隐藏该方式。默认：30，因为 CityPaq 接受最重 30 kg 的包裹。0 表示不限制。

Minimum order amount：仅当需要配送的商品小计（扣除优惠券后，税前）达到此金额时才显示该方式。留空则始终显示。

免运费

Free shipping：开启后，达到下方金额即免除 CityPaq 运费。

Free shipping from：需要配送的商品小计（扣除优惠券后，税前）达到此金额时，该方式运费为 0。仅在 Free shipping 开启时使用。

CityPaq 包裹柜选择

本分区包含一个指向 Correos 官方 CityPaq 查找器的链接。

Locker selection：顾客在下单前如何选择包裹柜。默认：顾客输入包裹柜。

Customer chooses from the Correos CityPaq list (Correos API, credentials below)：顾客可看到配送地址邮政编码下的有效 CityPaq 包裹柜，也可搜索其他 5 位邮政编码。若某邮政编码没有包裹柜，则依次列出同一地区、同一省份的包裹柜，并优先显示最近的邮政编码（最多 50 个）。若列表无法加载或找不到任何结果，顾客需手动输入包裹柜。

Customer enters the locker (code or address from the Correos finder)：必填字段，用于输入包裹柜代码（例如 S0000213D）或地址，长度为 3 至 120 个字符，并附有 Correos CityPaq 地图链接。

Customer chooses from my list of lockers (below)：必填的下拉列表，列出 My lockers 中的包裹柜。靠近顾客邮政编码的包裹柜会优先显示。

Do not ask for a locker：结账时不询问包裹柜。

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

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. 更改凭据或包裹柜选择方式时，缓存的包裹柜列表和最近一次 API 错误会被清除。

可用性

Geo zone：仅向此地理区域内的地址提供该方式。All zones（默认）表示所有西班牙地址。地理区域在 System > Localisation > Geo Zones 中管理。

Ignore geo zone：即使地址不在上方的地理区域内，也为所有西班牙地址提供 CityPaq。

高级

Debug log：将调试信息写入 storage/logs/vfd_cpq_debug.log.php（OpenCart 4 中为 system/storage/logs/vfd_cpq_debug.log.php）。该文件无法通过网页读取。即使此选项关闭，Correos API 错误也始终会被写入。凭据和个人数据永远不会被记录。

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

Remove data on uninstall：开启后，卸载扩展会删除设置、缓存的列表和日志。订单中保存的包裹柜会保留。关闭时（默认），所有数据都会保留，以便重新安装。

导入 / 导出

Export：点击 Download JSON 可将设置保存为 JSON 文件。API client ID 和 secret 不会包含在内。

Import：粘贴从本扩展导出的设置 JSON，然后点击 Import。这些值将像正常保存一样进行检查。已保存的凭据会保留。

结账时的工作方式

当 OpenCart 显示配送方式时，会向扩展请求 CityPaq 运费。如果设置了 Geo zone（且 Ignore geo zone 未开启），而地址位于该区域之外，则不提供 CityPaq。只有 Requires Shipping 设为 Yes 的商品才会计入：其他商品不增加重量，也不计入订单金额。扩展随后检查配送地址是否在西班牙、购物车重量和最低订单金额，查找西班牙的价格行（或 * 行）和包裹尺寸，并返回运费。若适用免运费，运费为 0。运费按店铺默认货币计算，按该货币的小数位数取整，并以顾客的货币显示，同时加上所选 Tax class 的税额。运费计算不会向 Correos 发出任何请求。

CityPaq locker 框会在配送方式步骤中出现在 CityPaq 方式下方。顾客一做出选择就会立即保存。不可接受的包裹柜会被拒绝并显示消息，之前的选择保持不变。使用 Correos 列表时，只有当 Correos 对所搜索的邮政编码提供了某个包裹柜代码，才会接受该代码，其名称和地址均取自 Correos。每次结账会话中，顾客最多可以搜索 30 个不同的邮政编码。之后，顾客将看到 Too many searches. Please enter the CityPaq locker you found on the Correos map.

配送方式步骤中的 Continue 按钮在没有有效包裹柜的情况下无法继续使用 CityPaq。这一点由服务器端检查。顾客会看到例如 Please choose the CityPaq locker where you want to collect your parcel. 下单时，包裹柜会保存到订单中。

在 OpenCart 4 中，顾客在结账页面的配送方式区块中点击 Choose，并在 Shipping method options 窗口中选择 CityPaq。CityPaq locker 框会出现在该窗口的 CityPaq 选项下方，其工作方式如上所述。该窗口的 Continue 按钮在没有有效包裹柜的情况下无法继续使用 CityPaq。OpenCart 4 会为结账保留一个订单，并在顾客每次重新确认时更新它，订单中的包裹柜也会随之更新。

只有在选择了 CityPaq 作为配送方式时才会请求 Correos 列表，而不是在绘制该步骤时请求。每个邮政编码的列表会缓存 12 小时。失败的请求会缓存 10 分钟，以免结账在每次刷新时都要等待 Correos。顾客永远看不到技术错误，只会看到 The Correos CityPaq list cannot be loaded right now. 消息和手动输入框。

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

取件点

所选包裹柜会添加到订单的配送方式中，例如 Correos CityPaq - CityPaq locker: ...。因此顾客可以在其账户的订单历史和订单电子邮件中看到它，并且它会打印在发票上，也会显示在 Sales > Orders 中。OpenCart 的订单成功页面不会显示配送方式。

在管理后台的订单页面上，历史记录上方的 CityPaq locker 面板会显示包裹柜，若是从列表中选择的，还会显示 Locker code:。要更改，请使用 Change CityPaq locker 字段并点击 Save：使用您的列表时，从下拉列表中选择另一个包裹柜；使用 Correos 列表时，输入包裹柜代码（会在 Correos 查询）或地址；其他情况下，输入新的代码或地址。将字段留空，或保持 -- Keep the current locker --，即可保留当前包裹柜。每次更改还会更新订单的配送方式文本，并在历史记录中添加 CityPaq locker changed to: ... 条目，但不会通知顾客。更改包裹柜需要订单的修改权限（sale/order）。无需访问扩展设置。即使扩展已禁用，CityPaq 订单仍会显示该面板。

许可证密钥

本扩展需要一个来自 vibefox.net 的 VibeFox 许可证密钥。许可证区块 License — VibeFox Correos CityPaq 是 Extensions > Extensions > Shipping > VibeFox Correos CityPaq > Edit 页面中设置上方的第一个区块。将密钥粘贴到 License key 中，然后点击 Activate。之后，该区块会显示部分隐藏的密钥、状态（例如许可证有效期截止日期和您的域名），以及以下按钮：Check now（重新检查状态）、Change key（输入另一个密钥）和 Remove key（从本店铺中移除该密钥）。其下方是 Product: opencart-shipping-correos-citypaq 一行和 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 及日期。店铺地址更改后，或在您的账户中释放了一个域名名额后，请点击 Check now。如果无法连接许可证服务器，扩展会继续以最后已知的状态运行。

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

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

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

故障排除

Correos CityPaq 未出现在结账页面：请检查许可证是否有效、Enable/Disable 是否已开启，以及配送地址是否在西班牙。检查 Geo zone（或开启 Ignore geo zone）。检查价格表是否有西班牙的行或 * 行，购物车是否在重量限制和 Minimum order amount 之内，以及商品的 Requires Shipping 是否设为 Yes。

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

某邮政编码没有包裹柜：Correos 没有为该邮政编码、其地区或其省份找到有效的包裹柜。顾客可以搜索其他邮政编码，或输入在 Correos CityPaq 地图上找到的包裹柜。

my lockers 下拉列表不显示：My lockers 为空或其行无效。每行至少需要 CODE | Name。

顾客在哪里找到包裹柜代码：在包裹柜字段下方链接的 Correos CityPaq 地图上。

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

面向开发者：结账会话和订单的包裹柜存储在 vfd_cpq_locker 表中（使用您的数据库前缀）。Correos API 地址可通过设置 vfd_cpq_api_url（用于测试）替换；设置页面上没有对应字段。

卸载

进入 Extensions > Extensions，选择 Shipping 类型，然后点击 VibeFox Correos CityPaq 旁边的 Uninstall（红色 − 按钮）。本扩展的许可证密钥和许可证状态总会被删除。OpenCart 总会重置 Enable/Disable、Sort order、Tax class 和 Geo zone。缓存的 Correos 包裹柜列表和最近一次 API 错误总会被删除。如果 Remove data on uninstall 已开启，则设置、日志以及没有订单的结账会话中的包裹柜也会被删除。如果关闭，其他设置会保留，并在您重新安装扩展时再次使用。订单中保存的包裹柜永远不会被删除，现有订单保留其配送方式和运费。

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

Correos 和 CityPaq 是其各自所有者的商标。本扩展与 Correos 无关联，也未获得 Correos 的认可或背书。