VibeFox SMSA Express for OpenCart — 帮助
要求
OpenCart：3.0.x（在 3.0.5.0 上测试）或 4.0.2 及更高版本（在 4.1.0.3 上测试）。
PHP：8.0 或更高版本。
SMSA Express 费率表：价格表中的价格来自您的 SMSA 账户或 SMSA 销售团队。请以您商店的默认货币输入。如果您的费率表以 SAR、AED 或其他货币计价，请先进行换算。
SMSA passKey（仅用于实时运费）：实时运费使用 SMSA 网络服务（SECOM，操作 getShipCharges）。SMSA 根据请求发放 passKey：请联系您的 SMSA 客户经理，或发送邮件至 info@smsaexpress.com。passKey 可能与 SMSA 电子商务门户的 API 密钥不同。SMSA 没有适用于此服务的测试（沙盒）服务器。
VibeFox 许可证密钥：在 vibefox.net 购买。一个密钥只能用于一个域名。
安装
下载文件是一个 zip 压缩包，内含适用于两个 OpenCart 版本的安装包。请在您的电脑上解压。其中包含 README.txt、OpenCart 3 安装包 vfd_smsa_express-oc3-(version).ocmod.zip 和 OpenCart 4 安装包 vfd_smsa_express.ocmod.zip。请只安装与您的 OpenCart 版本对应的安装包。两个版本使用同一个许可证密钥。
OpenCart 3
1. 在后台进入 Extensions > Installer，点击 Upload，然后选择文件 vfd_smsa_express-oc3-(version).ocmod.zip。该扩展不添加 OCMOD 修改，因此无需刷新 Extensions > Modifications。您也可以不使用 Installer，而是将此安装包中 upload 文件夹的内容复制到商店的根目录。
2. 进入 Extensions > Extensions，选择扩展类型 Shipping。找到 VibeFox SMSA Express，点击 Install（绿色的 + 按钮）。
3. 点击 Edit（铅笔按钮）打开设置页面。
4. 在 Edit 页面顶部的许可证区块中，将您的 VibeFox 许可证密钥输入 License key 字段，然后点击 Activate（参见许可证密钥）。
5. 在价格表中输入您的 SMSA Express 价格。
6. 可选：在 Live rates (API) 下开启 Live charges，输入您的 SMSA passKey、发货城市和国家；如果商店的默认货币不是 SAR，还需输入汇率。
7. 开启 Enable SMSA Express，然后点击 Save。
OpenCart 4
1. 在后台进入 Extensions > Installer，点击 Upload，然后选择文件 vfd_smsa_express.ocmod.zip。请勿重命名该文件：OpenCart 4 从文件名获取扩展代码，重命名后的安装包无法使用。
2. 该安装包会出现在同一页面的已安装扩展列表中。点击其旁边的 Install（绿色 + 按钮）。
3. 进入 Extensions > Extensions，选择扩展类型 Shipping。找到 VibeFox SMSA Express，点击 Install（绿色 + 按钮），然后点击 Edit（铅笔按钮）。
4. 请按 OpenCart 3 的第 4 至 7 步输入许可证密钥和设置。两个版本的设置页面及其字段相同。
安装后，该方式在您开启 Enable SMSA Express 并保存之前保持关闭。如果您在卸载后重新安装扩展，之前保留的 SMSA Express 设置将再次生效。
配置
所有设置都位于扩展页面：Extensions > Extensions > Shipping > VibeFox SMSA Express > Edit。各部分列在左侧。点击一个 Save 按钮即可保存整个页面，无需重新加载。每次保存还会清除缓存的 SMSA 运费。无效的方式标题、非数字的值、负数、汇率为 0、不是 3 个字母的货币代码、价格表中的错误价格、Minimum weight (kg) 大于 Maximum weight (kg)，或不是整数的排序值，都会被作为错误拒绝，并且在您更正之前不会保存任何内容。只有拥有修改此扩展权限的管理员用户才能保存设置。
启用实时运费后，设置上方的警告会告诉您缺少 passKey、发货城市或汇率，或价格表为空。如果商店没有 kg 重量等级，且其默认重量单位不被扩展识别，也会出现警告（此时商品重量将按 kg 读取）。请在 System > Localisation > Weight Classes 中添加一个 kg 重量等级。
常规
这些设置适用于所有地理区域。您可以在 Conditions 中将该方式限制在某个地理区域，或使用 Ignore shipping zones 将其限制在某个国家列表内。
Enable SMSA Express：在结账时显示或隐藏 SMSA Express。默认：关闭。
Method title：客户在购物车和结账时看到的配送方式名称。默认值：SMSA Express。必填，最多 64 个字符，且不能包含字符 < > ; = # { }。
Sort order：SMSA Express 在结账时配送方式中的位置。一个整数。
实时运费（API）（可选；如果 SMSA 没有返回运费，则使用价格表）
Live charges：从 SMSA Express 获取配送运费。关闭时，结账期间不会向 SMSA 发送任何内容。默认：关闭。
SMSA passKey：SMSA 网络服务（SECOM）的密钥。保存后，该字段保持为空，并显示 Saved — leave empty to keep it. 只有需要更改时才输入新值。勾选 Remove the saved passKey 可将其删除。如果日志显示 "Invalid Passkey"，则表示该服务不接受此密钥。请向 SMSA 索取网络服务的 passKey。
Ship-from city：您的包裹发出的城市，按 SMSA 的写法填写，例如 Riyadh、Jeddah 或 Dammam。实时运费必填：OpenCart 没有商店城市，因此它永远不会从商店地址中获取。
Ship-from country：您的包裹发出的国家。第一个选项 Store country 使用 System > Settings > Store > Local 中设置的商店国家。这是默认值。
Shipment type：作为运输类型发送给 SMSA。DLV（默认值）为标准配送。只有在 SMSA 为您提供了其他代码时才需更改。
Currency of SMSA charges：SMSA 返回运费所用货币的 3 位字母代码，通常为 SAR（默认值）。以该货币或商店默认货币之外的其他货币返回的运费不会被使用。
Exchange rate：SMSA 货币 1 个单位折合商店默认货币的价格，例如 0.27。当两种货币相同时不需要。如果不设置，则以其他货币返回的运费不会被使用，并采用价格表。
价格（以商店默认货币计价的 SMSA Express 费率表；在实时运费关闭时使用，并在 SMSA 没有返回运费时作为备用）
Price table：每个目的国家一行。点击 Add country 添加一行。* All other countries 行适用于没有自己行的国家。每行都有一个 Base 价格和重量列：XS ≤1 kg、S ≤2 kg、M ≤3 kg、L ≤5 kg 和 XL >5 kg。重量列为空或为 0 时使用基础价格。基础价格为 0 表示免运费。没有任何价格的行不会被保存。如果某个国家有两行，则使用第一行。"9.99" 和 "9,99" 均可接受。
Price for countries not in the table：当价格表中没有目的国家的行（也没有 * 行），或该行对于此重量没有价格时使用。留空则在这种情况下隐藏该方式。
Price applies：价格的计算方式。
商品重量会从 OpenCart 的重量等级换算为千克。
条件
Minimum weight (kg)：购物车重量低于此值时隐藏该方式。0 表示不限制（默认值）。
Maximum weight (kg)：购物车重量高于此值时隐藏该方式。默认值：30。0 或空字段表示不限制。
Minimum order amount：只有当需要配送的商品小计（使用优惠券后、税前）达到该金额时才显示该方式。留空则始终显示。
Free shipping from：需要配送的商品小计（使用优惠券后、税前）达到该金额时，SMSA Express 免运费。当购物车达到该金额时，价格为 0，并且不会向 SMSA 发出请求。留空则从不提供免运费。
Tax class：运费的税类，或 No tax（默认值）。如果您的价格（价格表和 SMSA 运费）已经包含税费（例如沙特增值税），请选择 No tax。
Geo zone：仅为此地理区域内的地址提供 SMSA Express。All zones（默认值）表示不限制。当 Ignore shipping zones 开启时不检查。地理区域在 System > Localisation > Geo Zones 中管理。
不使用配送区域时的可用性
通常，该方式会为 Conditions 中所选地理区域内的地址提供。
Ignore shipping zones：无论地理区域如何，为下列国家提供 SMSA Express。关闭时由地理区域决定，国家列表不会被使用。
Countries：该模式下的目标国家。留空则使用商店中所有已启用的国家。仅当 Ignore shipping zones 开启时才使用此字段。
高级
Debug log：将运费计算记录到 storage/logs/vfd_smsa_debug.log.php。该文件无法通过网页读取。不会记录客户地址和密钥。即使此选项关闭，实时运费的错误也始终会被记录。完成后请关闭日志。当文件达到 5 MB 时，它会被移动到 vfd_smsa_debug.old.log.php，并开始新的日志。
Log：显示调试日志的大小和最新条目。点击 Clear log 清空日志。
Remove data on uninstall：开启时，卸载扩展会删除 SMSA Express 设置和调试日志。关闭时（默认），设置会被保留，以便重新安装。缓存的运费始终会被删除。
导入 / 导出
Export：点击 Download JSON，将设置保存为 JSON 文件。passKey 不会被导出。
Import：粘贴之前导出的 JSON，然后点击 Import 恢复设置，例如在另一家商店中使用。这些值会像普通保存一样进行检查。已保存的 passKey 会被保留。
结账时的工作方式
OpenCart 显示配送方式时，会向扩展请求 SMSA Express 的价格。如果设置了 Geo zone（并且 Ignore shipping zones 已关闭），而地址不在该区域内，则不提供 SMSA Express。只有将 Requires Shipping 设为 Yes 的商品才会计算在内：其他商品不增加重量，也不计入订单金额。然后扩展检查条件：Ignore shipping zones 的国家（如果开启）、购物车重量和最低订单金额。礼品卡、积分和商店余额不计算在内。如果适用免运费，则价格为 0，并且不会向 SMSA 发出请求。
启用实时运费时，扩展会向 SMSA 发送发货城市和国家、客户的城市和国家、运输类型、以千克计的包裹重量，以及金额为 0 的货到付款金额。SMSA 会返回运费及其货币。扩展将其换算为商店的默认货币，并按其小数位数进行四舍五入。然后，价格会以客户的货币显示，并加上所选 Tax class 的税费。只有在客户输入了包含城市的送货地址之后，才会请求实时运费。
每个运费缓存一小时，因此相同的购物车不会触发新的请求。失败的请求缓存 5 分钟。发生超时或服务器错误后，2 分钟内不会再次询问 SMSA。密钥被拒绝后，5 分钟内不会再次询问。这样，结账就不会在每次刷新时都等待一个失败的服务。请求超时时间为 12 秒。
只要 SMSA 没有返回可用的运费（没有 passKey、尚未输入城市、密钥无效、超时、出错、该城市没有服务或货币未知），就使用价格表。如果价格表和 Price for countries not in the table 都无法给出价格，则隐藏该方式。客户永远不会看到错误。原因会写入日志。
该扩展仅计算配送价格。它不创建 SMSA 运单，不打印 AWB 标签，不处理退货，也不追踪包裹。货到付款及其手续费不包含在实时运费中。没有 SMSA 零售网点选择器：该方式为送货上门。它不会为订单增加任何内容：订单与其他 OpenCart 配送方式一样，显示方式标题和运费。
在 OpenCart 4 中，客户在结账页面的配送方式区块中点击 Choose，然后在 Shipping method options 窗口中选择 SMSA Express。该方式的工作方式与 OpenCart 3 相同。
许可证密钥
该扩展使用来自 vibefox.net 的 VibeFox 许可证密钥。License — VibeFox SMSA Express 许可证区块是 Extensions > Extensions > Shipping > VibeFox SMSA Express > Edit 页面中位于设置上方的第一个区块。将密钥粘贴到 License key 中并点击 Activate。之后，该区块会以掩码形式显示密钥、状态（例如许可证有效期截止日期和您的域名），以及以下按钮：Check now 用于重新检查状态，Change key 用于输入其他密钥，Remove key 用于从本商店移除密钥。其下方是 Product: opencart-shipping-smsa-express 一行，以及打开您 vibefox.net 账户的链接 Manage licenses and domains in your account。只有拥有该扩展 Modify 权限的管理员用户才能更改密钥。区块中的文字遵循后台语言（包括英语和俄语）。
如果密钥未被接受，区块会说明原因，例如 Key not found、This key belongs to another product、Domain limit reached，或带有日期的 License expired on。在商店地址更改后，或在您的账户中释放了一个域名名额后，请点击 Check now。如果无法连接许可证服务器，扩展将继续使用最后一次已知的状态运行。
一个密钥只能用于一个域名：即 OpenCart 配置中的商店地址。从商店中移除密钥不会释放其域名名额。请在您的 vibefox.net 账户中释放该名额。
没有有效密钥时，结账时客户看不到 SMSA Express，也不会计算任何运费。在同一浏览器中登录后台的管理员仍然可以在商店中看到该方式，并标有 (unlicensed — visible to admins only)，因此您可以在购买密钥之前进行设置和测试。在 OpenCart 4 上此预览不可用：商店无法看到后台登录，因此没有有效密钥时，该方式对所有人都隐藏。打开一次 Edit 页面后，后台 Dashboard 上会出现提醒。点击 × 关闭，可隐藏 7 天。现有订单不受影响。
许可证到期后，扩展仍会继续工作，但更新和支持需要续费。当您打开后台 Dashboard 或 Edit 页面时，状态会自动重新检查：输入密钥后的前 14 天内每天一次，之后每周一次。无需 cron 任务。卸载扩展时总会删除许可证密钥和许可证状态。
故障排除
结账时没有显示 SMSA Express：检查许可证是否有效，以及 Enable SMSA Express 是否开启。检查 Geo zone（或者在 Ignore shipping zones 开启时检查 Countries）、重量限制和 Minimum order amount。检查该国家或 * 是否设置了价格，或者是否设置了 Price for countries not in the table。检查商品的 Requires Shipping 是否设为 Yes。
客户看到的是价格表价格而不是 SMSA 运费：SMSA 需要客户的城市，因此在输入城市之前会显示价格表价格。当 SMSA 没有响应、拒绝密钥或城市，或者以没有汇率的货币返回运费时，也会使用价格表。请查看扩展页面上的 Log 字段以了解原因。
日志中出现 "Invalid Passkey"：该密钥不被 SMSA 网络服务接受。请向 SMSA 索取网络服务的 passKey。
客户的城市不被接受：SMSA 要求使用其自己的城市拼写。请检查送货地址中的城市以及 Ship-from city。
设置无法保存并显示错误：数字字段包含文本或负值，汇率为 0，货币代码不是 3 个字母，或 Minimum weight (kg) 大于 Maximum weight (kg)。请更正消息中提到的值，然后再次点击 Save。
运费被重复征税：您的费率表或 SMSA 运费可能已经包含增值税。请将 Tax class 设为 No tax。
更改后费率看起来过时：在扩展页面点击 Save。这会清除缓存的 SMSA 运费。
页面显示 "Warning: You do not have permission to modify VibeFox SMSA Express!"：您的管理员用户组可能只能查看设置。请在 System > Users > User Groups 中为该用户组授予 extension/shipping/vfd_smsa_express（OpenCart 3）或 extension/vfd_smsa_express/shipping/vfd_smsa_express（OpenCart 4）的修改权限。
面向开发人员：SMSA 网络服务地址可以通过设置 vfd_smsa_api_url（用于测试）进行替换；设置页面上没有对应字段。
卸载
进入 Extensions > Extensions，选择类型 Shipping，然后点击 VibeFox SMSA Express 旁边的 Uninstall（红色 − 按钮）。该扩展的许可证密钥和许可证状态总会被删除。OpenCart 总会重置 Enable SMSA Express、Sort order、Tax class 和 Geo zone。缓存的运费总会被删除。如果 Remove data on uninstall 已开启，SMSA Express 设置和调试日志也会被删除。如果已关闭，其他设置会被保留，并在您重新安装扩展时再次使用。已下单的订单会保留其配送方式和费用。
在 OpenCart 4 中，如需同时删除扩展文件，请在卸载后进入 Extensions > Installer，在已安装扩展列表中点击 VibeFox SMSA Express 旁边的 Uninstall（橙色 − 按钮），然后点击 Delete（红色垃圾桶按钮）以删除已上传的安装包。
SMSA Express 是其各自所有者的商标。本扩展与 SMSA Express 无关联，也未获得 SMSA Express 的认可。