VibeFox ShipStation for PrestaShop — 帮助
系统要求
PrestaShop：8.0 至 9.x。
PHP：8.0 或更高版本。模块无法安装在较旧的 PHP 版本上。
ShipStation 账户：请先在 ShipStation 中连接您的承运商（Settings > Shipping > Carriers），然后从 ShipStation > Settings > Account > API Settings 复制 API Key 和 API Secret。API 访问取决于您的 ShipStation 套餐。如果该页面不可用，说明您的套餐不包含 API 访问。本模块使用 ShipStation API V1（API Key 和 API Secret）。不支持只有单个 API 密钥的 ShipStation API V2 账户。没有密钥时，仅使用备用运费。
VibeFox 许可证密钥：在 vibefox.net 购买。一个密钥只能用于一个域名。
安装
1. 在后台进入 Modules > Module Manager，点击 Upload a module。选择模块的 ZIP 文件。
2. 上传完成后，点击 Configure；或稍后在模块列表中找到 VibeFox ShipStation 并点击 Configure。
3. 将您的 VibeFox 许可证密钥粘贴到 Configure 页面顶部许可证区块中的 License key 字段，然后点击 Activate（参见许可证密钥）。
4. 粘贴 API Key 和 API Secret，填写发货邮政编码，然后点击 Save。页面随后会列出您账户的承运商代码。在 Carrier codes 中填入您需要的代码，然后再次保存。
5. 如果您店铺的默认货币与 ShipStation 账户的货币不同，请设置 Exchange rate。
6. 可选：填写备用运费。
安装时，模块会创建承运商 ShipStation Shipping，配送时间文本为 ShipStation carriers (USPS, UPS, FedEx, ...)。该承运商会分配给所有区域和所有顾客组。您可以在 Shipping > Carriers 中更改区域、顾客组、配送时间、徽标和尺寸限制。请不要在那里设置价格：价格始终来自模块。
配置
所有设置都在模块页面中：Modules > Module Manager > VibeFox ShipStation > Configure。每个部分都有各自的 Save 按钮，它会保存整个页面。每次保存都会清除缓存的 ShipStation 运费，并检查 API Key 和 API Secret。随后页面会显示与您账户相连的承运商及其代码，例如 "stamps_com (Stamps.com), ups_walleted (UPS by ShipStation)"。
页面顶部的警告会告诉您实时运费何时无法工作：没有密钥、没有承运商代码、没有发货邮政编码、缺少汇率、连接检查失败，或承运商代码未连接到您的账户。当店铺的重量或尺寸单位是模块无法换算的单位时，也会出现警告。请在 International > Localization（Local units）中设置 kg、g、lb 或 oz，以及 cm、mm、m 或 in。负数或非数字文本的数字字段，或高于 Maximum weight 的 Minimum weight，都会被报告为错误，且不会保存任何内容。
常规
Enable ShipStation shipping：开启或关闭承运商。这与 Shipping > Carriers 中承运商状态的开关相同。
Name：结账时显示给顾客的承运商名称。默认值：ShipStation Shipping。必填，最多 64 个字符。
Tax：承运商的税务规则，或 No tax。ShipStation 运费不包含销售税。No tax 会按报价原样显示；税务规则会根据您的税务规则为运费加税。
ShipStation 账户
API Key：来自 ShipStation > Settings > Account > API Settings 的 API Key。它只会发送给 ShipStation，且绝不会被记录。保存后，该字段保持为空，并显示 Saved — leave empty to keep it. 只有在需要更改时才输入新值。
API Secret：同一页面中的 API Secret。它的处理方式与密钥相同。
Remove the saved API key and secret：保存密钥后出现。勾选并保存即可同时删除两者。
Carrier codes：一个或多个 ShipStation 承运商代码，以英文逗号分隔，例如 stamps_com, ups_walleted。最多使用 5 个代码，每个承运商发送一次 API 请求。如果您输入的数量更多，只保留前 5 个，页面会提示。系统会显示这些承运商中最便宜的运费。请从保存后显示的列表中获取代码。
Allowed services：可选，以英文逗号分隔的 ShipStation 服务代码，例如 usps_priority_mail, ups_ground。留空则显示上述承运商中最便宜的服务。
Package code："package"（默认）按您自己的箱子计算运费，并排除承运商的信封和统一价格箱。留空则计算承运商提供的所有包装类型。
发货地
Ship-from postal code：实时运费必填。ShipStation 仅根据邮政编码计算运费，且该邮政编码必须位于您 ShipStation 账户所在的国家。留空则使用 Shop Parameters > Contact > Stores 中的店铺邮政编码。
运费
Parcels：购物车发送给 ShipStation 的方式。
ShipStation account currency：ShipStation 返回运费所用的货币：USD、CAD、GBP、AUD、NZD 或 EUR。默认值：USD（美国账户）。
Exchange rate：账户货币 1 个单位折合店铺默认货币的价格，例如 0.92。只有当店铺默认货币与账户货币不同时才需要。没有汇率时，不会使用实时运费，而是采用备用运费。汇率不会自动更新。
备用运费（在没有实时运费时使用：没有 API 密钥、ShipStation 无法访问、地址没有承运商运费；价格以店铺默认货币计；如果希望在这种情况下隐藏承运商，请将表格和 Other countries 留空）
Prices by country：按国家设置基础运费，并按包裹重量设置尺寸列的表格：XS ≤ 1 kg、S ≤ 2 kg、M ≤ 3 kg、L ≤ 5 kg 和 XL > 5 kg。点击 Add country 添加一行，点击垃圾桶图标删除一行。尺寸为空时使用基础运费。基础运费为 0 表示免运费。* Default (all other countries) 一行适用于没有自有行的国家。没有任何价格的行不会被保存。
Other countries：当表格中没有该国家的价格时使用的运费。如果希望在这种情况下隐藏承运商，请将其留空。
条件
Free shipping from：购物车小计（折扣后、税前）达到该金额时免运费。此时不会向 ShipStation 发送请求。留空则关闭此功能。
Minimum subtotal：仅当购物车小计（折扣后、税前）至少达到该金额时才显示承运商。留空则始终显示。
Minimum weight：显示承运商所需的最低购物车重量，以店铺重量单位计。0 表示不限制。
Maximum weight：购物车重量高于此值时隐藏承运商，以店铺重量单位计。0 表示不限制。
无配送区域时的可用性
通常，承运商会在 Shipping > Carriers 中其所属的区域内提供。也可以改为按国家提供。
Ignore shipping zones：无论下方国家是否分配了区域，都为这些国家提供承运商。开启期间，承运商会被添加到所有区域，包括之后创建的区域。关闭时，这些已添加的区域会被移除。
Countries：该模式下的目的地国家。留空则使用店铺所有启用的国家。仅当 Ignore shipping zones 开启时才会使用此字段。
高级
Debug log：将 ShipStation 请求记录到模块文件夹中的 logs/vfd_shst_debug.log.php。该文件无法通过网页打开。即使此选项关闭，API 错误也始终会被记录。API Key、API Secret 和顾客地址绝不会被记录。邮政编码会被遮罩。
Log：显示日志的大小和最新条目。点击 Clear log 可清空。
Remove data on uninstall：开启时，卸载模块会删除设置、承运商、日志以及随订单保存的 ShipStation 服务。关闭时，所有内容都会保留，以便重新安装。
结账时的工作方式
在配送步骤，PrestaShop 会向模块询问价格。只有实体商品才计入：虚拟商品不增加重量，也不计入小计。模块首先检查条件：允许的国家（配合 Ignore shipping zones）、购物车重量和最低小计。如果适用免运费，承运商会以 0 元显示，并且不会向 ShipStation 发送请求。
随后，模块会向 ShipStation 发送发货邮政编码、目的国家、省/州、城市和邮政编码、包裹重量以及箱子尺寸。在顾客输入邮政编码之前不会发出请求。没有邮政编码的国家会使用备用运费。商品会装入一个箱子。如果某个商品没有尺寸，则只按重量计算包裹运费。
每个承运商代码会向 ShipStation 查询一次。模块使用允许的最便宜运费，并将其换算为店铺默认货币。随后，价格以顾客购物车的货币显示。
每个响应缓存 1 小时。当 ShipStation 返回的响应中没有可用运费时，该结果会记住 10 分钟。当 ShipStation 拒绝密钥或无法访问时，请求会暂停 5 分钟。遇到速率限制后，暂停时间取决于 ShipStation 给出的重置时间。请求超时时间为 12 秒。禁用模块会清除缓存的运费。
如果没有实时运费，价格会先取自备用运费表，然后取自 Other countries。如果两者都不适用，承运商会被隐藏。顾客从不会看到 ShipStation 的错误文本。详细信息会写入调试日志。
如果您在承运商已有订单后，在 Shipping > Carriers 中编辑该承运商，PrestaShop 会将其保存为新的承运商版本。模块会自动采用新版本。
模块仅计算运费。它不购买运单标签，不在 ShipStation 中创建订单或发货，不跟踪包裹，也不处理退货。没有自提点，结账时不能在多种服务之间选择，也不提供地址验证、保险、签收确认、拆分成多个包裹或运费加价功能。
订单
当订单使用 ShipStation 实时运费下单时，所选服务会随订单保存。后台订单页面会在 ShipStation 区块中以 Service 的形式显示它，例如 "USPS Ground Advantage - Package"，以便您在 ShipStation 中创建对应的运单标签。之后重新计算购物车不会改变它。使用备用运费或免运费下的订单没有服务区块。
许可证密钥
本模块需要一个来自 vibefox.net 的 VibeFox 许可证密钥。模块的许可证区块 License — VibeFox ShipStation 位于 Modules > Module Manager > VibeFox ShipStation > Configure 页面中，位于设置上方的第一个区块。将密钥输入 License key 并点击 Activate。之后，该区块会以掩码形式显示密钥、许可证状态（例如许可证有效期截止日期和您的域名），并提供以下按钮：Check now 用于重新检查状态，Change key 用于输入其他密钥，Remove key 用于从本店铺移除密钥。其下方是 Product: presta-shipping-shipstation 一行，以及打开您 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 账户中释放该名额。
没有有效的密钥，结账时不会向顾客显示 ShipStation 承运商，也不会计算运费。PrestaShop 前台无法得知您已登录后台，因此承运商对您也会被隐藏：您可以在购买密钥之前设置模块，但无法在结账时测试。提醒会出现在 Modules > Module Manager 的 Alerts 标签页中。现有订单不受影响。
许可证到期后，模块仍会继续运行，但更新和支持需要续费。在您使用后台期间，系统会自动重新检查状态：输入密钥后的前 14 天每天一次，之后每周一次。无需设置 cron 任务。卸载或重置模块时，总会删除许可证密钥和许可证状态。
故障排除
结账时没有显示 ShipStation：请检查许可证是否有效，以及 Enable ShipStation shipping 是否已开启。在 Shipping > Carriers 中，检查承运商是否覆盖顾客所在国家的区域和顾客组，或开启 Ignore shipping zones 并检查 Countries。检查重量限制和 Minimum subtotal。如果没有实时运费，请检查该国家、* Default 或 Other countries 是否设有价格。此外，商品页面中可能将商品限制为特定承运商。
结账显示备用运费而不是 ShipStation 运费：请检查模块页面顶部的警告（密钥、承运商代码、发货邮政编码、汇率）。开启 Debug log，重新加载结账页面，然后查看 Log 字段。顾客的邮政编码是必需的。输入之前不会发出请求。
应输入哪个承运商代码：使用密钥和 secret 保存设置。页面会列出您账户的承运商代码。请使用其中的一个或多个。
ShipStation 连接检查失败：消息会显示原因。请检查 API Key 和 API Secret，然后重新保存以再次检查。
运费与 ShipStation 不一致：包裹由商品重量和尺寸构成，商品装入一个箱子。没有尺寸的商品只按重量计算。运费缓存 1 小时。在模块页面点击 Save 可清除缓存。
页面提示找不到 ShipStation 承运商：该承运商已在 Shipping > Carriers 中被删除。请在 Modules > Module Manager 中重置模块以重新创建。
卸载
进入 Modules > Module Manager，打开 VibeFox ShipStation 旁边的菜单，然后选择 Uninstall。许可证密钥和许可证状态总会被删除。缓存的运费和连接检查结果总会被删除。如果 Remove data on uninstall 已开启，承运商会被删除（订单保留其历史记录），并删除设置、日志以及随订单保存的服务。如果已关闭，承运商仅被停用，设置以及已下订单的服务会被保留。重新安装模块或执行重置，会使承运商恢复到之前的状态。
ShipStation 是其各自所有者的商标。本模块与 ShipStation 没有关联，也未获得 ShipStation 的认可。