VibeFox Packeta for OpenCart — 帮助

系统要求

OpenCart：3.0.x（已在 3.0.5.0 上测试）或 4.0.2 及更高版本（已在 4.1.0.3 上测试），使用默认主题的默认结账流程。

PHP：8.0 或更高版本。

Packeta API 密钥：您可以在 Packeta 客户区（client.packeta.com）的 Client support 下找到它。它由 16 个字母和数字组成。小部件需要它才能在结账时打开，因此只有输入 API 密钥后，顾客才会看到该配送方式。

国家：捷克、斯洛伐克、匈牙利或罗马尼亚必须是您店铺中已启用的国家。它们包含在 OpenCart 的标准数据中。OpenCart 中匈牙利没有地区，因此地址的地区字段保持为空；这没有关系。

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

安装

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

OpenCart 3

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

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

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

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

5. 输入您的 Packeta API key 和价格：至少添加一行 Country prices（例如 * Default），或设置 Fallback cost。开启 Enable/Disable 并点击 Save。页面会显示 Packeta 是否接受了该密钥。

OpenCart 4

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

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

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

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

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

配置

所有设置都在扩展页面中：Extensions > Extensions > Shipping > VibeFox Packeta > Edit。各个部分列在左侧。底部的一个 Save 按钮会保存整个页面，无需刷新。只有拥有本扩展修改权限的管理员用户才能保存设置。

该方式仅针对 Packeta 自有取件点网络中的国家提供：CZ、SK、HU 和 RO。在设置上方，页面会显示 API 密钥检查结果以及问题警告：没有 API 密钥、没有价格、所选国家不在 Packeta 网络内，或店铺的重量单位是扩展无法识别的单位。每次保存后，警告都会更新。

所有价格和限制均接受逗号或小数点作为小数分隔符（4,99 或 4.99）。无效或负数会被拒绝并显示提示，该字段保留之前的值；其他字段会正常保存。

常规

Enable/Disable：在结账时开启或关闭 Packeta。默认：关闭。

Name：顾客看到的配送方式名称。默认：Packeta pickup point。必填，最多 64 个字符。

API key：来自 client.packeta.com > Client support 的 Packeta API 密钥。您也可以粘贴 32 个字符的 API 密码：仅保存其前 16 个字符，即 API 密钥。API 密钥是公开的：它会发送到顾客的浏览器以打开小部件。保存新密钥时，会通过 Packeta 承运商数据源进行检查，页面会显示 Packeta API key verified，或提示 Packeta 已拒绝该密钥。如果无法完成检查，密钥仍会保存，并在您下次保存时再次检查。

Widget language：取件点小部件的语言。Store / visitor language（默认）跟随页面语言。您也可以将其固定为捷克语、斯洛伐克语、匈牙利语、罗马尼亚语、英语、德语、波兰语或乌克兰语。

Pickup point types：小部件提供哪些 Packeta 网点。

Tax status：应用于运费的 OpenCart 税类，或 None (no tax on shipping)（默认）。

Sort order：Packeta 在结账配送方式中的排列位置。一个整数。

价格

Packeta 没有公开的运费 API。价格来自此表，并以您店铺的默认货币（不含税）输入。使用其他货币付款的顾客会看到换算后的价格。

Calculation type：Per order（默认）只收取一次价格。Per item (price x quantity) 会将价格乘以需要配送的商品数量。

Country prices：按目的国家和包裹重量设定价格。点击 Add country 添加一行，点击 × 按钮删除一行。每行包含一个 Price 以及重量列：XS 为 1 kg 以内，S 为 1–2 kg，M 为 2–3 kg，L 为 3–5 kg，XL 为 5 kg 以上。保持为 0 的重量列会使用 Price 列。没有自身行的国家会使用 * Default 行。新增的行默认为 * Default，所有价格为 0，即免运费。请在保存前选择国家并输入价格，或者删除该行。如果同一国家（或 * Default）出现在两行中，保存时只保留第一行。如果表格中的某个值不是大于或等于 0 的数字，表格将无法保存，页面会列出错误的值。

Fallback cost：当国家价格表中没有目的地对应的行，也没有 * Default 行时使用。将其留空则不在该地区提供此方式。

Free shipping from：购物车小计（使用优惠券后，不含税）达到该金额时，Packeta 配送免费。该条件先于价格表检查：达到此金额后，在提供该方式的每个 Packeta 国家，配送都免费，即使该国家没有国家行或备用费用。将其留空则从不提供免运费。

可用性

