VibeFox Packeta for PrestaShop — 帮助
系统要求
PrestaShop：8.0 至 9.x。
PHP：8.0 或更高版本。模块拒绝在更早的 PHP 版本上安装。
Packeta API 密钥：您可以在 Packeta 客户区（client.packeta.com）的 Client support 下找到它。它由 16 个字母和数字组成。小组件需要它才能在结账时打开，因此只有输入 API 密钥后，顾客才会看到该承运商。
国家：捷克共和国、斯洛伐克、匈牙利或罗马尼亚必须是您店铺中已启用的国家，并且位于承运商所关联的区域中。
VibeFox 许可证密钥：在 vibefox.net 购买。一个密钥只能用于一个域名。
安装
1. 进入后台，前往 Modules > Module Manager，点击 Upload a module。选择模块的 ZIP 文件。
2. 上传完成后，点击 Configure；或之后在模块列表中找到 VibeFox Packeta，再点击 Configure。
3. 在配置页面顶部的许可证区块中的 License key 字段输入您的 VibeFox 许可证密钥，然后点击 Activate（参见许可证密钥）。
4. 输入您的 Packeta API key 和价格：至少添加一行 Country prices（例如 * Default）或设置 Fallback cost。点击 Save。页面会显示 Packeta 是否接受了该密钥。
安装时，模块会创建承运商 Packeta pickup point，配送时长文字为 Packeta pickup point or Z-BOX。该承运商已关联捷克共和国、斯洛伐克、匈牙利和罗马尼亚的区域以及所有客户群组。您可以在 Shipping > Carriers 中修改区域、客户群组、配送时长和徽标。请勿在那里设置价格：价格始终来自模块。
配置
所有设置都位于模块页面：Modules > Module Manager > VibeFox Packeta > Configure。每个部分都有各自的 Save 按钮，点击后会保存整个页面。
承运商仅针对 Packeta 自有取件点网络覆盖的国家提供：CZ、SK、HU 和 RO。在设置上方，页面会显示 API 密钥检查结果，以及有关问题的警告：缺少 API 密钥、缺少价格、所选国家不在 Packeta 网络内、承运商缺失，或店铺使用了模块无法识别的重量单位。
所有价格和限制都接受逗号或句点作为小数点分隔符（4,99 或 4.99）。无效或负数会被拒绝并显示提示，同时保留之前的值。
常规
Enable/Disable：在结账时开启或关闭 Packeta。
Name：顾客看到的承运商名称。它也是 Shipping > Carriers 中的承运商名称。默认值：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：应用于运费的税务规则。None (no tax on shipping) 或 Taxable，并选择您的一个税务规则组。该选择会保存到承运商。
价格
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）出现在两行中，保存时只保留第一行。如果表格中的某个值不是有效数字，表格将不会保存，页面会列出错误的值。
Fallback cost：当国家表中没有目的地对应的行，且也没有 * Default 行时使用。留空则不在该地提供承运商。
Free shipping from：购物车小计（扣除折扣后、不含税）达到此金额时，Packeta 配送免费。该条件会先于价格表进行检查：达到此金额后，在所有提供该承运商的 Packeta 国家，配送均免费，即使某国家没有对应行或备用费用也一样。留空则从不提供免运费。
可用性
Minimum weight (kg)：购物车重量低于此值时隐藏该承运商。购物车重量会从您店铺的重量单位换算而来。留空或为 0 表示没有限制。
Maximum weight (kg)：购物车重量高于此值时隐藏该承运商。默认值：15。Packeta 取件点和 Z-BOX 通常接受最多 15 kg 的包裹；请查看您与 Packeta 的合同。留空或为 0 表示没有限制。保存时，如果最小重量大于最大重量，将被拒绝，并保留两个之前的值。
Minimum cart subtotal：仅当购物车小计（扣除折扣后、不含税）达到此金额时才提供该承运商。
Ignore shipping zones：开启后，该承运商会关联所有区域，并针对下方所选的国家提供。之后创建的区域会立即关联。关闭时，承运商会恢复其之前拥有的区域。关闭时，仅在 Shipping > Carriers 中为该承运商设置的区域内提供。
Countries (ignore zones mode)：该模式下的目的国家。留空则使用所有 Packeta 国家。不在 Packeta 取件点网络内的国家会被跳过。按住 Ctrl 并点击可选择多个国家。仅在开启 Ignore shipping zones 时使用此字段。
高级
Debug log：将运费计算和取件点选择记录到 modules/vfd_packeta/logs/。该文件无法通过网页打开。不会记录顾客的个人数据和 API 密钥。错误和失败的 API 密钥检查始终会被记录。完成后请关闭日志。
Log (last lines)：显示调试日志的最新条目。点击 Clear log 可清空日志。
Remove data on uninstall：开启后，卸载模块时会删除设置和日志。订单中保存的取件点始终保留。
结账时的工作方式
在配送步骤，PrestaShop 会向模块请求 Packeta 价格。只有实体商品计入：虚拟商品不增加重量，也不计入小计。模块会检查以下条件：配送国家是否在 Packeta 网络内、API 密钥、忽略区域模式下的国家列表、购物车重量以及购物车小计最低限额。如果适用免运费，价格为 0。否则价格取自国家表，其次取自备用费用。如果没有价格，承运商会被隐藏。
当顾客选择 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.」
如果您在承运商已有订单后，在 Shipping > Carriers 中编辑该承运商，PrestaShop 会将其保存为新的承运商版本。模块会自动跟随新版本。
Packeta 价格不会实时请求，而是来自您的价格表。模块不会创建 Packeta 运单、打印面单或跟踪包裹，默认也不提供上门配送或合作承运商的取件点。请按您平常的方式将订单中的取件点 ID 交给 Packeta，例如通过 client.packeta.com 导入。
取件点
取件点为必选项。如果顾客在配送步骤未选择取件点就点击 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 区块，包含名称、地址、Pickup point ID 和国家。如果某个 Packeta 订单没有取件点，该区块会显示「No pickup point was selected for this order.」
订单确认页面和订单详情页面：Packeta pickup point：包含名称和地址。
订单电子邮件：订单确认电子邮件中会在承运商信息中添加取件点名称和地址。商家的新订单电子邮件还包含 Pickup point ID。
取件点存储在模块数据表 vfd_pckt_point 中（购物车、订单、取件点 ID、名称和地址、国家）。
许可证密钥
本模块需要使用从 vibefox.net 获取的 VibeFox 许可证密钥。该模块的许可证区块 License — VibeFox Packeta 是 Modules > Module Manager > VibeFox Packeta > Configure 页面中位于设置上方的第一个区块。请将密钥输入 License key 并点击 Activate。之后，该区块会显示被遮蔽的密钥、状态（例如许可证有效期截止日期和您的域名），以及以下按钮：Check now（重新检查状态）、Change key（输入其他密钥）和 Remove key（从此店铺移除密钥）。其下方是 Product: presta-shipping-packeta 一行和 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 账户中释放该名额。
没有有效的密钥时，结账时不会向顾客显示 Packeta 承运商，也不会计算任何价格。PrestaShop 前台无法得知您已登录后台，因此承运商对您也会隐藏：您可以在购买密钥前设置模块，但无法在结账时测试。Modules > Module Manager 中的 Alerts 标签页会显示提醒。已有订单不受影响。
许可证到期后，模块仍会继续运行，但更新和支持需要续费。在后台工作时，系统会自动重新检查状态：输入密钥后的前 14 天每天一次，之后每周一次。无需设置 cron 任务。卸载或重置模块时，始终会删除许可证密钥和许可证状态。
故障排除
结账时没有显示 Packeta：请检查许可证是否有效、Enable/Disable 是否开启、是否已输入 API key，以及配送国家是否为 CZ、SK、HU 或 RO。检查该国家是否已设置价格（国家行、* Default 行或 Fallback cost）、重量和小计限制，以及承运商在 Shipping > Carriers 中是否涵盖顾客所在国家的区域和顾客所属群组（或已开启 Ignore shipping zones）。商品页面中也可能将商品限制为特定承运商。设置页面顶部会列出配置问题。开启 Debug log，即可在 Log (last lines) 中查看原因。
Packeta 拒绝了 API 密钥：请从 client.packeta.com > Client support 重新复制 API 密钥并保存。在此之前，小组件无法在结账时打开。
小组件无法打开：Packeta 脚本被广告或隐私拦截器、内容安全策略或 Packeta 服务中断所阻止。请在内容安全策略中允许 widget.packeta.com。开发者可以通过 actionVfdPcktWidgetUrl 钩子更改脚本 URL。
运费意外免费：请检查 Country prices 中 Price 为 0 的行，尤其是通过 Add country 添加但未填写的 * Default 行，并检查 Free shipping from。
重量限制或重量列看起来不正确：如果页面提示店铺的重量单位，请在 International > Localization（Local units）中设置 kg、g、lb 或 oz。其他单位都会被当作千克读取。
其他国家或承运商：开箱即用时，承运商适用于 CZ、SK、HU 和 RO。开发者可以使用 actionVfdPcktCountries 钩子添加国家，并使用 actionVfdPcktWidgetOptions 钩子将承运商 ID 传递给小组件。
页面提示 Packeta 承运商缺失：该承运商已在 Shipping > Carriers 中被删除。请在 Modules > Module Manager 中重置模块，以重新创建它。
卸载
前往 Modules > Module Manager，打开 VibeFox Packeta 旁边的菜单，选择 Uninstall。许可证密钥和许可证状态总会被删除。Packeta 承运商总会被删除（订单保留其承运商信息），同时删除已保存的 API 密钥检查结果。如果 Remove data on uninstall 已开启，则会删除设置、日志以及从未成为订单的购物车中的取件点。如果已关闭，设置会保留以便重新安装，重新安装时会再次创建承运商。已有订单始终保留已保存的取件点。
Packeta 是其各自所有者的商标。本模块与 Packeta 无关联，也未获得 Packeta 的认可。