VibeFox Servientrega for OpenCart — 帮助

要求

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

PHP：8.0 或更高版本。

Servientrega 账户（仅实时运费需要）：实时运费使用 Servientrega Cotizador Corporativo（企业报价 API）。您需要一个可访问它的 Servientrega 企业（信用）账户。需要三项信息：用户、密码和计费代码（código de facturación，通常以 SER 开头）。它们是您的 SISCLINET 凭据，由您的 Servientrega 商务顾问提供。如果您只使用固定价格，则无需 Servientrega 账户。

服务器访问（仅实时运费需要）：您的服务器必须能够通过 HTTP 访问 web.servientrega.com 的 8058 端口（报价 API）和 8081 端口（密码加密 Web 服务）。

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

安装

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

OpenCart 3

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

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

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

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

5. 若要使用实时运费，请输入用户、密码和计费代码，选择 Servientrega 产品，输入发货地的 DANE 代码；如果您的商店货币不是 COP，还需输入货币换算汇率。

6. 可选：添加按国家和重量的固定价格以及备用费用，开启 Enable Servientrega，然后点击 Save。

OpenCart 4

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

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

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

4. 请按 OpenCart 3 的第 4 至第 6 步输入许可证密钥和设置。设置页面及其字段在两个版本中相同。

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

配置

所有设置都在扩展页面中：Extensions > Extensions > Shipping > VibeFox Servientrega > Edit。各分区列在左侧。它们适用于所有地理区域。页面底部的一个 Save 按钮会在不刷新页面的情况下保存整个页面。每次保存都会清除缓存的 Servientrega 报价和登录令牌。只有对本扩展具有修改权限的管理员用户才能保存设置。

如果实时运费无法与已保存的设置配合工作，设置上方的警告会告诉您原因：缺少用户、密码或计费代码，缺少换算汇率，或缺少发货地 DANE 代码。如果商店没有千克重量等级或厘米长度等级，且其默认单位不为扩展所识别，也会出现警告；此时重量按 kg 读取，尺寸按 cm 读取。保存时，非数字的值、负数、汇率为 0、最低重量高于最高重量、表格中的错误价格、空的方式标题、超过 64 个字符或包含 < > ; = # { } 的标题，或非整数的排序值，都会被错误拒绝，且不会保存任何内容。

常规

Enable Servientrega：在结账时显示或隐藏 Servientrega。默认：关闭。

Method title：客户在购物车和结账时看到的配送方式名称。默认：Servientrega。必填，最多 64 个字符。

Sort order：Servientrega 在结账时配送方式中的排序位置。一个整数。

Servientrega API（哥伦比亚实时运费）（可选；没有凭据时仅使用固定价格）

User (login)：您的 Servientrega / SISCLINET 用户名。清空它也会删除已保存的密码。

Password：您的 Servientrega / SISCLINET 密码，按您输入的方式保存。扩展会在登录前通过 Servientrega Web 服务对其加密。保存后，该字段保持为空，并显示 Saved — leave empty to keep it. 仅在需要更改时才输入新值。

Billing code：您 Servientrega 账户的计费代码（código de facturación），即在 SISCLINET 中显示的代码。通常以 SER 开头。

实时运费需要这三个字段。实时运费仅针对哥伦比亚境内的目的地请求。其他国家使用固定价格。

Servientrega product：您与 Servientrega 的协议中要报价的服务。

Mercancía Premier（包裹；计费重量至少 3 kg）：默认选项。体积重量为每立方米 222 kg。

Mercancía Industrial（重型货物）：体积重量为每立方米 400 kg。

Documento unitario（文件）：用于文件。

计费重量为实际重量与体积重量中的较大者。

Currency conversion rate：Servientrega 以 COP 报价。如果您商店的默认货币不是 COP，请输入 1 COP 对应的商店货币价值，例如 0.00023。包裹的申报价值也按同样方式换算为 COP。如果您商店的货币是 COP，该字段会提示无需换算：请留空。如果您的商店使用其他货币且此字段为空，则不使用实时运费，改用固定价格。扩展不会获取汇率。小数分隔符可以是句点，也可以是逗号。

Ship from（用于实时运费）

Origin city (DANE code)：您发货所在城市的 8 位 DANE 代码，例如 11001000 Bogotá、05001000 Medellín、76001000 Cali 或 08001000 Barranquilla。也接受 5 位城市代码。OpenCart 中的商店地址是自由文本，因此发货地永远不会从中获取：没有此字段就没有实时运费。

