VibeFox Sameday Easybox for WooCommerce — 帮助
系统要求
WordPress：5.8 或更高版本。
WooCommerce：7.0 或更高版本，已安装并启用。未安装时插件无法激活。
PHP：8.0 或更高版本。
Sameday API 用户名和密码：API 访问权限属于罗马尼亚、匈牙利或保加利亚的 Sameday 商业账户。请咨询您的 Sameday 客户经理或 Sameday 集成团队。这些凭据通常与 eAWB 门户（eawb.sameday.ro、.hu 或 .bg）的凭据相同。对于演示 API，Sameday 会提供单独的测试凭据。若没有 API 用户名和密码，则不会提供该配送方式，因为顾客将无法选择快递柜。
VibeFox 许可证密钥：在 vibefox.net 购买。一个密钥只能用于一个域名。
安装
1. 在 WordPress 中进入 Plugins > Add New > Upload Plugin，选择插件的 ZIP 文件，然后点击 Install Now。您也可以通过 FTP 将 vfd_sameday_easybox 文件夹上传到 /wp-content/plugins/。
2. 点击 Activate。
3. 打开设置页面：WooCommerce > Settings > Shipping > VibeFox Sameday Easybox，或在插件页面中点击插件名称下方的 Settings。
4. 在页面顶部的许可证区块中输入您的 VibeFox 许可证密钥，然后点击 Activate。
5. 输入您的 Sameday API username 和 API password，选择 Sameday country 并保存。页面应显示 "Connected to Sameday ... easybox lockers"。Pickup point 和 Easybox service 会根据您的账户自动填写。
6. 设置价格：如果商店货币与 Sameday 货币不同，请设置 Exchange rate of the estimate；并设置一行 Country prices（例如 * Default）或 Fallback cost。
7. 在 WooCommerce > Settings > Shipping > Shipping zones 中，将 VibeFox Sameday Easybox 添加到您 Sameday 国家所在的配送区域，或开启 Ignore shipping zones。
配置
所有设置都位于同一页面：WooCommerce > Settings > Shipping > VibeFox Sameday Easybox。这些设置适用于所有配送区域。将该方式添加到某个区域时，区域窗口中只有一个字段：
Title (zone)：顾客在该区域看到的名称。留空则使用全局的 Name。
在设置上方，页面会显示连接状态：Sameday 主机、快递柜数量及列表的更新时间；或者 Sameday 拒绝了用户名或密码。页面还会列出配置问题，例如缺少凭据、缺少价格，或缺少估价所需的汇率。
所有价格和限制值均接受逗号或句点作为小数点（4,99 或 4.99）。无效数字会被拒绝并给出提示。
常规
Enable/Disable：一次性在所有区域中开启或关闭该方式。
Name：显示给顾客的配送方式名称。配送区域可以使用自己的 Title 覆盖它。Default：Sameday easybox。
Tax status：Taxable 会在配送费用上加收 WooCommerce 税费，None 则不加收。
Sameday 账户（API）
保存时，插件会登录 Sameday，并加载您的服务、取件点以及 easybox 快递柜列表。该列表每天刷新一次。
API username：您的 Sameday API 用户名。
API password：您的 Sameday API 密码。若 Sameday 拒绝该密码，10 分钟内不会再次尝试。
Sameday country：您 Sameday 账户所属的国家：Romania (api.sameday.ro)（默认）、Hungary (api.sameday.hu) 或 Bulgaria (api.sameday.bg)。仅提供该国的快递柜，并且该方式仅针对此目的地国家显示。
Test mode：使用 Sameday 演示 API 和演示凭据。
价格
使用顺序为：Sameday 估价（需设置 Pickup point 和 Easybox service）、国家价格表，最后是备用运费。价格表中的价格以商店货币输入。
Pickup point：您的 Sameday 取件点，即 Sameday 上门取件包裹的地点。登录成功后，它会显示您账户下的取件点列表，并自动选择默认取件点。用于 Sameday 估价。选择 - not set (price table only) - 则仅使用价格表。
Easybox service：用于 easybox 配送的 Sameday 服务，通常为 "Locker NextDay"（代码 LN），会自动选择。用于 Sameday 估价。
Exchange rate of the estimate：Sameday 以您 Sameday 国家的货币报价：RON、HUF 或 BGN（以欧元销售的保加利亚店铺为 EUR）。如果您的商店使用其他货币，请输入 1 个 Sameday 货币单位对应的商店货币金额，例如 0.20。未设置时，不使用估价，而是采用价格表。列弗和欧元会按固定汇率自动换算。
Table price：Per order 按一次收取价格。Per item (price x quantity) 按可配送商品数量相乘。这适用于价格表价格和备用运费。Sameday 估价始终针对整个包裹。
Country prices：按目的地国家和包裹重量设置的价格。点击 + Add country 添加一行，点击叉号删除一行。每行包含一个 Price 列以及重量列：XS 为 1 kg 以内，S 为 1–2 kg，M 为 2–3 kg，L 为 3–5 kg，XL 为 5 kg 以上。重量列保持为 0 时使用 Price 列。没有专属行的国家使用 * Default 行。新增的行默认为 * Default，所有价格均为 0，即免运费。保存前请选择国家并输入价格，或删除该行。如果同一国家出现在两行中，保存时只保留第一行。如果某个单元格不是有效数字，则不会保存该价格表。
Fallback cost：在没有 Sameday 估价且国家价格表中没有目的地对应行时使用。留空则此时不提供该配送方式。
Free shipping from：购物车小计（扣除折扣、不含税）达到该金额后，easybox 配送免费。仅适用于能找到价格的情况：国家行、* Default 行或备用运费（此时不请求估价），或 Sameday 估价。留空则从不提供免运费。
可用性
Minimum weight (kg)：购物车重量低于该值时隐藏该方式。重量会按商店的重量单位换算。留空或为 0 表示无限制。
Maximum weight (kg)：超过该重量的包裹不提供 easybox 配送。Default：30。请核对您 Sameday 合同中的限制以及 easybox 快递柜的尺寸。留空或为 0 表示无限制。
Minimum cart subtotal：仅当购物车小计（扣除折扣、不含税）达到该金额时才提供该方式。
Excluded shipping classes：购物车中包含以下任一 WooCommerce 配送类别的商品时，隐藏该方式。
Ignore shipping zones：开启后，即使该方式未添加到对应的配送区域，也会为下方所选的国家提供。关闭时，仅在已添加该方式的区域中提供。
Countries (ignore zones mode)：该模式下的目的地国家。留空则使用 Sameday 国家。与 Sameday 国家不同的国家会被跳过。仅当 Ignore shipping zones 开启时才使用此字段。
高级
Debug log：将运费计算、API 调用和快递柜选择记录到 WooCommerce > Status > Logs（来源为 "vfd-sameday-easybox"）。API 错误始终会被记录。不会记录密码、令牌或顾客个人数据。完成后请关闭日志。
Remove data on uninstall：开启后，删除插件时会一并删除设置以及该方式在各区域中的实例。停用插件从不删除任何内容。订单中保存的快递柜信息始终保留。
结账时的工作方式
顾客输入收货地址后，WooCommerce 会向插件请求运费。插件会检查以下条件：Sameday 账户的配送国家、API 凭据以及可用的快递柜列表、购物车重量、购物车最低小计和排除的配送类别。然后查找价格：Sameday 估价、国家价格表、备用运费。若没有价格，则隐藏该方式。若适用免运费，顾客将免费看到该方式。
否则，在顾客填写城市和省份后，插件会向 Sameday 请求估价。它会发送您的取件点和服务、包裹重量，以及顾客的街道地址、城市、省份和邮政编码。不会发送姓名、电子邮件或电话号码。布加勒斯特将以 "Sector 1" 的形式发送，与 Sameday 官方插件相同。估价会换算为您的商店货币。如果没有估价（未设置、尚未填写城市或省份、出错、没有汇率），价格会依次取自国家价格表和备用运费。若没有价格，则隐藏该方式。
Sameday 的问题绝不会影响结账。估价缓存 1 小时。错误缓存 10 分钟。超时或服务器错误后，5 分钟内不再请求估价。请求 15 秒后超时。结账时，快递柜列表从您的服务器读取，而不是从 Sameday 读取。
该方式适用于经典结账以及购物车和结账区块。它兼容 WooCommerce 高性能订单存储（HPOS）。
插件不生成 AWB（运单）、不打印面单、不跟踪包裹，也不处理货到付款。不提供上门快递配送，也没有 Sameday 地图组件。请在 Sameday eAWB 门户或您习惯使用的工具中，使用订单上显示的快递柜 ID 生成 AWB。
取件点选择
顾客选择该方式后，其下方会出现一个 easybox locker 区块，包含两个列表：- Select city - 和 - Select easybox locker -。若顾客所在城市有快递柜，则会自动预选该城市。每个快递柜都会显示其名称和地址。结账页面刷新或页面重新加载时，所选项会被保留。
快递柜为必选项。未选择时，结账会停止并显示 "Please choose a Sameday easybox locker."。无论是经典结账还是区块结账，服务器都会检查所选快递柜是否在列表中。伪造或已被移除的快递柜 ID 会被拒绝，并显示 "The selected easybox locker is not available any more. Please choose another easybox locker."。订单中保存的名称和地址来自该列表，而非浏览器。
后台订单页面：在收货地址下方显示 Sameday easybox locker，包括名称、地址以及用于 Sameday AWB 的 Locker ID。若某个 easybox 订单没有快递柜，页面会显示 "No easybox locker was selected for this order."。
感谢页面和订单查看页面：Sameday easybox locker: 及名称和地址。
订单邮件：HTML 和纯文本邮件中包含快递柜名称和地址。管理员邮件还包含 Locker ID。
在数据库中，快递柜保存在订单元数据 _vfd_sdeb_locker_id（用于 AWB 的 Sameday 快递柜 ID）和 _vfd_sdeb_locker_name（名称和地址）中。
许可证密钥
插件需要一个来自 vibefox.net 的 VibeFox 许可证密钥。许可证区块位于 WooCommerce > Settings > Shipping > VibeFox Sameday Easybox 页面顶部。将密钥粘贴到 License key 中，然后点击 Activate。该区块会显示状态，例如许可证有效期的截止日期以及您的域名。使用 Check now 重新检查状态，使用 Change key 输入其他密钥，使用 Remove key 将其从本站点移除。Manage licenses and domains in your account 链接会打开您的 vibefox.net 账户。
一个密钥只能用于一个域名。从站点移除密钥并不会释放该域名名额。请在您的 vibefox.net 账户中释放名额。
没有有效密钥时，结账页面不会向顾客显示 Sameday easybox。已登录的商店管理员仍可看到它，并标注为 (unlicensed — visible to admins only)，因此您可以在购买密钥前完成设置和测试。插件页面和 WooCommerce 页面上会显示提醒。现有订单不受影响。
许可证过期后，插件仍可继续工作，但更新和支持需要续费。状态会在后台自动重新检查。
故障排除
结账时不显示 Sameday easybox：请检查许可证是否有效，Enable/Disable 是否已开启，API 用户名和密码是否已填写且设置页面显示 "Connected to Sameday"，以及目的地国家是否为您 Sameday 账户所属的国家。请检查是否有可用价格（Sameday 估价、国家行、* Default 行或 Fallback cost）、重量和小计限制、Excluded shipping classes，以及该方式是否已添加到对应区域（或 Ignore shipping zones 已开启）。开启 Debug log，即可在 WooCommerce > Status > Logs 中查看原因。
Sameday 拒绝了 API 用户名或密码：请检查后重新保存。演示凭据仅在 Test mode 开启时有效，正式凭据仅在其关闭时有效。在此之前，如果存在已保存的快递柜列表，则会继续提供该列表，但不会使用 Sameday 估价。
价格来自我的价格表，而不是 Sameday：估价需要 Pickup point、Easybox service，以及在商店货币与 Sameday 货币不同时需要 Exchange rate of the estimate。只有在顾客填写城市和省份之后才会请求估价。当 Sameday 无法访问或返回错误时，将使用价格表或备用运费；原因会记录在日志中。
快递柜列表过旧或缺失：保存设置。当列表为空、超过一小时或上次加载失败时，会重新加载。如果刷新失败，则使用上一次的列表，并在状态中注明。
错误地免运费：请检查 Country prices 中 Price 为 0 的行，尤其是通过 + Add country 添加且未填写的 * Default 行。
跨境快递柜：开发者可以通过 vfd_sdeb_countries 过滤器添加目的地国家。快递柜列表始终来自您的账户。
许可证区块显示错误：请按照区块中的提示操作。例如，如果该密钥已在其他域名上使用，请在您的 vibefox.net 账户中释放名额，然后点击 Check now。如果站点地址已更改，请点击 Check now，为新域名激活该密钥。如果无法连接许可证服务器，插件将继续使用上一次已知的状态运行。
卸载
停用插件会保留所有数据，仅停止每日刷新快递柜列表。要删除插件，请先停用，然后在 Plugins 页面中删除。该插件的许可证密钥和许可证状态总会被删除，同时删除的还有已保存的快递柜列表、账户检查结果和所有缓存。只有在 Remove data on uninstall 开启时，设置和区域配送方式才会被删除；否则它们会保留，供以后重新安装时使用。现有订单会保留其配送项目和已保存的快递柜。
Sameday 和 easybox 是其各自所有者的商标。本插件与 Sameday 没有关联，也未获得 Sameday 的认可。