VibeFox ShipStation for OpenCart — 帮助

要求

OpenCart：3.0.x（在 3.0.5.0 上测试）或 4.0.2 及更高版本（在 4.1.0.3 上测试）。

PHP：8.0 或更高版本。

ShipStation 账户：在 ShipStation 中连接您的承运商（Settings > Shipping > Carriers），然后从 ShipStation > Settings > Account > API Settings 复制 API Key 和 API Secret。API 访问权限取决于您的 ShipStation 套餐。该扩展使用 ShipStation API V1（API Key 和 API Secret）。没有密钥时，仅使用备用价格。

VibeFox 许可证密钥：在 vibefox.net 购买。一个密钥只能用于一个域名。

安装

下载文件是一个 zip 压缩包，内含适用于两个 OpenCart 版本的安装包。请解压到您的电脑上。其中包含 README.txt、OpenCart 3 安装包 vfd_shipstation-oc3-(version).ocmod.zip 和 OpenCart 4 安装包 vfd_shipstation.ocmod.zip。只需安装适用于您 OpenCart 版本的安装包。两个版本的许可证密钥相同。

OpenCart 3

1. 在后台进入 Extensions > Installer，点击 Upload，然后选择文件 vfd_shipstation-oc3-(version).ocmod.zip。该扩展不添加 OCMOD 修改，因此无需刷新 Extensions > Modifications。您也可以不使用 Installer，而是将本安装包中 upload 文件夹的内容复制到商店的根目录。

2. 进入 Extensions > Extensions，选择扩展类型 Shipping。找到 VibeFox ShipStation，点击 Install（绿色的 + 按钮）。

3. 点击 Edit（铅笔按钮）打开设置页面。

4. 在 License key 栏中（位于 Edit 页面顶部的许可证块内）输入您的 VibeFox 许可证密钥，然后点击 Activate（参见许可证密钥）。

5. 粘贴 API Key 和 API Secret，输入发货邮政编码，然后点击 Save。页面现在会列出您账户的承运商代码。在 Carrier codes 中输入您需要的代码，然后再次保存。

6. 如果商店的默认货币与您的 ShipStation 账户货币不同，请设置 Exchange rate。您也可以选择填写备用价格。

7. 开启 Enable ShipStation shipping，然后点击 Save。

OpenCart 4

1. 在后台进入 Extensions > Installer，点击 Upload，然后选择文件 vfd_shipstation.ocmod.zip。请勿重命名该文件：OpenCart 4 从文件名获取扩展代码，重命名后的安装包无法使用。

2. 该安装包会出现在同一页面的已安装扩展列表中。点击其旁边的 Install（绿色的 + 按钮）。

3. 进入 Extensions > Extensions，选择扩展类型 Shipping。找到 VibeFox ShipStation，点击 Install（绿色的 + 按钮），然后点击 Edit（铅笔按钮）。

4. 按照 OpenCart 3 第 4 至 7 步的说明输入许可证密钥和设置。两个版本的设置页面及其字段相同。

安装后，该方式在您开启并保存之前保持关闭。如果您在卸载后重新安装扩展，之前保留的 ShipStation 设置将再次生效。

配置

所有设置都位于扩展页面：Extensions > Extensions > Shipping > VibeFox ShipStation > Edit。各部分列在左侧。点击一个 Save 按钮即可保存整个页面，无需重新加载。每次保存都会清除缓存的 ShipStation 运费，并检查 API Key 和 API Secret。随后页面会显示与您账户相连的承运商及其代码，例如 "stamps_com (Stamps.com), ups_walleted (UPS by ShipStation)"。只有拥有修改此扩展权限的管理员用户才能保存设置。

页面顶部的警告会告诉您实时运费何时无法工作：没有密钥、没有承运商代码、没有发货邮政编码、没有汇率、连接检查失败，或承运商代码未与您的账户连接。如果商店的重量或长度单位是扩展无法换算的单位，也会出现警告。请使用 kg、g、lb 或 oz，以及 cm、mm、m 或 in（System > Settings > Option）。无效的名称、数字字段或价格单元格中的负值或非数字文本、Minimum weight 大于 Maximum weight，或不是整数的排序值，都会作为错误提示，并且不会保存任何内容。

常规

Enable ShipStation shipping：在结账时显示或隐藏该方式。这是 Extensions > Extensions > Shipping 中扩展的状态。

Name：结账时显示给客户的配送方式名称。默认值：ShipStation Shipping。必填，最多 64 个字符，且不能包含字符 < > ; = # { }。

Tax class：运费的税类，或 No tax。ShipStation 运费不包含销售税。No tax 会按报价原样显示；选择税类则会根据您的税务规则为运费加税。

