VibeFox Mondial Relay for OpenCart — 帮助

系统要求

OpenCart：3.0.x（使用默认主题在 3.0.5.0 上测试）或 4.0.2 及更高版本（使用默认主题在 4.1.0.3 上测试）。

PHP：8.0 或更高版本。

Mondial Relay 账户：品牌代码（Enseigne）和私钥随 Mondial Relay 商务账户提供：请查看 mondialrelay.fr 的专业人士部分、您的 "Connect" 客户专区或您的销售联系人。地图选择器只需要品牌代码。最近网点列表需要两者。用于测试时，Mondial Relay 提供品牌代码 BDTEST13 和私钥 PrivateK。

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

安装

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

OpenCart 3

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

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

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

4. 在 Edit 页面顶部的许可证区块中，于 License key 处输入您的 VibeFox 许可证密钥，然后点击 Activate（参见许可证密钥）。

5. 输入您的品牌代码（Enseigne），如使用列表模式，还需输入私钥。填写 Country prices（例如法国一行）或 Fallback cost，开启 Enable/Disable，然后点击 Save。

OpenCart 4

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

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

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

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

安装后，在您开启 Enable/Disable 并保存之前，该方式保持关闭。如果您卸载后重新安装该扩展，之前保留的设置将再次使用。

配置

所有设置都在扩展页面中：Extensions > Extensions > Shipping > VibeFox Mondial Relay > Edit。各部分列在左侧。点击一次 Save 即可保存整个页面，无需重新加载。每次保存还会清除缓存的网点列表。只有对该扩展拥有修改权限的管理员用户才能保存设置。

页面顶部的警告会显示导致该方式隐藏的问题：缺少品牌代码、列表模式下缺少私钥、法国、比利时或西班牙没有价格，以及扩展无法识别的商店重量单位（此时商品重量按 kg 处理）。如果 Name 为空、超过 64 个字符或包含字符 < > ; = # { } 之一，Min weight (kg) 大于 Max weight (kg)，或品牌代码无效，页面会显示错误，且不会保存任何内容。数字字段的值如果不是数字（或为负数），会在 Save 后提示，并保留其之前的值；其他设置仍会保存。

常规

为法国、比利时、卢森堡、西班牙、葡萄牙和荷兰提供 Mondial Relay Point Relais 配送。该方式在其地理区域内提供（参见 Availability），或在开启 Ignore shipping zones 时，在所列国家提供。

Enable/Disable:在结账时显示或隐藏 Mondial Relay。默认：关闭。

Name:在购物车和结账时向顾客显示的配送方式名称。默认：Mondial Relay Point Relais。必填，最多 64 个字符。

Tax status:None（默认）表示表中的价格为最终价格。选择带有某个税类名称的 Taxable 选项，则表示 OpenCart 会在价格之上加上该税类的运费税。

Sort order:Mondial Relay 在结账时的配送方式中的位置。整数。

Mondial Relay 账户

Brand code (Enseigne):必填，最多 8 个字母和数字，例如用于测试的 BDTEST13。取件点地图和 Web Service 都会使用它。没有它，顾客无法选择 Point Relais，因此该方式不会在结账时显示。

Private Key:仅在 List of nearest points 选择器中需要。保存后，该字段保持为空，并显示 Saved - leave empty to keep it. 仅在需要更改时才输入新值。要删除已保存的密钥，请勾选 Remove the saved Private Key 并点击 Save。设置了品牌代码和私钥后，每次保存设置时都会测试与 Mondial Relay Web Service 的连接，并显示消息说明它们是否有效。

取件点选择器

顾客必须先选择一个 Point Relais，才能继续进入付款步骤。该网点会保存到订单中。

选择器：顾客如何选择 Point Relais。

Mondial Relay map (official widget, brand code only):Mondial Relay 官方的 Parcel Shop Picker，在顾客打开时从 widget.mondialrelay.com 加载。这是默认选项。

List of nearest points (Web Service, needs the Private Key):根据配送邮政编码，由您的服务器加载的最近网点下拉列表。如果 Web Service 失败，则改为提供地图。

价格（以您商店的默认货币计，不含税）

Mondial Relay 没有公开的运费 API：价格来自此表。

