VibeFox Econt for OpenCart — 帮助
系统要求
OpenCart：3.0.x（已在 3.0.5.0 上测试）或 4.0.2 及更高版本（已在 4.1.0.3 上测试）。
PHP：8.0 或更高版本。
国家：必须在 System > Localisation > Countries 中启用保加利亚和罗马尼亚。
Econt：无需合同或 API 密钥。网点列表是 Econt 的公开目录。仅向 Econt 发送国家代码，不发送任何顾客数据。只有当 Econt 要求您的店铺进行授权时，才需要填写 e-Econt 用户名和密码。e-Econt 登录方式详见 Econt 开发者页面（econt.com/developers）。
VibeFox 许可证密钥：在 vibefox.net 购买。一个密钥仅适用于一个域名。
安装
下载文件是一个 zip 压缩包，内含适用于两个 OpenCart 版本的安装包。请解压到您的电脑上。其中包括 README.txt、OpenCart 3 安装包 vfd_econt-oc3-（版本）.ocmod.zip 以及 OpenCart 4 安装包 vfd_econt.ocmod.zip。只需安装与您的 OpenCart 版本对应的安装包。两个版本使用相同的许可证密钥。
OpenCart 3
1. 进入后台，前往 Extensions > Installer，点击 Upload，然后选择文件 vfd_econt-oc3-（版本）.ocmod.zip。本扩展不会添加任何 OCMOD 修改，因此无需刷新 Extensions > Modifications。您也可以不使用安装器，直接将本安装包中 upload 文件夹的内容复制到店铺的根目录。
2. 前往 Extensions > Extensions，选择扩展类型 Shipping。找到 VibeFox Econt，点击 Install（绿色 + 按钮）。
3. 点击 Edit（铅笔按钮）打开设置页面。
4. 在 Edit 页面顶部许可证区块的 License key 中输入您的 VibeFox 许可证密钥，然后点击 Activate（参见 License key）。
5. 设置各国价格并检查其他选项（参见 Configuration），开启 Enable/Disable 并点击 Save。点击 Load offices from Econt now 测试连接。
OpenCart 4
1. 进入后台，前往 Extensions > Installer，点击 Upload，然后选择文件 vfd_econt.ocmod.zip。请勿重命名该文件：OpenCart 4 从文件名中获取扩展代码，重命名后的安装包无法使用。
2. 该安装包会出现在同一页面的已安装扩展列表中。点击其旁边的 Install（绿色 + 按钮）。
3. 前往 Extensions > Extensions，选择扩展类型 Shipping。找到 VibeFox Econt，点击 Install（绿色 + 按钮），然后点击 Edit（铅笔按钮）。
4. 按照 OpenCart 3 步骤 4 和 5 的方法输入许可证密钥并设置。两个版本的设置页面及其字段相同。
安装后，该方式保持关闭状态，直到您开启 Enable/Disable 并保存。如果卸载后重新安装扩展，将沿用您之前保留的设置。
配置
所有设置都位于扩展页面：Extensions > Extensions > Shipping > VibeFox Econt > Edit。各分区列在左侧。点击一个 Save 按钮即可保存整个页面，无需刷新。只有对本扩展拥有修改权限的管理员用户才能保存设置、加载网点或清空日志。
页面顶部会显示扩展的警告信息：demo API 已开启；未设置保加利亚或罗马尼亚的价格（此时该方式将永远不会显示）；某个国家最近一次获取网点的请求失败；或者您的店铺没有单位为 kg 的重量类别（此时商品重量将按单位名称读取：kg、g、lb 或 oz）。数字字段接受小数点逗号，例如 5,99。如果数字字段包含非数字或负数，或者 Minimum weight (kg) 大于 Maximum weight (kg)，错误提示会指出该字段，且不会保存任何内容。Name 为空或超过 64 个字符、Sort order 不是整数，或税率类别或地理区域未知，也会出现同样的情况。
常规
Enable/Disable：在结账时显示或隐藏 Econt 配送。默认：关闭。
Name：在购物车和结账时显示的配送方式名称。默认：Econt Express。必填，最多 64 个字符。
Sort order：该方式在结账时配送方式中的排列位置。整数。
Tax class：配送费的税率类别，或 --- None ---（默认）。OpenCart 会在下方价格的基础上加收此税。选择 --- None --- 时，价格即为最终价格。
Econt 网点列表
网点和 Econtomat 从 Econt API 加载，并缓存 24 小时。
Demo API：使用带有测试数据的 Econt 演示 API。在正式店铺中请保持关闭。演示网点的 ID 与真实网点不同。在演示模式下，若未设置登录信息，将使用 Econt 的公开测试账户。
Econt username：可选。您的 e-Econt 登录名，用于 HTTP Basic 授权。
Econt password：可选。保存在店铺数据库中，且从不写入日志。保存后，该字段将保持为空，并显示 Saved - leave empty to keep it. 仅当您需要修改时才输入新值。
Remove the saved password：开启后点击 Save，即可删除已保存的密码。
Office list：显示每个国家已缓存的网点数量以及加载时间。Load offices from Econt now 按钮会立即重新加载保加利亚和罗马尼亚的列表，并按国家显示结果。如果某次加载失败，将保留上一次成功加载的网点。即使没有此按钮，列表也会在首次结账时自动加载。修改 Demo API、用户名或密码会清空已缓存的列表。
结账时的网点选择器
Show：顾客可以选择的站点。
City order：优先显示最大的城市（索非亚、普罗夫迪夫、瓦尔纳、布加勒斯特等）。关闭时，城市按字母顺序排列。默认：开启。
City list width：城市列表的 CSS 宽度，例如 100% 或 300px。默认：100%。
Office list width：网点列表的 CSS 宽度，例如 100% 或 400px。默认：100%。
价格（分区标题显示您店铺的默认货币）
价格以店铺默认货币计，不含税。本扩展不会向 Econt 查询实时汇率。自 2026 年 1 月 1 日起，保加利亚使用欧元，因此保加利亚店铺通常应输入 EUR 价格。
Price per country：每行一个国家（或用逗号分隔）：国家代码、冒号、价格，例如 BG:5.99 和 RO:8.99（这些是默认值）。也可以使用小数点逗号：BG:5,99。价格为 0 表示免运费。如果该字段为空，则使用默认价格 BG:5.99 和 RO:8.99。格式不符的条目会被忽略，并在保存时列入警告。其余内容仍会保存。
Calculation：Per order（默认）只收取一次价格。Per item (price x quantity) 则按需配送的商品数量相乘计费。
Price for other countries：用于上方未列出的 Econt 国家（保加利亚或罗马尼亚）。留空或填 0 则在该国隐藏此方式。
条件
购物车小计是指需要配送的商品，即应用优惠券之后、税费之前的金额。
Free shipping from：购物车小计达到此金额即免运费。留空则从不提供免运费。
Minimum subtotal：仅当购物车小计至少达到此金额时才显示该方式。留空则始终显示。
Minimum weight (kg)：对较轻的购物车隐藏该方式。商品重量会从其重量类别换算为 kg。留空表示无限制。
Maximum weight (kg)：对较重的购物车隐藏该方式。留空表示无限制。
可用范围
Econt 仅配送至保加利亚和罗马尼亚。通常由地理区域决定提供该方式的地点；启用 Ignore geo zone 后，则改由所选国家决定。
Geo zone：仅向此地理区域内的地址提供 Econt。All Zones（默认）表示保加利亚和罗马尼亚全境。地理区域在 System > Localisation > Geo Zones 中管理。使用 Ignore geo zone 时不会使用地理区域。
Ignore geo zone：不检查地理区域。无论地址是否在地理区域内，都会在下列国家提供 Econt。
Countries：保加利亚和/或罗马尼亚。仅在启用 Ignore geo zone 时使用。若未选择任何国家，则表示所有 Econt 国家。
高级
Debug log：将调试信息写入 storage/logs/vfd_ecn_debug.log.php（OpenCart 4 中为 system/storage/logs/vfd_ecn_debug.log.php）。该文件无法通过网页读取。当其达到 5 MB 时，将开始新的日志。API 错误和警告（Econt 无法连接、没有网点、订单没有网点）始终会被记录。不会写入任何密码或顾客数据。
Log：显示日志的大小和最新条目。点击 Clear log 可将其清空。
Remove data on uninstall：开启后，卸载扩展时会删除 Econt 设置、日志以及未完成结账的选择记录。关闭时，设置会保留，以便重新安装。订单中保存的网点始终会保留。
导入 / 导出
Export：点击 Download JSON 将设置保存为 JSON 文件。密码不会被导出。
Import：粘贴之前导出的 JSON，然后点击 Import 即可恢复设置，例如在另一家店铺中使用。这些值会像普通保存一样进行检查。已保存的密码会保留。
结账时的工作方式
该方式仅面向保加利亚和罗马尼亚提供。OpenCart 显示配送方式时，会向扩展请求 Econt 价格。启用 Ignore geo zone 后，不检查地理区域，该方式仅针对所选的 Countries 提供（未选择时 = 保加利亚和罗马尼亚）。否则，如果设置了 Geo zone，地址必须位于其中。只有 Requires Shipping 设为 Yes 的商品才会计算在内：其他商品不增加重量，也不计入小计。扩展会检查重量限制和最低小计，然后获取该国的价格。如果购物车小计达到 Free shipping from，价格为 0。如果该国没有可用的网点列表，则隐藏该方式，因为配送始终送往网点。价格以您的默认货币计算，并以顾客的货币显示，同时包含所选 Tax class 的税费。
当顾客选择 Econt 时，该方式下方会出现两个列表：City 和 Office / Econtomat。网点列表每个页面只加载一次，且仅在选择 Econt 时加载。列表中会标出 Econtomat。选择结果会立即保存。如果网点列表无法加载，顾客会看到 Econt offices cannot be loaded right now. Please try again in a few minutes or choose another shipping method.
当顾客在配送方式步骤点击 Continue 时，扩展会在服务器上检查是否已选择网点，并且该网点存在于配送国家的 Econt 列表中（按 Show 过滤）。如果没有选择网点，顾客会看到 Please select an Econt office or Econtomat. 不在列表中的网点会被拒绝，并提示 The selected Econt office is not available for the shipping country. Please select it again. 网点名称始终取自 Econt 列表，而不是浏览器。
在 OpenCart 4 中，顾客在结账页面的配送方式区块中点击 Choose，并在 Shipping method options 窗口中选择 Econt。City 和 Office / Econtomat 列表会出现在该窗口中该方式的下方，并按上文所述工作。窗口中的 Continue 按钮在未选择有效网点时不会继续，并显示相同的提示信息。
网点列表缓存 24 小时，实时 API 和演示 API 分别缓存，每个国家也分别缓存。如果无法连接 Econt，将使用最近一次成功加载的列表，并且 10 分钟内不再重新请求 Econt。API 超时时间为 15 秒。网点列表来自 https://ee.econt.com/services/（实时）或 https://demo.econt.com/ee/services/（演示）。
本扩展仅使用固定价格。它不会向 Econt 查询实时价格，不会生成运单或标签，不会预约快递员，不会追踪包裹，不会处理货到付款，也不会配送到具体地址。只有保加利亚和罗马尼亚有网点列表。
取件点
下单时，结账时所选的网点会随订单一起保存：城市、网点名称和地址，以及 Econt 网点代码。在 e-Econt 中创建发货单时请使用该网点代码。
顾客：网点会添加到订单的配送方式中，例如 Econt Express - Econt office / Econtomat: city, office (address)（最多 128 个字符；在 OpenCart 4 中文本不会被缩短）。因此它会显示在顾客的订单历史、订单邮件、发票和后台订单中。OpenCart 4 为结账保留一个订单，每当顾客再次确认时都会更新该订单，订单的网点也会随之更新。
后台订单页面：在 Sales > Orders 中，历史记录上方的 Econt office / Econtomat 面板会显示网点及其网点代码，即使该方式之后被禁用也是如此。点击 Change 后，选择订单所在国家的其他城市和网点，然后点击 Save。面板会显示 Saved.，订单的配送方式文本会更新，订单历史中会记录一条备注（不发送给顾客），注明原网点和新网点。如果您未选择网点就点击 Save，面板会显示 Select a city and an office first - nothing was changed. 不在订单所在国家列表中的网点会被拒绝，并提示 The selected Econt office is not available for the shipping country - nothing was changed. 任何拥有订单修改权限的管理员用户都可以更改网点；无需访问扩展设置。如果网点列表无法加载，面板会显示 Econt offices cannot be loaded right now. 没有网点的订单会显示 No Econt office is saved for this order.，并且日志中会有一条对应的错误记录。
当店铺语言为保加利亚语或罗马尼亚语时，网点名称以当地语言显示（保加利亚为西里尔字母）；否则使用英文。
许可证密钥
本扩展需要一个来自 vibefox.net 的 VibeFox 许可证密钥。License — VibeFox Econt 许可证区块位于 Extensions > Extensions > Shipping > VibeFox Econt > Edit 页面中设置的上方，是第一个区块。请将密钥输入 License key，然后点击 Activate。之后，该区块会以掩码形式显示密钥、状态（例如许可证有效期至何时以及您的域名），并提供 Check now（重新检查状态）、Change key（输入另一个密钥）和 Remove key（从本店铺移除密钥）按钮。其下方是 Product: opencart-shipping-econt 一行以及 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 账户中释放该名额。
没有有效密钥时，结账时顾客将看不到 Econt 配送方式，也不会计算任何运费。在 同一浏览器 中登录后台的管理员用户，仍会在店铺中看到该方式，并标注 (unlicensed — visible to admins only)，因此您可以在购买密钥之前设置并测试扩展。在 OpenCart 4 中，此预览不可用：店铺无法看到后台登录状态，因此没有有效密钥时，该方式对所有人都隐藏。您打开过一次 Edit 页面后，后台的 Dashboard 上会出现提醒。点击 × 可关闭它，并在 7 天内隐藏。现有订单不受影响。
许可证过期后，扩展仍会继续运行，但更新和支持需要续费。当您打开后台的 Dashboard 或 Edit 页面时，系统会自动重新检查状态：输入密钥后的前 14 天每天一次，之后每周一次。无需 cron 任务。卸载扩展时，始终会删除许可证密钥和许可证状态。
故障排除
结账时不显示 Econt：请检查许可证是否有效，Enable/Disable 是否已开启，以及配送国家是否为保加利亚或罗马尼亚（须在 System > Localisation > Countries 中启用）。检查 Geo zone（或 Ignore geo zone 和 Countries）、该国是否已设置价格、重量限制以及 Minimum subtotal。检查设置中的 Office list 一行：在该国没有网点列表期间，该方式会被隐藏。检查商品的 Requires Shipping 是否设为 Yes。
网点列表无法加载：点击 Load offices from Econt now 并查看结果，或设置页面顶部的警告。错误始终会写入日志；如需更多详细信息，请开启 Debug log 并查看 Log 字段。如果 Econt 要求您的店铺授权，请填写 Econt username 和 Econt password。
顾客看到测试网点：Demo API 已开启。在正式店铺中请将其关闭。
价格使用哪种货币？使用您店铺的默认货币，不含税。顾客会以其自身货币看到价格。
税费加在价格之上：已选择了税率类别。如果您的价格已包含增值税，请将 Tax class 设为 --- None ---。
页面显示 "Warning: You do not have permission to modify VibeFox Econt!"：您的管理员用户组可能只有查看设置的权限。请在 System > Users > User Groups 中，为该用户组授予 extension/shipping/vfd_econt（OpenCart 3）或 extension/vfd_econt/shipping/vfd_econt（OpenCart 4）的修改权限。
卸载
前往 Extensions > Extensions，选择类型 Shipping，然后点击 VibeFox Econt 旁边的 Uninstall（红色 − 按钮）。本扩展的许可证密钥和许可证状态始终会被删除。OpenCart 始终会重置 Enable/Disable、Sort order、Tax class 和 Geo zone。扩展始终会删除其事件和缓存的网点列表。如果 Remove data on uninstall 已开启，其他设置、日志以及未完成结账的选择记录也会被删除。如果关闭，设置会保留，并在您重新安装扩展时继续使用。订单中保存的网点始终会保留，现有订单也会保留其配送方式和费用。
在 OpenCart 4 中，如需同时删除扩展文件，请在卸载后前往 Extensions > Installer，在已安装扩展列表中点击 VibeFox Econt 旁边的 Uninstall（橙色 − 按钮），然后点击 Delete（红色垃圾桶按钮）以删除已上传的安装包。
Econt 是其各自所有者的商标。本扩展与 Econt 无关联，也未获得 Econt 的认可。