Fixed prices（在没有实时运费时使用：没有凭据、目的地不在哥伦比亚、城市未知、缺少换算汇率、API 错误或该路线无服务覆盖）

Price per country：以商店默认货币（不含税）填写的国家和价格表。点击 Add country 添加一行，点击删除按钮删除一行。Price 适用于任何重量。重量列 XS（最多 1 kg）、S（1–2 kg）、M（2–3 kg）、L（3–5 kg）和 XL（超过 5 kg）在大于 0 时会替换该重量下的价格。* Default 行适用于所有没有自己行的国家。新行默认为 * Default。没有任何价格的行不会被保存。

Fallback cost：在没有实时运费且表格中没有匹配行时使用。留空则在这种情况下隐藏该方式。

Fixed price applies：固定价格的计费方式。

Per order（整个购物车的重量档位）：与购物车重量相符的重量列的价格，只收取一次。这是默认值。

Per item（每件商品的重量档位 × 数量）：每件商品对应重量列的价格，乘以其数量后相加。备用费用按商品件数相乘。

Servientrega 实时运费始终按每个发货单计算。

Conditions

Minimum weight (kg)：购物车重量低于此值时隐藏该方式。0 表示无限制（默认）。

Maximum weight (kg)：购物车重量高于此值时隐藏该方式。默认：50。0 表示无限制。

Minimum order amount：仅当需要配送的商品小计（使用优惠券后、税前）达到此金额时才显示该方式。留空则始终显示。

Free shipping from：当该小计达到此金额时免运费，并且不会向 Servientrega 发送请求。它适用于所有提供该方式的目的地，也适用于价格表中没有对应行的国家。留空则从不提供免运费。

Tax class：运费的税类，或 No tax（默认）。Servientrega 报价（ValorTotal）已包含承运商的费用。如果您不想在其上额外加税，请选择 No tax。

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

Availability without geo zone

通常该方式会在 Conditions 中选择的地理区域内提供，或者在所有地方提供。

Ignore shipping zones：无论地理区域如何，都为下方的国家提供 Servientrega。

Countries：该模式下的目的国。留空则使用商店中所有已启用的国家。此字段仅在 Ignore shipping zones 开启时使用。

Advanced

Debug log：将运费计算和 API 错误写入 storage/logs/vfd_svtg_debug.log.php。该文件无法通过网页读取。凭据、令牌和客户地址不会被记录。日志关闭时，不会写入任何内容，包括 API 错误。文件达到 5 MB 时，会被移动到 vfd_svtg_debug.old.log.php，并开始新的日志。完成后请关闭日志。

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

Remove data on uninstall：开启时，卸载扩展会删除所有 Servientrega 设置和日志。关闭时（默认），它们会被保留，以便重新安装。缓存的报价始终会被删除。

导入 / 导出

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

Import：粘贴之前导出的 JSON，然后点击 Import 以恢复设置，例如在另一家商店中。这些值会像正常保存一样进行检查。只要已设置用户，已保存的密码就会保留。

结账时的工作方式

当 OpenCart 显示配送方式时，它会向扩展请求 Servientrega 的价格。如果设置了 Geo zone 且地址在其之外，则不提供 Servientrega（除非开启了 Ignore shipping zones）。只有 Requires Shipping 设置为 Yes 的商品才会计入：其他商品不增加重量，也不计入订单金额。订单金额是这些商品在扣除优惠券折扣后、税前的价格。礼品卡和积分不计入。扩展首先检查条件：配送国家（使用 Ignore shipping zones）、购物车重量和最低订单金额。如果适用免运费，价格为 0，并且不会向 Servientrega 发送请求。然后它查找价格：Servientrega 实时运费，然后是价格表，最后是备用费用。如果没有价格，则该购物车隐藏此方式。

对于已设置凭据的哥伦比亚目的地，扩展会找到客户所在城市的 DANE 代码。它使用在邮政编码或城市字段中输入的 DANE 代码，或将省和城市与内置的约 1,130 个城市表进行匹配。省是地址的 Region / State：OpenCart 已包含哥伦比亚全部 33 个省。重音符号和 "D.C." 会被忽略。仅存在于一个省的城市，即使没有省名也能被找到。

然后，扩展会为每个订单向 Servientrega 发送一件货物：总重量从商品的重量等级换算为 kg，以及一个箱子，其长度和宽度取最大商品的尺寸，其容积为所有商品的总容积，换算为 cm。没有尺寸的商品按 10 × 10 × 10 cm 计算。申报价值为订单金额换算为 COP，最低为 6,000 COP。Servientrega 以 COP 返回总额。扩展将其换算为商店的默认货币，并按其小数位数进行舍入。客户会看到其货币的价格，并含所选 Tax class 的税。

