VibeFox Sameday Easybox for PrestaShop — 帮助
系统要求
PrestaShop：8.0 至 9.x。
PHP：8.0 或更高版本。模块无法在更低版本的 PHP 上安装。
Sameday API 用户名和密码：API 访问权限是罗马尼亚、匈牙利或保加利亚 Sameday 商业账户的一部分。请咨询您的 Sameday 客户经理或 Sameday 集成团队。这些凭据通常与 eAWB 门户（eawb.sameday.ro、.hu 或 .bg）的相同。演示 API 的测试凭据由 Sameday 另行提供。如果没有 API 用户名和密码，将不会提供该承运商，因为顾客无法选择快递柜。
地址表单中的县：Sameday 估价需要配送地址所在的县。PrestaShop 默认没有罗马尼亚、匈牙利和保加利亚的县。模块可以为您添加（参见下文的 easybox 快递柜 部分）。没有县的话，价格将来自您的价格表或备用运费。
VibeFox 许可证密钥：在 vibefox.net 购买。一个密钥对应一个域名。
安装
1. 进入后台，前往 Modules > Module Manager，点击 Upload a module。选择模块的 ZIP 文件。
2. 上传完成后，点击 Configure；或者之后在模块列表中找到 VibeFox Sameday Easybox，然后点击 Configure。
3. 在配置页面顶部的许可证区块的 License key 中输入您的 VibeFox 许可证密钥，然后点击 Activate（参见许可证密钥）。
4. 输入您的 Sameday API username 和 API password，选择 Sameday country，然后点击 Save。页面应显示「已连接到 Sameday ... easybox 快递柜」。Pickup point 和 Easybox service 会根据您的账户自动填写。
5. 设置价格：如果您的商店货币与 Sameday 货币不同，请设置 Exchange rate of the estimate；并设置一行 Country prices（例如 * Default）或 Fallback cost。
6. 如果页面提示商店在您的 Sameday 国家没有县，请点击 easybox 快递柜 部分中的 Add counties。
安装时，模块会创建承运商 Sameday easybox，其配送时间文字为 Delivery to a Sameday easybox locker。该承运商会分配给所有客户组以及罗马尼亚区域。您可以在 Shipping > Carriers 中更改配送区域、客户组、配送时间和图标。请勿在那里设置价格：价格始终来自本模块。
配置
所有设置都位于模块的 Configure 页面，分为六个部分。任一部分的 Save 按钮都会保存整个页面。
在设置上方，页面会显示连接状态：Sameday 主机、快递柜数量以及列表的更新时间，或 Sameday 拒绝了用户名或密码。页面还会列出配置问题，例如缺少凭据、缺少价格、缺少估价汇率、缺少县、店铺重量单位不被模块识别，或找不到承运商。
所有价格和限制都接受逗号或句点作为小数点（4,99 或 4.99）。无效或负数不会被保存：警告会指出对应字段，并保留之前的值。
常规
Enable/Disable：开启或关闭承运商。与 Shipping > Carriers 中的承运商状态相同。
Name：向顾客显示的配送方式名称（即承运商名称）。默认：Sameday easybox。
Tax status：None 表示价格为最终价。Taxable 并配合税务规则时，PrestaShop 会在价格上额外加收该配送税。
Sameday 账户（API）
保存时，模块会登录 Sameday 并加载您的服务、取件点以及快递柜列表。列表每天刷新。
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-api.demo.zitec.com）和演示凭据。
价格
使用顺序为：先 Sameday 估价（已设置 Pickup point 和 Easybox service 时），然后是按国家的价格表，最后是备用运费。价格表中的价格以商店默认货币输入。使用其他货币付款的顾客会看到换算后的价格。
Pickup point：您的 Sameday 取件点，即 Sameday 取件的地点。登录成功后，这是您账户中取件点的列表，并会自动选择默认项。用于 Sameday 估价。选择 - not set (price table only) - 则仅使用价格表。
Easybox service：Sameday 的 easybox 配送服务，通常为「Locker NextDay」（代码 LN），会自动选择。用于 Sameday 估价。
Exchange rate of the estimate：Sameday 以您 Sameday 国家的货币估价：RON、HUF 或 BGN（以欧元销售的保加利亚店铺为 EUR）。如果您的店铺使用其他货币销售，请输入 1 个 Sameday 货币单位对应的店铺货币值，例如 0.20。汇率必须大于 0。没有汇率时不使用估价，而是应用价格表。列弗和欧元会按固定汇率自动换算。
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 配送免费。小计达到后，承运商以零费用提供，且不再查询价格。留空则从不提供免运费。
可用性
Minimum weight (kg)：购物车重量低于此值时隐藏承运商。重量从店铺重量单位（kg、g、lb 或 oz）换算而来。留空或 0 表示无限制。
Maximum weight (kg)：超过此重量的包裹不提供 easybox 配送。默认：30。请核对您 Sameday 合同中的限制以及 easybox 格口尺寸。留空或 0 表示无限制。最低重量高于最高重量时不会保存：会显示警告，并保留之前的值。
Minimum cart subtotal：仅当购物车小计（需要配送的商品、扣除折扣后、不含税）达到此金额时才提供承运商。
Ignore shipping zones：开启后，即使下方所选国家的区域未为承运商设置，也会为这些国家提供承运商（若列表为空则为 Sameday 国家）。此时承运商会关联到所有已启用的区域，包括之后创建的区域。再次关闭时，承运商会恢复之前拥有的区域。关闭时，承运商仅在 Shipping > Carriers 中为其设置的区域内提供。
Countries (ignore zones mode)：该模式下的目的地国家。非 Sameday 国家的选项会被跳过，页面会对此发出警告。仅当 Ignore shipping zones 开启时才使用此字段。
easybox 快递柜
Locker list：显示已加载多少城市的多少个 easybox 快递柜及加载时间。Refresh the locker list now 会重新加载。列表在保存设置时刷新；若超过一天，则在结账请求后刷新。如需固定每日刷新，请在服务器的 cron 任务中每天调用此处显示的 Cron URL 一次。该 URL 包含一个密钥令牌。没有令牌时它会返回错误，且不会连接 Sameday。
Counties：Sameday 估价需要地址所在的县。若 PrestaShop 没有您 Sameday 国家的县（states），请点击 Add counties。模块会添加罗马尼亚、匈牙利或保加利亚的县，并在该国的地址表单中添加县字段。已存在的县不会重复添加。设置完成后，页面会显示县的数量。
高级
Debug log：将价格计算、API 调用和快递柜选择写入模块文件夹中的 logs/vfd_sdeb_debug.log.php 文件，该文件无法通过网页读取。API 错误始终会被记录。密码、令牌或顾客个人数据不会被记录。下方的 Log 字段显示文件末尾内容，并提供 Clear log 按钮。完成后请关闭日志。
Remove data on uninstall：开启后，卸载模块会删除设置和承运商。关闭时，卸载只会关闭承运商。快递柜列表和缓存始终会被删除。已保存在订单中的快递柜始终保留。
结账时的工作流程
店铺为购物车计算运费时，PrestaShop 会向模块请求 Sameday easybox 承运商的价格。模块会检查条件：Sameday 账户的配送国家、API 凭据和可用的快递柜列表、Ignore shipping zones 中的国家、购物车重量和最低购物车小计。不需要配送的商品（虚拟商品）不计算在内。若适用免运费，顾客会看到零费用的承运商。
否则，一旦顾客输入了城市和县，模块会向 Sameday 请求估价。它会发送您的取件点和服务、包裹重量以及顾客的街道、城市、县和邮政编码。不会发送姓名、电子邮件或电话号码。布加勒斯特会以「Sector 1」发送，与 Sameday 官方插件的做法相同。估价会换算为您的店铺货币。如果没有估价（未设置、尚无城市或县、出错、无汇率），价格将来自国家价格表，然后是备用运费。若没有价格，承运商将被隐藏。
Sameday 出现问题时不会影响结账。估价缓存 1 小时，错误缓存 10 分钟。超时或服务器错误后，5 分钟内不会请求估价。请求在 15 秒后超时。结账期间，快递柜列表从您的服务器读取，而不是从 Sameday 读取。
该承运商适用于 Classic 主题（PrestaShop 8）和 Hummingbird 主题（PrestaShop 9）的配送步骤。
本模块不生成 AWB（运单）、不打印面单、不跟踪包裹、不处理货到付款。不提供上门快递配送，也没有 Sameday 地图组件。请在 Sameday eAWB 门户或您常用的工具中，使用订单上显示的快递柜 ID 生成 AWB。
取件点
顾客选择该承运商后，其下方会出现一个 easybox locker 区块，包含两个列表：- Select city - 和 - Select easybox locker -。若收货地址所在城市有快递柜，则会自动预选。每个快递柜都会显示其名称和地址。所选项会立即保存到购物车中，因此在配送步骤刷新或重新加载页面后仍会保留。
快递柜为必选项。未选择快递柜时，顾客无法继续，并会看到「请选择一个 Sameday easybox 快递柜。」当顾客点击 Continue 时，服务器会检查所选快递柜是否在列表中。伪造或已被移除的快递柜 ID 会被拒绝，并提示「所选 easybox 快递柜已不可用，请选择其他 easybox 快递柜。」若无法加载列表，顾客会看到「无法加载 easybox 快递柜。请稍后再试，或选择其他配送方式。」订单中保存的名称和地址均来自该列表，而不是浏览器。订单提交后，其快递柜便不再变更。
后台订单页面：包含名称、地址以及用于 Sameday AWB 的 Locker ID 的 Sameday easybox locker 区块。若 easybox 订单没有快递柜，该区块会显示「此订单未选择 easybox 快递柜。」
订单确认页和订单历史页面：Sameday easybox locker：显示名称和地址。
订单邮件：快递柜名称和地址会添加到订单确认邮件的承运商信息中。发送给店铺的新订单邮件（Mail alerts 模块）还会包含 Locker ID。
许可证密钥
本模块需要一个来自 vibefox.net 的 VibeFox 许可证密钥。许可证区块 License — VibeFox Sameday Easybox 是 Modules > Module Manager > VibeFox Sameday Easybox > Configure 页面中位于设置上方的第一个区块。请在 License key 中输入该密钥，然后点击 Activate。之后，该区块会以掩码形式显示密钥、状态（例如许可证有效期截止日期和您的域名），以及以下按钮：Check now 用于重新检查状态，Change key 用于输入其他密钥，Remove key 用于从本店铺移除密钥。其下方是 Product: presta-shipping-sameday-easybox 一行，以及打开您 vibefox.net 账户的链接 Manage licenses and domains in your account。只有拥有本模块 Configure 权限的员工才能更改密钥。该区块的文字跟随后台语言显示（包括英文和俄文）。
如果密钥未被接受，该区块会说明原因，例如 Key not found、This key belongs to another product、Domain limit reached，或 License expired on 加一个日期。店铺地址变更后，或在您的账户中释放了一个域名名额后，请点击 Check now。如果无法连接许可证服务器，模块将继续使用上次已知的状态运行。
一个密钥对应一个域名：主店铺的域名，多店铺设置中也是如此。从店铺中移除密钥并不会释放其域名名额。请在您的 vibefox.net 账户中释放该名额。
没有有效密钥时，结账时不会向顾客显示 Sameday easybox 承运商，也不会请求或计算任何价格。PrestaShop 前台并不知道您已登录后台，因此承运商对您也会隐藏：您可以在购买密钥前设置模块，但无法在结账时测试。提醒会出现在 Modules > Module Manager 的 Alerts 选项卡中。现有订单不受影响。
许可证过期后，模块仍会继续运行，但更新和支持需要续订。您在后台工作时会自动重新检查状态：输入密钥后的前 14 天每天一次，之后每周一次。无需 cron 任务。卸载模块始终会删除许可证密钥和许可证状态。本模块的 Reset 不会删除数据，因此密钥和状态会保留。
故障排除
结账时不显示 Sameday easybox：请检查许可证是否有效、Enable/Disable 是否开启、API 用户名和密码是否已输入、配置页面是否显示「已连接到 Sameday」，以及目的国家是否为您 Sameday 账户所在的国家。检查是否有可用价格（Sameday 估价、国家行、* Default 行或 Fallback cost），以及重量和小计限制。在 Shipping > Carriers 中，检查承运商是否覆盖顾客所在国家的区域和顾客组，或开启 Ignore shipping zones。商品页面上也可能将商品限制为特定承运商。开启 Debug log，即可在 Log 字段中查看原因。
Sameday 拒绝了 API 用户名或密码：请检查后重新保存。演示凭据仅在 Test mode 开启时有效，正式凭据仅在其关闭时有效。在此之前，如有已保存的快递柜列表，则会继续提供，且不会使用 Sameday 估价。
价格来自我的价格表，而不是 Sameday：估价需要 Pickup point、Easybox service、地址表单中的县，以及当您的店铺货币与 Sameday 货币不同时的 Exchange rate of the estimate。只有在顾客输入城市和县之后才会请求估价。当 Sameday 无法访问或返回错误时，将使用价格表或备用运费；原因会记录在日志中。
快递柜列表过旧或缺失：请点击 Refresh the locker list now，或保存设置。如果刷新失败，将使用之前的列表，并在状态中注明。如果店铺处于维护模式，cron URL 会与店铺其他部分一样被阻止，除非允许 cron 服务器的 IP。
免运费被错误应用：请检查 Free shipping from 以及 Price 为 0 的 Country prices 行，尤其是通过 + Add country 添加且未填写的 * Default 行。
重量限制或重量列不匹配：如果页面提示店铺重量单位未知，请在 International > Localization（Local units）中设置 kg、g、lb 或 oz。
页面提示未找到 Sameday easybox 承运商：该承运商已在 Shipping > Carriers 中被删除。请在 Modules > Module Manager 中重置模块以重新创建。重置会保留现有承运商的设置和状态。
卸载
进入 Modules > Module Manager，打开 VibeFox Sameday Easybox 旁边的菜单，然后选择 Uninstall。许可证密钥和许可证状态始终会被删除。已保存的快递柜列表、账户检查结果和所有缓存始终会被删除。若 Remove data on uninstall 已开启，则承运商会被删除（订单保留历史记录），并删除设置和日志。若关闭，则仅关闭承运商，保留所有设置。重新安装模块后，已保存的承运商会恢复其原有状态。现有订单保留已保存的快递柜。
Sameday 和 easybox 是其各自所有者的商标。本模块与 Sameday 没有关联，也未获得 Sameday 的认可。