VibeFox Correos CityPaq for WooCommerce — 帮助

系统要求

WordPress：5.8 或更高版本。

WooCommerce：7.0 或更高版本，已安装并启用。未安装 WooCommerce 时插件无法激活。

PHP：8.0 或更高版本。

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

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

安装

1. 在 WordPress 中进入 Plugins > Add New > Upload Plugin，选择插件的 ZIP 文件，然后点击 Install Now。您也可以通过 FTP 将 vfd_correos_citypaq 文件夹上传到 /wp-content/plugins/。

2. 点击 Activate。

3. 打开设置：WooCommerce > Settings > Shipping > VibeFox Correos CityPaq，或在插件页面上点击插件名称下的 Settings。

4. 在页面顶部的许可证区块中输入您的 VibeFox 许可证密钥，然后点击 Activate。

5. 填写价格表，并选择顾客如何选择取件柜（参见“配置”）。

6. 在 WooCommerce > Settings > Shipping > Shipping zones 中，将 VibeFox Correos CityPaq 添加到西班牙的配送区域，或开启 Ignore shipping zones。

配置

所有设置都在同一页面：WooCommerce > Settings > Shipping > VibeFox Correos CityPaq。这些设置适用于所有配送区域。将该方式添加到某个区域时，区域窗口中只有一个字段：

Title (zone)：该区域结账时此选项的名称。留空则使用全局的 Name。

设置上方的警告会提示：价格表中没有可用的行、所选取件柜方式无法工作（列表中没有取件柜、没有 API 凭据），以及 Correos API 最近一次的错误。价格和金额接受小数点或小数逗号。

常规

CityPaq 取件柜仅存在于西班牙，因此该方式永远不会提供给其他国家。

Enable/Disable：一次性在所有区域中启用或禁用该方式。

Name：顾客在结账时看到的配送方式名称。默认：Correos CityPaq。

Tax status：Taxable 会在价格表价格的基础上加收 WooCommerce 税费，None 则不加收。

价格（标题会显示您的商店货币）

Price table：一行对应 Spain (ES)，和/或一行默认 *。每行包含基础 Price，以及 XS（1 kg 以内）、S（2 kg 以内）、M（3 kg 以内）、L（5 kg 以内）和 XL（5 kg 以上）包裹尺寸的可选价格。尺寸价格为 0 或留空时使用基础价格。点击 + Add row 添加一行，点击叉号删除一行。请以商店货币输入您与 Correos 合同中的价格。没有匹配行时，该方式会被隐藏。无效价格和重复行会在保存时提示。

Calculation type：包裹尺寸的确定方式。

Per order (size by the total cart weight)：整个购物车使用一个价格，按总重量选择。这是默认设置。

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

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

条件

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

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

Minimum order amount：仅当购物车小计（扣除折扣后，税前）达到此金额时才显示该方式。留空则始终显示。

Excluded shipping classes：购物车中包含以下 WooCommerce 配送类别中的商品时隐藏该方式，例如无法放入取件柜的大件商品。插件不检查包裹尺寸。

免运费

Free shipping：开启后，在下方金额起免除 CityPaq 运费。

Free shipping from：购物车小计（扣除折扣后，税前）达到此金额后，该方式运费为 0。仅在 Free shipping 开启时使用。

CityPaq 取件柜选择

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

Customer chooses from the Correos CityPaq list (Correos API, credentials below)：顾客可看到收货地址邮政编码内活跃的 CityPaq 取件柜，并可搜索另一个 5 位邮政编码。当某邮政编码没有取件柜时，先列出同一地区的取件柜，再列出同一省份的取件柜，离得最近的邮政编码优先。每个取件柜显示名称、地址、邮政编码、城镇和营业时间。若列表无法加载或找不到任何结果，顾客需改为手动输入取件柜。

Customer enters the locker (code or address from the Correos finder)：取件柜代码（例如 S0000213D）或地址为必填字段，并附有官方 Correos CityPaq 查询页面的链接。

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

Do not ask for a locker：结账时不询问取件柜。

如果您在没有 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。

更改凭据或取件柜选择时，已缓存的取件柜列表会被清除。

无配送区域时的可用性

Ignore shipping zones：即使没有任何配送区域包含该方式，也为每个西班牙地址提供 CityPaq。关闭（推荐）时，仅在您将该方式添加到配送区域的地方提供。

高级

