VibeFox Chilexpress for OpenCart — 帮助

系统要求

OpenCart: 3.0.x（已在 3.0.5.0 上测试）或 4.0.2 及更高版本（已在 4.1.0.3 上测试）。

PHP: 8.0 或更高版本。

Chilexpress API 密钥（仅用于实时运费）：在 Chilexpress 开发者门户（developers.wschilexpress.com）创建账户，并订阅两个产品：Rating (Cotizador) 和 Coverage (Coberturas / Georreferencia)。每个产品都有自己的订阅密钥。测试密钥仅适用于测试环境；正式密钥仅发放给签订了合同的 Chilexpress 企业客户。您还需要发货所在 comuna 的 Chilexpress county 代码，例如 STGO。如果只使用固定价格，则无需 API 密钥。

智利地区（仅用于实时运费）：实时运费需要配送地址的地区（区域）。OpenCart 3.0.5.0 包含智利 16 个地区中的 15 个；扩展可以添加缺少的地区（见下文 Chilean regions）。店铺中必须存在智利这一国家。

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

安装

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

OpenCart 3

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

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

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

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

5. 填写 Country prices 表格。如需实时运费，请输入两个订阅密钥、发货地的 county 代码，若店铺币种不是 CLP，还需输入 CLP 汇率；如果页面显示缺少的地区，请点击 Add Chilean regions，然后选择运费来源（见配置）。开启 Enable/Disable 并点击 Save。

OpenCart 4

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

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

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

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

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

配置

所有设置都位于扩展页面：Extensions > Extensions > Shipping > VibeFox Chilexpress > Edit。各个部分列在左侧。页面底部的一个 Save 按钮可在不重新加载页面的情况下保存整个页面。保存后您会看到 Settings saved. Cached Chilexpress rates and comuna lists were cleared. 只有拥有本扩展修改权限的管理员用户才能保存设置、清除日志或添加地区。

页面顶部会列出问题：已选择 API 运费但 Rating API 密钥为空；Coverage API 密钥为空；发货地 county 代码为空或无效；店铺币种不是 CLP 且未设置 CLP 汇率；Country prices 中没有智利或默认值的行；店铺中智利没有任何区域；扩展无法识别店铺的重量或长度单位（此时重量按 kg、尺寸按 cm 读取；请在 System > Localisation 中使用 kg、g、lb 或 oz 以及 cm、mm、m 或 in）。数字可以用小数点或逗号输入。如果 Name 为空、包含字符 < > ; = # { } 之一或超过 64 个字符，某个数字无效或为负数，CLP exchange rate 为 0，Min weight (kg) 大于 Max weight (kg)，Origin county code 不是 county 代码，或 Sort order 不是整数，则不会保存任何内容，页面会列出错误。

通用

每个地理区域对应一个 "Chilexpress" 配送方式；或仅对 Availability 下选定的地理区域提供。

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

Name:结账时显示给顾客的配送方式名称。默认：Chilexpress。必填，最多 64 个字符。

Tax class:运费的税类，或 No tax（默认）。Chilexpress API 运费按报价原样使用。如果报价已包含 IVA，而您的店铺会再额外加税，请选择 No tax。

Sort order:Chilexpress 在结账配送方式中的位置。一个整数。

运费

Rate source:价格的来源。

Fixed prices (Country prices below):价格来自 Country prices 表格。无需 API 密钥。这是默认选项。

Chilexpress API (method hidden when the API has no rate):向 Chilexpress 请求价格。如果 Chilexpress 对某个智利地址没有返回运费，则该购物车隐藏此方式。

Chilexpress API, fixed price if the API fails:向 Chilexpress 请求价格。如果没有运费，则使用固定价格。

实时运费仅适用于智利境内的目的地。其他国家始终使用固定价格。

Country prices:目的国家列表，包含 Price 列以及按包裹尺寸的可选价格，使用店铺默认币种，不含税。尺寸由购物车重量决定：XS 为 1 kg 以下，S 为 2 kg 以下，M 为 3 kg 以下，L 为 5 kg 以下，XL 为 5 kg 以上。尺寸价格保持为 0 时使用 Price。点击 Add country 添加一行。* Default (other countries) 行适用于没有单独行的国家。没有行（也没有默认行）的国家没有固定价格，因此该方式在该国家被隐藏。已保存且价格及各尺寸价格均为 0 的行表示免运费。空表格会显示一行智利且价格为 0，因此保存页面前请输入真实价格。重复的国家或无效价格会被自动修正（忽略重复项，价格设为 0），并有警告列出修正内容。

Calculation type:Per order（默认）只收取一次固定价格。Per item (fixed price x number of items) 会将其乘以购物车中的商品数量。Chilexpress API 运费始终按整个包裹报价。

Chilexpress API（实时运费）

本部分开头是开发者门户以及 Rating 和 Coverage 订阅页面的链接。

