VibeFox Sameday Easybox for OpenCart — 帮助

要求

OpenCart：3.0.x（已在 3.0.5.0 上测试）或 4.0.2 及更高版本（已在 4.1.0.3 上测试）。

PHP：8.0 或更高版本。

Sameday API 用户名和密码：API 访问权限是罗马尼亚、匈牙利或保加利亚 Sameday 企业账户的一部分。请咨询您的 Sameday 客户经理或 Sameday 集成团队。凭据通常与 eAWB 门户（eawb.sameday.ro、.hu 或 .bg）的相同。对于演示 API，Sameday 会提供单独的测试凭据。没有 API 用户名和密码，就不会提供该方式，因为客户无法选择储物柜。

国家和区县：您的 Sameday 账户所在国家必须在 System > Localisation > Countries 中启用。Sameday 估价需要配送地址的区县（Region / State 字段）。OpenCart 3 包含罗马尼亚和保加利亚的区县，但不包含匈牙利的区县（OpenCart 4.1 包含）。扩展可以为您添加（见下文 easybox 储物柜）。没有区县时，价格来自您的价格表或备用费用。

VibeFox 许可证密钥：在 vibefox.net 购买。一个密钥适用于一个域名。

安装

下载文件是一个 zip 压缩包，内含两个 OpenCart 版本的安装包。请在您的电脑上解压。其中包括 README.txt、OpenCart 3 安装包 vfd_sameday_easybox-oc3-(version).ocmod.zip 和 OpenCart 4 安装包 vfd_sameday_easybox.ocmod.zip。请只安装与您的 OpenCart 版本对应的安装包。两个版本使用相同的许可证密钥。

OpenCart 3

1. 在后台进入 Extensions > Installer，点击 Upload，选择文件 vfd_sameday_easybox-oc3-(version).ocmod.zip。本扩展不添加 OCMOD 修改，因此无需刷新 Extensions > Modifications。您也可以不使用 Installer，而是将安装包中 upload 文件夹的内容复制到商店的根目录。

2. 进入 Extensions > Extensions，选择扩展类型 Shipping，找到 VibeFox Sameday Easybox，然后点击 Install（绿色 + 按钮）。

3. 点击 Edit（铅笔按钮）打开设置页面。

4. 在 Edit 页面上方的许可证区块中，将您的 VibeFox 许可证密钥输入 License key，然后点击 Activate（参见许可证密钥）。

5. 输入 Sameday 的 API username 和 API password，选择 Sameday country，开启 Enable/Disable，然后点击 Save。页面应显示 "Connected to Sameday ... easybox lockers"。Pickup point 和 Easybox service 会根据您的账户自动填写。

6. 设置价格：如果商店货币与 Sameday 货币不同，请设置 Exchange rate of the estimate；并添加一行 Country prices（例如 * Default）或设置 Fallback cost。

7. 如果页面提示 OpenCart 中没有您 Sameday 国家的区县，请点击 easybox lockers 部分中的 Add counties。

OpenCart 4

1. 在后台进入 Extensions > Installer，点击 Upload，然后选择文件 vfd_sameday_easybox.ocmod.zip。请勿重命名该文件：OpenCart 4 从文件名获取扩展代码，重命名后的安装包无法使用。

2. 安装包会出现在同一页面的已安装扩展列表中。点击其旁边的 Install（绿色 + 按钮）。

3. 进入 Extensions > Extensions，选择扩展类型 Shipping。找到 VibeFox Sameday Easybox，点击 Install（绿色 + 按钮），然后点击 Edit（铅笔按钮）。

4. 按 OpenCart 3 第 4 至第 7 步的方式输入许可证密钥和设置。两个版本的设置页面及其字段相同。只有 cron URL 不同（参见 easybox 储物柜）。

安装后，该方式处于关闭状态，直到您开启 Enable/Disable 并保存。如果您卸载后重新安装扩展，之前保留的设置会再次生效，但该方式仍从关闭开始。

配置

所有设置都在扩展页面中：Extensions > Extensions > Shipping > VibeFox Sameday Easybox > Edit。各分区列在左侧。页面底部的一个 Save 按钮会在不刷新页面的情况下保存整个页面。只有对本扩展具有修改权限的管理员用户才能保存设置。

设置上方的页面显示连接状态：Sameday 主机、easybox 储物柜数量以及列表的更新时间，或 Sameday 拒绝了用户名或密码。页面还会列出配置问题，例如缺少凭据、缺少价格、缺少估价汇率、缺少区县、缺少千克重量等级，或所选国家不在您的 Sameday 国家范围内。