Minimum weight (kg)：购物车重量低于该值时隐藏此方式。商品重量由其 OpenCart 重量类别换算而来。留空或为 0 表示无限制。

Maximum weight (kg)：购物车重量高于该值时隐藏此方式。默认：15。Packeta 取件点和 Z-BOX 通常接受最多 15 kg 的包裹；请查看您与 Packeta 的合同。留空或为 0 表示无限制。保存时，高于最大值的最低重量会被拒绝，两个之前的值都会保留。

Minimum cart subtotal：仅当购物车小计（使用优惠券后，不含税）达到该金额时才提供此方式。

Geo zone：仅对此地理区域内的地址提供 Packeta。All zones（默认）表示无限制。当 Ignore shipping zones 开启时不会检查。地理区域在 System > Localisation > Geo Zones 中管理。

Ignore shipping zones：开启时，不检查地理区域，并对下方选定的国家提供此方式。关闭时（默认），仅在上方的地理区域内提供。

Countries (ignore zones mode)：该模式下的目的国家。留空则使用所有 Packeta 国家。不在 Packeta 取件点网络内的国家会被跳过。此字段仅在 Ignore shipping zones 开启时使用。

高级

Debug log：将运费计算和取件点选择记录到 storage/logs/vfd_pckt_debug.log.php。该文件无法通过网页读取。不会记录顾客的个人数据和 API 密钥。错误和失败的 API 密钥检查始终会被记录。完成后请关闭日志。当文件达到 5 MB 时，它会被移动到 vfd_pckt_debug.old.log.php，并开始新的日志。

Log (last lines)：显示调试日志的大小和最新条目。点击 Clear log 可清空日志。

Remove data on uninstall：开启时，卸载扩展会删除设置和日志。关闭时（默认），设置会保留，以便重新安装。订单中保存的取件点始终会保留。

导入 / 导出

导出：点击 Download JSON，将设置保存为 JSON 文件，包括 API 密钥（该密钥是公开的）。

导入：粘贴之前导出的 JSON，然后点击 Import 恢复设置，例如在另一家店铺中使用。这些值会像普通保存一样进行检查。

结账时的工作方式

OpenCart 显示配送方式时，会向扩展请求 Packeta 的价格。如果设置了 Geo zone（并且 Ignore shipping zones 处于关闭状态），且地址不在该区域内，则不会提供 Packeta。只有 Requires Shipping 设为 Yes 的商品才计入：其他商品不会增加重量，也不计入小计。扩展会检查以下条件：配送国家是否在 Packeta 网络内、API 密钥、忽略区域模式下的国家列表、购物车重量以及购物车最低小计。小计是需要配送的商品价格，已扣除优惠券折扣，且不含税。礼品卡、积分奖励和店铺余额不计入。如果适用免运费，价格为 0。否则，价格依次取自国家价格表和备用费用。如果没有价格，该方式将被隐藏。价格会以顾客的货币显示，并包含所选 Tax status 的税费。

在配送方式步骤的 Packeta 选项下方有一个 Choose pickup point 按钮。它会在顾客的浏览器中打开 Packeta 官方小部件，并传入目的国家、购物车重量、所选取件点类型和小部件语言。顾客选择取件点后，其名称和地址会显示在该方式下方，按钮会变为 Change pickup point。取件点会保存在结账会话中，重新加载页面后仍会保留。当收货地址更改为其他国家时，为之前国家选择的取件点将不再使用。

结账时，您的服务器不会向 Packeta 请求任何内容。小部件脚本仅在结账页面从 widget.packeta.com 加载。如果它被阻止（由于广告或隐私拦截器、内容安全策略或 Packeta 服务中断），顾客会看到以下消息："The Packeta pickup point widget could not be loaded. Please reload the page or choose another shipping method."

Packeta 的价格不会实时查询，而是来自您的价格表。本扩展不会创建 Packeta 运单、打印标签或跟踪包裹，并且默认不提供上门配送或合作承运商取件点。请以您惯常的方式将订单中的取件点 ID 提交给 Packeta，例如通过 client.packeta.com 导入。取件点按钮适用于默认主题的标准 OpenCart 结账流程。

在 OpenCart 4 中，顾客在结账页的配送方式区块中点击 Choose，并在 Shipping method options 窗口中选择 Packeta。Choose pickup point 按钮和所选取件点显示在该窗口中 Packeta 选项的下方，Packeta 小部件会在其上方打开。价格与 OpenCart 3 相同。

取件点

