VibeFox Shippo for PrestaShop — 帮助
系统要求
PrestaShop: 8.0 至 9.x。
PHP: 8.0 或更高版本。模块会拒绝在较旧的 PHP 版本上安装。
Shippo 账户: 创建 Shippo 账户，连接或启用承运商（USPS、UPS、FedEx、DHL 等），并从 Shippo > Settings > Advanced > API 复制 API 令牌。Shippo 对购买的面单收费，而不是对运费请求收费。新的 Shippo 账户可能需要先经 Shippo 验证，才会返回实时运费。没有令牌时，仅使用备用价格。
商品: 商品应设置重量和尺寸。没有尺寸的商品使用默认箱子尺寸。
VibeFox 许可证密钥: 在 vibefox.net 购买。一个密钥只能用于一个域名。
安装
1. 在后台进入 Modules > Module Manager，点击 Upload a module。选择模块的 ZIP 文件。
2. 上传完成后，点击 Configure，或之后在模块列表中找到 VibeFox Shippo 并点击 Configure。
3. 在 Configure 页面顶部的许可证区块中的 License key 处输入您的 VibeFox 许可证密钥，然后点击 Activate（见许可证密钥）。
4. 粘贴您的 Shippo API 令牌，并填写 Ship from 地址。实时运费需要邮政编码。
5. 选择 Shippo rate currency（若从美国发货则选 USD）；如果店铺默认货币不同，请输入 Exchange rate。
6. 可选择在按国家和重量的表格中输入备用价格，然后点击 Save。
安装时，模块会创建承运商 Shippo Shipping，其配送时间文本为 Shippo carriers (USPS, UPS, FedEx, DHL)。该承运商会分配给所有区域和所有客户组。您可以在 Shipping > Carriers 中更改区域、客户组、配送时间、图标和尺寸限制。请勿在那里设置价格：价格始终来自本模块。
配置
所有设置都在模块页面：Modules > Module Manager > VibeFox Shippo > Configure。每个部分都有自己的 Save 按钮，它会保存整个页面。每次保存也会清除缓存的 Shippo 运费。
页面顶部的警告会告诉您：承运商何时永远无法显示，或实时运费何时无法使用，例如没有 API 令牌、没有发货地邮政编码或国家、缺少汇率，或店铺的重量或尺寸单位不是模块能识别的单位（请在 International > Localization 的 Local units 中设置 kg、g、lb 或 oz，以及 cm、mm、m 或 in）。设置测试令牌时，通知会提醒您。保存时，非数字、负数或大于 Maximum weight (kg) 的 Minimum weight (kg) 会被报告为错误，直到您改正之前，任何内容都不会保存。
常规
Enable Shippo shipping: 开启或关闭该承运商。这与 Shipping > Carriers 中的承运商状态是同一个开关。
Name: 结账时显示给顾客的承运商名称。默认：Shippo Shipping。必填，最多 64 个字符。
Tax: 承运商的税务规则，或 No tax。Shippo 运费不含销售税。No tax 按报价原样显示；税务规则则依据您的税务规则为运费加税。
Shippo 账户
API token: 您的 Shippo API 令牌。正式店铺获取真实运费请使用正式令牌（shippo_live_...），Shippo 测试运费则使用测试令牌（shippo_test_...）。令牌仅发送给 Shippo，且绝不记录到日志中。保存后该字段保持为空，并显示 Saved — leave empty to keep it。只有在需要更改时才输入新值，或勾选 Remove the saved API token 以删除它。
Allowed carriers / services: 可选，以逗号分隔。按 Shippo 的名称输入承运商（USPS、UPS、FedEx、DHL Express），或输入 Shippo 服务等级令牌（usps_priority、ups_ground）。将显示允许范围内最便宜的运费。留空则显示任意承运商中最便宜的运费。
发货地址（包裹的寄出地址；若与店铺地址位于同一国家，空白字段将从 Shop Parameters > Contact > Stores 中的店铺地址获取）
Sender name / company: 寄件人姓名。它也用于签署海关申报单。若为空，则使用店铺名称。
Street address: 寄件人街道地址。
City: 寄件人城市。
State / province: 两位字母的州代码，例如 CA 或 NY。某些承运商需要此项。
Postal / ZIP code: 实时运费需要此项。
Country: 您的发货国家。默认：美国。
运费
Parcels: 购物车如何发送至 Shippo。
Default box size: 长 x 宽 x 高，单位为店铺的尺寸单位（显示在字段名称中），例如 30 x 20 x 10。Shippo 需要箱子尺寸。当购物车中某商品没有尺寸时使用此值。留空则使用 30 x 20 x 10 cm。无法读取的值会在保存后被忽略并提示。
Shippo rate currency: Shippo 为您的承运商报价所使用的货币，即发货国家的货币：USD（美国）、CAD（加拿大）、GBP（英国）、EUR（欧元区）或 AUD（澳大利亚）。默认：USD。Shippo 以店铺默认货币返回的运费始终按原样使用。
Exchange rate: Shippo 运费货币 1 个单位折合店铺默认货币的价格，例如 0.92。两种货币相同时无需填写。未填写时，其他货币的运费不予使用，并采用备用价格。本模块不会自动换算货币。
备用价格（在没有实时运费时使用：没有 API 令牌、Shippo 无法访问、令牌被拒绝，或该地址没有承运商运费；价格以店铺默认货币计，不含税；两个字段都留空则在此情况下隐藏该承运商）
Country prices: 按国家和购物车重量设置的价格表。点击 Add country 添加一行，点击垃圾桶图标删除一行。列为 Price，重量档位为 XS（最多 1 kg）、S（最多 2 kg）、M（最多 3 kg）、L（最多 5 kg）和 XL（超过 5 kg）。空白或为 0 的档位使用 Price 列。* Default 行适用于没有自有行的国家。新行默认为 * Default。所有单元格都为空时保存的行将收取 0，因此请删除未填写的行。
Other countries: 上表中未列出的国家（当没有 * Default 行时）的价格。留空则对这些国家隐藏该承运商。
条件
Free shipping from: 购物车小计（折扣后、税前）达到该金额后免运费。届时不会向 Shippo 发出请求。留空则关闭此功能。
Minimum subtotal: 仅当购物车小计（折扣后、税前）不低于此金额时才显示该承运商。留空则始终显示。
Minimum weight (kg): 显示承运商所需的最低购物车重量。0 表示无限制。
Maximum weight (kg): 购物车重量超过此值时隐藏该承运商。默认：30。0 表示无限制。空白字段保存为 30。
无配送区域时的可用性
通常，该承运商在 Shipping > Carriers 中的配送区域内提供。另外，也可以不依赖区域、按国家提供。
Ignore shipping zones: 无论所属区域是否已分配，都为下列国家提供该承运商。开启时，该承运商会被添加到所有区域，包括之后创建的区域。关闭时，这些添加的区域会被移除，承运商保留其自身的区域。
Countries: 该模式下的目的国家。留空则使用店铺所有已启用的国家。仅当 Ignore shipping zones 开启时才使用此字段。
高级
Debug log: 将 Shippo 请求记录到模块文件夹中的 logs/vfd_shpo_debug.log.php。该文件无法通过网页打开。即使此选项关闭，API 错误也总会被记录。API 令牌和顾客地址绝不会被记录。
Log: 显示日志的大小和最新条目。点击 Clear log 可清空日志。
Remove data on uninstall: 开启时，卸载模块会删除模块设置、承运商和日志。关闭时，所有内容都会保留，以便重新安装。缓存的运费始终会被删除。随订单保存的承运商和服务属于订单历史，会被保留。
结账时的工作方式
在配送步骤，PrestaShop 向模块请求 Shippo 价格。只计算实物商品：虚拟商品不增加重量，也不计入小计。模块首先检查条件：Ignore shipping zones 的国家、购物车重量和最低小计。若适用满额包邮，则价格为 0，且不会向 Shippo 发出请求。
然后，模块将发货地址、顾客地址和包裹发送给 Shippo。对于 PrestaShop 要求邮政编码的国家，请求会等到顾客输入邮政编码后再发出。对于国际运输，会附加包含商品名称、数量、重量和价值的海关申报单。Shippo 返回您承运商的运费，模块使用允许范围内最便宜的运费。价格以店铺默认货币计算，然后以顾客的购物车货币显示。
在按订单模式下，商品装入一个箱子：最大商品的最长边和中间边，加上所有单位的最短边之和。若任何商品没有尺寸，则整个包裹使用默认箱子尺寸。在按商品模式下，每件商品作为单独的包裹计算运费，并将运费乘以其数量。
每个响应按地址和包裹缓存 1 小时。当 Shippo 返回的响应中没有可用运费时，该地址会被记住 10 分钟。发生超时、令牌被拒绝、服务器错误或速率限制后，模块会暂停请求 5 分钟，并改用备用价格。请求超时时间为 10 秒。
若没有实时运费，价格取自备用价格表，然后取自 Other countries。若两者都不适用，则隐藏该承运商。顾客永远不会看到错误。原因会写入调试日志。
如果您在订单产生后于 Shipping > Carriers 中编辑该承运商，PrestaShop 会将其保存为新的承运商版本。模块会自动跟随新版本。
本模块仅计算运费。它不购买面单，不跟踪包裹，不验证地址，也不提供取货或寄存点、保险、签收选项或退货面单。只显示允许范围内最便宜的运费，而非所有服务的列表。除上述装箱方式外，不进行箱子打包，也不加收运费加价或手续费。
订单
使用实时 Shippo 运费下单时，模块会保存所选的 Carrier / service，并且对于每个订单一个包裹的情况，还会保存 Estimated delivery days。它们会显示在后台订单页面的 Shippo 区块中，方便您在 Shippo 中购买对应的面单。数据会与订单一起固定：之后对购物车的更改不会改变它。使用备用价格或免运费的订单没有 Shippo 区块。
许可证密钥
本模块使用来自 vibefox.net 的 VibeFox 许可证密钥。许可证区块 License — VibeFox Shippo 位于 Modules > Module Manager > VibeFox Shippo > Configure 页面的最上方，位于设置之上。将密钥粘贴到 License key 中，然后点击 Activate。之后，该区块会显示被遮蔽的密钥、状态（例如许可证有效期截止日期和您的域名），以及以下按钮：Check now（重新检查状态）、Change key（输入另一个密钥）和 Remove key（从此店铺中移除密钥）。其下方有一行 Product: presta-shipping-shippo 和链接 Manage licenses and domains in your account，点击后会打开您的 vibefox.net 账户。只有拥有该模块 Configure 权限的员工才能更改密钥。该区块的文字跟随后台语言显示（包含英语和俄语）。
如果密钥未被接受，该区块会说明原因，例如 Key not found、This key belongs to another product、Domain limit reached，或 License expired on 加某个日期。在店铺地址更改后，或在您的账户中释放了一个域名名额后，请点击 Check now。如果无法连接许可证服务器，模块会继续使用上次已知的状态运行。
一个密钥只能用于一个域名：即主店铺的域名，多店铺设置中也是如此。从店铺中移除密钥不会释放其域名名额。请在您的 vibefox.net 账户中释放该名额。
没有有效密钥时，结账时不会向顾客显示 Shippo 承运商，也不会计算运费。PrestaShop 前台无法知道您已登录后台，因此承运商对您也是隐藏的：您可以在购买密钥之前设置模块，但无法在结账时测试。Modules > Module Manager 中的 Alerts 选项卡上会出现提醒。现有订单不受影响。
许可证到期后，模块仍会继续工作，但更新和支持需要续订。在您使用后台时，系统会自动再次检查状态：输入密钥后的前 14 天每天检查一次，之后每周检查一次。无需设置 cron 任务。卸载或重置模块时，总会删除许可证密钥和许可证状态。
故障排除
Shippo 未出现在结账页面: 请检查许可证是否有效，以及 Enable Shippo shipping 是否已开启。在 Shipping > Carriers 中，检查该承运商是否覆盖顾客所在国家的区域和顾客所在的客户组（或 Ignore shipping zones 已开启且该国家被允许）。检查重量限制和 Minimum subtotal。若没有实时运费，请检查该国家、* Default 或 Other countries 是否设有价格。商品也可以在商品页面中限制为特定承运商。
实时运费不显示: 开启 Debug log，重新加载结账页面，并查看模块页面上的 Log 字段。常见原因：没有 API 令牌或发货地邮政编码；店铺默认货币与 Shippo 运费货币不同且没有汇率；顾客尚未输入邮政编码；您的 Shippo 账户中没有承运商服务该地址；或 Shippo 账户尚未验证。
在正式店铺中测试运费: 测试令牌（shippo_test_...）会返回 Shippo 测试运费。请使用正式令牌（shippo_live_...）。
意外国家免运费: 请检查价格表中是否有空行，尤其是空的 * Default 行。所有单元格都为空的行会收取 0。
更改后运费看起来过时: 请在模块页面点击 Save。这会清除缓存的 Shippo 运费。
页面提示未找到 Shippo 承运商: 该承运商已在 Shipping > Carriers 中被删除。请在 Modules > Module Manager 中重置模块以重新创建。
卸载
进入 Modules > Module Manager，打开 VibeFox Shippo 旁边的菜单，选择 Uninstall。许可证密钥和许可证状态始终会被删除。缓存的运费始终会被删除。如果 Remove data on uninstall 已开启，承运商会被删除（订单保留其历史记录），并删除设置和日志。如果已关闭，承运商仅被停用，所有设置都会保留。重新安装模块会使承运商恢复其之前的状态。现有订单保留其 Shippo 承运商和服务数据。
Shippo 是其各自所有者的商标。本模块与 Shippo 无关联，也未获得 Shippo 的认可或背书。