VibeFox PostNord for OpenCart — 帮助
系统要求
OpenCart：3.0.x（已在 3.0.5.0 上测试）或 4.0.2 及更高版本（已在 4.1.0.3 上测试）。
PHP：8.0 或更高版本。
PostNord API 密钥（用于服务点选择器）：在 developer.postnord.com 上创建免费账户，添加一个应用并复制其 API 密钥。没有密钥时配送方式仍可使用，但顾客无法选择服务点。
PostNord 协议：要寄送包裹，您需要常用的 PostNord 客户协议，例如 MyPack Collect 或 MyPack Home。
VibeFox 许可证密钥：在 vibefox.net 购买。一个密钥只能用于一个域名。
安装
下载文件是一个 zip 文件，内含两个 OpenCart 版本的安装包。请在您的电脑上解压。其中包含 README.txt、OpenCart 3 安装包 vfd_postnord-oc3-(version).ocmod.zip 和 OpenCart 4 安装包 vfd_postnord.ocmod.zip。请只安装与您的 OpenCart 版本对应的安装包。两个版本的许可证密钥相同。
OpenCart 3
1. 在后台进入 Extensions > Installer，点击 Upload，然后选择文件 vfd_postnord-oc3-(version).ocmod.zip。本扩展不添加 OCMOD 修改，因此无需刷新 Extensions > Modifications。您也可以不使用 Installer，而是将安装包中 upload 文件夹的内容复制到商店的根目录。
2. 进入 Extensions > Extensions，选择扩展类型 Shipping。找到 VibeFox PostNord，点击 Install（绿色的 + 按钮）。
3. 点击 Edit（铅笔按钮）打开设置页面。
4. 在 Edit 页面顶部的许可证区块中，将您的 VibeFox 许可证密钥输入 License key 字段，然后点击 Activate（参见许可证密钥）。
5. 开启 Enable/Disable（服务点配送）和/或 Home delivery，粘贴 PostNord 的 API key，选择 Agreement country，填写 Country prices 或 Fallback cost（参见配置），然后点击 Save。
OpenCart 4
1. 在后台进入 Extensions > Installer，点击 Upload，然后选择文件 vfd_postnord.ocmod.zip。请不要重命名该文件：OpenCart 4 会从文件名获取扩展代码，重命名后的安装包无法使用。
2. 该安装包会出现在同一页面的已安装扩展列表中。点击其旁边的 Install（绿色的 + 按钮）。
3. 进入 Extensions > Extensions，选择扩展类型 Shipping。找到 VibeFox PostNord，点击 Install（绿色的 + 按钮），然后点击 Edit（铅笔按钮）。
4. 按照 OpenCart 3 步骤 4 和 5 的方式输入许可证密钥和设置。两个版本的设置页面及其字段相同。
安装后，两个选项在您开启其中之一并保存之前都处于关闭状态。如果您卸载后重新安装本扩展，之前保留的 PostNord 设置会再次生效。
配置
所有设置都在扩展页面中：Extensions > Extensions > Shipping > VibeFox PostNord > Edit。各分区列在左侧。页面底部的一个 Save 按钮可在不重新加载页面的情况下保存整个页面。每次保存还会清除缓存的服务点列表。只有拥有本扩展修改权限的管理员用户才能保存设置。
如果某个值有误，则不会保存任何内容，页面会显示原因：名称为空、超过 64 个字符或包含 < > ; = # { }；排序不是整数；税务状态或地理区域无效；或 Min weight (kg) 大于 Max weight (kg)。数字字段中的值如果不是大于或等于 0 的数字，将以空值保存并显示提示。价格表单元格中的值如果不是大于或等于 0 的数字，将以 0 保存并显示提示。
在设置上方，如果尚未设置 API 密钥、尚未设置任何价格，或商店中没有“kg”重量等级，页面会发出警告。
常规
两种配送选项会在 Availability 中设置的地理区域内提供，或针对 Ignore shipping zones 中的国家提供。
Enable/Disable：开启或关闭 PostNord 配送到服务点或包裹柜的功能。顾客在结账时选择网点。默认：关闭。
Name：结账时服务点选项的名称，例如“PostNord MyPack Collect”。默认：PostNord。必填，最多 64 个字符，不得包含 < > ; = # { }。
Home delivery：同时提供 PostNord 上门配送，即不带服务点的第二个选项。默认：关闭。
Home delivery name：结账时上门配送选项的名称，例如“PostNord MyPack Home”。默认：PostNord Home delivery。与 Name 的规则相同。
Sort order：PostNord 在结账时配送方式中的位置。一个整数。
Tax status：None (the prices are final)（默认），或一个税类：此时 OpenCart 会在价格之上加上该税类的配送税。两种选项均适用。
PostNord API（服务点选择器）
API key：您在 developer.postnord.com 上的应用的 API 密钥。它只会从您的服务器发送给 PostNord，绝不会发送到浏览器，也绝不会写入日志。保存后该字段保持为空，并显示 Saved - leave empty to keep it. 只有需要更改时才输入新值。
Remove the saved API key：勾选后点击 Save，即可删除已保存的密钥。
Test mode：使用 PostNord 测试环境（atapi2.postnord.com）。仅适用于为测试环境签发的密钥。
Agreement country：您的 PostNord 客户协议所属国家：瑞典、丹麦、挪威或芬兰。它决定提供哪些服务点。Same as the delivery country（默认）则使用顾客所在国家。
价格
分区标题显示您商店的默认货币。价格以该货币表示，不含税，且两种选项的价格相同。PostNord 没有公开的价格 API，因此您需要设置自己的价格，通常是您 PostNord 协议中的价格。计算顺序为：免运费门槛，然后是国家价格表，最后是备用费用。
Calculation type：Per order（默认）只收取一次费用。Per item (price x number of items) 则按购物车中的商品数量相乘计费。
Country prices：按目的国家和购物车重量设置的价格。点击 Add country 添加一行，点击 × 按钮删除一行。每行包含一个 Price 列和重量列：XS 为 1 kg 及以下，S 为 2 kg 及以下，M 为 3 kg 及以下，L 为 5 kg 及以下，XL 为 5 kg 以上。重量列为 0 时使用 Price 列，Price 为 0 则表示免运费。国家 * All other countries 涵盖所有没有自己单独一行的国家。小数可用逗号或句点（9,99 或 9.99）。新增的一行默认为 * All other countries，所有价格为 0。保存前请选择国家并输入价格，或删除该行。空单元格将以 0 保存。
Fallback cost：当国家价格表中既没有目的地所在的行，也没有 * 行时使用。留空则对这些国家隐藏 PostNord。
Free shipping from：免运费的购物车小计金额（需要配送的商品、扣除优惠券后、不含税），达到该金额时 PostNord 免费。它在国家价格表之前检查，因此对没有价格行的国家同样适用。留空则从不提供免运费。
可用性
Min weight (kg)：购物车重量低于此值时隐藏 PostNord。商品重量会根据其重量等级进行换算。默认：0，即无限制。
Max weight (kg)：购物车重量高于此值时隐藏 PostNord。默认：30。0 表示无限制。请核对您的 PostNord 服务的重量限制：包裹柜接受的重量低于服务点。
Minimum subtotal：仅当购物车小计（需要配送的商品、扣除优惠券后、不含税）至少达到此金额时才显示 PostNord。留空则始终显示。
Geo zone：仅对此地理区域内的地址提供 PostNord。All zones（默认）表示无限制。地理区域在 System > Localisation > Geo Zones 中管理。当 Ignore shipping zones 开启时不使用此项。
Ignore shipping zones：开启时不检查地理区域，并对下方列出的国家提供 PostNord。关闭时仅在地理区域内提供。
Countries (Ignore shipping zones)：此模式下的目的国家。留空则允许所有国家。仅当 Ignore shipping zones 开启时才使用此字段。
高级
Debug log：将运费计算和 API 调用写入 storage/logs/vfd_ptnd_debug.log.php。该文件无法通过网页读取。API 错误始终会记录。API 密钥从不记录。完成后请关闭日志。文件达到 5 MB 时，将开始新的日志。
Log：显示调试日志的大小和最新条目。点击 Clear log 可清空。
Remove data on uninstall：开启时，卸载扩展会删除 PostNord 设置和日志。缓存的服务点列表始终会被删除。订单中保存的服务点始终保留。
导入 / 导出
Export：点击 Download JSON，将设置保存为 JSON 文件。API 密钥不会被导出。
Import：粘贴之前导出的 JSON，然后点击 Import 恢复设置，例如在另一家商店中使用。数值的检查方式与普通保存相同。已保存的 API 密钥会保留。
结账时的工作方式
OpenCart 显示配送方式时，会向扩展询问每个 PostNord 选项的价格。只有 Requires Shipping 设为 Yes 的商品才会计算在内：其他商品不增加重量，也不计入小计。扩展会检查地理区域或国家列表、购物车重量和最低小计。若适用免运费，价格为 0。否则，价格取自国家价格表，然后是备用费用。如果没有价格，则隐藏该选项。价格以默认货币计算，并以顾客的货币显示，并包含所选 Tax status 的税费。价格计算从不联系 PostNord。
对于服务点选项，且配送地址位于瑞典、丹麦、挪威或芬兰，您的服务器会向 PostNord Business Location API 请求距离配送邮编最近的 10 个服务点。它会发送配送国家和邮编以及协议国家。API 超时时间为 10 秒。列表按邮编缓存 6 小时，“无网点”的回复缓存 1 小时。API 错误缓存 5 分钟，因此 PostNord 服务中断不会拖慢每次结账更新。缓存保存在扩展自身的数据库表中。配送步骤从不等待 PostNord：如果列表尚未缓存，则会在顾客选择该选项后加载。
对于其他目的地，仍可使用您的价格提供这些选项，但不显示选择器。上门配送选项从不显示选择器。
扩展不请求 PostNord 的实时价格，也不生成运单、不预约发货（EDI）、不提供跟踪号码，也不发送跟踪邮件。没有地图视图。发货请使用 PostNord Portal、Skicka Direkt Business 或标签工具；这些工具需要已保存的服务点 ID。
在 OpenCart 4 中，顾客在结账页的配送方式区块中点击 Choose，并在 Shipping method options 窗口中选择一个 PostNord 选项。价格与 OpenCart 3 相同。
取件点
当配送地址位于瑞典、丹麦、挪威或芬兰时，服务点选项下方会出现一个 PostNord service point 列表，显示最近的网点，按城市分组，每个网点都附有地址和距离。在输入邮编之前，顾客会看到“请输入邮编以选择 PostNord 服务点。”选择结果会立即保存，用于结账。
列表加载完成后，必须选择一个网点。如果未选择，配送方式步骤中的 Continue 会停止，并提示“请选择一个 PostNord 服务点。”所选网点会在服务器上与 PostNord 针对该配送地址的列表进行核对。为其他邮编选择的网点不会被使用。
选择器从不阻止销售。如果列表无法加载（尚未设置 API 密钥、PostNord API 不可用、邮编附近没有网点），顾客会看到一条提示，但仍可下单。此时 PostNord 会配送到距离地址最近的服务点。
订单页面、邮件和发票：网点会添加到订单的配送方式中，例如“PostNord：名称，地址（ID 12345）”（先是选项名称，然后是网点）。如果文本超过 128 个字符，则省略地址（OpenCart 4 没有此限制，始终保留地址）。它会显示在 OpenCart 显示配送方式的所有位置：顾客的订单历史、订单邮件、发票以及 Sales > Orders。没有网点的订单则保留普通的配送方式名称。
管理员订单页面：在 Sales > Orders 中，订单页面在历史记录上方显示一个 PostNord service point 面板，包含名称、地址和 Service point ID。如果未选择网点，则显示“未选择 - PostNord 将配送到距离配送地址最近的服务点”。
在 OpenCart 4 中，服务点列表显示在 Shipping method options 窗口中服务点选项的下方，并且每次打开窗口时都会重新加载，因为在一页式结账中地址可能会变化。窗口中的 Continue 按钮在没有列表中的网点时不会继续，并显示相同的消息。如果顾客在列表仍在加载时点击它，窗口会等待列表，不显示任何消息，然后自行再次点击 Continue。列表不可用时也不会阻止订单。OpenCart 4 为结账保留一个订单，并在顾客每次重新确认时更新它，订单的服务点也会随之更新。
许可证密钥
本扩展需要一个来自 vibefox.net 的 VibeFox 许可证密钥。许可证区块 License — VibeFox PostNord 是 Extensions > Extensions > Shipping > VibeFox PostNord > Edit 页面中的第一个区块，位于设置上方。将密钥输入 License key 并点击 Activate。之后，该区块会以掩码形式显示密钥、状态（例如许可证有效期截止日期和您的域名），以及以下按钮：Check now（重新检查状态）、Change key（输入其他密钥）和 Remove key（从本店铺移除密钥）。其下方有一行 Product: opencart-shipping-postnord，以及一个链接 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 账户中释放名额。
如果没有有效的密钥，PostNord 配送选项不会在结账时显示给顾客，也不会计算运费。在后台同一浏览器中登录的管理员用户仍能在店铺中看到这些选项，并标记为 (unlicensed — visible to admins only)，因此您可以在购买密钥之前完成设置和测试。在 OpenCart 4 中没有此预览功能：店铺无法识别后台登录状态，因此没有有效密钥时，这些选项对所有人都隐藏。打开一次 Edit 页面后，后台 Dashboard 会出现提醒。点击 × 关闭，可隐藏 7 天。现有订单不受影响。
许可证到期后，扩展仍会继续运行，但更新和支持需要续费。当您打开后台 Dashboard 或 Edit 页面时会自动再次检查状态：输入密钥后的前 14 天每天一次，之后每周一次。无需 cron 任务。卸载扩展总会删除许可证密钥和许可证状态。
故障排除
结账时没有显示 PostNord：请检查许可证是否有效，以及 Enable/Disable（或 Home delivery）是否已开启。当 Ignore shipping zones 开启时，检查 Geo zone 或 Countries 列表。检查该国家是否已设置价格（国家行、* 行或 Fallback cost）、重量限制和 Minimum subtotal。检查商品的 Requires Shipping 是否设为 Yes。
选择器提示无法加载服务点：检查 API key 和 Test mode 设置。正式环境密钥无法用于测试环境，反之亦然。开启 Debug log，重新加载结账页面，然后查看扩展页面上的 Log 字段。订单仍可提交；此时 PostNord 会配送到最近的服务点。
服务点不符合预期：检查 Agreement country。它决定提供哪些服务点。
错误地免运费：检查 Country prices 中 Price 为 0 的行，尤其是使用 Add country 添加后未填写的 * 行，并检查 Free shipping from。
修改后服务点看起来过时：在扩展页面点击 Save，这会清除缓存的列表。
商品重量看起来不正确：如果扩展页面提示商店没有“kg”重量等级，请检查 System > Localisation > Weight Classes。商品重量会按其等级的单位名称进行换算，无法识别的单位将按 kg 处理。
页面显示“Warning: You do not have permission to modify VibeFox PostNord!”：您的管理员用户组可能只能查看设置。请在 System > Users > User Groups 中为该组授予 extension/shipping/vfd_postnord（OpenCart 3）或 extension/vfd_postnord/shipping/vfd_postnord（OpenCart 4） 的修改权限。
面向开发人员：可以通过设置 vfd_ptnd_api_url（用于测试）替换 PostNord API 地址；该设置在设置页面中没有对应字段。
卸载
进入 Extensions > Extensions，选择类型 Shipping，然后点击 VibeFox PostNord 旁边的 Uninstall（红色 − 按钮）。扩展的许可证密钥和许可证状态总会被删除。OpenCart 总会重置扩展状态、Sort order、Tax status 和 Geo zone。缓存的服务点列表总会被删除。如果 Remove data on uninstall 已开启，PostNord 设置、调试日志以及从未成为订单的结账中的服务点也会被删除。如果已关闭，其他设置会保留，并在您重新安装扩展时再次使用。现有订单会保留其配送方式、费用和已保存的服务点。
在 OpenCart 4 中，如需同时删除扩展文件，请在卸载后进入 Extensions > Installer，在已安装扩展列表中点击 VibeFox PostNord 旁边的 Uninstall（橙色的 − 按钮），然后点击 Delete（红色垃圾桶按钮）以删除已上传的安装包。
PostNord 是其各自所有者的商标。本扩展与 PostNord 无关联，也未获得 PostNord 的认可。