Sort order：该方式在结账时配送方式中的位置。一个整数。

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：实时运费必填，例如 78703。ShipStation 仅根据邮政编码计算运费，且该邮政编码必须位于您 ShipStation 账户所在的国家。OpenCart 没有商店邮政编码，因此不会从商店地址中获取。

运费

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：一个表格，每个国家有一个 Base 价格，并按包裹重量设置尺寸列：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 表示不限制（默认值）。

可用性

Geo zone：仅为此地理区域内的地址提供该方式。All zones（默认值）表示不限制。当 Ignore shipping zones 开启时不检查。地理区域在 System > Localisation > Geo Zones 中管理。

Ignore shipping zones：无论地理区域如何，为下列国家提供该方式。

Countries：该模式下的目标国家。留空则使用商店中所有已启用的国家。仅当 Ignore shipping zones 开启时才使用此字段。

高级

Debug log：将 ShipStation 请求记录到 storage/logs/vfd_shst_debug.log.php（OpenCart 4 为 system/storage/logs/vfd_shst_debug.log.php）。该文件无法通过网页读取。即使此选项关闭，API 错误也始终会被记录。API Key、API Secret 和客户地址从不记录。邮政编码会被遮蔽。当文件达到 5 MB 时，它会被移动到 vfd_shst_debug.old.log.php，并开始新的日志。

Log：显示日志的大小和最新条目。点击 Clear log 清空日志。

Remove data on uninstall：开启时，卸载扩展会删除 ShipStation 设置和日志。关闭时（默认），它们会被保留，以便重新安装。缓存的运费始终会被删除。已下单订单的 ShipStation 服务始终会被保留。

导入 / 导出

Export：点击 Download JSON，将设置保存为 JSON 文件。API Key 和 API Secret 不会被导出。

Import：粘贴之前导出的 JSON，然后点击 Import 恢复设置，例如在另一家商店中使用。这些值会像普通保存一样进行检查。已保存的 API Key 和 API Secret 会被保留。

结账时的工作方式

OpenCart 显示配送方式时，会向扩展请求 ShipStation 的价格。如果设置了 Geo zone（并且 Ignore shipping zones 已关闭），而地址不在该区域内，则不提供该方式。只有将 Requires Shipping 设为 Yes 的商品才会计算在内：其他商品不增加重量，也不计入小计。然后扩展检查条件：允许的国家（配合 Ignore shipping zones）、购物车重量和最低小计。礼品卡、积分和商店余额不计算在内。如果适用免运费，则该方式以 0 元显示，并且不会向 ShipStation 发出请求。

随后，扩展会向 ShipStation 发送发货邮政编码、目的国家、州/省代码、城市和邮政编码、包裹重量以及箱子尺寸。在客户输入邮政编码之前不会发出任何请求。没有邮政编码的国家使用备用价格。商品装入一个箱子。如果某个商品没有尺寸，则仅按重量计算包裹运费。

ShipStation 会针对每个承运商代码查询一次。扩展使用最便宜的允许运费，将其换算为商店默认货币，并按其小数位数进行四舍五入。然后，价格会以客户的货币显示，并加上所选 Tax class 的税费。

每个响应缓存 1 小时。当 ShipStation 的响应中没有可用运费时，该响应会记住 10 分钟。当 ShipStation 拒绝密钥或无法连接时，请求暂停 5 分钟。遇到速率限制后，暂停时间遵循 ShipStation 给出的重置时间。请求超时时间为 12 秒。

如果没有实时运费，价格将来自备用价格表，然后来自 Other countries。如果两者都不适用，则隐藏该方式。客户永远看不到 ShipStation 的错误文本。详细信息会写入调试日志。

该扩展只计算运费。它不购买运单，不创建 ShipStation 订单或发货，不追踪包裹，也不处理退货。没有取货点，结账时也没有在多个服务之间选择的功能，没有地址验证、保险、签名确认、拆分为多个包裹的打包功能，也没有运费加价功能。

在 OpenCart 4 中，客户在结账页面的配送方式区块中点击 Choose，并在 Shipping method options 窗口中选择 ShipStation。该方式的工作方式与 OpenCart 3 相同。

订单

当订单使用实时 ShipStation 运费下单时，所选服务会随订单一起保存。在 Sales > Orders 中打开订单：订单历史上方的 ShipStation 面板会将其显示为 Service，例如 "USPS Ground Advantage - Package"，以便您在 ShipStation 中创建对应的运单。在按商品计费模式下，服务会以逗号分隔的形式列出。之后对购物车的更改不会改变它，即使您关闭该方式后，面板仍会显示。使用备用价格或免运费下单的订单没有 ShipStation 面板。

OpenCart 4 为结账保留一个订单，并在客户每次重新确认时更新该订单。已保存的 ShipStation 服务会随之更新。如果客户改选其他配送方式，或现在适用备用价格，已保存的服务会从订单中移除。

许可证密钥