Country prices:按目的国家和包裹重量的价格。点击 Add country 添加一行，点击删除按钮可删除一行。将 * Default 选为其他所有国家的国家。每行有一个 Price 和重量列：1 kg 以下为 XS，1-2 kg 为 S，2-3 kg 为 M，3-5 kg 为 L，5 kg 以上为 XL。重量列为空或为 0 时使用 Price 列。如果 Price 也为空，则该重量的配送免费，因此如果只使用部分重量列，请填写 Price。小数可用点或逗号（4.90 或 4,90）。没有任何价格的行以及国家未知的行在保存时会被删除，不是数字的值会被提示并留空。

Fallback cost:用于表中没有行的国家。留空则对这些国家隐藏该方式。

Calculation type:价格的计算方式。

Per order (weight of the whole parcel):购物车一个价格，重量列根据购物车总重量选择。这是默认选项。

Per item (each item priced by its own weight):每件商品按其自身重量定价并乘以数量，然后将价格相加。

Free shipping from:购物车小计（扣除折扣后，不含税）达到该金额后配送免费。留空则不设免运费。

可用性

Min weight (kg):购物车重量低于此值时隐藏该方式。0 表示无限制（默认）。

Max weight (kg):购物车重量高于此值时隐藏该方式。Mondial Relay 在 Points Relais 接受最重 30 kg 的包裹。默认：30。0 表示无限制。空字段表示 30 kg。

Minimum subtotal:仅当购物车小计（需要配送的商品，扣除折扣后，不含税）至少达到此金额时才显示该方式。留空则始终显示。

Geo zone:仅为该地理区域内的地址提供该方式。All zones（默认）表示所有地区。地理区域在 System > Localisation > Geo Zones 中管理。开启 Ignore shipping zones 时不检查。

Ignore shipping zones:开启时不检查 Geo zone：该方式仅在下方列出的国家提供；如果列表为空，则在所有受支持的国家提供。

Countries (ignore zones):该模式下的目的国家。仅当开启 Ignore shipping zones 时才会使用此字段。该列表仅包含有 Points Relais 的国家。

高级

Debug log:将费率计算、Web Service 调用和网点选择写入 storage/logs/vfd_mrel_debug.log.php（在 OpenCart 4 中为 system/storage/logs/vfd_mrel_debug.log.php）。该文件无法通过网页读取。即使关闭此选项，错误也始终会被记录。密钥和顾客数据从不记录。文件达到 5 MB 时，会移至 vfd_mrel_debug.old.log.php，并开始新的日志。

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

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

导入 / 导出

Export:点击 Download JSON，将设置保存为 JSON 文件，不包含私钥。

Import:粘贴之前导出的 JSON，然后点击 Import 恢复设置，例如在另一个商店中。适用与 Save 相同的检查。已保存的私钥会保留。

结账时的工作方式

该方式仅为有 Points Relais 的国家提供：法国、比利时、卢森堡、西班牙、葡萄牙和荷兰。当顾客无法选择网点时，该方式会隐藏：没有品牌代码，或在列表模式下没有私钥。如果设置了 Geo zone 且地址在其之外，则不提供该方式。开启 Ignore shipping zones 时，不检查地理区域，仅服务该列表中的国家（列表为空时服务所有受支持的国家）。

OpenCart 显示配送方式时，会向扩展请求价格。只有将 Requires Shipping 设为 Yes 的商品才会计入：其他商品不增加重量，也不计入小计。商品重量会从 OpenCart 的重量类别换算为 kg。小计是需要配送的商品价格，在扣除优惠券折扣后、税前。扩展会检查购物车重量和最低小计。价格来自国家的那一行（或 * 行）：重量列，否则为 Price。没有对应行时使用备用费用。如果没有价格，该方式将被隐藏。如果小计达到 Free shipping from，价格变为 0。价格以您商店的默认货币计算，按其小数位取整，并以顾客的货币显示，同时加上所选 Tax status 的税费。计算价格时不会向 Mondial Relay 发出请求。

在 OpenCart 4 中，顾客在结账页的配送方式区块中点击 Choose，并在 Shipping method options 窗口中选择 Mondial Relay。价格与 OpenCart 3 相同。

扩展不请求实时费率：Mondial Relay 没有公开的运费 API。它不创建运单、不打印标签、不跟踪包裹。请在您的 Mondial Relay "Connect" 空间中，使用订单中显示的 Point Relais 编号创建运单。不提供上门配送（Domicile）。

取件点

当顾客在配送方式步骤选择 Mondial Relay 选项时，其下方会出现一个 Mondial Relay pickup point 框。

