HostBill、Blesta、または独自のシステムから Zinn® ホスティングを販売

WHMCS をご利用の場合は、代わりに[WHMCS モジュール] (/kb/whmcs-module) をご利用ください — このページはそれ以外のすべてを対象としています。2つのオプションがあり、どちらも無料で、どちらも GPL-2.0-or-later です。

HostBill

WHMCS 向けと同じ6つのアクションを備えたホスティングモジュールです。

1. [ダウンロード] (https://zinndigital.com/integrations)して解凍します。
2. zinnディレクトリをincludes/modules/Hosting/にアップロードし、ファイルがincludes/modules/Hosting/zinn/class.zinn.phpおよびincludes/modules/Hosting/zinn/ZinnHostBillClient.phpに配置されるようにします。
3. Settings → Modules → HostingでZinn Digital®を有効化し、接続を追加します:

• API address: https://api.zinndigital.com
• API key: お客様の Zinn® API キー (passwordフィールドであるため、HostBill によって暗号化されて保存されます)

1. 対象の商品でProduct line (例: mainstream)、Stack (デフォルトはwordpress)、および任意でApplicationとPHP versionを設定します。
2. Test connectionを押します。

⛔ zinnディレクトリの名前を変更しないでください。 HostBill のローダーはディレクトリ名から検索対象のクラスを導出するため、名前を変更するとパネルに一覧表示されるものの呼び出されることのないモジュールが生成されてしまいます。

その他すべて — PHP クライアント

依存関係なし、パネルへの前提条件なしの単一ファイルです。ご自身のコードベースにZinnProvisioning.phpを配置し、6つのメソッドを呼び出してください。

require_once 'ZinnProvisioning.php';

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

// When an order is paid — once per CUSTOMER, then once per SERVICE:
$orgId  = $zinn->account('customer-4211', 'Acme Ltd');
$siteId = $zinn->provision('service-9915', $orgId, 'acme.com', 'mainstream', 'wordpress');
// Store $orgId against your customer and $siteId against your service.

$zinn->suspend($siteId, 'INV-2026-114 unpaid');   // an invoice goes unpaid
$zinn->unsuspend($siteId);                        // they pay
$zinn->terminate($siteId);                        // they cancel — schedules a deletion

// When they click "log in to my hosting" — mint it on the CLICK, never on page render:
header('Location: ' . $zinn->signInLink($siteId));

PHP をお使いではないですか ? [API リファレンス] (https://zinndigital.com/developers/api)に同様の呼び出しが記載されており、あらゆる環境から実行していただけます。

API キー

必要な権限は7つだけであり、それ以上は不要です: org.create、org.read、sites.create、sites.view、sites.delete、reseller.view、reseller.provision。

⛔ reseller.manageではありません。 請求パネルに入力するキーは、未払いを理由とした顧客の一時停止やログインを実行できるべきですが、お客様ご自身の決済ゲートウェイの認証情報を書き換えられるべきではありません。

違反すると費用が発生する2つのルール

1. アカウントのキーはお客様の CUSTOMER に、サイトのキーはお客様の SERVICE に関連付けてください。 顧客による2回目の注文は、その顧客がすでに保持しているアカウントに割り当てる必要があります。両方のキーをサービスに関連付けると、1人の顧客が関連性のない3つのアカウントと3つの別個のコントロールパネルを持つ結果になります。
2. すべての作成時に、対象の要素に対する独自 ID から派生した冪等性キーを送信してください。 あらゆる請求システムで再試行が発生します — ゲートウェイのコールバックが2回届く、管理者が失敗したプロビジョニングを再実行する、顧客がダブルクリックするなどです。これがない場合、2回目の試行によって2つ目のサイトが作成され、その分の請求が発生します。両モジュールおよび PHP クライアントはお客様に代わってこれを処理します。API を直接呼び出す場合は、Idempotency-Keyを送信してください。

見落としやすい3つのフィールド

それぞれが操作全体を失敗させ、検証エラーとしてしか表示されません — ただし、最初のフィールドだけは何も表示されません:

• ⛔⛔ 最初のサイトがプロビジョニングされる前に、クライアントをプランに割り当てる必要があります。これには 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} からドメインを読み取ってください。エイリアスではなく、サイト自体のプライマリドメインと照合されます。

1文だけでなく、エラー全体を確認してください

バリデーション拒否のメッセージは、あえて汎用的なものとなっています — "The request was well-formed but failed validation." — なぜなら、対応に必要な情報はフィールド名とその理由を示す details に含まれているためです。両モジュールおよび PHP クライアントは、管理者に表示するメッセージにこれを追加します。お客様ご自身で API を呼び出している場合は、error.details を確認してください。一部のエントリには文章ではなく単一の値のみが含まれており、お客様のリセラープランに空きがない場合に max_sites: 0 が返されるのはそのためです。

最初の注文の前に

お客様のクライアントが購入したサイトは、お客様のリセラープランのサイト割り当てに対してカウントされるため、空きのあるプランが必要です。接続テストではこれを検出できません (プログラムを読み取るだけで何もプロビジョニングしないため)。その結果、まだ販売できない状態であっても正常なアカウントとして報告されます。割り当てがない状態で行われた注文は、まさにその旨を示すメッセージとともに拒否されます。

ダウンロードの検証

両方のアーカイブは、他の場所へリダイレクトされることなく、独自のホスト名から TLS 経由で配信され、[ダウンロードページ] (https://zinndigital.com/integrations) のダウンロードリンクの横にそれぞれの SHA-256チェックサムが記載されています。