VibeFox Blue Express for WooCommerce — 帮助
系统要求
WordPress：5.8 或更高版本。
WooCommerce：7.0 或更高版本，已安装并启用。未安装时插件无法启用。
PHP：8.0 或更高版本。
Blue Express 账户（仅实时运费需要）：实时运费需要 Blue Express 电商账户及其 API 密钥（x-api-key）。请向 Blue Express 申请：developers.bluex.cl 或 gpo.integraciones@bx.cl。您使用的服务（EX、PY 或 MD）必须已在您的 Blue Express 合同中开通。如果只使用固定价格，则无需 API 密钥。
自提点：Blue Express 地图由顾客浏览器从 widget-pudo.blue.cl 加载。
VibeFox 许可证密钥：在 vibefox.net 购买。一个密钥只能用于一个域名。
安装
1. 在 WordPress 中进入 Plugins > Add New > Upload Plugin，选择插件的 ZIP 文件，然后点击 Install Now。您也可以通过 FTP 将 vfd_blue_express 文件夹上传到 /wp-content/plugins/。
2. 点击 Activate。
3. 打开设置：WooCommerce > Settings > Shipping > VibeFox Blue Express，或在插件页面中点击插件名称下方的 Settings。
4. 在页面顶部的许可证区块中输入您的 VibeFox 许可证密钥，然后点击 Activate。
5. 输入 API 密钥、服务、发货地区代码（例如 SCL）、如果店铺货币不是 CLP 则输入 CLP 汇率，以及固定价格（例如 CL=4500）。参见“配置”。
6. 进入 WooCommerce > Settings > Shipping > Shipping zones，将 VibeFox Blue Express 添加到您的智利配送区域。在方式设置中选择标题和配送类型（送货上门或到 Blue Express 网点自提）。添加两次即可同时提供两种选项。
配置
主要设置位于 WooCommerce > Settings > Shipping > VibeFox Blue Express。这些设置适用于所有配送区域。如果设置会导致该方式或实时运费被隐藏（例如没有 API 密钥、没有 CLP 汇率、固定价格表为空），页面顶部会显示警告。保存设置会清除缓存。
区域窗口（将该方式添加到配送区域时）
Title：该区域中展示给顾客的配送方式名称。留空则使用全局的 Name。
Delivery type：As in the global settings（默认）、Home delivery 或 Pickup at a Blue Express point (PUDO)。在一个区域中添加两次该方式，即可同时提供送货上门和自提。
常规
Enable/Disable：在所有配送区域中统一启用或停用该方式。
Name：结账时显示的配送方式名称。各区域可设置自己的标题。默认：Blue Express。
Tax status：Blue Express 价格已含 IVA。如果 WooCommerce 不应在此基础上另加税，请选择 None；如果应加税，请选择 Taxable。
Blue Express API（实时运费需要）
API key：您的 Blue Express API 密钥（请求头 x-api-key）。未填写时，仅使用固定价格。
Service：用于计算运费的 Blue Express 服务：Express (EX)（默认）、Prioritario (PY) 或 SameDay (MD)。该服务必须已在您的 Blue Express 合同中开通。
Origin district code：您发货地点的 Blue Express 地区代码，例如圣地亚哥的 SCL（默认）。如有疑问，请咨询 Blue Express。
CLP per 1 (your currency)：Blue Express 价格以智利比索（CLP）计价。如果您的店铺使用其他货币，请填写该货币一个单位等于多少 CLP，例如 1050。未填写时，不使用实时运费。店铺货币为 CLP 时忽略此项。
价格
Rate source：价格的计算方式。
Fixed prices：每个国家占一行，格式为 COUNTRY_CODE=PRICE，金额使用店铺货币，例如 CLP 店铺中的 CL=4500，或 EUR 店铺中的 CL=4.50。小数点可用逗号或句点。无效行会在保存时提示。固定价格可用于任何国家。
Fixed price per：Order 每单收取一次价格。Item (price x quantity) 按购物车中的商品数量乘以价格。此设置仅适用于固定价格。API 运费始终针对整个包裹。
条件
Min weight (kg)：购物车重量低于此值时隐藏该方式。0 表示不限制。
Max weight (kg)：购物车重量高于此值时隐藏该方式。默认：100。0 表示不限制。
Minimum order subtotal：仅当购物车小计（店铺货币）达到此金额时才显示该方式。留空则始终显示。
Excluded shipping classes：如果购物车中任一商品属于所选的 WooCommerce 配送类别，则隐藏该方式。
免运费
Free shipping：开启后，购物车小计达到一定金额即免运费。
Free from subtotal：免运费的购物车小计金额（店铺货币）。
Blue Express 网点自提（PUDO）
Pickup point by default：开启后，Blue Express 方式将配送到顾客选定的 Blue Express 网点。这是 Delivery type = As in the global settings 的区域方式的默认设置。顾客必须选择网点才能下单。
无配送区域时的可用性
Ignore shipping zones：即使该方式未添加到对应的配送区域，也提供该方式。此时使用全局设置（没有区域标题和配送类型）。
Countries：该模式下的目的地国家。留空则使用您发货的所有国家。仅在启用 Ignore shipping zones 时使用。
高级
Debug log：将请求和决策记录到 WooCommerce > Status > Logs，来源为 "vfd-blue-express"。API 错误始终会被记录。API 密钥和顾客地址从不记录。
Remove data on uninstall：开启后，删除插件时会移除其设置和区域方式。停用插件从不删除设置。订单中保存的自提点信息会保留。
结账时的工作方式
顾客输入配送地址后，插件会检查购物车重量、Minimum order subtotal 和 Excluded shipping classes。如果适用免运费，运费为 0，且不会向 Blue Express 发送请求。
要获得实时运费，地址必须位于智利，并包含地区和城市（市镇）。插件会先请求 Blue Express 识别市镇，然后请求该服务、发货地区、目的地和包裹的价格。每件商品的重量和尺寸都会换算为千克和厘米后发送。没有重量或尺寸的商品按 0.01 kg、10 x 10 x 10 cm 发送。申报价值以 CLP 发送。CLP 价格会换算为店铺货币。
运费缓存 1 小时，市镇数据缓存 12 小时。API 调用失败后会记住 5 分钟，超时时间为 10 秒，因此速度慢或不可用的 API 不会拖慢每次结账刷新。API 错误绝不会显示给顾客：该方式会被隐藏，或在备用模式下使用固定价格。原因会写入日志。
该方式适用于经典结账以及购物车和结账区块。它兼容 WooCommerce 高性能订单存储（HPOS）。
插件不会在 Blue Express 创建运单或面单，不分配运单号，也不显示物流跟踪更新。请在您的 Blue Express 账户中创建运单。没有按市镇划分的地区运费表：请使用 Blue Express API 运费，或按国家设置一个固定价格。实时运费仅适用于智利。
自提点
选择配送类型 Pickup at a Blue Express point (PUDO) 后，顾客会在 Blue Express 选项下方看到 Choose pickup point，无论是经典结账还是区块结账。点击按钮将打开官方 Blue Express 地图，顾客可在其中选择网点。所选网点会显示其名称和地址，按钮随即变为 Change pickup point。然后按 Blue Express 自提（PUDO）价格重新计算运费。
没有网点就无法下单：顾客会看到 Please choose a Blue Express pickup point. 该检查在服务器端进行。
所选网点会连同 Blue Express 网点代码、名称和地址一起保存到订单中。在管理员订单页面中，它显示在收货地址下方，标注为 Blue Express pickup point。点击 Edit 可在 Blue Express 地图上选择其他网点，或手动输入网点代码、名称和地址，然后点击 Save pickup point。此更改会记录在订单备注中。顾客可在订单页面和订单邮件（HTML 与纯文本）中看到网点信息。发送给店铺的邮件也会显示网点代码。已有订单会保留其自提点数据。
许可证密钥
插件需要来自 vibefox.net 的 VibeFox 许可证密钥。许可证区块位于 WooCommerce > Settings > Shipping > VibeFox Blue Express 页面顶部。将密钥粘贴到 License key 中，然后点击 Activate。区块会显示状态，例如许可证的有效期截止日期以及您的域名。使用 Check now 可重新检查状态，Change key 用于输入其他密钥，Remove key 用于从本站点移除密钥。链接 Manage licenses and domains in your account 可打开您的 vibefox.net 账户。
一个密钥只能用于一个域名。从站点移除密钥不会释放其域名名额。请在您的 vibefox.net 账户中释放该名额。
没有有效密钥时，结账时不会向顾客显示 Blue Express。已登录的店铺管理员仍可看到它，并标注 (unlicensed — visible to admins only)，因此您可以在购买密钥之前设置并测试插件。插件页面和 WooCommerce 页面会显示提醒。现有订单不受影响。
许可证到期后，插件仍可继续工作，但更新和支持需要续费。系统会在后台自动重新检查状态。
故障排除
结账时不显示 Blue Express：请检查许可证是否有效、Enable/Disable 是否已开启、该方式是否已添加到顾客地址所在的区域（或 Ignore shipping zones 已开启且允许该国家）。阅读设置页面顶部的警告。检查重量限制、Minimum order subtotal 和 Excluded shipping classes；如果您使用固定价格或备用方案，还要检查 Fixed prices 中是否有该国家的对应行。
不显示实时运费：使用 Blue Express API only 时，如果没有运费，该方式会被隐藏。请开启 Debug log，重新加载结账页面，然后打开 WooCommerce > Status > Logs（来源 "vfd-blue-express"）。常见原因包括：没有 API 密钥、店铺货币不是 CLP 且没有汇率、地址缺少地区或市镇、Blue Express 无法识别该市镇，或出现 API 错误（例如 API 密钥被拒绝时返回 HTTP 401 或 403）。使用 Blue Express API, fixed price if the API gives no rate 时，在您解决问题期间，顾客仍会获得固定价格。
税费被加在 Blue Express 价格之上：Blue Express 价格已含 IVA。如果 WooCommerce 不应再加税，请将 Tax status 设为 None。
地图无法打开：地图由顾客浏览器从 widget-pudo.blue.cl 加载，因此该地址必须可以访问，且不能被您的网站屏蔽。
修改后运费似乎过时：保存设置页面。这会清除缓存的运费和市镇数据。
许可证区块显示错误：请按区块中的提示操作。例如，如果该密钥已在其他域名上使用，请在 vibefox.net 账户中释放一个名额，然后点击 Check now。如果站点地址已更改，请点击 Check now，为新域名激活密钥。如果无法连接许可证服务器，插件将沿用最后一次已知的状态继续工作。
卸载
停用插件会保留所有设置，只清除缓存。要删除插件，请先停用，然后在 Plugins 页面中删除。本插件的许可证密钥、许可证状态和缓存始终会被删除。只有在 Remove data on uninstall 开启时，才会删除设置和区域方式；否则它们会保留，以便日后重新安装。订单中保存的自提点永远不会被删除。
Blue Express 是其各自所有者的商标。本插件与 Blue Express 没有关联，也未获得 Blue Express 的认可。