该扩展使用来自 vibefox.net 的 VibeFox 许可证密钥。许可证块 License — VibeFox ShipStation 位于 Extensions > Extensions > Shipping > VibeFox ShipStation > Edit 的第一个块，位于设置上方。将密钥粘贴到 License key 中，然后点击 Activate。之后，该块会以掩码形式显示密钥、状态（例如许可证有效期截止日期和您的域名），以及以下按钮：Check now 用于重新检查状态，Change key 用于输入其他密钥，Remove key 用于从本商店移除密钥。其下方是 Product: opencart-shipping-shipstation 一行，以及 Manage licenses and domains in your account 链接，该链接会打开您的 vibefox.net 账户。只有拥有该扩展 Modify 权限的管理员用户才能更改密钥。该块的文字跟随后台语言显示（包含英文和俄文）。

如果密钥未被接受，该块会说明原因，例如 Key not found、This key belongs to another product、Domain limit reached，或 License expired on 加上日期。更改商店地址后，或在您的账户中释放一个域名名额后，请点击 Check now。如果无法连接许可证服务器，扩展会继续使用最后一次已知的状态。

一个密钥只能用于一个域名：即 OpenCart 配置中的商店地址。从商店移除密钥并不会释放其域名名额。请在您的 vibefox.net 账户中释放名额。

没有有效密钥时，结账时不会向客户显示 ShipStation，也不会计算运费。在同一浏览器中登录后台的管理员用户仍会在商店中看到该方式，并标有 (unlicensed — visible to admins only)，因此您可以在购买密钥之前设置和测试该扩展。在 OpenCart 4 上此预览不可用：商店看不到后台登录状态，因此没有有效密钥时，该方式对所有人都隐藏。打开一次 Edit 页面后，后台 Dashboard 会出现提醒。点击 × 关闭它，可隐藏 7 天。现有订单不受影响。

许可证到期后，扩展仍会继续工作，但更新和支持需要续费。当您打开后台 Dashboard 或 Edit 页面时会自动重新检查状态：输入密钥后的前 14 天每天一次，之后每周一次。无需 cron 任务。卸载扩展时总会删除许可证密钥和许可证状态。

故障排除

ShipStation 未出现在结账页面：检查许可证是否有效，以及 Enable ShipStation shipping 是否开启。检查 Geo zone（或者在 Ignore shipping zones 开启时检查 Countries）、重量限制和 Minimum subtotal。如果没有实时运费，请检查该国家、* Default 或 Other countries 是否设置了价格。检查商品的 Requires Shipping 是否设为 Yes。

结账时显示备用价格而不是 ShipStation 运费：检查扩展页面顶部的警告（密钥、承运商代码、发货邮政编码、汇率）。开启 Debug log，重新加载结账页面，并查看 Log 字段。客户的邮政编码是必需的。在输入之前不会发出请求。

应输入哪个承运商代码：使用密钥和 Secret 保存设置。页面会列出您账户的承运商代码。使用其中一个或多个。

ShipStation 连接检查失败：消息会显示原因。检查 API Key 和 API Secret，然后再次保存以重新检查。

运费与 ShipStation 不一致：包裹是根据商品的重量和尺寸构建的，商品装入一个箱子。没有尺寸的商品仅按重量计算运费。运费缓存 1 小时。在扩展页面点击 Save 可清除缓存。

页面显示 "Warning: You do not have permission to modify VibeFox ShipStation!"：您的管理员用户组可能只能查看设置。请在 System > Users > User Groups 中为该用户组授予 extension/shipping/vfd_shipstation（OpenCart 3）或 extension/vfd_shipstation/shipping/vfd_shipstation（OpenCart 4）的修改权限。

面向开发人员：ShipStation API 地址可以通过设置 vfd_shst_api_url（用于测试）进行替换；设置页面上没有对应字段。

卸载

进入 Extensions > Extensions，选择类型 Shipping，然后点击 VibeFox ShipStation 旁边的 Uninstall（红色 − 按钮）。该扩展的许可证密钥和许可证状态总会被删除。OpenCart 总会重置 Enable ShipStation shipping、Sort order、Tax class 和 Geo zone。缓存的运费和连接检查结果总会被删除。如果 Remove data on uninstall 已开启，ShipStation 设置和调试日志也会被删除。如果已关闭，其他设置会被保留，并在您重新安装扩展时再次使用。已下单的订单会保留其配送方式、费用和 ShipStation 服务。

在 OpenCart 4 中，如需同时删除扩展文件，请在卸载后进入 Extensions > Installer，在已安装扩展列表中点击 VibeFox ShipStation 旁边的 Uninstall（橙色 − 按钮），然后点击 Delete（红色垃圾桶按钮）以删除已上传的安装包。

ShipStation 是其各自所有者的商标。本扩展与 ShipStation 无关联，也未获得 ShipStation 的认可。