VibeFox SMSA Express for WooCommerce — 帮助
系统要求
WordPress：5.8 或更高版本。
WooCommerce：5.0 或更高版本，已安装并启用。未安装时插件无法启用。
PHP：8.0 或更高版本。
SMSA Express 费率卡：费率表中的价格来自您的 SMSA 账户或 SMSA 销售团队。请以您的店铺货币输入。如果您的费率卡以 SAR、AED 或其他货币计价，请先换算。
SMSA passKey（仅用于实时运费）：实时运费使用 SMSA 网络服务（SECOM，操作 getShipCharges）。SMSA 应要求提供 passKey：请联系您的 SMSA 客户经理，或致信 info@smsaexpress.com，并提供您的账户号码申请 SMSA 网络服务访问权限。passKey 可能与 SMSA 电子商务门户的 API 密钥不同。SMSA 没有该服务的测试（沙盒）服务器。
VibeFox 许可证密钥：在 vibefox.net 购买。一个密钥只能用于一个域名。
安装
1. 在 WordPress 中进入 Plugins > Add New > Upload Plugin，选择插件的 ZIP 文件，点击 Install Now。您也可以通过 FTP 将 vfd_smsa_express 文件夹上传到 /wp-content/plugins/。
2. 点击 Activate。
3. 打开设置：WooCommerce > Settings > Shipping > VibeFox SMSA Express，或在插件页面点击插件名称下方的 Settings。
4. 在页面顶部的许可证区块中输入您的 VibeFox 许可证密钥，然后点击 Activate。
5. 在费率表中输入您的 SMSA Express 价格。
6. 可选：在 Live rates (API) 下开启 Live charges，输入您的 SMSA passKey、发货城市和国家；如果店铺货币不是 SAR，还需输入汇率。
7. 在 WooCommerce > Settings > Shipping > Shipping zones 中，将 VibeFox SMSA Express 添加到某个配送区域（例如“沙特阿拉伯”），或开启 Ignore shipping zones 并选择国家。
配置
所有设置都在同一页面：WooCommerce > Settings > Shipping > VibeFox SMSA Express。这些设置适用于所有配送区域。将该方式添加到某个区域时，区域窗口只有一个字段：
Title (zone)：顾客在此区域看到的名称。留空则使用全局的 Method title。
每次保存设置时，已缓存的 SMSA 运费都会被清除。开启实时运费后，设置上方的警告会提示缺少 passKey、发货城市或汇率，或费率表为空。
常规
Enable/Disable：一次性在所有区域启用或禁用该方式。
Method title：购物车和结账页面显示的配送方式名称。区域可以覆盖此名称。默认：SMSA Express。
实时费率（API）（可选；若 SMSA 未返回运费，则使用费率表）
Live charges：从 SMSA Express 获取配送运费。默认：关闭。
SMSA passKey：SMSA 网络服务（SECOM）的密钥。若日志显示“Invalid Passkey”，表示该服务不接受此密钥。请向 SMSA 申请网络服务 passKey。
Ship-from city：您的包裹发出的城市，按 SMSA 的拼写填写，例如 Riyadh、Jeddah 或 Dammam。留空则使用 WooCommerce > Settings > General 中的店铺城市。
Ship-from country：您的包裹发出的国家。默认为您的店铺所在国家。
Shipment type：作为配送类型发送给 SMSA。DLV（默认）为标准配送。仅当 SMSA 给了您其他代码时才需更改。
Currency of SMSA charges：SMSA 返回的每笔运费都带有货币代码，通常为 SAR（默认）。不使用该货币和店铺货币以外的货币计价的运费。
Exchange rate：1 个 SMSA 货币单位折合店铺货币的价格，例如 0.24。两种货币相同时无需填写。未填写时，其他货币的运费不会被使用，将改用费率表。小数点和逗号均可作为小数分隔符。
价格（您的 SMSA Express 费率卡，以店铺货币计价；实时运费关闭时使用，SMSA 未返回运费时作为备用）
Price table：每个目的国家一行。点击 + Add country 添加一行，点击叉号删除一行。* All other countries 一行适用于没有单独行的国家。每行包含基础价格和重量列：XS 至 1 千克，S 至 2 千克，M 至 3 千克，L 至 5 千克，XL 超过 5 千克。重量列为空或为 0 时使用基础价格。基础价格为 0 表示免运费。保存时会删除没有任何价格的行。“9.99”和“9,99”均可接受。
Price for countries not in the table：当费率表中没有目的国家的行（也没有 * 行），或该行没有此重量的价格时使用。留空则在这种情况下隐藏该方式。
Price applies：价格的计算方式。
商品重量会从您店铺的重量单位换算为千克。
条件
Minimum weight (kg)：购物车重量低于此值时隐藏该方式。0 表示无限制。
Maximum weight (kg)：购物车重量高于此值时隐藏该方式。默认：30。0 表示无限制。
Minimum order amount：仅当购物车小计（折扣后、税前）达到此金额时才显示该方式。留空则始终显示。
Free shipping from：购物车小计（折扣后、税前）达到此金额时 SMSA Express 配送免费。仅在该方式对目的地有价格时才提供免费配送：SMSA 运费、费率表中的行或不在费率表中的国家的价格。若费率表有价格，则不会向 SMSA 发送请求。留空则从不提供免费配送。
Excluded shipping classes：购物车中包含以下任一 WooCommerce 配送类别的商品时，隐藏该方式。
Tax status：Taxable 会将 WooCommerce 税费加到配送费用上，None 则不加。如果您的价格（费率表和 SMSA 运费）已含税，例如沙特增值税，请选择 None。
无配送区域时的可用性
Ignore shipping zones：即使该方式未添加到任何配送区域，也为下方指定的国家提供 SMSA Express。
Countries：此模式下的目的国家。留空则使用您配送到的所有国家。仅当 Ignore shipping zones 开启时使用此字段。添加到配送区域的方式始终对该区域的国家生效。
高级
Debug log：将每次运费计算记录到 WooCommerce > Status > Logs，来源为 vfd_smsa_express。不记录顾客地址和密钥。即使此选项关闭，实时运费的错误也始终会被记录。完成后请关闭日志。
Remove data on uninstall：开启后，删除插件会移除所有 SMSA Express 设置和区域方式。停用插件从不删除任何内容。
结账时的工作流程
当顾客输入配送地址时，WooCommerce 会向插件请求价格。插件首先检查条件：配送国家、购物车重量、最低订单金额和排除的配送类别。若适用免费配送且目的地有价格，则该方式以 0 元显示。
开启实时运费后，插件会向 SMSA 发送您的发货城市和国家、顾客的城市和国家、配送类型、以千克计的包裹重量，以及 0 元的货到付款金额。SMSA 返回运费及其货币。插件将其换算为您的店铺货币并显示。只有顾客输入城市后才会请求实时运费。
每笔运费缓存一小时，因此同一购物车不会触发新的请求。失败的请求缓存 5 分钟。超时或服务器错误后，2 分钟内不再询问 SMSA。密钥被拒绝后，5 分钟内不再询问。这样，结账页面不会在每次刷新时都等待故障服务。请求超时时间为 12 秒。
只要 SMSA 未返回可用运费（无 passKey、尚未输入城市、缺少商品重量、密钥无效、超时、错误、该城市无服务或货币未知），就使用费率表。若费率表和 Price for countries not in the table 都没有价格，则隐藏该方式。顾客永远不会看到错误。原因会写入日志。
该方式适用于经典结账以及购物车与结账区块。兼容 WooCommerce 高性能订单存储（HPOS）。包含阿拉伯语翻译。
插件仅计算配送费用。它不会创建 SMSA 运单、打印 AWB 面单、处理退货或追踪包裹。货到付款及其费用不包含在实时运费中。没有 SMSA 零售网点选择器：该方式为上门配送。
许可证密钥
插件需要使用从 vibefox.net 获取的 VibeFox 许可证密钥。许可证区块位于 WooCommerce > Settings > Shipping > VibeFox SMSA Express 页面顶部。将密钥粘贴到 License key 中，然后点击 Activate。该区块显示状态，例如许可证有效期的截止日期和您的域名。使用 Check now 重新检查状态，Change key 输入其他密钥，Remove key 将其从本站点移除。链接 Manage licenses and domains in your account 会打开您的 vibefox.net 账户。
一个密钥只能用于一个域名。从站点移除密钥不会释放域名名额。请在您的 vibefox.net 账户中释放该名额。
没有有效密钥时，SMSA Express 不会在结账时向顾客显示。已登录的店铺管理员仍可看到，并标注 (unlicensed — visible to admins only)，方便您在购买密钥前设置和测试插件。插件页面和 WooCommerce 页面上会显示提醒。现有订单不受影响。
许可证到期后，插件仍可继续工作，但更新和支持需要续费。状态会在后台自动重新检查。
故障排除
SMSA Express 未出现在结账页面：请检查许可证是否有效、Enable/Disable 是否开启、该方式是否已添加到顾客所在国家的区域（或 Ignore shipping zones 已开启且该国家已允许）。检查重量限制、Minimum order amount 和 Excluded shipping classes。检查该国家或 * 是否有价格，或是否已设置 Price for countries not in the table。
顾客看到的是费率表价格而非 SMSA 运费：SMSA 需要顾客的城市，因此在输入城市之前会显示费率表价格。当 SMSA 未响应、拒绝密钥或城市，或返回的运费使用了没有汇率的货币时，也会使用费率表。请打开 WooCommerce > Status > Logs，来源 vfd_smsa_express，查看原因。
日志中出现“Invalid Passkey”：SMSA 网络服务不接受该密钥。请向 SMSA 申请网络服务 passKey。
顾客的城市不被接受：SMSA 要求使用其自身的城市拼写。开发者可以使用 vfd_smsa_express_live_request_fields 过滤器调整请求，例如城市名称。
配送费被重复征税：您的费率卡或 SMSA 运费可能已包含增值税。请将 Tax status 设为 None。
更改后费率看起来已过时：请保存设置页面。这会清除已缓存的 SMSA 运费。
许可证区块显示错误：请按照区块中的提示操作。例如，若该密钥已在其他域名上使用，请在 vibefox.net 账户中释放一个名额，然后点击 Check now。若站点地址已更改，请点击 Check now 为新域名激活密钥。若无法连接许可证服务器，插件将继续使用最近一次的已知状态。
卸载
停用插件会保留所有数据。如需删除，请在 Plugins 页面停用并删除。本插件的许可证密钥和许可证状态始终会被删除。设置、区域方式和已缓存的运费只有在开启 Remove data on uninstall 时才会删除。否则会保留，供以后重新安装时使用。现有订单会保留其配送行。
SMSA Express 是其各自所有者的商标。本插件与 SMSA Express 无关，也未获得其认可或背书。