通过 WHMCS 出售 Zinn® 虚拟主机

Zinn Digital® 模块将 WHMCS 自身的按钮转换为我们平台上的真实操作。订单会配置您客户的主机。WHMCS 的逾期账单自动化会暂停主机。标记账单为已付会释放主机。取消操作会安排删除。并且您的客户在其客户专区中会获得一个登录主机面板按钮，可直接将其登录。

它是免费的，采用 GPL-2.0-or-later 许可证，并且在我们平台上没有特权路径：它调用的每个端点都是有文档记录的端点，您可以使用自己的 API 密钥自行调用。

开始之前

您需要两件事，而第二件事往往会让人措手不及。

具有有效计划的 Zinn® 分销商账户。 请在 zinndigital.com 注册并启用分销功能。
包含站点额度的分销商计划。 您的客户订购的站点会占用您的计划额度，因此您需要一个有剩余空间的计划。

准则 ⚠️ 测试连接无法告知您订单是否会成功。 它会读取您的计划但不配置任何内容，因此它会报告一个健康的 active 账户，但该账户尚不能销售任何东西。如果您的第一个订单失败并显示 “此组织没有主机计划，因此尚无法托管站点”，这就是原因所在——请购买或延长您的分销商计划并重新下单。该模块没有任何问题。

1. 创建 API 密钥

在您的 Zinn® 仪表板中，打开 API 密钥 并创建一个恰好具有这十一个权限的密钥：

| 权限 | 需要它的原因 | | ---------------------- | ------------------------------------------------------------ | | org.create | 在客户下第一个订单时为其打开 Zinn® 账户。 | | org.read | 读取您的客户账户。 | | sites.create | 配置站点。 | | sites.view | 读取服务及其使用情况。 | | sites.delete | 终止服务。 | | reseller.view | 列出您已售出的内容，并读取磁盘和带宽。 | | reseller.provision | 暂停、释放、为客户登录、设置其计划并更改其套餐。 | | billing.view | 在执行升级之前读取升级所需的费用。 | | sites.manage | 通过按钮清除缓存并创建备份。 | | sites.panel_access | 更改 WordPress 管理员的密码。 | | hosting.php.manage | 在升级或降级时切换 PHP 版本。 |

⛔ 请勿授予 reseller.manage 权限。 粘贴到计费面板中的密钥应当能够因未付款而保留客户并将其登录。它不应能够读取和重写您自己的支付网关凭据。reseller.provision 的存在就是为了让您无需授予权限更大的那一个。 ⛔ org.create 不是可选的。 没有它，模块可以读取您的账户但无法打开新账户，因此测试连接会通过，但第一个订单会返回 403。 ⛔⛔ 请授予整张表中的权限，并注意测试连接无法告知您是否遗漏了权限。 它会读取您的分销商计划但不配置任何内容，因此对于缺少其中任何权限的密钥，它也会显示为绿色。您最终会在几个月后遇到这种情况：当客户触发某个被缺失权限覆盖的操作时，系统会返回 403 错误。

2. 安装模块

下载模块并解压。
将 zinn 目录上传到您的 WHMCS 安装中，以便模块文件存放在 modules/servers/zinn/zinn.php。

⛔ 该目录必须命名为 zinn。 WHMCS 从其目录名称派生配置模块的函数名，因此将其重命名为 zinn-whmcs 或 zinndigital 会生成一个 WHMCS 列出并允许您选择但永远不会调用的模块——并且没有任何错误提示。压缩包已经解压为正确的名称；请勿将其重命名。

3. 添加服务器

在 WHMCS 中：配置 (Configuration) → 系统设置 (System Settings) → 服务器 (Servers) → 添加新服务器 (Add New Server)。

名称 (Name)：任意名称，例如 Zinn Digital®
主机名 (Hostname)：api.zinndigital.com
类型 (Type)：Zinn Digital®
密码 (Password)：您在第 1 步中获得的 API 密钥

