VibeFox Econt for PrestaShop — 帮助
系统要求
PrestaShop：8.0 至 9.x。
PHP：8.0 或更高版本。模块拒绝安装在更早的 PHP 版本上。
Econt：无需 Econt 合同或 API 密钥。网点列表是 Econt 公开的名录数据。仅向 Econt 发送国家代码，不发送顾客数据。仅当 Econt 要求您的店铺进行授权时，才需填写 e-Econt 用户名和密码。e-Econt 登录方式详见 Econt 开发者页面（econt.com/developers）。
VibeFox 许可证密钥：在 vibefox.net 购买。一个密钥仅适用于一个域名。
安装
1. 在后台依次进入 Modules > Module Manager，点击 Upload a module。选择模块的 ZIP 文件。
2. 上传完成后，点击 Configure；或之后在模块列表中找到 VibeFox Econt 并点击 Configure。
3. 在 Configure 页面顶部的许可证区块中，于 License key 处输入您的 VibeFox 许可证密钥，然后点击 Activate（参见许可证密钥）。
4. 设置各国运费并检查其他选项（参见配置），然后点击 Save。点击 Load offices from Econt now 测试连接。
安装时，模块会创建 Econt Express 承运商，配送时效文本为 Delivery to an Econt office or Econtomat。该承运商分配给保加利亚和罗马尼亚的区域以及所有客户组。您可以在 Shipping > Carriers 中更改区域、客户组、配送时效、徽标和尺寸限制。请勿在那里设置运费：价格始终由模块决定。
配置
所有设置都位于模块页面：Modules > Module Manager > VibeFox Econt > Configure。每个部分都有各自的 Save 按钮，点击后会保存整个页面。运费和条件适用于承运商的所有区域。
页面顶部，模块会显示以下警告：未找到 Econt 承运商、演示 API 已开启、未设置保加利亚或罗马尼亚的运费（此时承运商将始终不显示）、某国家最近一次网点请求失败，或模块无法识别店铺的重量单位（此时重量按千克计算；请在 International > Localization 的 Local units 中设置单位）。数字字段也接受逗号作为小数分隔符，例如 5,99。如果数字字段包含非数字或负数，或者 Minimum weight (kg) 大于 Maximum weight (kg)，错误提示会指出该字段，并且不会保存任何内容。
常规
Enable/Disable:开启或关闭 Econt 配送。这与 Shipping > Carriers 中的承运商状态是同一开关。
Name:在购物车和结账时显示的承运商名称。默认值：Econt Express。必填，最多 64 个字符。
Tax:承运商的税务规则，或 No tax。PrestaShop 会在下方的运费基础上加收此税。选择 No tax 时，运费即为最终价格。
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 并保存即可删除密码。
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（启用 Ignore zones 时，承运商区域以外的国家此时将没有运费）。格式不正确的条目会被忽略，并在保存时列入警告。其余内容仍会保存。
Calculation:Per order 只收取一次运费。Per item (price x quantity) 则将运费乘以需要配送的商品数量。
Price for other countries:用于上方未列出的 Econt 国家（保加利亚或罗马尼亚）。留空或填 0 将在该国家隐藏承运商。
条件
购物车小计是指需要配送的商品，在折扣之后、税费之前的金额。
Free shipping from:达到此购物车小计即免运费。留空则永不提供免运费。
Minimum subtotal:仅当购物车小计至少达到此金额时才显示承运商。留空则始终显示。
Minimum weight (kg):对较轻的购物车隐藏承运商。商品重量会从店铺的重量单位换算为千克。留空则不设上限。
Maximum weight (kg):对较重的购物车隐藏承运商。留空则不设上限。
无配送区域时的可用性
Ignore zones:当收货地址所在的区域未关联该承运商时，也向下列国家提供 Econt。开启后，承运商会关联到所有启用的区域，之后新建的区域也会自动关联。再次关闭时，承运商会恢复为之前所关联的区域。已关联的区域仍会照常运作。Econt 仍仅提供给保加利亚和罗马尼亚。
Countries:保加利亚和/或罗马尼亚。仅在启用 Ignore zones 时使用。若未勾选任何国家，则为店铺配送至的所有 Econt 国家。
高级
Debug log:将调试信息写入模块文件夹中的 logs/vfd_ecn_debug.log.php。该文件无法通过网页访问。API 错误始终会被记录。密码和顾客数据不会写入。
Log:显示日志的大小及最新条目。点击 Clear log 可清空日志。
Remove data on uninstall:开启时，卸载模块会删除 Econt 设置、承运商和日志。关闭时，设置会保留，以便重新安装时使用。订单中保存的网点始终会保留。
结账时的工作流程
该承运商仅提供给保加利亚和罗马尼亚。在配送步骤中，PrestaShop 会向模块请求 Econt 运费。只有实物商品才计入：虚拟商品不增加重量，也不计入小计。模块会检查重量限制和最低小计，然后获取该国家的运费。若购物车小计达到 Free shipping from，运费为 0。若该国家没有网点列表，则隐藏承运商，因为配送始终送达网点。运费先以默认货币计算，然后以顾客购物车的货币显示。
顾客选择 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 列表，而非浏览器。该选择器可用于 Classic 主题和 Hummingbird 主题。
网点列表缓存 24 小时，实时 API 和演示 API 分别缓存。若无法连接 Econt，则使用最近一次成功获取的列表，且 10 分钟内不再请求 Econt。API 超时时间为 15 秒。网点列表来源于 https://ee.econt.com/services/（实时）或 https://demo.econt.com/ee/services/（演示）。
如果订单产生后，您在 Shipping > Carriers 中编辑该承运商，PrestaShop 会将其保存为新的承运商版本。模块会自动跟随新版本。
模块仅使用固定运费。它不会向 Econt 查询实时运费，不会生成运单或标签，不会预约快递员，不跟踪包裹，不处理货到付款，也不送货上门。只有保加利亚和罗马尼亚有网点列表。
取件点
下单时，购物车所选的网点会与订单一同保存：城市、网点名称和地址，以及 Econt 网点代码。在 e-Econt 中创建发货单时请使用该网点代码。
后台订单页面：一个 Econt office / Econtomat 区块会显示网点和 Office code。在 Change 下，选择订单所在国家的其他城市和网点，然后点击 Save。更改会立即保存，并且一条私密订单留言会记录旧网点和新网点。如果未选择网点就点击 Save，区块会显示 Select a city and an office first - nothing was changed. 任何有权编辑订单的员工都可以更改网点；无需访问模块页面。若网点列表无法加载，区块会显示 Econt offices cannot be loaded right now.
同一购物车产生的多个订单：网点归属于第一个订单。从同一购物车下的其他订单不会获得网点：日志中会记录一条错误，且其区块会提示该购物车的网点属于另一个订单。请与顾客确认网点，并在 e-Econt 中手动创建发货单。
顾客：网点会显示在顾客的订单页面和订单确认页面上，并会添加到订单确认电子邮件以及发给店铺的新订单电子邮件中的承运商名称里。
当店铺语言为保加利亚语或罗马尼亚语时，网点名称以当地语言显示（保加利亚为西里尔字母）；其他情况下以英文显示。
许可证密钥
本模块需要一个来自 vibefox.net 的 VibeFox 许可证密钥。许可证区块 License — VibeFox Econt 位于 Modules > Module Manager > VibeFox Econt > Configure 页面的最顶部，在设置上方。将密钥输入 License key 并点击 Activate。之后，该区块会显示已遮蔽的密钥、状态（例如许可证有效期截止日期和您的域名），以及以下按钮：Check now（重新检查状态）、Change key（输入其他密钥）和 Remove key（从本店铺移除密钥）。其下方是一行 Product: presta-shipping-econt 以及链接 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 账户中释放名额。
如果没有有效密钥，Econt 承运商不会在结账时向顾客显示，也不会计算运费。PrestaShop 前台无法识别您已登录后台，因此您自己也看不到该承运商：您可以在购买密钥前设置模块，但无法在结账时测试。Modules > Module Manager 的 Alerts 选项卡中会出现提醒。已有订单不受影响。
许可证到期后，模块仍会继续运行，但更新和支持需要续费。在您使用后台期间，系统会自动重新检查状态：输入密钥后的前 14 天内每天一次，之后每周一次。无需 cron 任务。卸载或重置模块时，始终会删除许可证密钥和许可证状态。
故障排除
结账时未显示 Econt：请检查许可证是否有效、Enable/Disable 是否开启，以及配送国家是否为保加利亚或罗马尼亚。在 Shipping > Carriers 中，检查该承运商是否覆盖客户所在国家的区域以及客户组（或开启 Ignore zones 并检查 Countries）。检查是否已为该国家设置运费、重量限制以及 Minimum subtotal。检查设置中的 Office list 一行：若该国家没有可用的网点列表，承运商会被隐藏。此外，也可以在商品页面中将商品限制为特定承运商。
网点列表无法加载：点击 Load offices from Econt now 并查看结果，或查看设置页面顶部的警告。错误始终会写入日志；开启 Debug log 可获取更多详细信息，并查看 Log 字段。若 Econt 要求您的店铺进行授权，请填写 Econt username 和 Econt password。
顾客看到的是测试网点：Demo API 已开启。请在正式店铺中将其关闭。
运费使用哪种货币？使用店铺默认货币，不含税。顾客会以其购物车货币看到运费。
税费加在运费之上：承运商设有税务规则。若您的运费已包含增值税，请将 Tax 设置为 No tax。
页面显示未找到 Econt 承运商：该承运商已在 Shipping > Carriers 中被删除。请在 Modules > Module Manager 中重置模块，以重新创建。
卸载
进入 Modules > Module Manager，打开 VibeFox Econt 旁边的菜单，选择 Uninstall。许可证密钥和许可证状态始终会被删除。缓存的网点列表始终会被删除。若 Remove data on uninstall 已开启，承运商会被删除（订单保留其历史记录），设置和日志也会被删除。若关闭，承运商仅会被停用，所有设置都会保留。再次安装模块时，会恢复已保存的承运商及其原有状态。重置模块会保留当前承运商状态。订单中保存的网点始终会保留。
Econt 是其各自所有者的商标。本模块与 Econt 无关联，也未获得 Econt 的认可。