VibeFox Andreani for OpenCart — 帮助
系统要求
OpenCart：3.0.x（已在 3.0.5.0 上测试）或 4.0.2 及更高版本（已在 4.1.0.3 上测试），使用默认主题。
PHP：8.0 或更高版本。
Andreani 账户（仅用于实时运费）：实时运费使用 Andreani 报价 API。Andreani 会向企业客户提供 API 凭据、客户代码和合同编号，通常在每月约 300 票发货量起。请访问 developers.andreani.com 或写信至 ventapyme@andreani.com。您需要 API 用户名和密码、客户代码（código de cliente）以及合同编号。Andreani 会为每项服务（送货上门、网点自取）分别签发合同。没有 API 访问权限时，请使用固定价格。网点选择器无需凭据即可使用。
VibeFox 许可证密钥：在 vibefox.net 购买。一个密钥只能用于一个域名。
安装
下载包是一个 zip 文件，包含两个 OpenCart 版本的安装包。请先解压到您的电脑上。其中包含 README.txt、OpenCart 3 安装包 vfd_andreani-oc3-(version).ocmod.zip 和 OpenCart 4 安装包 vfd_andreani.ocmod.zip。只需安装与您的 OpenCart 版本对应的安装包。两个版本的许可证密钥相同。
OpenCart 3
1. 在管理后台进入 Extensions > Installer，点击 Upload，然后选择文件 vfd_andreani-oc3-(version).ocmod.zip。该扩展不添加任何 OCMOD 修改，因此无需刷新 Extensions > Modifications。您也可以不使用 Installer，而将本安装包中 upload 文件夹的内容复制到商店的根目录。
2. 进入 Extensions > Extensions，选择扩展类型 Shipping。找到 VibeFox Andreani，点击 Install（绿色 + 按钮）。
3. 点击 Edit（铅笔按钮）打开设置页面。
4. 在 Edit 页面顶部的 License key 许可证块中输入您的 VibeFox 许可证密钥，然后点击 Activate（参见许可证密钥）。
5. 设置名称、运费来源、各国价格（例如 AR=5000），如果使用实时运费，还需设置 API 凭据、客户代码和合同编号（参见配置）。点击 Save。
OpenCart 4
1. 在管理后台进入 Extensions > Installer，点击 Upload，然后选择文件 vfd_andreani.ocmod.zip。请勿重命名该文件：OpenCart 4 会从文件名获取扩展代码，重命名后的安装包将无法使用。
2. 安装包会出现在同一页面已安装扩展的列表中。点击其旁边的 Install（绿色 + 按钮）。
3. 进入 Extensions > Extensions，选择扩展类型 Shipping。找到 VibeFox Andreani，点击 Install（绿色 + 按钮），然后点击 Edit（铅笔按钮）。
4. 按照 OpenCart 3 的步骤 4 和 5 输入许可证密钥和设置。两个版本的设置页面及其字段相同。
安装后，Enable/Disable 和 Enable second option 均为关闭状态，在您开启某个选项并点击 Save 之前，Andreani 不会在结账时提供。如果卸载后重新安装该扩展，将重新使用您保留的 Andreani 设置，但两个选项仍为关闭状态：请将其开启并点击 Save。
配置
所有设置都位于扩展页面：Extensions > Extensions > Shipping > VibeFox Andreani > Edit。各分区列在左侧。点击一次 Save 即可保存整个页面，且无需重新加载。保存后您会看到 Settings saved. Cached token, branches and rates were cleared. 只有拥有该扩展修改权限的管理员用户才能保存设置。
页面顶部会显示缺少设置的警告：选择了 API 运费但未填写 API 用户名和密码，或未填写合同编号；商店货币不是 ARS 但未设置 ARS exchange rate；或 Country prices 中没有阿根廷的价格。如果扩展无法识别商店的重量或尺寸单位，也会显示警告（此时重量按 kg、尺寸按 cm 读取）。
保存时，以下情况会被拒绝且不会保存任何内容：名称为空、名称超过 64 个字符或包含字符 < > ; = # { }；Min weight (kg) 大于 Max weight (kg)；或 Sort order 不是整数。非数字值、负数或 0 及以下的 ARS exchange rate 不会被保存，警告会指出对应字段。
常规
Andreani 在结账时提供两个选项：此处以及 Andreani API 和 Delivery and rates 中设置的主选项，以及 Second option。两者都会在配送方式步骤中显示在 Andreani 标题下。
Enable/Disable：开启或关闭 Andreani 主选项。默认：关闭。第二选项有自己的开关。
Name：顾客在结账时看到的主选项名称。默认：Andreani。必填。
Tax status：None (the API rate is taken with IVA)（默认），或您的某个税率类别。选择税率类别后，OpenCart 会在运费上加收税费，因此 API 运费按不含 IVA 计取。选择 None 时，API 运费按含 IVA 计取。两个选项均使用此设置。
Sort order：Andreani 在结账时配送方式中的排列位置。整数。
Andreani API（实时运费需要）
Environment：Sandbox / QA (apisqa.andreani.com)（默认）或 Production (apis.andreani.com)。请使用您的凭据所属的环境。
API username：您的 Andreani API 用户名。
API password：您的 Andreani API 密码。保存后，该字段保持为空，并显示 Saved - leave empty to keep it. Clearing the API username removes it too. 只有需要更改时才输入新值。
Client code：Andreani 提供的客户代码（código de cliente），例如 CL0000000。
Contract number：用于运费的服务合同，例如送货上门。第二选项可以使用其他合同，例如网点自取。
Origin branch code：用于运费报价的可选发货网点（sucursalOrigen）。留空则使用您合同中配置的网点。
配送与运费
Delivery modality：主选项的配送方式。第一部分说明 Andreani 在何处取件（您的地址，或您投递包裹的网点）。第二部分说明顾客在何处取得包裹。
Rate source：价格的计算方式。
Country prices：按目的国家设置的固定价格，以商店默认货币计算，不含税，每行一个国家，格式为 CC=PRICE，例如 AR=5000。用于固定模式以及 API 回退。没有对应行的国家不提供固定价格。格式不正确的行会被忽略，保存时警告会列出它们。
ARS exchange rate：Andreani 以阿根廷比索报价。仅当商店默认货币不是 ARS 时需要：即 1 ARS 相当于的商店货币金额，例如 0.001。未设置时，不使用 API 运费。
Default product weight (kg)：用于请求 API 运费和检查重量限制时，没有重量的商品所使用的重量。留空表示 0.5 kg。
Calculation type：Per order（默认）只收取一次价格。Per item (price x number of items) 将 Country prices 中的固定价格乘以购物车中的商品数量。Andreani 的实时运费已针对整个购物车，不会再乘以数量。
可用性
Min weight (kg)：选项显示所需的最低购物车重量。0 表示无限制（默认）。
Max weight (kg)：购物车的最高重量。超过时选项会被隐藏。默认：100。留空表示 100 kg，0 表示无限制。
Minimum subtotal：仅当购物车小计（需要配送的商品，优惠券之后，不含税，以商店默认货币计）不低于该金额时才显示该选项。留空则始终显示。
Geo zone：仅向该地理区域中的地址提供 Andreani。All zones（默认）表示无限制。地理区域在 System > Localisation > Geo Zones 中管理。开启 Ignore shipping zones 时不使用。
Ignore shipping zones：无论地理区域如何，都为下方列出的国家提供 Andreani。默认：关闭。
Countries：该模式下的目的国家。留空则允许所有国家。仅在开启 Ignore shipping zones 时使用。
免运费
Free shipping：开启免运费门槛。默认：关闭。
Free shipping from：购物车小计（以商店默认货币计）达到此金额时运费为免费。需要开启 Free shipping。
第二选项
第二个 Andreani 选项，拥有自己的名称、配送方式和合同，例如主选项为“a domicilio”，此处为“retiro en sucursal”，以同时提供两者。其他所有设置均共用。
Enable second option：在结账时提供第二选项。默认：关闭。
Second option name：该选项在结账时的名称。默认：Andreani - branch pickup。必填。
Delivery modality：Use global setting 或四种配送方式之一。默认：Door to branch (Puerta a Sucursal)。
Contract number：Andreani 会为每项服务（送货上门、网点自取）分别签发合同。留空则使用全局合同。
网点选择器（适用于 Door to branch 和 Branch to branch）
Province select width：省份列表的 CSS 宽度，例如 100% 或 300px。默认：100%。
Branch select width：网点列表的 CSS 宽度，例如 100% 或 400px。默认：100%。
高级
Debug log：将 API 请求和运费计算记录到 storage/logs/vfd_andr_debug.log.php。该文件无法通过网页读取。错误始终会被记录。凭据和令牌绝不会写入日志。文件达到 5 MB 时，会被移至 vfd_andr_debug.old.log.php，并开始新的日志。
Log：显示日志的大小和最新条目。点击 Clear log 可清空。
Remove data on uninstall：开启时，卸载扩展将删除所有 Andreani 设置和日志。关闭时（默认），这些数据会保留以便重新安装。订单中保存的网点数据始终保留。
导入 / 导出
Export：点击 Download JSON 将设置保存为 JSON 文件。API 密码不会被导出。
Import：粘贴之前导出的 JSON，然后点击 Import 以恢复设置，例如在另一家商店中使用。数值会像正常保存时一样进行检查。已保存的 API 密码会被保留。
结账时的运行方式
OpenCart 显示配送方式时，会向扩展请求每个已启用 Andreani 选项的价格。如果设置了 Geo zone 且 Ignore shipping zones 关闭，则地理区域之外的地址不提供 Andreani。只有 Requires Shipping 设为 Yes 的商品才会计算在内：其他商品不增加重量，也不计入小计。随后，扩展会检查国家（开启 Ignore shipping zones 时）、购物车重量（商品重量换算为 kg，没有重量的商品使用 Default product weight (kg)）以及 Minimum subtotal。小计是需要配送的商品价格，即扣除优惠券折扣后、税前的金额。
在固定模式下，价格取自 Country prices。在实时运费模式下，扩展会登录 Andreani API，并使用目的邮政编码、合同、客户代码、以 kg 计的重量、由商品尺寸得出的体积以及申报价值（以 ARS 计的购物车小计）请求报价。只有有效的阿根廷邮政编码（4 位数字，或 C1425ABC 之类的 CPA）才会请求实时运费。当商店货币不是 ARS 时，ARS 金额会使用 ARS exchange rate 换算。价格以商店默认货币计算，按其小数位数取整，并以顾客的货币显示，同时加上所选 Tax status 的税费。
登录令牌最多保留 23 小时，并在 Andreani 拒绝时自动更新。报价缓存 1 小时。失败的 API 调用 5 分钟内不会重复发起。所有数据都存储在 OpenCart 缓存中，因此条目的保存时间不会超过 OpenCart 缓存的有效期（默认 1 小时），到期后会重新请求。API 错误绝不会显示给顾客：该选项会被隐藏，或在回退模式下使用固定价格。原因会写入日志。
如果开启了 Free shipping，且购物车小计达到 Free shipping from，则运费为 0。免运费仅适用于该选项有价格的情况：如果 Andreani API 未返回运费，且没有可回退的固定价格，则不显示该选项。
该扩展不会创建 Andreani 发货单、打印面单或跟踪包裹。请使用 Andreani 网络门户完成这些操作。
在 OpenCart 4 上，顾客在结账页面的配送方式块中点击 Choose，并在 Shipping method options 窗口中选择一个 Andreani 选项。这些选项的工作方式与 OpenCart 3 相同；网点的选择见自提网点。
自提网点
当提供 Door to branch 或 Branch to branch 选项时，配送方式步骤中会在其下方立即显示省份列表和网点列表。省份会根据配送地址所在的地区预先选定。网点列表来自 Andreani 的公开网点 API，并最长缓存 12 小时（在 OpenCart 缓存期限之内）。不接收包裹的网点不会列出。配送步骤本身从不等待 Andreani：如果列表尚未缓存，会在后台加载，顾客会短暂看到 Loading Andreani branches...。如果没有可用网点，顾客会看到 No Andreani branches available right now. Please try again later or choose another shipping method.
顾客一选择，选择即被保存。只接受 Andreani 当前列表中的网点。没有网点时，配送步骤中的 Continue 无法通过，顾客会看到 Please select an Andreani pickup branch. 顾客继续时，服务器会再次检查网点。如果网点已不在列表中，顾客会看到 The selected Andreani branch is not available. Please choose another one.
在 OpenCart 4 上，省份列表和网点列表显示在 Shipping method options 窗口中，就位于 Andreani 网点选项下方，文字和检查与 OpenCart 3 相同。在窗口中未选择网点时，点击 Continue 无法通过，并会在选项下方显示 Please select an Andreani pickup branch. 如果商店在顾客继续时拒绝该网点，消息会显示在结账页面顶部，窗口保持打开。OpenCart 4 为结账保留一个订单，每次确认时都会更新该订单；订单中的网点也会同步更新，当顾客将订单改为其他配送方式时，网点会被删除。
在某个 Andreani 选项下选择的网点，不属于使用其他选项或其他配送方式下的订单。
该选择器是为 OpenCart 3 默认主题的单页结账以及 OpenCart 4 默认主题的结账设计的。配送步骤布局不同的主题可能需要修改选择器脚本。
订单
订单会保存配送方式，以及对于网点类配送方式所选的网点。
Shipping method of the order：网点会添加到配送方式文本中，例如 Andreani - branch pickup: 加网点名称。如果选项名称未提及网点，则会在网点名称前添加 Pickup branch:（当名称中不含 Andreani 时则为 Andreani pickup branch:），例如 Andreani - Pickup branch: 加网点名称。该文本会出现在发给顾客和商店的订单邮件、顾客的订单历史、发票以及后台订单页面中。OpenCart 将文本限制为 128 个字符；完整的网点数据由扩展保存。OpenCart 的订单成功页面不显示配送方式。
Admin order page：在 Sales > Orders 中打开一个订单。Andreani 面板会显示 Andreani modality，以及网点类配送方式的 Andreani branch（名称、ID 和省份）。点击 Edit，选择其他省份和网点，然后点击 Save 进行修改。您会看到 Branch updated.，订单配送方式文本中的网点也会被替换。只能保存 Andreani 列表中的网点。如果列表不可用，您会看到 The Andreani branch list is not available right now - the branch cannot be changed. 修改网点需要 sale/order 的修改权限以及对 extension/shipping/vfd_andreani（OpenCart 3）或 extension/vfd_andreani/shipping/vfd_andreani（OpenCart 4）的访问权限。即使扩展已关闭，对于已通过 Andreani 下单的订单，仍会显示该面板。
扩展关闭时，Andreani 面板不会显示。网点数据仍会保留，订单的配送方式文本也不会更改。现有订单保留其网点数据。
许可证密钥
该扩展需要一个来自 vibefox.net 的 VibeFox 许可证密钥。License — VibeFox Andreani 许可证块是 Extensions > Extensions > Shipping > VibeFox Andreani > Edit 页面中设置上方的第一个块。在 License key 中输入密钥并点击 Activate。之后，该块会以掩码形式显示密钥、许可状态（例如许可有效期截止日期和您的域名），并提供以下按钮：Check now 用于重新检查状态，Change key 用于输入其他密钥，Remove key 用于从本商店移除密钥。其下方有一行 Product: opencart-shipping-andreani，以及打开您的 vibefox.net 账户的链接 Manage licenses and domains in your account。只有对该扩展拥有 Modify 权限的管理员用户才能更改密钥。该块的文字跟随后台语言显示（包含英语和俄语）。
如果密钥未被接受，该块会显示原因，例如 Key not found、This key belongs to another product、Domain limit reached，或带日期的 License expired on。商店地址更改后，或在您的账户中释放了一个域名名额后，请点击 Check now。如果无法连接许可证服务器，扩展将继续使用最后已知的状态运行。
一个密钥只能用于一个域名：即 OpenCart 配置中的商店地址。从商店中移除密钥不会释放其域名名额。请在您的 vibefox.net 账户中释放该名额。
没有有效密钥时，结账时不会向顾客显示 Andreani 配送选项，也不计算运费。在同一浏览器中已登录后台的管理员用户仍可在商店中看到该方式，并标记为 (unlicensed — visible to admins only)，因此您可以在购买密钥之前设置和测试扩展。在 OpenCart 4 上此预览不可用：商店看不到后台登录状态，因此没有有效密钥时，该方式对所有人隐藏。您打开过一次 Edit 页面后，后台 Dashboard 上会出现提醒。点击 × 可将其关闭 7 天。现有订单不受影响。
许可证过期后，扩展仍会继续运行，但更新和支持需要续费。打开后台 Dashboard 或 Edit 页面时会自动再次检查状态：输入密钥后的前 14 天每天一次，之后每周一次。无需 cron 任务。卸载扩展时始终会删除许可证密钥和许可证状态。
故障排除
结账时不显示 Andreani：请检查许可证是否有效，Enable/Disable 是否已开启（对于第二选项，还需开启 Enable second option），以及安装后是否已点击 Save。检查 Geo zone，或 Ignore shipping zones 和 Countries。检查 Country prices 中是否有该国家的行（用于固定价格或回退），以及重量限制和 Minimum subtotal。阅读 Edit 页面顶部的警告。检查商品的 Requires Shipping 是否设为 Yes。
实时运费不显示：开启 Debug log，重新加载结账页面，然后查看扩展页面上的 Log 字段。它会显示原因：缺少凭据或合同编号、登录失败（用户名、密码或环境错误）、尚无有效的阿根廷邮政编码、没有汇率，或 Andreani 返回 HTTP 错误。使用 Andreani API, fixed price if the API fails 时，在您解决问题期间，顾客仍会获得固定价格。
我的商店不使用阿根廷比索：将 ARS exchange rate 设置为 1 ARS 相当于的商店默认货币金额。
运费税似乎有误：在 Tax status 中选择税率类别时，使用的是不含 IVA 的 Andreani 运费，OpenCart 会另外加税。选择 None 时，使用含 IVA 的运费，且不加税。请检查商店设置中是否已启用税费，以及该税率类别是否包含阿根廷的税率。
列表中没有网点：Andreani 网点 API 未响应。失败的请求会在 5 分钟后重试。请检查日志。
预先选择了错误的省份：省份是根据配送地址的地区读取的。顾客始终可以选择其他省份。
修改后运费看起来已过时：在扩展页面点击 Save。这将清除缓存的令牌、网点列表和运费。
页面提示 "Warning: You do not have permission to modify VibeFox Andreani!"：您的管理员用户组可能只有查看设置的权限。请在 System > Users > User Groups 中为该用户组授予 extension/shipping/vfd_andreani（OpenCart 3）或 extension/vfd_andreani/shipping/vfd_andreani（OpenCart 4）的修改权限。
面向开发者：Andreani API 地址可通过设置 vfd_andr_api_url（用于测试）替换；该设置在设置页面中没有对应字段。
卸载
进入 Extensions > Extensions，选择 Shipping 类型，然后点击 VibeFox Andreani 旁边的 Uninstall（红色 − 按钮）。该扩展的许可证密钥和许可证状态始终会被删除。OpenCart 始终会重置状态、Sort order、Tax status 和 Geo zone。扩展始终会移除其结账和订单页面处理程序，以及缓存的令牌、网点列表和运费。如果 Remove data on uninstall 已开启，所有 Andreani 设置和调试日志也会被删除。如果已关闭，其他设置会保留，并在您重新安装扩展时再次使用。订单中保存的网点数据永远不会被删除，现有订单会保留其配送方式和运费。
在 OpenCart 4 上，如果还要删除扩展的文件，请在卸载后进入 Extensions > Installer，在已安装扩展列表中点击 VibeFox Andreani 旁边的 Uninstall（橙色 − 按钮），然后点击 Delete（红色垃圾桶按钮）以删除已上传的安装包。
Andreani 是其各自所有者的商标。本扩展与 Andreani 无关联，也未获得其认可。