⛔ 密钥需要放入密码 (Password) 字段中，WHMCS 会对其进行加密存储。请勿将其放入产品配置选项中——这些选项在数据库中是纯文本的，所有管理员都可见，而此凭据可以创建和销毁您客户的主机。

点击测试连接 (Test Connection)。它会进行真实的调用并报告我们平台返回的结果，而不是仅检查字段是否已填写。

4. 创建产品

配置 (Configuration) → 系统设置 (System Settings) → 产品/服务 (Products/Services)，然后将模块设置 (Module Settings) 设置为您刚刚添加的服务器。各字段如下：

| 字段 | 必填 | 说明 | | -------------------- | ------ | ------------------------------------------------------------ | | 产品线 (Product line) | 是 | 您正在销售的 Zinn® 产品线 — mainstate（托管型 WordPress）、footprint_free、wordpress、linux、cloud、agency、app_hosting、ai_hosting、lms_hosting、managed_database、vector_hosting、zinn_compute、fleet_linux、fleet_enterprise、mail 或 reseller。 | | 技术栈 (Stack) | 是 | 构建的内容：wordpress（默认）、woocommerce、php、static、node、one_click、headless_cms、nextcloud 或 owncloud。 | | 应用程序 (Application) | 否 | 仅适用于 one_click 和 headless_cms 技术栈 — 要安装哪个应用程序。在任何其他技术栈上指定应用程序都会被拒绝，因为该技术栈已经决定了要安装的内容。 | | PHP 版本 (PHP version) | 否 | 例如 8.3。如果留空，则使用该产品线默认版本。产品线不提供的版本会被拒绝，并附带其支持的版本列表。 | | 计划代码 (Plan code) | 是 | 此产品销售的 Zinn® 计划。GET /v1/reseller/prices 会列出您的计划。缺少此项的订单将被拒绝 — 请参见下方的警告。 | | 计费周期 (Billing interval) | 否 | monthly（每月，默认）或 annual（每年）— 为您该客户的批发产品线产生费用的周期。您向自己的客户收取的费用是在 WHMCS 产品中设置的，不受此影响。 |

⛔⛔ 计划代码是必填项，缺少该代码的订单将被故意拒绝。 在 2026-09-01 之前，此字段是装饰性的，没有任何程序读取它，因此模块订购的主机没有任何计划——由此产生的一切后果都是静默发生的。您的批发对账单是根据客户的实时订阅生成的，因此服务没有任何行项目，只要它运行，就不会向您开具任何发票；您的客户也没有继承任何额度，因此没有任何磁盘或文件配额应用于其站点；并且更改套餐时无可更改之物，因此您售出的升级无法执行。在整个过程中，站点配置和提供服务都堪称完美。

该模块现在改为拒绝该订单，因为没有安全的计划供其猜测：猜测配置的主机可能会落在您未选择且可能未定价的计划上，并且——与您会立即看到的拒绝不同——它只会在对账单到达时（如果真有的话）才会浮出水面。

将自动设置 (Auto Setup) 设置为您偏好的选项 — 该模块对于 WHMCS 服务 ID 是幂等的，因此重试配置会返回相同的站点，而不会向您收取第二个站点的费用。

每个 WHMCS 操作的功能

| WHMCS 操作 | 我们端发生的事情 | | --------------------------- | ------------------------------------------------------------ | | 创建 (Create) | 创建客户的 Zinn® 账户（或复用他们已有的账户）并配置其站点。 | | 暂停 (Suspend) | 将站点置于未付款挂起状态。保留内容；不删除任何内容。 | | 取消暂停 (Unsuspend) | 解除您的挂起。 | | 终止 (Terminate) | 安排删除站点，并提供宽限期。日期会显示在客户专区中。 | | 用量更新 (Usage update) | 每天一次刷新每项服务的磁盘和带宽。 | | 登录主机面板 (Log in to hosting panel) | 打开一个单次使用的登录链接，直接进入客户的面板。 | | 更改套餐 (Change Package) | 升级或降级服务。移动套餐，如果新产品指定了 PHP 版本，则同时更改 PHP 版本。 | | 更改密码 (Change Password) | 设置 WordPress 管理员的密码。对于没有此类账户的技术栈，此方框不会显示。 | | 续费 (Renew) | 确认服务仍然存在。Zinn® 主机是持续提供的，因此没有要延长远程期限的问题。 | | 同步用量 / 清除缓存 / 创建备份 (Sync Usage / Purge Cache / Take Backup) | 管理员服务页面上的按钮。您的客户在其客户专区中可使用“清除缓存”和“创建备份”。 | | 服务选项卡 (Service tab) | 状态、计划、磁盘、带宽、任何计划的删除时间以及谁实施了暂停。 | | 导入 (Import) | ListAccounts 会读取每一页，因此导入操作不会在第一页静默停止。 |

