VibeFox Servientrega for WooCommerce — 帮助
系统要求
WordPress：5.8 或更高版本。
WooCommerce：5.0 或更高版本，已安装并启用。未安装 WooCommerce 时插件无法激活。
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 购买。一个密钥只能用于一个域名。
安装
1. 在 WordPress 中进入 Plugins > Add New > Upload Plugin，选择插件的 ZIP 文件，然后点击 Install Now。您也可以通过 FTP 将 vfd_servientrega 文件夹上传到 /wp-content/plugins/。
2. 点击 Activate。
3. 打开设置：WooCommerce > Settings > Shipping > VibeFox Servientrega，或在插件页面点击插件名称下方的 Settings。
4. 在页面顶部的许可证区块中输入您的 VibeFox 许可证密钥，然后点击 Activate。
5. 如需实时运费，请输入用户名、密码和计费代码，选择 Servientrega 产品，输入发货地 DANE 代码；如果店铺货币不是 COP，还需输入货币换算汇率（参见「配置」）。
6. 可选：按国家和重量添加固定运费，并设置备用运费。
7. 在 WooCommerce > Settings > Shipping > Shipping zones 中将 VibeFox Servientrega 添加到配送区域，或开启 Ignore shipping zones 并选择国家。
配置
所有设置位于同一页面：WooCommerce > Settings > Shipping > VibeFox Servientrega。这些设置适用于所有配送区域。将该方式添加到某个区域时，区域窗口中只有一个字段：
Title (zone)：顾客在此区域看到的名称。留空则使用全局的 Method title。
每次保存设置时，缓存的 Servientrega 报价和登录令牌都会被清除。如果按已保存的设置无法获取实时运费，设置页面上方会显示警告并说明原因：缺少用户名、密码或计费代码，缺少换算汇率，或缺少发货地 DANE 代码。
常规
Enable/Disable：一次性在所有区域启用或禁用该方式。
Method title：在购物车和结账页面显示的配送方式名称。区域可以覆盖此名称。默认值：Servientrega。
Servientrega API（哥伦比亚实时运费）（可选；未填写凭据时仅使用固定运费）
User (login)：您的 Servientrega / SISCLINET 用户名。
Password：您的 Servientrega / SISCLINET 密码，按您输入的内容保存。插件会在登录前由 Servientrega Web 服务对密码进行加密，与官方 Servientrega 客户端的做法一致。
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，请留空。如果店铺使用其他货币且此字段为空，则不使用实时运费，改用固定运费。插件不会获取汇率。小数点和逗号均可作为小数分隔符。
发货地（用于实时运费）
Origin city (DANE code)：您发货所在市镇的 8 位 DANE 代码，例如 11001000 Bogotá、05001000 Medellín、76001000 Cali 或 08001000 Barranquilla。也接受 5 位市镇代码。如果留空，且 WooCommerce > Settings > General 中的店铺地址位于哥伦比亚，则使用店铺地址所在的市镇。
固定运费（在没有实时运费时使用：未填写凭据、目的地在哥伦比亚以外、市镇未知、缺少换算汇率，或 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 时会替代该重量下的 Price。* Default 行适用于所有没有单独设置行的国家。
Fallback cost：在没有实时运费且表格中没有匹配行时使用。留空则在这种情况下隐藏该方式。
Fixed price applies：固定运费的计费方式。
Servientrega 实时运费始终按每个发货单计算。
条件
Minimum weight (kg)：购物车重量低于此值时隐藏该方式。0 表示无限制。
Maximum weight (kg)：购物车重量高于此值时隐藏该方式。默认值：50。0 表示无限制。
Minimum order amount：仅当购物车小计（扣除折扣后、税前）达到此金额时才显示该方式。留空则始终显示。
Free shipping from：购物车小计（扣除折扣后、税前）达到此金额时免运费。仅适用于该方式有价格的情况：表格价格或备用运费（此时不会向 Servientrega 发送请求），或实时运费。留空则从不提供免运费。
Excluded shipping classes：购物车中包含以下任一 WooCommerce 配送类别的商品时，隐藏该方式。
Tax status：Taxable 会将 WooCommerce 税费加到运费上，None 则不加。Servientrega 报价（ValorTotal）已包含承运商的费用。如果不想在此基础上再加税，请选择 None。
无配送区域时的可用性
Ignore shipping zones：即使该方式未添加到任何配送区域，也为下方指定的国家提供 Servientrega。
Countries：此模式下的目的地国家。留空则使用您配送的所有国家。此字段仅在 Ignore shipping zones 开启时使用。
高级
Debug log：将运费计算和 API 错误写入 WooCommerce 日志：WooCommerce > Status > Logs，来源 vfd_servientrega。凭据、令牌和顾客地址不会被记录。使用完毕后请关闭日志。
Remove data on uninstall：开启后，删除插件会移除所有 Servientrega 设置、区域方式和缓存的报价。停用插件则不会删除任何内容。
结账时的工作方式
顾客输入配送地址后，WooCommerce 会向插件请求运费。插件首先检查条件：配送国家、购物车重量、最低订单金额和排除的配送类别。然后查找价格：先是 Servientrega 实时运费，其次是价格表，最后是备用运费。如果没有价格，则隐藏该方式。如果适用免运费，则以 0 元价格显示该方式。
对于已设置凭据且目的地在哥伦比亚的订单，插件会查找顾客所在市镇的 DANE 代码。它会使用作为邮编或城市字段输入的 DANE 代码，或将省份和城市与内置的约 1,130 个市镇表格进行匹配。重音符号和 "D.C." 会被忽略。仅存在于一个省份中的城市名称，即使未填写省份也能找到。
随后，插件会向 Servientrega 发送每个订单一个包裹：将店铺单位的总重量换算为千克，并附上一个箱子，箱子的长宽取最大商品的尺寸，体积为所有商品的总体积，换算为厘米。没有尺寸的商品按 10 × 10 × 10 cm 计算。申报价值为购物车小计换算为 COP 后的金额，且不低于 6,000 COP。Servientrega 以 COP 返回总额，插件再将其换算为店铺货币。
登录令牌会保存到过期为止，最长 4 天。被拒绝的令牌会自动续期一次。每个报价按路线和包裹缓存 1 小时，因此同一购物车不会重复发起请求。失败的请求（加密、登录或报价）会缓存 10 分钟，使结账页面在每次刷新时都无需等待 Servientrega。每个请求的超时时间为 10 秒。
如果没有实时运费，则价格取自固定运费表，然后取自 Fallback cost。如果两者都不适用，则隐藏该方式。顾客永远不会看到 API 错误。原因会写入调试日志。
该方式适用于经典结账以及购物车和结账区块。它兼容 WooCommerce 高性能订单存储（HPOS）。包含西班牙语翻译（哥伦比亚、西班牙）。
插件仅计算运费。它不会生成运单（guías）、面单或贴纸，不会预约取件，不会跟踪或取消发货，也不允许顾客选择 Servientrega 网点（Centro de Soluciones）。请在 SISCLINET 或您的 Servientrega 门户中创建运单。不提供货到付款（logística de recaudo）报价。实时报价仅适用于哥伦比亚境内的国内发货。厄瓜多尔、秘鲁、巴拿马以及国际发货使用固定运费。
许可证密钥
插件需要来自 vibefox.net 的 VibeFox 许可证密钥才能使用。许可证区块位于 WooCommerce > Settings > Shipping > VibeFox Servientrega 页面顶部。将密钥粘贴到 License key 中，然后点击 Activate。该区块会显示状态，例如许可证有效期至何时以及您的域名。使用 Check now 重新检查状态，使用 Change key 输入其他密钥，使用 Remove key 从本站移除密钥。链接 Manage licenses and domains in your account 会打开您的 vibefox.net 账户。
一个密钥只能用于一个域名。从站点移除密钥并不会释放其域名名额。请在您的 vibefox.net 账户中释放该名额。
没有有效密钥时，Servientrega 不会在结账时显示给顾客。已登录的店铺管理员仍可看到它，并标有 (unlicensed — visible to admins only)，以便您在购买密钥前完成插件的设置和测试。插件页面和 WooCommerce 页面上会显示提醒。现有订单不受影响。
许可证到期后，插件仍可继续工作，但更新和支持需要续费。系统会在后台自动重新检查状态。
故障排除
结账时未显示 Servientrega：请检查许可证是否有效、Enable/Disable 是否已开启，以及该方式是否已添加到顾客所在国家的区域中（或已开启 Ignore shipping zones 且该国家已允许）。检查重量限制、Minimum order amount 和 Excluded shipping classes。在没有实时运费的情况下，请检查该国家或 * Default 是否设置了价格，或是否已设置 Fallback cost。
实时运费未显示：开启 Debug log，刷新结账页面，然后打开 WooCommerce > Status > Logs，来源选择 vfd_servientrega。常见原因：缺少换算汇率（店铺货币不是 COP）、缺少发货地 DANE 代码、顾客的省份或城市尚未填写或不是已知市镇、凭据错误，或该路线没有覆盖范围。如果您已设置固定运费，则可覆盖这些情况。
登录失败：请与您的 Servientrega 商务顾问核对用户名、密码和计费代码。登录失败后，插件会等待 10 分钟再尝试。保存设置可立即重试。
无法识别顾客的城市：省份和城市会与内置的 DANE 表格进行匹配。对于不常见的写法，顾客可以将 8 位 DANE 代码作为邮编输入。开发者可以使用 vfd_svtg_dane_code 过滤器进行映射。
更改后运费似乎过时：保存设置页面。这会清除缓存的 Servientrega 报价和令牌。
面向开发者：vfd_svtg_quote_request 和 vfd_svtg_default_dimensions 过滤器可用于调整报价请求，以及没有尺寸的商品的尺寸。vfd_svtg_api_base 和 vfd_svtg_soap_url 用于更改接口地址，例如 Servientrega 为您提供其他服务器时。
许可证区块显示错误：请按照区块中的提示操作。例如，如果该密钥已在其他域名上使用，请在 vibefox.net 账户中释放一个名额，然后点击 Check now。如果站点地址已更改，请点击 Check now，为新域名激活密钥。如果无法连接许可证服务器，插件将继续使用最后已知的状态运行。
卸载
停用插件会保留所有数据。如需移除，请先停用，然后在 Plugins 页面中删除。本插件的许可证密钥和许可证状态始终会被移除。设置、区域方式、缓存的报价和令牌仅在 Remove data on uninstall 已开启时才会被移除。否则它们将保留，以便日后重新安装。现有订单保留其运费明细。
Servientrega 是其各自所有者的商标。本插件与 Servientrega 没有关联，也未获得 Servientrega 的认可。