VibeFox Servientrega for PrestaShop — 帮助
系统要求
PrestaShop：8.0 至 9.x。
PHP：8.0 或更高版本。模块拒绝在较旧的 PHP 版本上安装。
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 购买。一个密钥对应一个域名。
安装
1. 在后台进入 Modules > Module Manager，点击 Upload a module。选择模块的 ZIP 文件。
2. 上传完成后，点击 Configure；或者之后在模块列表中找到 VibeFox Servientrega，然后点击 Configure。
3. 在 Configure 页面顶部的许可证区块的 License key 中输入 VibeFox 许可证密钥，然后点击 Activate（参见许可证密钥）。
4. 如需实时运费，请输入用户名、密码和计费代码，选择 Servientrega 产品，输入发货地的 DANE 代码；如果店铺货币不是 COP，还需输入货币汇率。如果店铺尚无哥伦比亚省份，请点击 Add Colombian departments（参见配置）。
5. 可选：添加按国家和重量设置的固定运费以及备用运费，然后点击 Save。
安装时，模块会创建 Servientrega 承运商，配送时间文本为 Servientrega courier delivery。该承运商分配给所有区域和所有客户群组。可以在 Shipping > Carriers 中更改区域、客户群组、配送时间、Logo 和尺寸限制。请勿在那里设置价格：价格始终来自模块。
配置
所有设置都在模块页面：Modules > Module Manager > VibeFox Servientrega > Configure。设置适用于所有区域。每个部分都有各自的 Save 按钮，点击后会保存整个页面。每次保存都会清除缓存的 Servientrega 报价和登录令牌。
如果保存的设置无法支持实时运费，表单上方的警告会说明原因：缺少用户名、密码或计费代码，缺少汇率，或缺少发货地 DANE 代码。如果店铺的重量或尺寸单位（International > Localization，Local units）模块无法识别，也会出现警告；此时重量按 kg、尺寸按 cm 读取。保存时，以下情况会报错并拒绝保存，且不保存任何内容：非数字的值、负数、汇率为 0、最低重量大于最高重量、表格中的价格错误，或方式标题超过 64 个字符。
常规
Enable Servientrega：一次性在所有区域开启或关闭该承运商。这与 Shipping > Carriers 中的承运商状态是同一开关。
Method title：顾客在购物车和结账时看到的承运商名称。默认：Servientrega。必填，最多 64 个字符。
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 协议中要报价的服务。
计费重量取实际重量与体积重量中的较大者。
Currency conversion rate：Servientrega 以 COP 报价。如果店铺默认货币不是 COP，请输入 1 COP 等于的店铺货币数值，例如 0.00023。申报的包裹价值也按同样方式换算为 COP。如果店铺货币为 COP，请留空。如果店铺使用其他货币且此字段为空，则不使用实时运费，改用固定运费。模块不会获取汇率。小数点和逗号均可作为小数分隔符。
Colombian departments：省份有助于区分同名的市镇。PrestaShop 默认没有哥伦比亚的省份；若没有这些省份，则只能识别在哥伦比亚唯一的城市名称。点击 Add Colombian departments，可将 33 个省份添加为哥伦比亚的州（ISO 代码 ANT、DC……），为哥伦比亚开启 Contains states，并在哥伦比亚地址表单中添加省份字段。已存在的省份不会重复添加。一切就绪后，该字段会显示哥伦比亚地址拥有的省份数量。
Ship from（用于实时运费）
Origin city (DANE code)：发货所在市镇的 8 位 DANE 代码，例如 11001000 Bogotá、05001000 Medellín、76001000 Cali 或 08001000 Barranquilla。也接受 5 位市镇代码。如果该字段为空，且 Shop Parameters > Contact > Stores 中的店铺地址位于哥伦比亚，则使用店铺地址所在的市镇。
固定运费（在没有实时运费时使用：无凭据、目的地在哥伦比亚以外、市镇未知、缺少汇率、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 行适用于没有自有行的所有国家。没有任何价格的行不会被保存。
Fallback cost：在没有实时运费且没有表格行匹配时使用。留空则在这种情况下隐藏该承运商。
Fixed price applies：固定运费的计费方式。
Servientrega 实时运费始终按每个发货单计算。
条件
Minimum weight：购物车重量低于此值时隐藏该承运商，单位为 kg。0 表示不限制。
Maximum weight：购物车重量高于此值时隐藏该承运商，单位为 kg。默认：50。0 表示不限制。
Minimum order amount：仅当购物车小计（折扣后、税前）达到此金额时才显示该承运商。留空则始终显示。
Free shipping from：当购物车小计（折扣后、税前）达到此金额时免运费，且不向 Servientrega 发送请求。适用于提供该承运商的所有目的地，包括价格表中没有对应行的国家。留空则从不提供免运费。
Tax：承运商的税务规则，或 No tax。Servientrega 报价（ValorTotal）已包含承运商费用。如果不希望在其上另加税，请选择 No tax。
无配送区域时的可用性
通常，承运商会在 Shipping > Carriers 中分配给它的区域提供。
Ignore shipping zones：即使承运商未分配到下列国家所在的区域，也为这些国家提供 Servientrega。此时承运商会被分配到所有区域，包括之后创建的区域。关闭此选项会恢复承运商原有的区域。
Countries：该模式下的目的地国家。留空则使用店铺所有启用的国家。仅在 Ignore shipping zones 开启时使用此字段。
高级
Debug log：将运费计算和 API 错误写入模块文件夹中的 logs/vfd_svtg_debug.log.php。该文件无法通过网页打开。凭据、令牌和顾客地址不会被记录。日志关闭时，不会写入任何内容，包括 API 错误。使用完毕后请关闭日志。
Log：显示调试日志的大小和最新条目。点击 Clear log 可清空。
Remove data on uninstall：开启时，卸载模块会删除所有 Servientrega 设置、承运商、缓存的报价和日志。过往订单保留其承运商。关闭时，所有内容都会保留，以便重新安装。
结账时的运作方式
在配送步骤，PrestaShop 向模块请求 Servientrega 价格。只有实体商品计入：虚拟商品不增加重量，也不计入订单金额。模块首先检查条件：配送国家（结合 Ignore shipping zones）、购物车重量和最低订单金额。若适用免运费，价格为 0，且不会向 Servientrega 发送请求。然后查找价格：先是 Servientrega 实时运费，其次是价格表，最后是备用运费。若没有价格，则该购物车中隐藏该承运商。
对于已设置凭据且目的地为哥伦比亚的订单，模块会查找顾客所在市镇的 DANE 代码。它会使用作为邮编或城市字段输入的 DANE 代码，或将省份和城市与内置的约 1,130 个市镇表进行匹配。重音符号和 "D.C." 会被忽略。仅存在于一个省份中的城市名称，即使没有省份也能被找到。
随后，模块向 Servientrega 按每个订单发送一件货物：总重量从店铺单位换算为 kg，以及一个箱子，其长宽取最大商品的长和宽，高度取所有商品的总体积，并换算为 cm。没有尺寸的商品按 10 × 10 × 10 cm 计算。申报价值为购物车小计换算为 COP 后的金额，最低为 6,000 COP。Servientrega 以 COP 返回总价。模块将其换算为店铺默认货币，顾客则以购物车货币看到价格。
登录令牌在过期前保存，最长 4 天。被拒绝的令牌会自动续期一次。每条报价按路线和包裹缓存 1 小时，因此同一购物车不会触发新的请求。失败的请求（加密、登录或报价）会缓存 10 分钟，以免结账页面每次刷新都等待 Servientrega。每次请求的超时时间为 10 秒。
顾客永远不会看到 API 错误。开启调试日志时，原因会被写入日志。
如果在订单产生后于 Shipping > Carriers 中编辑承运商，PrestaShop 会将其保存为承运商的新版本。模块会自动跟随新版本。
模块只计算运费。它不会生成运单（guías）、面单或贴纸，不会预约取件，不会跟踪或取消发货，也不允许顾客选择 Servientrega 网点（Centro de Soluciones）。请在 SISCLINET 或 Servientrega 门户中生成运单。不报价货到付款（logística de recaudo）。实时报价仅适用于哥伦比亚境内的国内发货。其他国家使用固定运费。
许可证密钥
本模块需要从 vibefox.net 获取的 VibeFox 许可证密钥。许可证区块 License — VibeFox Servientrega 是 Modules > Module Manager > VibeFox Servientrega > Configure 页面中位于设置上方的第一个区块。请在 License key 中输入该密钥，然后点击 Activate。之后，该区块会以掩码形式显示密钥、状态（例如许可证有效期截止日期和您的域名），以及以下按钮：Check now 用于重新检查状态，Change key 用于输入其他密钥，Remove key 用于从本店铺移除密钥。其下方是 Product: presta-shipping-servientrega 一行，以及打开您 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 账户中释放该名额。
如果没有有效的密钥，结账时不会向顾客显示 Servientrega 承运商，也不会请求或计算任何运费。PrestaShop 前台并不知道您已登录后台，因此承运商对您也会隐藏：您可以在购买密钥前设置模块，但无法在结账时测试。提醒会出现在 Modules > Module Manager 的 Alerts 选项卡中。现有订单不受影响。
许可证过期后，模块仍会继续运行，但更新和支持需要续订。您在后台工作时会自动重新检查状态：输入密钥后的前 14 天每天一次，之后每周一次。无需 cron 任务。卸载或重置模块始终会删除许可证密钥和许可证状态。
故障排除
结账时没有显示 Servientrega：检查许可证是否有效，以及 Enable Servientrega 是否开启。在 Shipping > Carriers 中，检查该承运商是否覆盖顾客所在国家的区域和顾客所属的群组，或开启 Ignore shipping zones 并检查 Countries。检查重量限制和 Minimum order amount。若没有实时运费，检查该国家或 * Default 行是否有价格，或是否设置了 Fallback cost。此外，商品页面中也可能将商品限制为特定承运商。
实时运费没有显示：开启 Debug log，刷新结账页面，并查看模块页面上的 Log 字段。常见原因：缺少汇率（店铺货币不是 COP）、没有发货地 DANE 代码、顾客的省份或城市尚未填写或不是已知的市镇、凭据错误，或该路线没有服务。如果已设置固定运费，这些情况下会使用固定运费。
登录失败：请与 Servientrega 商务顾问核对用户名、密码和计费代码。登录失败后，模块会等待 10 分钟再尝试。保存设置可立即重试。
顾客的城市无法识别：点击 Add Colombian departments，让顾客可以选择其省份。对于少见的拼写，顾客可以将 8 位 DANE 代码作为邮编输入。
修改后运费看起来过时：在模块页面点击 Save。这会清除缓存的 Servientrega 报价和令牌。
页面提示找不到 Servientrega 承运商：该承运商已在 Shipping > Carriers 中被删除。请在 Modules > Module Manager 中重置模块，以重新创建。
开发人员：钩子 actionVfdSvtgDaneCode 和 actionVfdSvtgQuoteRequest 允许修改目的地 DANE 代码和报价请求。
卸载
进入 Modules > Module Manager，打开 VibeFox Servientrega 旁边的菜单，选择 Uninstall。许可证密钥和许可证状态始终会被删除。缓存的报价、令牌和加密密码始终会被删除。如果开启了 Remove data on uninstall，承运商将被删除（订单保留历史记录），设置和日志也会被删除。如果关闭，则仅停用承运商，所有设置都会保留。重新安装模块或使用 Reset，会让承运商恢复之前的状态。
Servientrega 是其各自所有者的商标。本模块与 Servientrega 无关联，也未获得 Servientrega 的认可。