升级：谁向谁收费

您的客户绝不会收到来自 Zinn® 的关于订单或升级的发票。 您通过 WHMCS 向他们开具账单；我们则在您的批发对账单上向您开具账单。因此，“更改套餐”会转移客户的权益以及您下一份对账单上的行项目，而不涉及任何银行卡——WHMCS 已经收取了客户的款项并计算了自己的分摊额。

客户的第二项服务。 在同一计划下，它是该计划自身站点额度下的另一个站点，不会授予其他任何内容。在不同的计划下，它会被拒绝：替换实时计划会导致两个服务之一失去计费。要么在同一计划下销售两项服务，要么在 WHMCS 中将客户设置为独立的客户记录。

“更改密码”仅适用于 WordPress。 Zinn® 主机没有单一的“服务密码”——您的客户通过登录按钮访问其面板——并且 php 或 static 站点没有要更改的应用程序账户。WHMCS 会完全隐藏该框，而不是显示一个无法使用的框。

您绝不能将其简化为两个的三个答案

取消暂停可能会返回拒绝响应。 这意味着站点是由我们的滥用防范团队暂停的，而不是由您暂停的，任何计费面板都不得将其解除。消息中会说明这一点；请将其展示给您的管理员，而不是重试。
终止会安排删除，而不是执行删除。 日期会以 pending_deletion_at 的形式返回，并且客户专区会显示它。告诉客户其数据已经消失而实际并非如此，比什么都不说还要糟糕。
磁盘和带宽可能是未知的，而未知并不等于零。 当我们无法读取数据时，模块会保持该数字不变，而不是写入 0——否则，WHMCS 会向您的客户显示一个令人放心的空用量条，而该站点我们根本没有读取到数据。

故障排除

测试连接通过，但第一个订单因权限错误而失败。 API 密钥缺少 org.create 权限。模块必须在创建客户站点之前打开客户的账户。

订单失败，提示组织没有主机计划。 您的分销商计划没有剩余的站点额度，或者您还没有持有计划。请参阅上面的开始之前。

订单失败并提及技术栈。 产品上的技术栈 (Stack) 字段为空或指定了我们不构建的内容。除非您在销售其他产品，否则请将其设置为 wordpress。

取消操作失败。 请确保您使用的是 1.0.0 或更高版本的模块。早期版本未发送删除确认，导致每个终止请求都被拒绝，从而使服务保持运行并继续计费。

提及某个字段的拒绝响应。 我们的验证错误会在消息后面的括号中指明字段和原因，例如 (php_version: 7.2 is not offered on this product line)。这是可操作的半句——其前面的句子是故意保持通用的。

验证您的下载

每个归档文件均通过 TLS 从我们自己的主机名提供，从不重定向到第三方主机。其 SHA-256 校验和打印在下载页面上的下载链接旁。下载后请进行比较：

macOS 或 Linux：shasum -a 256 zinn-whmcs-1.0.0.zip
Windows：certutil -hashfile zinn-whmcs-1.0.0.zip SHA256

未使用 WHMCS？

我们提供适用于其他任何系统的 HostBill 模块和单文件 PHP 客户端，两者皆免费且均可在同一个下载页面上找到。模块使用的每个端点都位于 API 参考中。