VibeFox ShipStation for WooCommerce — 帮助

系统要求

WordPress：5.8 或更高版本。

WooCommerce：7.0 或更高版本，已安装并启用。没有 WooCommerce 时插件无法激活。

PHP：8.0 或更高版本。

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. 在 WordPress 中进入 Plugins > Add New > Upload Plugin，选择插件的 ZIP 文件，然后点击 Install Now。您也可以通过 FTP 将 vfd_shipstation 文件夹上传到 /wp-content/plugins/。

2. 点击 Activate。

3. 打开设置：WooCommerce > Settings > Shipping > VibeFox ShipStation，或在插件页面中点击插件名称下方的 Settings。

4. 在页面顶部的许可证区块中输入您的 VibeFox 许可证密钥，然后点击 Activate。

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

6. 如果您的店铺货币与 ShipStation 账户货币不同，请设置 Exchange rate。

7. 可选：填写备用运费。

8. 在 WooCommerce > Settings > Shipping > Shipping zones 中将 VibeFox ShipStation 添加到配送区域，或者启用 Ignore shipping zones 并选择国家。

配置

所有设置都位于同一页面：WooCommerce > Settings > Shipping > VibeFox ShipStation。这些设置适用于所有配送区域。将该方式添加到某个区域时，区域窗口中只有一个字段：

Title (zone)：顾客在该区域看到的名称。留空则使用全局的 Name。

每次保存设置时，缓存的 ShipStation 运费都会被清除，并检查 API Key 和 API Secret。页面随后会显示与您账户相连的承运商及其代码，例如 "stamps_com (Stamps.com), ups_walleted (UPS by ShipStation)"。设置上方的警告会告诉您实时运费无法工作的原因：缺少密钥、缺少承运商代码、缺少发货邮政编码、缺少汇率、连接检查失败，或承运商代码未连接到您的账户。

常规

Enable/Disable：一次性在所有区域启用或停用该方式。

Name：结账时显示的配送方式名称。区域可以用自己的 Title 覆盖它。默认：ShipStation Shipping。

ShipStation 账户

API Key：来自 ShipStation > Settings > Account > API Settings 的 API Key。

API Secret：同一页面中的 API Secret。

Carrier codes：一个或多个 ShipStation 承运商代码，用逗号分隔，例如 stamps_com, ups_walleted。最多使用 5 个代码，每个承运商发送一次 API 请求。显示这些承运商中最便宜的运费。请从保存后显示的列表中获取代码。

Allowed services：可选，用逗号分隔的 ShipStation 服务代码，例如 usps_priority_mail, ups_ground。留空则显示上述承运商中最便宜的服务。

Package code："package"（默认）按您自己的箱子计算运费，并排除承运商的信封和平邮包装盒。留空则计算承运商提供的所有包装类型的运费。

发货地

Ship-from postal code：实时运费必需。ShipStation 仅根据邮政编码计算运费，且该编码必须位于您 ShipStation 账户所在的国家。留空则使用 WooCommerce > Settings > General 中的店铺邮政编码。

运费

Parcels：购物车发送到 ShipStation 的方式。

ShipStation account currency：ShipStation 返回运费所用的货币：USD、CAD、GBP、AUD、NZD 或 EUR。默认：USD（美国账户）。

Exchange rate：账户货币 1 个单位折合为店铺货币的价格，例如 0.92。仅当店铺货币与账户货币不同时才需要。不设置时，不使用实时运费，改用备用运费。汇率不会自动更新。

Tax status：Taxable 允许 WooCommerce 根据您的税务规则对运费征税；None 则不征税。ShipStation 运费不包含销售税。

备用运费（在没有实时运费时使用：没有 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 表示不限制。

Disabled shipping classes：如果购物车中包含这些 WooCommerce 配送类别之一的商品，则隐藏该方式。

不使用配送区域时的可用性

Ignore shipping zones：无论该方式是否添加到某个区域，都为下方所列国家提供该方式。

Countries：该模式下的目的地国家。留空则使用店铺配送的所有国家。该字段仅在 Ignore shipping zones 开启时使用。添加到配送区域的方式始终适用于该区域的国家。

高级

Debug log：将 ShipStation 请求记录到 WooCommerce > Status > Logs，来源为 vfd-shipstation。即使此选项关闭，API 错误也始终会被记录。API Key、API Secret 和顾客地址从不记录。邮政编码会被遮蔽。