Debug log：将调试信息写入 WooCommerce > Status > Logs，来源为 vfd-correos-citypaq。即使此选项关闭，Correos API 错误也始终会被记录。凭据和个人数据从不记录。

Remove data on uninstall：开启后，删除插件会移除其设置和区域方式。停用插件从不删除任何内容。订单中保存的取件柜会保留。

结账时的工作方式

当顾客在西班牙输入配送地址时，WooCommerce 会向插件请求运费。插件检查购物车重量、最低订单金额和排除的配送类别，找到西班牙（或 * 行）的价格行和包裹尺寸，并显示价格。如适用免运费，则价格为 0。

顾客选择 CityPaq 后，取件柜字段会出现在该方式下方。没有有效取件柜就无法下单。服务器端也会检查这一点，通过配送和结账区块下的订单同样适用。使用 Correos 列表时，只有 Correos 向该顾客提供过的取件柜代码才会被接受，其名称和地址取自 Correos。每个顾客会话的邮政编码搜索次数有限。达到上限后，顾客需改为手动输入取件柜。

Correos 列表按邮政编码缓存 12 小时。失败的请求缓存 10 分钟，这样结账页面在每次刷新时都不必等待 Correos。API 超时时间为 12 秒。顾客永远看不到技术错误，只会看到一条简短提示和手动输入字段。

该方式适用于经典结账以及配送和结账区块。它兼容 WooCommerce 高性能订单存储（HPOS）。

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

取件点

所选取件柜保存在订单中。它会显示在订单管理页面的收货地址下方、订单接收页面、My account > Orders 中，以及所有订单电子邮件（HTML 和纯文本）中，标签为 CityPaq locker。

在订单管理页面，您可以在 Change CityPaq locker 字段中更改取件柜：从您的列表中选择其他取件柜，或输入新的代码或地址。使用 Correos 列表时，输入的取件柜代码会在 Correos 查询。将字段留空即可保留当前取件柜。每次更改都会添加一条订单备注。

许可证密钥

插件使用来自 vibefox.net 的 VibeFox 许可证密钥运行。许可证区块位于 WooCommerce > Settings > Shipping > VibeFox Correos CityPaq 页面顶部。将密钥粘贴到 License key 中，然后点击 Activate。该区块会显示状态，例如许可证有效期截止日期和您的域名。使用 Check now 重新检查状态，Change key 输入其他密钥，Remove key 从本站点移除密钥。链接 Manage licenses and domains in your account 会打开您的 vibefox.net 账户。

一个密钥只能用于一个域名。从站点移除密钥不会释放域名名额。请在您的 vibefox.net 账户中释放名额。

没有有效密钥时，Correos CityPaq 不会向结账时的顾客显示。已登录的商店管理员仍可看到它，并带有 (unlicensed — visible to admins only) 标记，因此您可以在购买密钥之前设置和测试插件。插件页面和 WooCommerce 页面上会显示提醒。现有订单不受影响。

许可证过期后，插件仍可继续工作，但更新和支持需要续费。状态会在后台自动重新检查。

故障排除

Correos CityPaq 未出现在结账页面：请检查许可证是否有效、Enable/Disable 是否开启、地址是否位于西班牙，以及该方式是否已添加到对应的配送区域（或 Ignore shipping zones 是否开启）。检查价格表是否包含西班牙的行或 * 行，以及购物车是否在重量限制、Minimum order amount 和 Excluded shipping classes 范围内。

尽管已选择 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 查询页面上。

开发者说明：取件柜保存在订单元数据 _vfd_cpq_locker（到处显示的文本）和 _vfd_cpq_locker_id（取件柜代码，当从 Correos 列表或您的列表中选择时）中。插件使用 Correos 正式环境的 "terminals" API。该 API 没有已记录的沙盒环境。

许可证区块显示错误：请按照区块中的提示操作。例如，如果该密钥已在另一个域名上使用，请在您的 vibefox.net 账户中释放名额，然后点击 Check now。如果站点地址已更改，请点击 Check now，为新域名激活密钥。如果无法连接许可证服务器，插件将继续使用最近一次已知的状态运行。

卸载

停用插件会保留所有数据。要删除插件，请先停用，然后在 Plugins 页面删除。本插件的许可证密钥和许可证状态总是会被删除，缓存的 Correos 取件柜列表和最近一次的 API 错误也会被删除。只有开启了 Remove data on uninstall 时，设置和区域方式才会被删除；否则它们会保留，以便日后重新安装。订单中保存的取件柜从不会被删除，现有订单也会保留其配送行。

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