取件点为必选项。如果顾客在配送方式步骤中未选择取件点就点击 Continue，该步骤不会完成，顾客会看到提示："Please choose a Packeta pickup point."。如果所选取件点位于收货地址以外的国家，顾客会看到提示："The selected Packeta pickup point is not in your shipping country. Please choose a pickup point again."。扩展不会向 Packeta 验证取件点 ID；它只检查是否已选择取件点以及其国家是否匹配。

订单创建时，取件点会附加到订单上：

订单的配送方式：取件点名称和地址会添加到方式名称中，例如 Packeta pickup point: <point>（最多 128 个字符）。顾客会在订单历史和订单邮件中看到它，并且它会打印在发票上。OpenCart 的订单成功页面不会显示配送方式。

管理后台订单页面：在 Sales > Orders 中打开订单。Packeta pickup point 面板会显示名称和地址、Pickup point ID 以及国家。如果 Packeta 订单没有取件点，面板会显示："No pickup point was selected for this order."

在 OpenCart 4 中，Shipping method options 窗口中的 Continue 按钮在没有取件点时不会继续，并显示相同的消息。OpenCart 4 为结账保留一个订单，并在顾客每次重新确认时更新它，订单的取件点也会随之更新。订单管理页面中的 Packeta pickup point 面板显示在 History 部分上方。

取件点存储在扩展自己的数据表 vfd_pckt_point 中（结账会话、订单、取件点 ID、名称和地址、国家）。

许可证密钥

本扩展需要配合 vibefox.net 提供的 VibeFox 许可证密钥使用。许可证区块 License — VibeFox Packeta 是 Extensions > Extensions > Shipping > VibeFox Packeta > Edit 页面的第一个区块，位于设置上方。将密钥粘贴到 License key 中，然后点击 Activate。之后，该区块会以隐藏方式显示密钥，并显示状态（例如许可证有效期截止日期和您的域名），以及以下按钮：Check now（重新检查状态）、Change key（输入其他密钥）和 Remove key（从此店铺中移除密钥）。其下方是 Product: opencart-shipping-packeta 一行，以及 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 账户中释放该名额。

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

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

故障排除

结账时没有显示 Packeta：请检查许可证是否有效、Enable/Disable 是否已开启、API key 是否已输入，以及配送国家是否为 CZ、SK、HU 或 RO。检查该国家是否设置了价格（国家行、* Default 行或 Fallback cost）、重量和小计限制，以及 Geo zone（或 Ignore shipping zones 及其国家）。检查商品的 Requires Shipping 是否设为 Yes。设置页面顶部会列出配置问题。开启 Debug log，即可在 Log (last lines) 中查看原因。

Packeta 拒绝了 API 密钥：请从 client.packeta.com > Client support 重新复制 API 密钥并保存。在此之前，小部件无法在结账时打开。

小部件无法打开：Packeta 脚本被广告或隐私拦截器、内容安全策略或 Packeta 服务中断阻止。请在您的内容安全策略中允许 widget.packeta.com。

错误地免运费：请检查 Country prices 中 Price 为 0 的行，尤其是通过 Add country 添加且未填写的 * Default 行，并检查 Free shipping from。

重量限制或重量列看起来不对：如果页面提示店铺重量单位有问题，请使用单位为 kg、g、lb 或 oz 的重量类别，并在 System > Settings 的 Local 选项卡中设置默认重量类别。其他单位会被当作千克处理。

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

面向开发者：其他扩展可以添加国家、向小部件传递承运商 ID 等选项，或通过 OpenCart 事件 vfd_packeta/countries、vfd_packeta/widget_options、vfd_packeta/widget_url 和 vfd_packeta/widget_language 更改小部件脚本的 URL 或语言（带 catalog/ 前缀的触发器，例如 catalog/vfd_packeta/widget_options）。

卸载

进入 Extensions > Extensions，选择类型 Shipping，然后点击 VibeFox Packeta 旁边的 Uninstall（红色 − 按钮）。该扩展的许可证密钥和许可证状态始终会被删除。OpenCart 始终会重置 Enable/Disable、Sort order、Tax status 和 Geo zone。已保存的 API 密钥检查始终会被删除，取件点按钮和订单面板也不再显示。如果 Remove data on uninstall 处于开启状态，则会删除设置、日志以及从未成为订单的结账中的取件点。如果处于关闭状态，其他设置会保留，并在您重新安装扩展时再次使用。现有订单始终保留已保存的取件点及其配送方式中的取件点信息。

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

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