Remove data on uninstall：开启后，删除插件时会移除其设置以及它在配送区域中的方式。停用插件从不会删除设置。

结账时的工作方式

当顾客输入配送地址时，WooCommerce 会向插件请求运费。插件首先检查条件：购物车重量、最低小计和停用的配送类别。如果适用免运费，则该方式以 0 元显示，并且不会向 ShipStation 发送请求。

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

每个承运商代码都会向 ShipStation 查询一次。插件会显示允许的最便宜运费，并将其换算为店铺货币，显示在该方式名称下方。

每个响应缓存 1 小时。当 ShipStation 返回的结果中没有可用运费时，该结果会记住 10 分钟。当 ShipStation 拒绝密钥或无法访问时，请求会暂停 5 分钟。触发速率限制后，暂停时间遵循 ShipStation 的重置时间。请求超时时间为 12 秒。停用插件会清除缓存的运费。

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

该方式适用于经典结账以及购物车和结账区块。它兼容 WooCommerce 高性能订单存储（HPOS）。

插件仅计算运费。它不购买运单标签，不在 ShipStation 中创建订单或发货，不跟踪包裹，也不处理退货。不提供自提点，结账时不能在多种服务之间选择，没有地址验证、保险、签名确认、拆分为多个包裹，也不提供运费加价功能。

订单

订单的配送项目会保存所选的 Service，例如 "USPS Ground Advantage - Package"。您可以在管理后台的订单页面中看到它，并可在 ShipStation 中创建对应的运单标签。

许可证密钥

插件需要使用来自 vibefox.net 的 VibeFox 许可证密钥。许可证区块位于 WooCommerce > Settings > Shipping > VibeFox ShipStation 页面顶部。将密钥粘贴到 License key 中并点击 Activate。该区块会显示状态，例如许可证有效期至何时以及您的域名。使用 Check now 重新检查状态，使用 Change key 输入其他密钥，使用 Remove key 将其从本站点移除。链接 Manage licenses and domains in your account 会打开您的 vibefox.net 账户。

一个密钥只能用于一个域名。从站点中移除密钥并不会释放其域名名额。请在您的 vibefox.net 账户中释放该名额。

没有有效的密钥时，ShipStation 不会在结账时向顾客显示。已登录的店铺管理员仍会看到它，并标注为 (unlicensed — visible to admins only)，以便您在购买密钥之前设置和测试插件。插件页面和 WooCommerce 页面上会显示提醒。现有订单不受影响。

许可证过期后，插件仍会继续工作，但更新和支持需要续费。状态会在后台自动重新检查。

故障排除

ShipStation 没有出现在结账页面：请检查许可证是否有效、Enable/Disable 是否开启，以及该方式是否已添加到顾客所在国家的区域（或 Ignore shipping zones 已开启且该国家被允许）。检查重量限制、Minimum subtotal 和 Disabled shipping classes。如果没有实时运费，请检查该国家、* Default 或 Other countries 是否设置了价格。

结账显示的是备用运费而不是 ShipStation 运费：请检查设置页面顶部的警告（密钥、承运商代码、发货邮政编码、汇率）。开启 Debug log，然后打开 WooCommerce > Status > Logs，来源为 vfd-shipstation。顾客的邮政编码是必需的，输入之前不会发出请求。

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

运费与 ShipStation 不一致：包裹根据商品的重量和尺寸构建，商品装入一个箱子。没有尺寸的商品仅按重量计算。运费缓存 1 小时。保存设置可清除缓存。

面向开发者：过滤器 vfd_shst_rate_request、vfd_shst_selected_rate 和 vfd_shst_api_url 可分别更改每个承运商的运费请求、所选运费以及 API 基础 URL。

许可证区块显示错误：请按照区块中的提示操作。例如，如果该密钥已在另一个域名上使用，请在您的 vibefox.net 账户中释放一个名额，然后点击 Check now。如果站点地址已更改，请点击 Check now 为新域名激活密钥。如果无法连接许可证服务器，插件将按最近一次已知状态继续工作。

卸载

停用插件会保留设置，仅清除缓存的运费。要删除它，请在 Plugins 页面中停用并删除。该插件的许可证密钥和许可证状态、缓存的运费以及已保存的承运商列表总会被删除。只有在 Remove data on uninstall 开启时，设置和区域方式才会被删除；否则会保留，以便日后重新安装。现有订单保留其配送项目。

ShipStation 是其各自所有者的商标。本插件与 ShipStation 没有关联，也未获得 ShipStation 的认可。