登录令牌在过期前保留，最长 4 天。被拒绝的令牌会自动续期一次。每条报价按路线和包裹缓存 1 小时，因此相同的购物车不会触发新的请求。失败的请求（加密、登录或报价）缓存 10 分钟，这样结账时就不会在每次刷新时都等待 Servientrega。每次请求的超时时间为 10 秒。

客户永远看不到 API 错误。开启调试日志时，原因会写入日志。

本扩展只计算运费。它不创建运单（guías）、标签或贴纸，不预约取件，不跟踪或取消货件，也不允许客户选择 Servientrega 网点（Centro de Soluciones）。请在 SISCLINET 或您的 Servientrega 门户中创建运单。不报价货到付款（logística de recaudo）。实时报价仅适用于哥伦比亚境内的国内发货。它不会为订单添加任何内容：订单显示配送方式名称和运费，与其他任何 OpenCart 配送方式一样。

在 OpenCart 4 上，客户在结账页面的配送方式区块中点击 Choose，然后在 Shipping method options 窗口中选择 Servientrega，该窗口会显示方式名称及价格。该方式的工作方式与 OpenCart 3 相同。

许可证密钥

本扩展需要来自 vibefox.net 的 VibeFox 许可证密钥。许可证区块 License — VibeFox Servientrega 位于 Extensions > Extensions > Shipping > VibeFox Servientrega > Edit 页面的最上方，在设置之前。将密钥粘贴到 License key 中并点击 Activate。之后，该区块会显示遮盖后的密钥、状态（例如许可证有效期截止日期和您的域名），以及以下按钮：Check now（重新检查状态）、Change key（输入其他密钥）和 Remove key（从本商店移除密钥）。其下方是 Product: opencart-shipping-servientrega 一行和 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 账户中释放该名额。

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

许可证到期后，扩展仍会继续工作，但更新和支持需要续期。打开后台 Dashboard 或 Edit 页面时会自动再次检查状态：输入密钥后的前 14 天每天一次，之后每周一次。无需设置定时任务（cron）。卸载扩展时总会删除许可证密钥和许可证状态。

故障排除

Servientrega 未在结账时出现：请检查许可证是否有效，并确认 Enable Servientrega 已开启。检查 Geo zone，或开启 Ignore shipping zones 并检查 Countries。检查重量限制和 Minimum order amount。如果没有实时运费，请检查该国家或 * Default 是否有价格，或是否设置了 Fallback cost。检查商品的 Requires Shipping 是否设置为 Yes。

实时运费不显示：开启 Debug log，重新加载结账页面，并查看扩展页面上的 Log 字段。常见原因：缺少换算汇率（商店货币不是 COP）、没有发货地 DANE 代码、客户的省或城市尚未输入或不是已知城市、凭据错误、该路线无服务覆盖，或服务器无法通过端口 8058 和 8081 访问 web.servientrega.com。如果您已设置固定价格，它会覆盖这些情况。

登录失败：请与您的 Servientrega 商务顾问核对用户、密码和计费代码。登录失败后，扩展会等待 10 分钟再进行下一次尝试。保存设置可立即重试。

无法识别客户的城市：客户应在 Region / State 字段中选择省份。对于罕见的拼写，客户可以将 8 位 DANE 代码作为邮政编码输入。

修改后报价看起来过时：在扩展页面点击 Save。这会清除缓存的 Servientrega 报价和令牌。

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

面向开发者：OpenCart 事件 vfd_servientrega/dane_code 和 vfd_servientrega/quote_request 允许其他扩展更改目标 DANE 代码和报价请求。

卸载

进入 Extensions > Extensions，选择 Shipping 类型，然后点击 VibeFox Servientrega 旁边的 Uninstall（红色 − 按钮）。许可证密钥和许可证状态总会被删除。OpenCart 总会重置 Enable Servientrega、Sort order、Tax class 和 Geo zone。缓存的报价、令牌和加密密码总会被删除。若 Remove data on uninstall 开启，其他设置和日志也会被删除。若关闭，则会保留，并在您重新安装扩展时再次使用。现有订单会保留其配送方式和费用。

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

Servientrega 是其所有者的商标。本扩展与 Servientrega 无关联，也未获得 Servientrega 认可。