Test environment:使用 Chilexpress 测试环境（qaservices.wschilexpress.com）。请配合测试密钥使用，并在正式店铺中关闭。默认：关闭。

Rating API key:Rating (Cotizador) 产品的订阅密钥。

Coverage API key:Coverage (Coberturas / Georreferencia) 产品的订阅密钥。用于查找顾客 comuna 的 Chilexpress county 代码（即地址的 City 字段及其地区）。

保存后，密钥字段保持为空，并显示 Saved — leave empty to keep it. 只有在需要更改时才输入新值。密钥按您输入的内容保存，仅去除首尾空格。

Remove the saved Rating API key 和 Remove the saved Coverage API key:开启其中一个并点击 Save，即可删除该密钥。

Origin county code:您发货所在 comuna 的 Chilexpress county 代码，2–5 个字母，例如 STGO（Santiago Centro）、PROV（Providencia）或 VALP（Valparaíso）。安装后为空。不是 county 代码的值会被拒绝并显示错误。

Service:用于计算运费的 Chilexpress 服务。如果目的地不提供该服务，则使用可提供的最便宜服务。

Cheapest available:Chilexpress 提供的最便宜服务。

Prioritario (next business day, before 11:00)

Express (next business day):默认选项。

Extendido (1-2 business days)

Extremos (2-3 business days, remote areas)

CLP exchange rate:Chilexpress 以智利比索报价。仅当店铺默认币种不是 CLP 时需要：该币种下 1 CLP 的价格，例如 0.001。没有它则不使用 API 运费。若店铺币种为 CLP，请留空。该值必须大于 0。

Chilean regions:智利的 comuna 按地区查询，因此实时运费需要地址的地区（区域）。该字段显示智利有多少个区域以及缺少哪些地区，并附有 Add Chilean regions 按钮。它只会将缺少的地区添加为智利的区域；现有区域不会改变，同一地区也不会被重复添加。当 16 个地区全部就位时，该字段显示 All 16 Chilean regions are zones of Chile。如果智利不是店铺的国家，字段会提示：请在 System > Localisation > Countries 中添加。

可用性

Min weight (kg):方式显示所需的最低购物车重量。0 表示无限制（默认）。

Max weight (kg):购物车重量超过此值时隐藏该方式。默认：25。0 表示无限制；字段为空时表示 25 kg。

Minimum subtotal:仅当购物车小计（需配送的商品，扣除优惠券后，不含税）不低于此金额时显示该方式。留空则始终显示。

Geo zone:仅对该地理区域内的地址提供此方式。All zones（默认）表示无限制。地理区域在 System > Localisation > Geo Zones 中管理。当 Ignore shipping zones 开启时不使用。

Ignore shipping zones:对下方列出的国家提供此方式，不检查地理区域。

Countries:该模式下的目的国家。留空则允许所有国家。仅当 Ignore shipping zones 开启时使用此字段。

免运费

Free shipping:开启免运费门槛。

Free shipping from:购物车小计（需配送的商品，扣除优惠券后，不含税）达到该金额即免运费。仅在 Free shipping 开启时使用。此时不会向 API 发出请求。

高级

Debug log:将 API 请求和运费计算写入 storage/logs/vfd_chx_debug.log.php。该文件无法通过网页读取。即使此选项关闭，API 错误也始终会被记录。API 密钥和顾客地址从不记录。文件达到 5 MB 时，会被移至 vfd_chx_debug.old.log.php，并开始新的日志。

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

Remove data on uninstall:开启后，卸载扩展会删除其所有设置、缓存运费和日志。关闭时（默认），所有内容都会保留，以便重新安装。与订单一起保存的 Chilexpress 服务始终保留。

导入 / 导出

Export:点击 Download JSON，将设置保存为 JSON 文件。API 密钥不会被导出。

Import:粘贴之前导出的 JSON，然后点击 Import，即可恢复设置，例如在另一家店铺中使用。这些值的检查方式与普通保存相同。已保存的 API 密钥会被保留。

结账时的工作方式

OpenCart 显示配送方式时，会向扩展请求 Chilexpress 价格。如果设置了 Geo zone、Ignore shipping zones 关闭且地址在该区域之外，则不提供 Chilexpress。只有 Requires Shipping 设为 Yes 的商品才会计入：其他商品不增加重量，也不计入小计。重量会根据商品的重量和长度类别换算为千克，尺寸换算为厘米。小计是需配送商品的价格，扣除优惠券折扣后、不含税，并以店铺默认币种计算。礼品卡、奖励积分和店铺余额不计入。扩展会先检查条件：允许的国家（配合 Ignore shipping zones）、购物车重量和最低小计。如果适用免运费，价格为 0，并且不会向 Chilexpress 发出任何请求。

