VibeFox Andreani for PrestaShop — 帮助
系统要求
PrestaShop：8.0 至 9.x。
PHP：8.0 或更高版本。模块拒绝在更低版本的 PHP 上安装。
Andreani 账户（仅用于实时运费）：实时运费使用 Andreani 报价 API。Andreani 向企业客户提供 API 凭据、客户代码和合同编号，通常在每月约 300 单发货量起。请访问 developers.andreani.com 或写信至 ventapyme@andreani.com。您需要 API 用户名和密码、客户代码以及合同编号。Andreani 为每项服务（送货上门、网点自取）分别签发合同。没有 API 访问权限时，请使用固定价格。网点选择器无需凭据即可使用。
VibeFox license key：在 vibefox.net 购买。一个密钥对应一个域名。
安装
1. 在后台进入 Modules > Module Manager，点击 Upload a module。选择模块的 ZIP 文件。
2. 上传完成后，点击 Configure；或者之后在模块列表中找到 VibeFox Andreani，然后点击 Configure。
3. 在 Configure 页面顶部许可证区块的 License key 中输入您的 VibeFox 许可证密钥，然后点击 Activate（参阅许可证密钥）。
4. 设置名称、运费来源、各国价格（例如 AR=5000），如使用实时运费，还需设置 API 凭据、客户代码和合同编号（参见配置）。点击 Save。
安装时，模块会创建两个承运商：
两个承运商都分配到阿根廷区域和所有客户组。您可以在 Shipping > Carriers 中修改区域、客户组、配送时间、徽标和尺寸限制。请不要在那里设置价格：价格始终来自模块。
配置
所有设置都在模块页面：Modules > Module Manager > VibeFox Andreani > Configure。每个部分都有自己的 Save 按钮，它会保存整个页面。保存后，您会看到 Settings saved. Cached token, branches and rates were cleared. 页面顶部会显示缺失设置的警告（API 凭据、合同编号、ARS 汇率、阿根廷无价格、承运商已被删除）。如果模块无法识别商店的重量或尺寸单位，也会显示警告（此时重量按 kg、尺寸按 cm 读取）。保存时，超过 64 个字符的名称或大于 Max weight (kg) 的 Min weight (kg) 会被拒绝，且不会保存任何内容。不是数字的值、负数，或者等于或小于 0 的 ARS exchange rate 不会被保存，并且警告会指出对应的字段。
General
Enable/Disable：开启或关闭 Andreani 配送。这与 Shipping > Carriers 中主承运商的状态是同一个开关。第二个选项有自己的开关。
Name：顾客在结账时看到的承运商名称。默认：Andreani。必填。
Tax status：None，或 Taxable 并选择您的某个税务规则。使用税务规则时，商店会将税费加到运费上，因此使用不含 IVA 的 API 运费。选择 None 时，使用含 IVA 的 API 运费。该设置会保存到两个 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 kg，0 表示无限制。
Minimum subtotal：仅当购物车小计（需要配送的商品，折扣后，不含税）不低于此金额时才显示承运商。留空则始终显示。
Ignore shipping zones：无需设置区域，即可为下方国家提供 Andreani 配送。开启后，两个承运商都会关联到所有区域，之后创建的区域也会立即关联。关闭后，承运商会恢复之前的区域。
Countries：该模式的目的国家。留空则允许所有国家。仅在 Ignore shipping zones 开启时使用。
免运费
Free shipping：开启免运费门槛。
Free shipping from：购物车小计达到此金额即免运费。需要开启 Free shipping。
第二选项
第二个 Andreani 承运商，拥有自己的名称、配送方式和合同，例如主承运商为 "a domicilio"，此处为 "retiro en sucursal"，以同时提供两种方式。所有其他设置均为共用。
Enable second option：开启或关闭第二个承运商。这与 Shipping > Carriers 中它的状态是同一个开关。默认：关闭。
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 请求和运费计算记录到模块文件夹中的 logs/vfd_andr_debug.log.php。该文件无法通过网页打开。错误始终会被记录。凭据和令牌从不写入日志。
Log：显示日志的大小和最新条目。点击 Clear log 可清空日志。
Remove data on uninstall：开启时，卸载模块会删除所有模块设置和承运商。关闭时，卸载只会关闭承运商。订单中保存的网点数据始终保留。
结账时的工作方式
在配送步骤中，PrestaShop 会向模块请求每个 Andreani 承运商的价格。只计算实体商品：虚拟商品不增加重量，也不计入小计。模块会检查国家（开启 Ignore shipping zones 时）、购物车重量（商品重量换算为 kg，没有重量的商品使用 Default product weight (kg)）以及 Minimum subtotal。
在固定模式下，价格取自 Country prices。在实时模式下，模块会登录 Andreani API，并使用目的地邮政编码、合同、客户代码、以 kg 计的重量、根据商品尺寸计算的体积以及申报价值（以 ARS 计的购物车小计）请求报价。仅对有效的阿根廷邮政编码请求实时运费。当商店货币不是 ARS 时，ARS 金额会按 ARS exchange rate 换算。价格先以商店默认货币计算，然后以顾客的购物车货币显示。
登录令牌缓存 23 小时，并在 Andreani 拒绝时自动更新。报价缓存 1 小时。失败的 API 调用 5 分钟内不会重复发送。API 错误从不向顾客显示：承运商会被隐藏，或在备用模式下使用固定价格。原因会写入日志。
如果 Free shipping 已开启，且购物车小计达到 Free shipping from，则价格为 0。免运费只适用于承运商有价格的情况：如果 Andreani API 未返回运费，且没有可用于回退的固定价格，则不会显示该承运商。
如果您在订单产生后修改 Shipping > Carriers 中的承运商，PrestaShop 会将其保存为新版本的承运商。模块会自动跟随新版本。
模块不会创建 Andreani 运单、打印面单或跟踪包裹。请为此使用 Andreani 网站门户。
取货点
选择带有 Door to branch 或 Branch to branch 的承运商时，配送步骤中其下方会出现省份列表和网点列表。省份会根据收货地址预先选定。网点列表来自 Andreani 公开的网点 API，并缓存 12 小时。不交付包裹的网点不会列出。如果没有可用网点，顾客会看到 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.
在顾客切换到其他承运商之前，在 Andreani 下选择的网点不属于该订单。
订单
订单会保存配送方式，对于网点类配送方式，还会保存所选网点。
Admin order page：一个 Andreani 区块显示配送方式和网点（名称、ID 和省份）。点击 Edit，选择其他省份和网点，然后点击 Save 进行更改。您会看到 Branch updated. 只能保存 Andreani 列表中的网点。如果列表不可用，则无法更改网点。
客户：网点显示为 Andreani pickup branch:，位于订单确认页面和订单详情页面。
电子邮件：在订单确认邮件和发给商店的新订单邮件（Mail alerts 模块）中，网点会添加到承运商名称后。发给商店的邮件还会显示网点 ID。
现有订单保留其网点数据。
许可证密钥
模块需要使用在 vibefox.net 获得的 VibeFox 许可证密钥。License — VibeFox Andreani 许可证区块是 Modules > Module Manager > VibeFox Andreani > Configure 页面中位于设置上方的第一个区块。将密钥粘贴到 License key 中，然后点击 Activate。之后，该区块会以掩码形式显示密钥、许可状态（例如许可证有效期截止日期和您的域名），并提供以下按钮：Check now（再次检查状态）、Change key（输入另一个密钥）和 Remove key（从本商店移除密钥）。其下方是 Product: presta-shipping-andreani 一行，以及链接 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 账户中释放该名额。
没有有效密钥时，Andreani 承运商不会在结账时向顾客显示，也不会计算运费。PrestaShop 前台无法得知您已登录后台，因此承运商对您也会隐藏：您可以在购买密钥之前设置模块，但无法在结账时测试。Modules > Module Manager 中的 Alerts 选项卡会显示提醒。现有订单不受影响。
许可证到期后，模块仍会继续工作，但更新和支持需要续订。在后台工作时，系统会自动再次检查状态：输入密钥后的前 14 天每天检查一次，之后每周检查一次。无需 cron 任务。卸载或重置模块总会删除许可证密钥和许可状态。
故障排除
结账时没有 Andreani：请检查许可证是否有效，Enable/Disable 是否开启（第二个承运商还需开启 Enable second option）。在 Shipping > Carriers 中，检查承运商是否覆盖顾客所在国家的区域和顾客组，或开启 Ignore shipping zones 并检查 Countries。检查 Country prices 中是否有该国家的行（用于固定价格或备用），并检查重量限制和 Minimum subtotal。阅读 Configure 页面顶部的警告。此外，商品页面上也可能将商品限制为特定承运商。
实时运费不显示：开启 Debug log，重新加载结账页面，然后查看模块页面上的 Log 字段。它会显示原因：缺少凭据或合同编号、登录失败（用户名、密码或环境错误）、尚无有效的阿根廷邮政编码、没有汇率或 Andreani HTTP 错误。使用 Andreani API, fixed price if the API fails 时，在您解决问题期间，顾客仍会获得固定价格。
我的商店不使用阿根廷比索：将 ARS exchange rate 设置为 1 ARS 等于您商店默认货币的数值。
运费税似乎不对：在 Tax status 中使用税务规则时，使用不含 IVA 的 Andreani 运费，PrestaShop 会添加自己的税。选择 None 时，使用含 IVA 的运费，且不添加税。请检查税务功能是否已启用，以及是否已为阿根廷设置税务规则。
列表中没有网点：Andreani 网点 API 没有响应。失败的请求会在 5 分钟后重试。请检查日志。
修改后运费似乎过时：在模块页面点击 Save。这会清除缓存的令牌、网点列表和运费。
页面提示未找到 Andreani 承运商：该承运商已在 Shipping > Carriers 中被删除。请在 Modules > Module Manager 中重置模块以重新创建它。
卸载
进入 Modules > Module Manager，打开 VibeFox Andreani 旁边的菜单，然后选择 Uninstall。许可证密钥和许可状态始终会被删除。缓存的令牌、网点列表和运费也始终会被删除。如果 Remove data on uninstall 已开启，承运商会被删除（订单保留历史记录），并删除设置、日志以及没有订单的购物车中的网点选择。如果已关闭，承运商只会被关闭，所有设置都会保留。重新安装模块或对模块执行 Reset，会使两个承运商恢复之前的状态。订单中保存的网点数据永远不会被删除。
Andreani 是其各自所有者的商标。本模块与 Andreani 无关联，也未获得 Andreani 的认可。