某些错误会阻止保存，此时不会保存任何内容：Enter a valid name (1-64 characters, without < > ; = # { }).、Sort order must be a whole number.，或无效的税类或地理区域。其他问题只会保留某一个值：所有价格和限制都接受逗号或句点作为小数分隔符（4,99 或 4.99），无效或负数不会被保存。警告会指明字段，并保留之前的值。

常规

Enable/Disable：在结账时显示或隐藏该方式。这是 Extensions > Extensions > Shipping 中扩展的状态。默认：关闭。

Name：显示给客户的配送方式名称。默认：Sameday easybox。最多 64 个字符。

Tax class：--- None ---（默认）表示价格为最终价格。选择税类后，OpenCart 会在价格上加上该税类的税。

Sort order：该方式在结账时的配送方式中的排序位置。必须为整数。

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-api.demo.zitec.com）和演示凭据。

价格（分区标题显示商店默认货币）

使用顺序为：Sameday 估价（当 Pickup point 和 Easybox service 已设置时）、然后是国家价格表，最后是备用费用。价格表以商店默认货币输入。使用其他货币付款的客户会看到换算后的价格。

Pickup point：您的 Sameday 取件点，即 Sameday 收取包裹的地点。登录成功后，它是您账户取件点的列表，并自动选择默认的取件点。在此之前，它是一个用于输入 ID 的字段。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，即免运费。保存前请选择国家并输入价格，或删除该行。如果同一国家出现在两行中，保存时只保留第一行，并会显示警告。如果某个单元格不是大于或等于 0 的数字，则不会保存该表。

Fallback cost：在没有 Sameday 估价、且价格表中没有该目的地的行时使用。留空则在这种情况下不提供该方式。

Free shipping from：购物车小计（需要配送的商品，扣除折扣后，不含税）达到此金额时，easybox 配送免费。小计达到该金额时，该方式免费提供，且不会查询任何价格。留空则从不提供免运费。

可用性

Minimum weight (kg)：购物车重量低于此值时隐藏该方式。重量由商品的重量等级换算。留空或为 0 表示无限制。

Maximum weight (kg)：超过此重量的包裹不提供 easybox 配送。默认：30。请检查您 Sameday 合同的限制以及 easybox 储物箱的尺寸。留空或为 0 表示无限制。最低重量高于最高重量时不会保存：会显示警告，并保留之前的值。

Minimum cart subtotal：仅当购物车小计（需要配送的商品，扣除折扣后，不含税）达到此金额时才提供该方式。留空表示没有最低金额。

Geo zone：仅为该地理区域内的地址提供该方式。All Zones（默认）表示无限制。地理区域在 System > Localisation > Geo Zones 中管理。开启 Ignore shipping zones 时不检查。

Ignore shipping zones：开启时，不检查地理区域，并针对下方选择的国家提供该方式（如果列表为空，则为 Sameday 国家）。关闭时，仅适用上方的地理区域。

Countries (ignore zones mode)：该模式下的目的国。除 Sameday 国家以外的国家会被跳过，页面会对此发出警告。仅在 Ignore shipping zones 开启时使用此字段。

easybox 储物柜

Locker list：显示已加载多少城市中的多少个 easybox 储物柜以及加载时间。Refresh the locker list now 会重新加载。保存设置时会刷新列表；列表超过一天后，在结账请求之后也会刷新（最多每小时一次）。如需每天固定刷新，请在服务器的 cron 任务中每天调用此处显示的 URL 一次。在 OpenCart 3 上形如 https://your-store/index.php?route=extension/shipping/vfd_sameday_easybox/cron&token=(token)，在 OpenCart 4 上形如 https://your-store/index.php?route=extension/vfd_sameday_easybox/shipping/vfd_sameday_easybox.cron&token=(token)。请完全按照设置页面显示的 URL 复制。该 URL 包含一个密钥令牌。没有正确的令牌时，它会返回错误，且不会联系 Sameday。方式关闭时，它也不会执行任何操作。

Counties：显示 OpenCart 中为您的 Sameday 国家拥有多少个区县。如果没有，请点击 Add counties。扩展会将该国的区县添加到 System > Localisation > Zones，地址表单的 Region / State 字段随之会列出这些区县。已经存在的区县不会重复添加。OpenCart 4.1 已包含三个国家的全部区县，因此那里不需要该按钮。

高级

Debug log：将汇率计算、API 调用和储物柜选择写入 storage/logs/vfd_sdeb_debug.log.php，该文件无法通过网页读取。API 错误始终会被记录。密码、令牌或客户个人数据不会被记录。文件达到 5 MB 时，会开始新的日志。完成后请关闭日志。

Log：显示调试日志的大小和最新条目。点击 Clear log 可清空。

Remove data on uninstall：开启时，卸载扩展会删除设置、缓存的 Sameday 数据和日志。关闭时（默认），设置会保留。储物柜列表和缓存始终会被删除。订单中保存的储物柜始终会保留。

导入 / 导出

Export：点击 Download JSON 可将设置保存为 JSON 文件。API 密码不会被导出。

Import：粘贴之前导出的 JSON，然后点击 Import。这些值会通过与表单相同的检查。已保存的密码会保留。

结账时的工作方式

当 OpenCart 显示配送方式时，它会向扩展请求 Sameday easybox 的价格。扩展会检查地理区域（或 Ignore shipping zones 中的国家）、Sameday 账户的配送国家、API 凭据以及可用的储物柜列表、购物车重量和最低购物车小计。只有 Requires Shipping 设置为 Yes 的商品才会计算在内。小计是这些商品在扣除优惠券折扣后、不含税的价格。如果适用免运费，客户会看到该方式且无需付费。

否则，一旦客户输入了城市和区县，扩展就会向 Sameday 请求估价。它会发送您的取件点和服务、包裹重量以及客户的街道地址、城市、区县和邮政编码。不会发送姓名、电子邮件或电话号码。布加勒斯特会以 "Sector 1" 的形式发送，与官方 Sameday 插件一致。估价会换算为您的商店货币。如果没有估价（未设置、尚无城市或区县、出错、无汇率），价格将来自国家价格表，然后是备用费用。如果没有价格，该方式将被隐藏。价格以客户的货币显示，并含所选 Tax class 的税。

Sameday 的问题绝不会影响结账。估价缓存 1 小时。错误缓存 10 分钟。超时或服务器错误后，5 分钟内不会请求估价。请求在 15 秒后超时。在结账期间，储物柜列表从您的服务器读取，而不是从 Sameday 读取。

本扩展不创建 AWB（发货单）、不打印标签、不跟踪包裹、不处理货到付款。没有上门快递配送，也没有 Sameday 地图组件。请使用 Sameday eAWB 门户或您常用的工具，并以订单中显示的储物柜 ID 创建 AWB。

在 OpenCart 4 上，顾客在结账页面的配送方式区块中点击 Choose，然后在 Shipping method options 窗口中选择 Sameday easybox。价格与 OpenCart 3 相同。

取件点

客户选择该方式时，其下方会出现一个 easybox locker 区块，包含两个列表：- Select city - 和 - Select easybox locker -。若配送地址所在城市有储物柜，则会预先选中该城市。每个储物柜显示其名称和地址。选择会立即保存到结账流程中，因此再次打开配送步骤时仍会保留。

必须选择储物柜。没有选择的话，客户无法继续，并会看到 "Please choose a Sameday easybox locker."。客户点击 Continue 时，服务器会检查所选储物柜是否在列表中。伪造或已删除的储物柜 ID 会被拒绝，并显示 "The selected easybox locker is not available any more. Please choose another easybox locker."。如果无法加载列表，客户会看到 "The easybox lockers could not be loaded. Please try again in a moment or choose another shipping method."。随订单保存的名称和地址来自该列表，而不是来自浏览器。

订单页面、邮件和发票：储物柜会被添加到订单的配送方式中，例如 "Sameday easybox: 名称 - 地址"（先是方式名称，然后是储物柜）。客户可在订单确认、订单历史和订单邮件中看到它，您可在发票上看到它。

管理员订单页面：在 Sales > Orders 中，订单页面有一个 Sameday easybox locker 面板，显示名称、地址以及用于 Sameday AWB 的 Locker ID。如果某个 easybox 订单没有储物柜，面板会显示 "No easybox locker was selected for this order."。即使该方式已关闭，该面板也会显示。

在 OpenCart 4 上，easybox locker 区块显示在 Shipping method options 窗口中、Sameday easybox 选项下方，并且每次窗口打开时都会重新加载城市列表，因为单页结账时地址可能会变化。窗口中的 Continue 按钮在没有有效储物柜时不会继续，显示相同的消息。OpenCart 4 为结账保留一个订单，并在顾客每次重新确认时更新它，订单的储物柜也会随之更新。管理员订单页面的面板显示在 History 部分的上方。

许可证密钥

本扩展需要来自 vibefox.net 的 VibeFox 许可证密钥。License — VibeFox Sameday Easybox 许可证区块是 Extensions > Extensions > Shipping > VibeFox Sameday Easybox > Edit 页面中位于设置上方的第一个区块。将密钥粘贴到 License key 中，然后点击 Activate。之后，该区块会以掩码形式显示密钥、状态（例如许可证有效期至的日期和您的域名），以及以下按钮：Check now（重新检查状态）、Change key（输入另一个密钥）和 Remove key（从本商店移除密钥）。其下方是 Product: opencart-shipping-sameday-easybox 一行，以及 Manage licenses and domains in your account 链接，它会打开您的 vibefox.net 账户。只有对本扩展具有 Modify 权限的管理员用户才能更改密钥。该区块的文字跟随后台语言显示（包括英语和俄语）。

如果密钥未被接受，该区块会说明原因，例如 Key not found、This key belongs to another product、Domain limit reached，或带日期的 License expired on。更改商店地址后，或在账户中释放域名名额后，请点击 Check now。如果无法连接许可证服务器，扩展会继续使用最后已知的状态运行。

一个密钥仅适用于一个域名：即 OpenCart 配置中的商店地址。从商店移除密钥不会释放其域名名额。请在您的 vibefox.net 账户中释放该名额。

如果没有有效的密钥，Sameday easybox 配送方式不会在结账时显示给顾客，也不会请求或计算价格。以同一浏览器登录后台的管理员仍可在商店中看到该配送方式，并标记为 (unlicensed — visible to admins only)，因此您可以在购买密钥之前设置和测试扩展。在 OpenCart 4 上没有此预览：商店看不到后台登录状态，因此没有有效密钥时，所有人都看不到该配送方式。打开一次 Edit 页面后，后台 Dashboard 会出现提醒。点击 × 关闭，可隐藏 7 天。现有订单不受影响。

许可证到期后，扩展仍会继续运行，但更新和支持需要续费。打开后台 Dashboard 或 Edit 页面时会自动重新检查状态：输入密钥后的前 14 天每天一次，之后每周一次。无需 Cron 任务。卸载扩展时始终会删除许可证密钥和许可证状态。

故障排除

Sameday easybox 未在结账时出现：请检查许可证是否有效、Enable/Disable 是否开启、API 用户名和密码是否已输入、设置页面是否显示 "Connected to Sameday"，以及目的国是否为您 Sameday 账户所在的国家。检查是否有可用价格（Sameday 估价、国家行、* Default 行或 Fallback cost）、重量和小计限制、Geo zone 以及 Ignore shipping zones 中的国家。检查商品的 Requires Shipping 是否设置为 Yes。开启 Debug log 可在 Log 字段中查看原因。

Sameday 拒绝了 API 用户名或密码：请检查后重新保存。演示凭据仅在 Test mode 开启时有效，正式凭据仅在其关闭时有效。在此之前，若有已保存的储物柜列表则会提供该列表，且不会使用 Sameday 估价。

价格来自我的价格表，而非 Sameday：估价需要 Pickup point、Easybox service、您 Sameday 国家的区县，并且，如果您的商店货币与 Sameday 货币不同，还需要 Exchange rate of the estimate。只有在客户输入城市和区县之后才会请求估价。当 Sameday 无法访问或返回错误时，将使用价格表或备用费用；原因记录在日志中。

储物柜列表过旧或缺失：请点击 Refresh the locker list now 或保存设置。如果刷新失败，将使用之前的列表，且状态会显示相关信息。

配送意外免费：请检查 Free shipping from 以及 Price 为 0 的 Country prices 行，尤其是通过 Add country 添加且未填写的 * Default 行。

重量限制或重量列不匹配：如果页面提示没有单位为 "kg" 的重量等级，请在 System > Localisation > Weight Classes 中添加一个千克重量等级。

页面显示 "Warning: You do not have permission to modify VibeFox Sameday Easybox!"：您的管理员用户组可能只能查看设置。请在 System > Users > User Groups 中授予该组对 extension/shipping/vfd_sameday_easybox（OpenCart 3）或 extension/vfd_sameday_easybox/shipping/vfd_sameday_easybox（OpenCart 4）的修改权限。

卸载

进入 Extensions > Extensions，选择 Shipping 类型，然后点击 VibeFox Sameday Easybox 旁边的 Uninstall（红色 − 按钮）。本扩展的许可证密钥和许可证状态总会被删除。OpenCart 总会重置 Enable/Disable、Sort order、Tax class 和 Geo zone。保存的储物柜列表、账户检查结果和所有缓存总会被删除。若 Remove data on uninstall 开启，其他设置、cron 令牌和日志也会被删除。若关闭，则会保留，并在您重新安装扩展时再次使用。现有订单会保留已保存的储物柜。

在 OpenCart 4 上，如需同时删除扩展文件，请在卸载后进入 Extensions > Installer，在已安装扩展列表中点击 VibeFox Sameday Easybox 旁边的 Uninstall（橙色 − 按钮），然后点击 Delete（红色垃圾桶按钮）删除已上传的安装包。

Sameday 和 easybox 是其各自所有者的商标。本扩展与 Sameday 无关联，也未获得 Sameday 认可。