对于智利地址且运费来源为 API 的情况，扩展会从 City 字段获取地址的地区（区域）和 comuna，并在该地区的 comuna 列表中查找 Chilexpress county 代码（Coverage API）。重音符号、空格和拼写变体会被忽略，因此 Ñuñoa 与 Nunoa 匹配，Santiago 与 Santiago Centro 匹配。在 City 字段中输入的 county 代码也会被接受。然后扩展会向 Rating API 发送发货地和目的地的 county 代码、购物车重量（至少 0.1 kg）、包裹尺寸（最大商品的长和宽，高度叠加）以及以 CLP 计的购物车小计作为申报价值。Chilexpress 返回其服务；扩展使用所选服务或最便宜的服务，并将比索金额换算为店铺默认币种。价格会按该币种的小数位数取整，然后以顾客的币种显示，并附加所选 Tax class 的税费。

运费缓存 1 小时。comuna 列表最长缓存 7 天，但不会超过 OpenCart 缓存其条目的时间（默认 1 小时）。失败的请求会被记住 5 分钟，因此缓慢或不可用的 API 不会拖慢每次结账页面刷新。API 超时时间为 10 秒。如果 Chilexpress 返回错误、没有带价格的服务，或 comuna 或地区未知，顾客不会看到任何错误。在仅 API 模式下，该方式会被隐藏，或使用固定价格。原因会写入调试日志。

扩展只计算运费。它不创建发货单或运输订单（OT），不打印面单，不预约取件，也不跟踪包裹；请在您的 Chilexpress 账户中预订发货。顾客无法选择 Chilexpress 网点，也没有 comuna 选择器：顾客在标准 City 字段中输入 comuna。国际发货使用固定价格。

在 OpenCart 4 上，顾客在结账页面的配送方式区块中点击 Choose，并在 Shipping method options 窗口中选择 Chilexpress，例如 Chilexpress - $5.49。该方式的工作方式与 OpenCart 3 相同。

订单

使用 Chilexpress 下单时，扩展会保存其运费的计算方式。在 Sales > Orders 中，订单页面会显示 Chilexpress 面板，包含 Chilexpress service（实时运费时为 Chilexpress 报价的服务，例如 Express；否则为短横线）以及 Price：Live rate (Chilexpress Rating API)、Fixed price 或 Free shipping。即使该方式已关闭，该面板仍会显示。在 OpenCart 4 上，Chilexpress 面板显示在 History 上方；当订单在结账时被重新确认，或更改为其他配送方式时，面板会随之更新。

许可证密钥

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

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

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

故障排除

Chilexpress 没有出现在结账页面：请检查许可证是否有效以及 Enable/Disable 是否开启。检查 Geo zone（或 Ignore shipping zones 和 Countries）、重量限制以及 Minimum subtotal。使用固定价格时，请确认该国家或 * Default (other countries) 有一行。请确认商品的 Requires Shipping 设为 Yes。

智利境内的运费为免费，但实际不应免费：智利的 Country prices 行（或默认行）在 Price 和尺寸列中为 0。请输入价格并点击 Save。

未显示实时运费，改用固定价格：请先检查扩展页面顶部的警告。否则开启 Debug log，刷新结账页面，并查看扩展页面上的 Log 字段。常见原因：地址没有地区，或智利缺少地区（请使用 Add Chilean regions）；Chilexpress 无法识别的 comuna（请检查 City 字段和地区）；使用了错误产品或环境的密钥；或目的地没有 Chilexpress 覆盖。

日志中出现 HTTP 401 或 403：订阅密钥错误、未激活，或属于其他产品或环境。测试密钥仅在 Test environment 开启时有效。

使用其他币种的店铺未采用 API 运费：请输入 CLP exchange rate。

API 运费包含 IVA 还是不包含？它们按 Chilexpress 的报价原样使用。如果您的店铺对运费加税，而报价已包含 IVA，请将 Tax class 设为 No tax。

更改后运费似乎过时：请在扩展页面点击 Save。这会清除缓存的运费和 comuna 列表。

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

面向开发者：Chilexpress API 的基础地址可以通过设置 vfd_chx_api_base_url（用于测试）替换；设置页面上没有对应字段。

卸载

进入 Extensions > Extensions，选择类型 Shipping，然后点击 VibeFox Chilexpress 旁边的 Uninstall（红色 − 按钮）。本扩展的许可证密钥和许可证状态总会被删除。OpenCart 总会重置 Enable/Disable、Sort order、Tax class 和 Geo zone。缓存的运费和 comuna 列表总会被删除。如果 Remove data on uninstall 开启，其他设置和调试日志也会被删除。如果关闭，这些内容会保留，并在您重新安装扩展时再次使用。与订单一起保存的 Chilexpress 服务永远不会被删除，现有订单也会保留其配送方式和运费。通过 Add Chilean regions 添加的智利地区会保留在店铺中。

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

Chilexpress 是其各自所有者的商标。本扩展与 Chilexpress 没有关联，也未获得 Chilexpress 的认可。