VibeFox Jadlog for WooCommerce — 帮助
系统要求
WordPress：5.8 或更高版本。
WooCommerce：5.0 或更高版本，已安装并启用。未安装时插件无法激活。
PHP：8.0 或更高版本。
Jadlog 合同（用于实时运费和取件点）：实时运费和取件点列表来自 Jadlog Embarcador API。签订合同后，您的 Jadlog 特许经销商会提供访问权限。您需要 Embarcador API 令牌、合同中登记的发件人 CNPJ（或 CPF）、经常账户（conta corrente），以及合同编号（如有）。如果您只使用固定运费，则不需要 Jadlog 合同。
VibeFox 许可证密钥：在 vibefox.net 购买。一个密钥只能用于一个域名。
安装
1. 在 WordPress 中进入 Plugins > Add New > Upload Plugin，选择插件 ZIP 文件并点击 Install Now。您也可以通过 FTP 将 vfd_jadlog 文件夹上传到 /wp-content/plugins/。
2. 点击 Activate。
3. 打开设置：WooCommerce > Settings > Shipping > VibeFox Jadlog，或在插件页面点击插件名称下方的 Settings。
4. 在页面顶部的许可证区块中输入您的 VibeFox 许可证密钥，然后点击 Activate。
5. 粘贴 API 令牌，填写 CNPJ、经常账户、合同编号和发货 CEP，选择 Jadlog 服务；如果您的店铺货币不是 BRL，请输入 BRL 汇率。如需要，可添加固定运费或备用费用（请参阅「配置」）。
6. 在 WooCommerce > Settings > Shipping > Shipping zones 中，将 VibeFox Jadlog 添加到巴西的配送区域；或开启 Ignore shipping zones 并选择国家。若还要提供 Jadlog Pickup 取件点，请将该方式第二次添加到此区域，并选择 Pickup (40) 作为服务。
配置
所有设置都在同一页面：WooCommerce > Settings > Shipping > VibeFox Jadlog。它们适用于所有配送区域。将该方式添加到某个区域时，区域窗口中有两个字段：
Title (zone): 顾客在此区域看到的名称。留空则使用全局的 Method title。
Jadlog service (zone): 此区域方式使用的服务。Same as the global setting 表示使用主设置页面中的服务。若要在同一区域提供例如送货上门（.Package）和 Jadlog Pickup 取件点，请将该方式添加两次。
当区域标题为空且服务为 Pickup 时，全局标题后会加上「Pickup」一词，使两种方式的名称有所区别。
设置页面顶部会对不完整的设置显示警告：缺少 API 令牌、缺少 CNPJ 或经常账户、缺少发货 CEP，或店铺不以 BRL 销售却未设置 BRL 汇率。每次保存设置时，缓存的 Jadlog 运费和取件点列表都会被清除。
常规
Enable/Disable: 在所有区域同时启用或禁用该方式。
Method title: 购物车和结账时显示的配送方式名称。默认：Jadlog。区域可以覆盖此名称。
Jadlog 实时运费
仅针对巴西地址且 CEP 为完整 8 位数字时请求实时运费。
API token: Jadlog 提供的 Embarcador 令牌。可粘贴带或不带「Bearer」一词的令牌。留空则仅使用固定运费。
CNPJ: Jadlog 合同中登记的发件人 CNPJ（14 位）或 CPF（11 位）。允许使用点、斜杠和短横线。若数字位数错误，插件会发出警告。
Current account (conta corrente): 您的 Jadlog 经常账户号码。没有它和 CNPJ，Jadlog 无法报价，只会使用固定运费。
Contract number: 您的 Jadlog 合同编号（如果特许经销商提供了）。
Origin CEP: 包裹发出地的邮政编码，8 位数字。以 00000-000 格式保存。若店铺地址在巴西，留空则使用 WooCommerce > Settings > General 中的店铺邮编。
Jadlog service: 您合同的服务（modalidade）：.Package（3，默认）、.Com（9）、Expresso（0）、Rodoviário（4）、Econômico（5）、Doc（6）、Corporate（7）、Internacional（10）、Cargo（12）、Emergencial（14）或 Pickup（40）。Pickup 提供顾客附近的 Jadlog Pickup 取件点。区域方式可以使用其他服务。
Insurance type: Normal (N)（默认）或 Own insurance policy (A — apólice)，以您的 Jadlog 合同约定为准。
Volumetric weight: Jadlog 按实际重量与体积重量中的较大者计费。
BRL exchange rate: Jadlog 以巴西雷亚尔报价。如果您的店铺货币是 BRL，则无需此字段。否则请输入 1 BRL 相当于店铺货币的金额，例如 0.16。Jadlog 运费将乘以该汇率，发送给 Jadlog 的申报订单金额会换算回 BRL。未设置汇率时，不使用实时运费，仅适用固定运费。小数点和逗号均可作为小数分隔符。
Delivery time: 在配送方式标题旁显示 Jadlog 返回的配送时效，例如「Jadlog（3 个工作日）」。默认开启。配送时效始终保存在订单中。
Jadlog Pickup 取件点（由 Pickup (40) 服务使用；需要 API 令牌）
Points to show: 提供的取件点数量，从 1 到 10。默认：5。
固定运费（在没有 API 令牌、Jadlog 不服务的国家，以及 Jadlog 未返回运费时使用）
Price per country: 一个表格，列有 Country、Price、XS、S、M、L 和 XL，以店铺货币计价。点击 + Add country 添加一行，点击叉号删除。尺寸列按购物车重量选择：XS 为 1 kg 以下，S 为 2 kg 以下，M 为 3 kg 以下，L 为 5 kg 以下，XL 为 5 kg 以上。尺寸列为空时使用 Price。价格为 0 表示该国家免运费。将 * Default 用作所有其他国家。保存时会删除没有任何价格的行。
Fallback cost: 当 Jadlog 和表格都未提供运费时使用。留空则在这种情况下隐藏该方式。
Fixed price applies: Per order 按订单收取一次运费。Per item (price × quantity) 按购物车中的商品数量相乘。这仅适用于固定运费和备用费用。Jadlog 运费已涵盖整个购物车。
条件
Minimum weight (kg): 购物车重量低于此值时隐藏该方式。0 表示无限制。
Maximum weight (kg): 购物车重量高于此值时隐藏该方式。默认：150。0 表示无限制。
Minimum order amount: 仅当购物车小计（折扣后、税前）达到此金额时才显示该方式。留空则始终显示。
Excluded shipping classes: 购物车包含任一这些 WooCommerce 配送类别的商品时隐藏该方式。
Free shipping from: 购物车小计（折扣后、税前）达到此金额即免运费。留空则不提供免运费。
Tax status: Taxable 会在运费上加收 WooCommerce 税费，None 则不加。Jadlog 运费为承运商的最终价格。如果不希望 WooCommerce 对其加税，请选择 None。
无配送区域时的可用性
Ignore shipping zones: 即使该方式未添加到任何配送区域，也为下列国家提供 Jadlog。此模式下使用全局的 Jadlog service。
Countries: 此模式下的目的地国家。留空则使用您发货的所有国家。仅在开启 Ignore shipping zones 时使用此字段。
高级
Debug log: 将每个 Jadlog 请求和响应记录到 WooCommerce > Status > Logs，来源为 vfd-jadlog。即使此选项关闭，API 错误也始终会被记录。令牌、CNPJ 和账户绝不会被记录，顾客的 CEP 会被缩短。使用完毕后请关闭日志。
Remove data on uninstall: 开启后，删除插件会移除所有 Jadlog 设置和区域方式。停用插件从不删除设置。缓存的运费始终会被清除。
结账时的工作方式
顾客输入配送地址时，WooCommerce 会向插件请求运费。插件首先检查条件：购物车重量、最低订单金额和排除的配送类别。如果购物车小计达到 Free shipping from，则免运费，且不会向 Jadlog 发送任何运费请求。
对于 CEP 为完整 8 位数字的巴西配送地址，插件会向 Jadlog 发送发货和收货 CEP、重量、您的 CNPJ、经常账户、合同、服务、保险类型以及申报订单金额，并以您的店铺货币显示返回的运费。无重量的购物车按 0.1 kg 报价。若无实时运费（无令牌、地址在巴西以外、CEP 不完整、无 BRL 汇率、Jadlog 错误），插件会依次使用 Price per country 表格和 Fallback cost。若两者都不能提供运费，则该购物车隐藏此方式。
每个运费缓存 1 小时，因此同一购物车不会触发新的请求。失败的请求缓存 10 分钟。若 Jadlog 无响应、返回服务器错误或拒绝令牌，则 10 分钟内不再调用 API。API 超时时间为 10 秒。顾客从不会看到 API 错误，原因会写入日志。
该方式适用于经典结账以及购物车和结账区块。它与 WooCommerce 高性能订单存储（HPOS）兼容。
插件仅计算运费并列出 Pickup 取件点。它不会创建 Jadlog 运单、打印面单、预约上门取件、取消运单或追踪包裹。不显示 Pickup 取件点地图，也不向 Jadlog 请求国际报价。其他国家请使用固定运费。
取件点
使用 Pickup (40) 服务的方式仅对巴西地址提供。顾客输入完整 8 位数字的 CEP 后，插件会向 Jadlog 查询附近的活跃 Pickup 取件点，并最多提供 Points to show 个取件点。每个取件点都是独立的配送选项，有各自的运费，例如「Jadlog Pickup：取件点名称 — 地址」。顾客通过选择配送选项来选定取件点，经典结账以及购物车和结账区块中均是如此。
每个取件点的运费都向 Jadlog 请求。若 Jadlog 未为某个取件点提供运费，则使用固定运费；没有任何运费的取件点会被排除。取件点列表缓存 12 小时。
没有 API 令牌、没有完整 8 位数字 CEP、Jadlog 不可用或附近没有活跃取件点时，Pickup 方式会被隐藏。没有取件点的订单无法发货。
订单
订单的配送行会保存 Jadlog 服务，以及（若 Jadlog 返回）以工作日计的配送时效。对于 Pickup 订单，配送行名称包含取件点名称和地址，订单还会保存 Pickup 取件点的名称、地址和 ID。您可在管理员订单页面的配送行下方看到这些信息。顾客可在「感谢购买」页面和订单邮件中看到所选取件点。
请自行在 Jadlog 系统中预约运单。订单会显示您所需的服务和 Pickup 取件点 ID。
许可证密钥
本插件需要使用来自 vibefox.net 的 VibeFox 许可证密钥。许可证区块位于 WooCommerce > Settings > Shipping > VibeFox Jadlog 页面顶部。将密钥粘贴到 License key 中并点击 Activate。该区块会显示状态，例如许可证有效期至何时以及您的域名。使用 Check now 重新检查状态，使用 Change key 输入其他密钥，使用 Remove key 将其从本站点移除。Manage licenses and domains in your account 链接可打开您的 vibefox.net 账户。
一个密钥只能用于一个域名。从站点移除密钥不会释放域名名额。请在您的 vibefox.net 账户中释放名额。
没有有效密钥时，Jadlog 不会在结账时向顾客显示。已登录的店铺管理员仍可看到，并标注为 (unlicensed — visible to admins only)，以便您在购买密钥前设置和测试插件。插件页面和 WooCommerce 页面会显示提醒。现有订单不受影响。
许可证到期后，插件仍会继续工作，但更新和支持需要续费。状态会在后台自动重新检查。
故障排除
Jadlog 未出现在结账页面：请检查许可证是否有效、Enable/Disable 是否已开启、该方式是否已添加到顾客所在国家的区域（或已开启 Ignore shipping zones 且允许该国家）。请查看设置页面顶部的警告、重量限制、Minimum order amount 和 Excluded shipping classes。如果顾客尚未输入完整 8 位数字的 CEP，则只能使用固定运费，因此请添加 Price per country 的行或 Fallback cost。
只显示固定运费：开启 Debug log，重新加载结账页面，然后打开 WooCommerce > Status > Logs，来源为 vfd-jadlog。日志会显示原因：缺少 CNPJ 或经常账户、缺少发货 CEP、收货 CEP 不完整、缺少 BRL 汇率，或 Jadlog 的错误信息。
日志中出现 HTTP 401 或 403：Jadlog 拒绝了 API 令牌。请与您的 Jadlog 特许经销商核对。此错误后 API 将暂停 10 分钟。保存设置会清除暂停，因此您可以立即重试。
取件点未出现：Pickup 方式需要 API 令牌以及巴西地址的完整 8 位数字 CEP。如果 Jadlog 在该 CEP 附近没有活跃取件点，该方式会被隐藏。请查看日志了解原因。
价格显示为雷亚尔而不是我的货币：请输入 BRL exchange rate（1 BRL 相当于店铺货币的金额）。
运费看起来过低或过高：请填写商品重量和尺寸。无重量的购物车按 0.1 kg 报价，而体积重量需要尺寸。
修改后运费显示过时：保存设置页面。这会清除缓存的 Jadlog 运费和取件点列表。
许可证区块显示错误：请按区块中的提示操作。例如，若该密钥已在其他域名上使用，请在您的 vibefox.net 账户中释放名额，然后点击 Check now。若站点地址已更改，请点击 Check now 以便为新域名激活密钥。若无法连接许可证服务器，插件将沿用最后已知的状态继续工作。
卸载
停用插件会保留所有设置和区域方式，仅清除缓存的运费和取件点列表。要移除插件，请在 Plugins 页面停用并删除。本插件的许可证密钥和许可证状态以及缓存的运费始终会被移除。只有开启了 Remove data on uninstall 时，设置和区域方式才会被移除；否则将保留，以便日后重新安装。现有订单会保留其配送行，包含 Jadlog 服务和取件点。
Jadlog 是其各自所有者的商标。本插件与 Jadlog 无关联，亦未获得 Jadlog 的认可或背书。