知识库

通过 HostBill、Blesta 或您自己的系统销售 Zinn® 主机

从 HostBill、Blesta 或您自己的系统销售 Zinn® 主机：免费的 HostBill 模块、单文件 PHP 客户端、违反时会产生费用的两项规则，以及容易被遗漏的两个请求字段。

如果您运行 WHMCS，请改用 WHMCS 模块——本页面适用于其他所有情况。有两个选项，均免费且均遵循 GPL-2.0-or-later 许可协议。

HostBill

一个具有与 WHMCS 模块相同的六个操作的托管模块。

下载它并解压。
将 zinn 目录上传到 includes/modules/Hosting/，使文件位于 includes/modules/Hosting/zinn/class.zinn.php 和 includes/modules/Hosting/zinn/ZinnHostBillClient.php。
设置 → 模块 → 托管，激活 Zinn Digital®，并添加连接：

API 地址：https://api.zinndigital.com
API 密钥：您的 Zinn® API 密钥（一个 password 字段，因此 HostBill 会加密存储它）

在产品上设置产品线（例如 mainstream）、技术栈（默认为 wordpress），以及可选的应用程序和 PHP 版本。
点击测试连接。

⛔ 请勿重命名 zinn 目录。 HostBill 的加载器根据目录名称派生其查找的类，因此重命名会导致控制面板列出该模块但从不调用它。

其他所有情况——PHP 客户端

单个文件，无依赖项，无面板假设。将 ZinnProvisioning.php 放入您自己的代码库并调用六个方法。

require_once 'ZinnProvisioning.php';

$zinn = new ZinnProvisioning(getenv('ZINN_API_KEY'));

// 当订单完成支付时——每个客户执行一次，然后每个服务执行一次：
$orgId  = $zinn->account('customer-4211', 'Acme Ltd');
$siteId = $zinn->provision('service-9915', $orgId, 'acme.com', 'mainstream', 'wordpress');
// 针对您的客户存储 $orgId，针对您的服务存储 $siteId。

$zinn->suspend($siteId, 'INV-2026-114 unpaid');   // 账单未支付
$zinn->unsuspend($siteId);                        // 客户完成支付
$zinn->terminate($siteId);                        // 客户取消——计划删除

// 当他们点击“登录我的托管”时——在点击时生成，绝不要在页面渲染时生成：
header('Location: ' . $zinn->signInLink($siteId));

不编写 PHP？相同的调用包含在 API 参考中，您可以使用任何语言发起调用。

API 密钥

七项权限，不多不少：org.create、org.read、sites.create、sites.view、sites.delete、reseller.view、reseller.provision。

⛔ 不可包含 reseller.manage。 您粘贴到计费面板中的密钥应该能够因未付款而暂停客户以及使其登录；它不应该能够重写您自己的支付网关凭据。

违反时会造成经济损失的两条规则

将账户与您的客户关联，并将站点与您的服务关联。 客户的第二个订单必须归入他们已有的账户中。如果将两者都与服务关联，一个客户最终将拥有三个互不相关的账户和三个独立的控制面板。
在每次创建时发送幂等密钥，该密钥派生自您自己为该对象设置的 ID。 每个计费系统都会重试——网关回调到达两次、管理员重新运行失败的配置、客户双击。若没有它，第二次尝试将创建第二个站点，并且您需要为此付费。两个模块和 PHP 客户端都会为您处理此事；如果您直接调用 API，请发送 Idempotency-Key。

容易遗漏的三个字段

每一个都会导致整个谓词失效，且除了第一个会显示为完全无内容之外，其余都仅显示为验证错误：

⛔⛔ 在为客户配置第一个站点之前，必须先为其指定一个方案，使用 POST /v1/reseller/clients/{orgId}/plan，并将其 subscription_id 传递给 POST /v1/sites。这种情况不会显示任何错误。新客户账户不包含任何订阅，且 POST /v1/sites 没有方案字段，因此在没有方案的情况下配置的站点将完全没有任何方案：您的批发对账单是根据客户的有效订阅生成的，因此只要托管服务持续运行，就不会产生账单项，且 Zinn® 不会向您收取任何费用；您的客户不会继承任何配额，因此其站点不会应用任何限额；并且升级也无法更改任何内容。订单返回 201，站点完成配置并完美运行。两端都不会对此报告任何异常。

顺序至关重要：POST /v1/sites 会记录其运行时存在的任何订阅，因此事后设置的方案不会追溯关联。

POST /v1/sites 需要 stack_type。 若省略此项，任何订单都无法成功。
DELETE /v1/sites/{siteId} 需要请求体 {"confirm_domain": "<the site's own domain>"} —— 即输入的确认信息，因为这是一个破坏性操作动词。若省略此项，任何取消操作都无法成功，因此服务将继续运行，且您将继续为此被计费。请从 GET /v1/reseller/services/{siteId} 重新读取域名，而不要使用您自己的记录：系统会将其与站点自身的主域名进行比对，绝不会与别名进行比对。

阅读完整的错误信息，而不仅仅是那句话

验证拒绝的消息是刻意通用化的 —— "The request was well-formed but failed validation."（请求格式正确但验证失败。）—— 因为包含可操作信息的部分位于 details 中，其中指明了字段及其原因。各个模块和 PHP 客户端都会将其附加到向您的管理员显示的消息中。如果您是自行调用 API，请读取 error.details；某些条目仅包含一个单纯的值而非完整句子，这正是当您的分销商方案没有空额时，您会收到 max_sites: 0 的原因。