VibeFox Andreani for WooCommerce — 帮助
系统要求
WordPress：5.8 或更高版本。
WooCommerce：7.0 或更高版本，已安装并启用。未安装时插件无法激活。
PHP：8.0 或更高版本。
Andreani 账户（仅用于实时运费）：实时运费使用 Andreani 报价 API。Andreani 会向企业客户发放 API 凭据、客户代码和合同编号，通常在每月约 300 票货件以上时提供。请访问 developers.andreani.com，或写信至 ventapyme@andreani.com。您需要 API 用户名和密码、客户代码以及合同编号。Andreani 会为每项服务（送货上门、网点自取）分别签发合同。没有 API 访问权限时，请使用固定价格。网点选择器无需凭据即可使用。
VibeFox 许可证密钥：在 vibefox.net 购买。一个密钥仅适用于一个域名。
安装
1. 在 WordPress 中进入 Plugins > Add New > Upload Plugin，选择插件的 ZIP 文件，然后点击 Install Now。您也可以通过 FTP 将 vfd_andreani 文件夹上传至 /wp-content/plugins/。
2. 点击 Activate。
3. 打开设置：WooCommerce > Settings > Shipping > VibeFox Andreani，或在插件页面中点击插件名称下方的 Settings。
4. 在页面顶部的许可证区块中输入您的 VibeFox 许可证密钥，然后点击 Activate。
5. 设置名称、运费来源、按国家设定的价格（例如 AR=5000），如使用实时运费，还需设置 API 凭据、客户代码和合同编号（见配置）。
6. 进入 WooCommerce > Settings > Shipping > Shipping zones，打开或新建阿根廷的配送区域，然后添加 VibeFox Andreani。在区域窗口中，您可以为该选项设置标题、配送方式以及不同的合同。您也可以开启 Ignore shipping zones，改为选择国家。
配置
主要设置位于 WooCommerce > Settings > Shipping > VibeFox Andreani。这些设置适用于所有配送区域。页面顶部会显示缺失设置的警告（API 凭据、合同编号、汇率、阿根廷无价格）。每次保存设置时，缓存的令牌、网点列表和运费都会被清除。
区域窗口（将该方式添加到配送区域时）
Title:该选项在结账时的名称。留空则使用全局的 Name。
Delivery modality:Use global setting，或四种配送方式之一（见下文）。将该方式在同一区域中添加两次，例如上门到家和网点自取，即可同时提供两种方式。
Contract number:该选项使用的 Andreani 合同。留空则使用全局合同。
常规
Enable/Disable:一次性在所有区域中启用或禁用 Andreani 配送。
Name:结账时向顾客显示的配送方式名称。默认：Andreani。
Tax status:Taxable 表示 WooCommerce 会对运费加收税款，因此 API 运费不含 IVA。None 表示 API 运费含 IVA。
Andreani API（实时运费所需）
Environment:Sandbox / QA (apisqa.andreani.com)（默认）或 Production (apis.andreani.com)。请使用您的凭据所属的环境。
API username:您的 Andreani API 用户名。
API password:您的 Andreani API 密码。
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。
Calculation type:Per order 只收取一次价格。Per item (price x number of items) 将 Country prices 中的固定价格乘以购物车中的商品数量。Andreani 实时运费本身已针对整个购物车，不会再乘以数量。
可用性
Min weight (kg):方式显示所需的最低购物车重量。0 表示无限制。
Max weight (kg):最大购物车重量。超过时该方式将被隐藏。默认：100。0 表示无限制。
Minimum subtotal:仅当购物车小计不低于该金额时才显示该方式。留空则始终显示。
Excluded shipping classes:如果购物车中的任一商品属于所选的 WooCommerce 配送类别，该方式将被隐藏。
Ignore shipping zones:即使未将该方式添加到配送区域，也为下方的国家提供该方式。
Countries:该模式的目的国家。留空则允许所有国家。仅在 Ignore shipping zones 开启时使用。
免运费
Free shipping:开启免运费门槛。
Free shipping from:购物车小计达到此金额时免运费。需要开启 Free shipping。
结账时的网点选择器（对 Door to branch 和 Branch to branch 显示）
Province select width:省份列表的 CSS 宽度，例如 100% 或 300px。默认：100%。
Branch select width:网点列表的 CSS 宽度，例如 100% 或 400px。默认：100%。
高级
Debug log:将 API 请求和运费计算记录到 WooCommerce > Status > Logs（来源 "vfd-andreani"）。错误始终会被记录。凭据和令牌从不记录。
Remove data on uninstall:开启后，删除插件时会移除其所有设置和区域方式。停用插件从不会删除任何内容。订单中保存的网点数据始终保留。
结账时的运作方式
当顾客输入收货地址时，插件会检查购物车重量（商品重量会换算为千克，没有重量的商品使用 Default product weight (kg)）、Minimum subtotal 和 Excluded shipping classes。
在固定模式下，价格取自 Country prices。在实时模式下，插件会登录 Andreani API，并使用目的邮编、合同、客户代码、千克重量、由商品尺寸计算的体积以及申报价值（购物车小计，以 ARS 计）请求报价。只有在邮编为有效的阿根廷邮编时才会请求实时运费。当您的店铺货币不是 ARS 时，ARS 金额会使用 ARS exchange rate 换算。
登录令牌会缓存 23 小时，并在 Andreani 拒绝时自动更新。报价缓存 1 小时。失败的 API 调用 5 分钟内不会重复。API 错误从不会显示给顾客：该方式会被隐藏，或在备用模式下使用固定价格。原因会写入日志。
如果 Free shipping 已开启，且购物车小计达到 Free shipping from，运费为 0。免运费仅适用于该方式有价格的情况：如果 Andreani API 未返回运费（且没有可回退的固定价格），则不显示该方式。使用 Per item 时，固定价格会乘以商品数量。
该方式适用于经典结账以及购物车和结账区块。它兼容 WooCommerce 高性能订单存储（HPOS）。
插件不会创建 Andreani 运单、打印面单或跟踪包裹。这些操作请使用 Andreani 网站门户。
自提网点
选择 Door to branch 或 Branch to branch 时，结账页面中 Andreani 选项下方会显示省份列表和网点列表，无论是经典结账还是结账区块。省份会根据收货地址预先选定。网点列表来自 Andreani 公开的网点 API，并缓存 12 小时。不接收包裹的网点不会列出。如果没有可用网点，顾客会看到提示，并可选择其他配送方式。
未选择网点则无法下单：顾客会看到 Please select an Andreani pickup branch. 两种结账方式均在服务器端进行此项检查。
所选网点会保存到订单中。在管理员订单页面中，配送方式和网点显示在收货地址下方。点击 Edit 可选择其他省份和网点。顾客在订单页面和订单电子邮件（HTML 和纯文本）中会看到网点显示为 Andreani pickup branch。现有订单保留其网点数据。
许可证密钥
本插件需要一个来自 vibefox.net 的 VibeFox 许可证密钥。许可证区块位于 WooCommerce > Settings > Shipping > VibeFox Andreani 页面顶部。将密钥粘贴到 License key 中，然后点击 Activate。该区块会显示状态，例如许可证有效期至何时以及您的域名。使用 Check now 重新检查状态，使用 Change key 输入其他密钥，使用 Remove key 将其从本站点移除。链接 Manage licenses and domains in your account 会打开您的 vibefox.net 账户。
一个密钥仅适用于一个域名。从站点移除密钥不会释放其域名名额。请在您的 vibefox.net 账户中释放名额。
没有有效密钥时，结账时不会向顾客显示 Andreani。已登录的店铺管理员仍可看到它，并标记为 (unlicensed — visible to admins only)，因此您可以在购买密钥前设置和测试插件。插件页面和 WooCommerce 页面上会出现提醒。现有订单不受影响。
许可证到期后，插件仍可继续运行，但更新和支持需要续费。状态会在后台自动重新检查。
故障排除
结账时不显示 Andreani：请检查许可证是否有效、Enable/Disable 是否开启，以及该方式是否已添加到顾客地址所在的配送区域（或已开启 Ignore shipping zones 且允许该国家）。请检查 Country prices 中是否有该国家的行（用于固定价格或作为备用），并检查重量限制、Minimum subtotal 和 Excluded shipping classes。请阅读设置页面顶部的警告。
实时运费不显示：请开启 Debug log，刷新结账页面，然后打开 WooCommerce > Status > Logs（来源 "vfd-andreani"）。日志会显示原因：缺少凭据或合同编号、登录失败（用户名、密码或环境错误）、尚无有效的阿根廷邮编、没有汇率，或 Andreani 的 HTTP 错误。使用 Andreani API, fixed price if the API fails 时，顾客在您修复问题期间仍会获得固定价格。
我的店铺不使用阿根廷比索：请将 ARS exchange rate 设置为 1 ARS 在您店铺货币中的价值。
运费税款看起来不对：当 Tax status 设为 Taxable 时，使用不含 IVA 的 Andreani 运费，WooCommerce 会加收自己的税款。设为 None 时，使用含 IVA 的运费，WooCommerce 不加税。如果您使用 Taxable，请确认已设置 WooCommerce 税率。
列表中没有网点：Andreani 网点 API 没有响应。失败的请求会在 5 分钟后重试。请查看日志。
修改后运费看起来过时：请保存设置页面。这会清除缓存的令牌、网点列表和运费。
许可证区块显示错误：请按照区块中的提示操作。例如，如果该密钥已在另一个域名上使用，请在您的 vibefox.net 账户中释放一个名额，然后点击 Check now。如果站点地址已更改，请点击 Check now 为新域名激活密钥。如果无法连接许可证服务器，插件将继续按最后已知的状态运行。
卸载
停用插件会保留所有设置，仅清除缓存。要移除插件，请先停用，然后在 Plugins 页面中删除。本插件的许可证密钥和许可证状态，以及缓存的令牌、网点列表和运费，始终会被移除。只有开启了 Remove data on uninstall 时，设置和区域方式才会被移除；否则将保留，以便之后重新安装时使用。订单中保存的网点数据永远不会被删除。
Andreani 是其各自所有者的商标。本插件与 Andreani 没有关联，也未获得 Andreani 的认可。