地图模式：点击 Choose a Point Relais 按钮，会在窗口中打开 Mondial Relay 官方地图，并使用配送国家、邮政编码和包裹重量。顾客选定网点后，会显示为 Selected:，按钮变为 Change Point Relais。地图组件仅在顾客打开地图时从 widget.mondialrelay.com 加载，其地图库则从 unpkg.com 加载。请在您的隐私政策中说明此事。

列表模式：下拉列表 - Choose a Point Relais - 显示根据配送邮政编码得出的最近 10 个网点及其距离。所选网点会显示其营业时间。列表由您的服务器加载，因此浏览器中不会为此运行任何第三方脚本。列表缓存 12 小时，空结果缓存 1 小时，失败的请求会记住 5 分钟。Web Service 超时时间为 10 秒。没有邮政编码时，顾客会看到 Enter your postcode to see the nearest pickup points. 如果找不到任何网点或列表不可用，顾客会看到类似"取件点列表目前不可用，请使用地图。"的消息，并会提供地图。

所选网点会立即保存到顾客的会话中。网点为必选项。顾客点击 Continue 时，店铺会再次检查该网点。没有网点时，顾客会看到 Please choose a Mondial Relay pickup point.，并且无法进入付款。与配送地址不在同一国家的网点会被拒绝，并提示该网点不在配送国家内。在列表模式下，网点还会与该地址的列表进行核对。下单后，选择会被清除，因此下一个购物车需要重新选择。

在 OpenCart 4 中，Mondial Relay pickup point 框显示在 Shipping method options 窗口中 Mondial Relay 选项的下方，地图在该窗口内打开。Escape 键只关闭地图。窗口中的 Continue 按钮在没有有效网点时不会继续，并显示相同的消息。

下单后，网点会与订单保留在一起。订单的配送方式会显示方式名称，后跟网点名称、地址和编号，例如 Mondial Relay Point Relais: TABAC DU LOUVRE, 12 RUE DE RIVOLI, 75001 PARIS (FR-066974)，因此顾客可以在订单电子邮件和其账户的订单历史中看到它。发给店铺的新订单电子邮件会在评论块中显示网点及其编号。在 Sales > Orders 中，订单页面会显示一个 Mondial Relay pickup point 面板，包含网点名称、地址和 Point Relais 编号；如果没有，则显示 No Point Relais was saved for this order. 在 OpenCart 4 中，该面板显示在 History 上方。OpenCart 4 为结账保留一个订单，并在顾客每次重新确认时更新它，订单的网点也会随之更新。如果顾客将该订单切换到其他配送方式，其网点将被移除。

许可证密钥

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

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

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

故障排除

结账时没有显示 Mondial Relay：检查许可证是否有效，以及 Enable/Disable 是否已开启。检查 Geo zone，或开启 Ignore shipping zones 并检查其国家列表。检查扩展页面顶部的警告：没有品牌代码、列表模式下没有私钥、国家没有价格、超出重量和小计限制、以及没有 Points Relais 的国家，都会导致该方式隐藏。检查商品的 Requires Shipping 是否设为 Yes。

保存后 Web Service 测试失败：消息会显示 Mondial Relay 的错误，例如品牌代码无效或安全密钥无效。请与 Mondial Relay 核对品牌代码和私钥。

网点列表为空或不可用：顾客需要先提供配送邮政编码。如果 Web Service 失败，则改为提供地图。开启 Debug log，重新加载结账页面，并查看扩展页面上的 Log 字段以了解原因。

地图无法打开：地图从 widget.mondialrelay.com 和 unpkg.com 加载。请检查隐私或脚本拦截器，或您商店的内容安全策略（Content Security Policy）是否阻止了它们。如果无法加载地图，顾客会看到"无法加载 Mondial Relay 地图。请稍后再试，或选择其他配送方式。"

订单页面显示 No Point Relais was saved for this order：该订单是在没有配送国家网点的情况下下单的。原因已写入日志。请在创建运单前向顾客索取 Point Relais。

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

卸载

进入 Extensions > Extensions，选择类型 Shipping，然后点击 VibeFox Mondial Relay 旁边的 Uninstall（红色 − 按钮）。该扩展的许可证密钥和许可证状态始终会被删除。OpenCart 始终会重置 Enable/Disable、Sort order、Tax status 和 Geo zone。缓存的网点列表始终会被删除。如果开启了 Remove data on uninstall，其他设置和调试日志也会被删除。如果关闭，它们会保留，并在您重新安装扩展时再次使用。订单中保存的取件点始终保留，现有订单保留其配送方式和费用。

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

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