知识库

在您的自有系统中销售 Zinn® 主机

通过您自己的计费面板、WordPress 网站或脚本驱动 Zinn® 托管：获取 API 密钥，进行您的第一次调用，以及整个集成所包含的六个调用。

您在转售我们的托管服务。您的客户归您所有：您的价格、您的发票、您的支付服务商。无论您目前运行的是什么系统——计费面板、您自己的 WordPress 网站还是某个脚本——这就是您驱动我们平台的方式。

您的客户实际看到的是什么

在了解技术机制之前：您的客户永远不需要看到我们。 有三个界面，您可以选择使用哪一个。

| 界面 | 归属 | |---|---| | 托管面板（使用您自己的主机名） | 在转售 → 您的品牌下设置面板主机名，您的客户即可使用您的标志和颜色登录 panel.yourcompany.com。相同的面板，您的地址。 | | 您自己的网站 | WordPress 插件会在您的网站上提供域名搜索和一键登录链接，并通过您自己的 WooCommerce 结账流程处理订单。 | | 您的计费面板 | WHMCS 或 HostBill 仍然作为前端入口；模块在其背后进行开通，客户中心按钮可将他们直接登录到其托管服务中。 |

⛔ 无论您选择哪一个，您都是客户的名义商家：您的价格、您的发票、您的增值税号、您的支付服务商。我们会按批发价向您按月开具账单。

设置面板主机名后，将其填入 WordPress 插件的面板地址字段中，不要填入其他地方——此 API 生成的登录链接会自动遵循该地址。

四种接入方式

有四种接入方式，它们在底层执行相同的操作：

| | 适用于 | |---|---| | WHMCS 模块 | WHMCS 商店 | | HostBill 模块 | HostBill 商店 | | WordPress 插件 | 通过您自己的 WordPress 或 WooCommerce 网站进行销售 | | API | 任何其他系统——Blesta、内部系统、cron 脚本 |

1. 获取 API 密钥

在您的控制面板中，前往API 密钥并创建一个。仅赋予其所需权限：

| 权限 | 原因 | |---|---| | org.read | 读取您的客户账户 | | sites.create | 开通网站 | | sites.view | 读取服务 | | sites.delete | 终止服务 | | reseller.view | 列出您的服务并读取用量 | | reseller.provision | 暂停、释放客户并为其登录 |

⛔ 切勿向集成授予 reseller.manage 权限。 该权限会编辑您的价格表以及您自己的支付网关凭据。reseller.provision 的存在正是为了让您粘贴到计费面板或网站中的密钥不需要该权限。

密钥仅显示一次。将其存储在您存储其他凭据的地方——切勿存放在 Web 服务器提供访问的文件中。

2. 发起您的第一次调用

curl https://api.zinndigital.com/v1/reseller/services \
  -H "Authorization: Bearer zdk_live_…"

该命令会返回您已开通的所有服务，每站点一行，包含其所属客户、状态以及您收取的费用。在新账户上它是一个空列表——这是正确的结果，而不是错误。

3. 完整的集成，只需六次调用

WHEN                 CALL
an order is paid     POST   /v1/orgs                                   once per CUSTOMER
                     POST   /v1/sites                                  once per SERVICE
they have not paid   POST   /v1/reseller/services/{siteId}/suspend
they pay             POST   /v1/reseller/services/{siteId}/unsuspend
they cancel          DELETE /v1/sites/{siteId}
"log in to hosting"  POST   /v1/reseller/services/{siteId}/sso

开通操作包含两次调用，键（key）非常重要：

# 1. 客户账户——以您的客户 ID 为键
curl -X POST https://api.zinndigital.com/v1/orgs \
  -H "Authorization: Bearer zdk_live_…" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: account-4211" \
  -d '{"type":"customer","name":"Acme Ltd"}'

# 2. 他们的网站——以您的服务 ID 为键
curl -X POST https://api.zinndigital.com/v1/sites \
  -H "Authorization: Bearer zdk_live_…" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: service-9915" \
  -d '{"org_id":"<from step 1>","product_line":"mainstream","primary_domain":"acme.com"}'

弄错会导致金钱损失的两个规则

以您的客户（CUSTOMER）为账户建键，以您的服务（SERVICE）为网站建键。 客户的第二个订单必须落入他们已有的账户中。如果都以服务建键，最终会导致一个客户拥有三个不相关的账户和三个独立的面板。
在每个 POST 请求中发送一个从您自己的该项事物 ID 构建的 Idempotency-Key。 每个计费系统都会重试——网关回调到达两次、管理员重新运行失败的开通、客户双击。如果没有该密钥，第二次尝试将创建一个新网站，您将为此被收费。

您绝不能简化为两项的三种响应

unsuspend 可能会返回 409。 这意味着我们的滥用处理团队正在扣留该网站，而不是您。显示此消息；不要重试。
**终止操作是计划删除，而不是立即执行。** 返回的日期格式为 pending_deletion_at。在数据尚未删除时告诉客户数据已消失，比什么都不说还要糟糕。
disk_used_bytes 可以是 null，且 null 不等于零。 这意味着我们无法测量，而不是没有使用任何空间。请跳过它——不要将 0 写入您自己的记录中，否则您会向客户展示一个没有读取数据的网站的绿色用量条。

4. 将客户登录

POST /v1/reseller/services/{siteId}/sso 会返回一个一次性 URL，可将您的客户直接带入其自己的账户中并自动完成登录。

⛔ 在他们点击时生成，切勿在渲染页面时生成。 该链接是一次性的且会在几分钟内过期，因此写入页面的链接会在第一次页面浏览时失效，并残留在您与浏览器之间的所有缓存中。

5. 改为安装模块

WHMCS — 将模块复制到 modules/servers/zinn/，添加一个服务器，其密码为您的 API 密钥，并在产品上设置产品线。点击测试连接：它会发起真实调用并告知您平台的响应。
HostBill — 复制到 includes/modules/Hosting/zinn/ 并以相同方式连接。
WordPress — Zinn® Reseller Toolkit：提供域名服务、客户托管服务的登录链接，以及订单付款后的 WooCommerce 开通功能。开源地址位于 <https://github.com/Zinn-Digital/zinn-reseller-toolkit>，或者从控制面板中的插件处下载。