知识库

从您自己的系统销售 Zinn® 托管

通过您自己的计费面板、WordPress 网站或脚本驱动 Zinn® 托管：获取 API 密钥，进行首次调用，并完成构成整个集成的六次调用。

您分销我们的托管服务。您的客户完全属于您：您的价格、您的发票、您的支付服务商。以下介绍了您如何通过现有运行的任何系统——计费面板、您自己的 WordPress 网站或脚本——来驱动我们的平台。

您的客户实际看到的内容

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

界面	归属主体
托管面板，位于您自己的主机名上	在分销 → 您的品牌下设置面板主机名，您的客户即可在 `panel.yourcompany.com` 登录，看到的是您的徽标和配色。相同的面板，您的专属地址。
您自己的网站	WordPress 插件会在您的网站上添加域名搜索功能和一键登录链接，并通过您自己的 WooCommerce 结账流程接收订单。
您的计费面板	WHMCS 或 HostBill 保持作为前端入口；模块在后台进行配置开通，客户区按钮可让他们直接登录至其托管服务。

⛔ 无论您选择哪种方式，您都是面向客户的记录在案商户（merchant of record）：您的价格、您的发票、您的增值税号、您的支付服务商。我们每月按批发价向您开具账单。

一旦您设置了面板主机名，请将其填入 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. 完整集成，仅需六次调用

触发时机              调用
订单已付款           POST   /v1/orgs                                   每个“客户”一次
                     POST   /v1/sites                                  每项“服务”一次
客户未付款           POST   /v1/reseller/services/{siteId}/suspend
客户付款             POST   /v1/reseller/services/{siteId}/unsuspend
客户取消服务         DELETE /v1/sites/{siteId}
“登录至托管服务”     POST   /v1/reseller/services/{siteId}/sso

配置开通包含两次调用，键的关联至关重要：

# 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"}'

两条一旦出错就会造成经济损失的规则

将账户以您的“客户”为键，将站点以您的“服务”为键。客户的第二笔订单必须归入其已有的账户中。如果将两者都以服务为键，同一客户最终会拥有三个互不相关的账户和三个独立的面板。
在每个 POST 请求中发送一个 Idempotency-Key，基于您自己对该实体的 ID 构建。每个计费系统都会进行重试——网关回调到达两次、管理员重新运行失败的配置开通、客户双击。若没有该密钥，第二次尝试将创建一个重复的站点，并且您需要为此付费。

不得合并简化处理的三种响应

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>，或从您控制面板中的插件下载。