VibeFox SMSA Express for PrestaShop — 帮助
系统要求
PrestaShop：8.0 至 9.x。
PHP：8.0 或更高版本。模块拒绝在较旧的 PHP 版本上安装。
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. 进入后台，前往 Modules > Module Manager，点击 Upload a module。选择模块的 ZIP 文件。
2. 上传完成后，点击 Configure；或者稍后在模块列表中找到 VibeFox SMSA Express 并点击 Configure。
3. 将您的 VibeFox 许可证密钥粘贴到配置页顶部许可证区块中的 License key 字段，然后点击 Activate（参见许可证密钥）。
4. 在价格表中输入您的 SMSA Express 价格，然后点击 Save。
5. 可选：在 Live rates (API) 下开启 Live charges，输入您的 SMSA passKey、发货城市和国家；如果您店铺的默认货币不是 SAR，还需输入汇率。
安装时，模块会创建 SMSA Express 承运商，配送时效文本为 SMSA Express courier。该承运商会分配给所有区域和所有客户组。您可以在 Shipping > Carriers 中修改区域、客户组、配送时效、Logo 和尺寸限制。请勿在那里设置价格：价格始终来自本模块。
配置
所有设置都在模块页面：Modules > Module Manager > VibeFox SMSA Express > Configure。每个部分都有自己的 Save 按钮，点击后会保存整个页面。每次保存还会清除缓存的 SMSA 运费。非数字的值、负数、汇率为 0、非 3 个字母的货币代码，或 Minimum weight 大于 Maximum weight，都会被拒绝并显示错误，在您更正之前不会保存任何内容。
开启实时运费后，设置上方的警告会提示缺少 passKey、发货城市或汇率，或价格表为空。如果模块无法识别店铺的重量单位（此时商品重量将按 kg 读取），也会显示警告。请在 International > Localization（Local units）中设置 kg、g、lb 或 oz。
常规
Enable SMSA Express：一次性在所有区域开启或关闭承运商。这与 Shipping > Carriers 中的承运商状态是同一个开关。
Method title：在购物车和结账时显示的承运商名称。默认值：SMSA Express。必填，最多 64 个字符。
Tax：承运商的税务规则，或 No tax。如果您的价格（价格表和 SMSA 运费）已包含税费（例如沙特增值税），请选择 No tax。
实时运费（API）（可选；如果 SMSA 未返回运费，则使用价格表）
Live charges：从 SMSA Express 获取配送运费。默认：关闭。
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。留空则使用 Shop Parameters > Contact > Stores 中设置的店铺城市。
Ship-from country：您的包裹发出的国家。默认为您店铺所在的国家。
Shipment type：作为运输类型发送给 SMSA。DLV（默认）为标准配送。只有在 SMSA 提供了其他代码时才需修改。
Currency of SMSA charges：SMSA 返回的每个运费都带有货币代码，通常为 SAR（默认）。与此货币和您店铺默认货币都不同的运费不会被使用。
Exchange rate：SMSA 货币 1 个单位折合为您店铺默认货币的价格，例如 0.27。两种货币相同时无需填写。未填写时，其他货币的运费不会被使用，而是应用价格表。小数点和逗号均可作为小数分隔符。
价格（您在店铺默认货币下的 SMSA Express 费率表；实时运费关闭时使用，SMSA 未返回运费时作为备用）
Price table：每个目的国家一行。点击 Add country 添加一行，点击垃圾桶图标删除一行。* Default (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 配送免费。购物车达到该金额时，价格为 0，并且不会向 SMSA 发送请求。留空则从不提供免运费。
无配送区域时的可用性
通常情况下，承运商会在 Shipping > Carriers 中分配给它的区域内提供。
Ignore shipping zones：无论匹配哪个区域，都为下面列出的国家提供 SMSA Express。开启后，承运商会添加到所有区域，包括之后创建的区域。关闭时，会移除这些已添加的区域。
Countries：该模式下的目的国家。留空则使用店铺所有已启用的国家。仅当 Ignore shipping zones 开启时使用此字段。
高级
Debug log：将运费计算记录到模块文件夹中的 logs/vfd_smsa_debug.log.php。该文件无法通过网页打开。不会记录顾客地址和密钥。实时运费的错误始终会被记录，即使此选项已关闭。使用完毕后请关闭日志。
Log：显示调试日志的大小和最新条目。点击 Clear log 可清空。
Remove data on uninstall：开启时，卸载模块会删除 SMSA Express 设置、承运商和日志。关闭时，所有内容都会保留，以便重新安装。缓存的运费始终会被删除。
结账时的工作方式
在配送步骤，PrestaShop 会向模块请求 SMSA Express 的价格。只有实体商品才计入：虚拟商品不增加重量，也不计入订单金额。模块首先检查条件：Ignore shipping zones 的国家（如已开启）、购物车重量和最低订单金额。如果适用免运费，则价格为 0，并且不会向 SMSA 发送请求。
开启实时运费后，模块会向 SMSA 发送您的发货城市和国家、顾客的城市和国家、运输类型、包裹重量（kg）以及金额为 0 的货到付款金额。SMSA 返回运费及其货币。模块将其换算为您店铺的默认货币，然后价格以顾客购物车的货币显示。只有在顾客填写了包含城市的配送地址之后，才会请求实时运费。
每个运费缓存 1 小时，因此同一购物车不会重复发起请求。失败的请求缓存 5 分钟。发生超时或服务器错误后，2 分钟内不再向 SMSA 请求。密钥被拒绝后，5 分钟内不再请求。因此，结账不会在每次刷新时都等待一个出现故障的服务。请求超时时间为 12 秒。
只要 SMSA 没有返回可用的运费（没有 passKey、尚未输入城市、缺少商品重量、密钥无效、超时、错误、该城市无服务或货币未知），就使用价格表。如果价格表和 Price for countries not in the table 都无法给出价格，承运商将被隐藏。顾客永远不会看到错误。原因会写入日志。
如果您在承运商已有订单后，在 Shipping > Carriers 中编辑了该承运商，PrestaShop 会将其保存为新的承运商版本。模块会自动跟随新版本。
本模块仅计算配送运费。它不会创建 SMSA 运单、打印 AWB 面单、处理退货或跟踪包裹。货到付款及其手续费不包含在实时运费中。没有 SMSA 零售网点选择器：该承运商为送货上门。
许可证密钥
本模块需要来自 vibefox.net 的 VibeFox 许可证密钥。模块的许可证区块 License — VibeFox SMSA Express 位于 Modules > Module Manager > VibeFox SMSA Express > Configure 页面中，位于设置上方的第一个区块。将密钥输入 License key 并点击 Activate。之后，该区块会以掩码形式显示密钥、许可证状态（例如许可证有效期截止日期和您的域名），并提供以下按钮：Check now 用于重新检查状态，Change key 用于输入其他密钥，Remove key 用于从本店铺移除密钥。其下方是 Product: presta-shipping-smsa-express 一行，以及打开您 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 账户中释放该名额。
没有有效的密钥，结账时不会向顾客显示 SMSA Express 承运商，也不会计算运费。PrestaShop 前台无法得知您已登录后台，因此承运商对您也会被隐藏：您可以在购买密钥之前设置模块，但无法在结账时测试。提醒会出现在 Modules > Module Manager 的 Alerts 标签页中。现有订单不受影响。
许可证到期后，模块仍会继续运行，但更新和支持需要续费。在您使用后台期间，系统会自动重新检查状态：输入密钥后的前 14 天每天一次，之后每周一次。无需设置 cron 任务。卸载或重置模块时，总会删除许可证密钥和许可证状态。
故障排除
结账时没有显示 SMSA Express：请检查许可证是否有效，并确认 Enable SMSA Express 已开启。在 Shipping > Carriers 中，检查承运商是否覆盖顾客所在国家的区域以及顾客所属的客户组（或 Ignore shipping zones 已开启且该国家被允许）。检查重量限制和 Minimum order amount。检查该国家或 * 是否有价格，或是否已设置 Price for countries not in the table。此外，商品详情页中可能将商品限制为特定承运商。
顾客看到的是价格表价格，而不是 SMSA 运费：SMSA 需要顾客的城市，因此在输入城市之前会显示价格表价格。当 SMSA 无响应、拒绝密钥或城市，或以没有汇率的货币返回运费时，也会使用价格表。请查看模块页面上的 Log 字段以了解原因。
日志中出现 "Invalid Passkey"：SMSA 网络服务不接受该密钥。请向 SMSA 索取网络服务的 passKey。
顾客的城市不被接受：SMSA 使用其自己的城市拼写。请检查配送地址中的城市以及 Ship-from city。
设置无法保存且出现错误：数字字段包含文本或负值，汇率为 0，货币代码不是 3 个字母，或 Minimum weight 高于 Maximum weight。请更正消息中指出的值，然后再次点击 Save。
配送运费被重复征税：您的费率表或 SMSA 运费可能已包含增值税。请将 Tax 设置为 No tax。
更改后运费看起来过时：在模块页面点击 Save。这会清除缓存的 SMSA 运费。
页面提示未找到 SMSA Express 承运商：该承运商已在 Shipping > Carriers 中删除。请在 Modules > Module Manager 中重置模块以重新创建。
卸载
前往 Modules > Module Manager，打开 VibeFox SMSA Express 旁边的菜单，选择 Uninstall。许可证密钥和许可证状态始终会被删除。缓存的运费始终会被删除。如果 Remove data on uninstall 已开启，承运商将被删除（订单保留其历史记录），设置和日志也会被删除。如果已关闭，承运商仅会被停用，所有设置都会保留。重新安装模块或执行 Reset，会将承运商恢复为之前的状态。
SMSA Express 是其各自所有者的商标。本模块与 SMSA Express 没有关联，也未获得其认可。