VibeFox Chilexpress for PrestaShop — 帮助
系统要求
PrestaShop：8.0 至 9.x。
PHP：8.0 或更高版本，实时运费需要 cURL 扩展。模块不会安装在较旧的 PHP 版本上。
Chilexpress API 密钥（仅用于实时运费）：在 Chilexpress 开发者门户（developers.wschilexpress.com）创建账户，并订阅两个产品：Rating（Cotizador）和 Coverage（Coberturas / Georreferencia）。每个产品都有各自的订阅密钥。测试密钥仅适用于测试环境；生产密钥发给签有客户合同的 Chilexpress 企业客户。您还需要发货所在 comuna 的 Chilexpress county 代码，例如 STGO。如果您只使用固定价格，则不需要 API 密钥。
智利地区（仅用于实时运费）：实时运费需要收货地址的地区。PrestaShop 默认没有智利地区；模块可以为您添加（见下文 Chilean regions）。店铺中必须存在智利国家。
VibeFox 许可证密钥：在 vibefox.net 购买。一个密钥只能用于一个域名。
安装
1. 在后台进入 Modules > Module Manager，点击 Upload a module。选择模块的 ZIP 文件。
2. 上传完成后，点击 Configure，或以后在模块列表中找到 VibeFox Chilexpress 并点击 Configure。
3. 在 Configure 页面顶部的许可证区块中，将您的 VibeFox 许可证密钥粘贴到 License key 中，然后点击 Activate（见许可证密钥）。
4. 填写 Country prices 表格。如需实时运费，请输入两个订阅密钥、发货的 origin county 代码，并且如果店铺货币不是 CLP，还需输入 CLP 汇率；如果页面提示，点击 Add Chilean regions；然后选择运费来源（见配置）并点击 Save。
安装时，模块会创建 Chilexpress 承运商，配送时间文本为 Chilexpress courier。该承运商关联智利区域和所有客户组。您可以在 Shipping > Carriers 中更改区域、客户组、配送时间、图标和尺寸限制。不要在那里设置价格：价格始终来自模块。如需在其他区域提供 Chilexpress，请在该页面将其添加到承运商，或开启 Ignore shipping zones。
配置
所有设置都在模块页面：Modules > Module Manager > VibeFox Chilexpress > Configure。每个部分都有自己的 Save 按钮，它会保存整个页面。每次保存还会清除缓存的 Chilexpress 运费和 comuna 列表。修改需要该模块的 "configure" 权限；没有该权限时，页面会显示 You do not have permission to configure this module.
页面顶部会列出问题：已选择 API 运费，但缺少密钥、origin county 代码或 CLP 汇率；价格表中没有智利或默认的行；店铺没有智利地区，或智利地址表单中没有地区字段；模块无法识别店铺的重量或尺寸单位（此时将按千克或厘米读取；请在 International > Localization 的 Local units 中设置）；承运商已被删除。数字可以用小数点或逗号输入，与后台语言的习惯一致。无效或负数、为 0 的 CLP exchange rate、大于 Max weight (kg) 的 Min weight (kg)，或超过 64 个字符的 Name 都属于错误，在您更正之前不会保存任何内容。
常规
Enable/Disable：开启或关闭 Chilexpress 配送。这与 Shipping > Carriers 中的承运商状态是同一个开关。
Name：结账时顾客看到的配送方式名称，也就是承运商名称。默认：Chilexpress。必填，最多 64 个字符。
Tax：承运商的税务规则，或 No tax（新承运商的默认值）。Chilexpress API 运费按报价原样使用。如果报价已包含 IVA，而您的店铺会在其上再加税，请选择 No tax。
运费
Rate source：价格来源。
实时运费仅适用于智利境内的目的地。其他国家始终使用固定价格。
Country prices：目的国家表格，包含 Price 列以及可选的按包裹尺寸计的价格，使用店铺默认货币，不含税。尺寸根据购物车重量确定：1 千克以内为 XS，2 千克以内为 S，3 千克以内为 M，5 千克以内为 L，超过 5 千克为 XL。尺寸保持为 0 时使用 Price。点击 Add country 添加一行，点击垃圾桶图标删除一行。* Default 行适用于没有自有行的国家。没有行（且没有 * Default）的国家没有固定价格，因此该承运商在那里会被隐藏。价格和尺寸价格均为 0 的行表示免运费。空表格会显示一行智利且价格为 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 服务。如果目的地不提供该服务，则使用报价最便宜的可用服务。
CLP exchange rate：Chilexpress 以智利比索报价。仅当店铺默认货币不是 CLP 时才需要：1 CLP 以该货币表示的价格，例如 0.001。未设置时不使用 API 运费。如果店铺货币是 CLP，请留空。该值必须大于 0。
Chilean regions：智利的 comuna 按地区查找，因此实时运费需要地址的地区。如果店铺没有智利地区，该字段会显示 Add Chilean regions 按钮。它会将 16 个地区作为智利的州添加（ISO 代码 RM、VS…），为智利开启 "Contains states"，并将地区字段添加到智利地址表单中。已存在的地区（按代码或名称判断）不会重复添加。一切就绪后，该字段会显示 Chilean addresses have a region 以及地区数量。
可用性
Min weight (kg)：承运商出现所需的最低购物车重量。0 表示没有限制。
Max weight (kg)：购物车重量超过此值时，承运商会被隐藏。默认：25。0 表示没有限制；字段为空表示 25 千克。Min weight (kg) 不能大于此值。
Minimum subtotal：仅当购物车小计（需要配送的商品，扣除折扣后，不含税）至少达到此金额时才显示承运商。留空则始终显示。
Ignore shipping zones：即使下列国家所在的区域未与该承运商关联，也为这些国家提供该承运商：承运商会关联所有区域，之后创建的区域也会被关联。关闭时，承运商会恢复其之前的区域。
Countries：该模式的目的国家，从店铺的启用国家中选择。留空则允许所有国家。仅在开启 Ignore shipping zones 时使用此字段。
免运费
Free shipping：开启免运费门槛。
Free shipping from：购物车小计（需要配送的商品，扣除折扣后，不含税）达到该金额后免运费。仅在开启 Free shipping 时使用。在这种情况下不会向 API 发送请求。
高级
Debug log：将 API 请求和运费计算写入模块文件夹中的 logs/vfd_chx_debug.log.php。该文件无法通过网页打开。即使关闭此选项，API 错误也始终会被记录。API 密钥和顾客地址绝不会被记录。
Log：显示调试日志的大小和最新条目。点击 Clear log 可清空。
Remove data on uninstall：开启时，卸载模块会删除所有模块设置、承运商、缓存的运费、日志以及随订单保存的服务。关闭时，所有内容都会保留，以便重新安装。订单本身始终会保留。
结账时的工作方式
在配送步骤，PrestaShop 会向模块请求 Chilexpress 价格。只有需要配送的商品才计算在内：虚拟商品不增加重量，也不计入小计。小计是在购物车规则（优惠券）之后计算的，不含税，以店铺默认货币计。模块首先检查条件：允许的国家（结合 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 千克）、包裹尺寸（最大商品的长和宽，高度叠加），以及以 CLP 计的购物车小计作为申报价值。Chilexpress 返回其服务；模块使用所选服务或最便宜的服务，并将比索金额换算为店铺默认货币。价格按该货币的小数位数进行四舍五入，然后以顾客的购物车货币显示。
运费缓存 1 小时，comuna 列表缓存 7 天。失败的请求会记住 5 分钟，因此缓慢或不可用的 API 不会拖慢每次结账页面刷新。API 超时时间为 10 秒。如果 Chilexpress 返回错误、没有带价格的服务，或者 comuna 或地区无法识别，顾客不会看到任何错误。在仅 API 模式下，承运商会被隐藏；否则使用固定价格。原因会写入调试日志。
如果您在订单产生后，在 Shipping > Carriers 中编辑了承运商，PrestaShop 会将其保存为承运商的新版本。模块会自动跟随新版本。
模块只计算运费。它不会创建发货单或运输订单（OT），不打印面单，不预约取件，也不跟踪包裹；请在您的 Chilexpress 账户中预订发货。顾客无法选择 Chilexpress 网点，也没有 comuna 选择器：顾客在标准的 City 字段中输入 comuna。国际配送使用固定价格。
订单
使用 Chilexpress 承运商下单时，模块会保存其价格的计算方式。后台的订单页面会显示 Chilexpress 区块，其中包括 Chilexpress service（如果是实时运费，则为 Chilexpress 报价的服务，例如 Express）和 Price source：Live rate (Chilexpress Rating API)、Fixed price 或 Free shipping。
许可证密钥
模块使用来自 vibefox.net 的 VibeFox 许可证密钥。模块 Configure 页面上方的许可证区块 License — VibeFox Chilexpress 位于 Modules > Module Manager > VibeFox Chilexpress > Configure 中，位于设置上方。将密钥粘贴到 License key 中，然后点击 Activate。之后，该区块会以掩码形式显示密钥、状态（例如许可证有效期截止日期和您的域名），以及以下按钮：Check now（重新检查状态）、Change key（输入其他密钥）和 Remove key（从此店铺中移除密钥）。其下方是 Product: presta-shipping-chilexpress 一行，以及打开您 vibefox.net 账户的链接 Manage licenses and domains in your account。只有拥有该模块 Configure 权限的员工才能更改密钥。该区块的文本跟随后台语言（包括英文和俄文）。
如果密钥未被接受，区块会说明原因，例如 Key not found、This key belongs to another product、Domain limit reached，或 License expired on 加某个日期。店铺地址更改后，或在您的账户中释放了一个域名名额后，请点击 Check now。如果无法连接许可证服务器，模块会继续使用最后已知的状态运行。
一个密钥只能用于一个域名：主店铺的域名，多店铺配置中同样如此。从店铺中移除密钥不会释放其域名名额。请在您的 vibefox.net 账户中释放名额。
没有有效密钥时，结账时不会向顾客显示 Chilexpress 承运商，也不会计算运费。PrestaShop 前台无法得知您已登录后台，因此承运商对您也会隐藏：您可以在购买密钥前设置模块，但无法在结账时测试。Modules > Module Manager 的 Alerts 标签页会出现一条提醒。现有订单不受影响。
许可证到期后，模块仍会继续运行，但更新和支持需要续费。在您使用后台期间，系统会自动重新检查状态：输入密钥后的前 14 天每天一次，之后每周一次。无需 cron 任务。卸载或重置模块时，始终会删除许可证密钥和许可证状态。
故障排除
结账时不显示 Chilexpress：检查许可证是否有效，以及 Enable/Disable 是否已开启。在 Shipping > Carriers 中，检查承运商是否覆盖顾客所在国家的区域和顾客的客户组（或者已开启 Ignore shipping zones 且该国家在 Countries 中）。检查重量限制和 Minimum subtotal。使用固定价格时，检查该国家或 * Default 是否有一行。商品也可能在商品页面中被限制为特定承运商。
智利的配送应收费却免费：Country prices 中智利（或 * Default）那一行的 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 设为 No tax。
修改后运费看起来过时：在模块页面点击 Save。这会清除缓存的运费和 comuna 列表。
页面提示 "The Chilexpress carrier was not found"：承运商已在 Shipping > Carriers 中被删除。请在 Modules > Module Manager 中重置模块以重新创建。
页面提示 "The country Chile does not exist in this shop"：请在 International > Locations > Countries 中添加或启用智利，然后使用 Add Chilean regions。
卸载
进入 Modules > Module Manager，打开 VibeFox Chilexpress 旁边的菜单，然后选择 Uninstall。许可证密钥和许可证状态始终会被删除。缓存的运费和 comuna 列表始终会被删除。如果 Remove data on uninstall 已开启，承运商会被删除（订单保留其历史记录），并且设置、日志以及随订单保存的服务也会被删除。如果已关闭，承运商仅会被停用，所有设置都会保留。重新安装模块会恢复已保存的承运商及其之前的状态。通过 Add Chilean regions 添加的智利地区会保留在店铺中。
Chilexpress 是其各自所有者的商标。本模块与 Chilexpress 没有关联，也未获得 Chilexpress 的认可。