独自のシステムから Zinn® ホスティングを販売する

お客様は弊社のホスティングを再販します。クライアントはお客様のものです。価格設定、請求書、決済プロバイダーもすべてお客様が管理します。これは、請求パネル、独自の WordPress サイト、スクリプトなど、すでにお使いの環境から弊社のプラットフォームを操作する方法です。

クライアントが実際に目にするもの

仕組みを説明する前に確認しておきたい点として、クライアントが弊社を目にすることは一切ありません。 3つの画面形態があり、どれを使用するかはお客様が選択できます。

⛔ どの方法を選択しても、お客様がクライアントに対する登録事業者 (Merchant of Record) となります。お客様の価格、請求書、VAT 番号、決済プロバイダーが適用されます。弊社は月に一度、卸売価格でお客様に請求いたします。

パネルのホスト名を設定したら、WordPress プラグインの パネルアドレス フィールドにのみ入力してください。他の場所には入力しないでください。この API が発行するサインインリンクは自動的にそれに従います。

4つの導入方法

4つの導入方法がありますが、内部で実行される処理はすべて同じです。

1. API キーの取得

ダッシュボードで API キー に移動し、キーを作成します。必要な権限のみを付与してください。

⛔ 連携機能に reseller.manage を付与しないでください。 この権限は、価格表やお客様独自の決済ゲートウェイの認証情報を編集するためのものです。請求パネルやウェブサイトに貼り付けるキーにこの権限を不要にするために、まさに reseller.provision が存在します。

キーは一度だけ表示されます。他の認証情報と同様の安全な場所に保管してください。ウェブサーバーが配信するファイル内には絶対に保存しないでください。

2. 最初の呼び出しを実行する

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

これにより、プロビジョニング済みのすべてのサービスがサイトごとに1行ずつ、所属するクライアント、ステータス、お客様が請求している金額とともに返されます。新規アカウントの場合は空のリストが返されますが、これはエラーではなく正常な応答です。

3. 連携の全体フロー (6つの呼び出し)

タイミング             呼び出し
注文の支払い完了時     POST   /v1/orgs                                   顧客ごとに1回
                       POST   /v1/sites                                  サービスごとに1回
未払い時               POST   /v1/reseller/services/{siteId}/suspend
支払い完了時           POST   /v1/reseller/services/{siteId}/unsuspend
解約時                 DELETE /v1/sites/{siteId}
「ホスティングにログイン」 POST   /v1/reseller/services/{siteId}/sso

プロビジョニングは2回の呼び出しで行われ、キーの指定が重要になります。

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

間違えるとコストが発生する2つのルール

1. アカウントには顧客 ID を、サイトにはサービス ID をキーとして設定してください。 顧客の2回目の注文は、既存のアカウントに紐付ける必要があります。両方にサービス ID をキーとして設定してしまうと、1人の顧客に無関係な3つのアカウントと3つの別個のパネルが作成される事態になります。
2. すべての POST に、対象物に対するお客様独自の ID から生成した Idempotency-Key を送信してください。 あらゆる請求システムで再試行が発生します (ゲートウェイのコールバックが2回届く、管理者が失敗したプロビジョニングを再実行する、顧客がダブルクリックするなど)。キーがない場合、2回目の試行で2つ目のサイトが作成され、その分の請求が発生してしまいます。

混同してはならない3つの応答

• unsuspend は 409 を返す場合があります。 これは、お客様ではなく弊社の不正対策チームがサイトを保留していることを意味します。メッセージを表示し、再試行は行わないでください。
• **契約解除 (終了) は削除をスケジュールするものであり、即座に削除を実行するわけではありません。** 日付は pending_deletion_at として返されます。まだデータが残っている段階で顧客にデータが消失したと伝えるのは、何も伝えないことよりも好ましくありません。
• disk_used_bytes は null になる場合があり、null はゼロではありません。 これは測定できなかったことを意味し、使用量がゼロだったわけではありません。スキップしてください。お客様独自の記録に 0 を書き込まないでください。さもないと、測定値が取得できていないサイトに対して顧客に正常を示す緑色の使用量バーを表示することになってしまいます。

4. クライアントのサインイン

POST /v1/reseller/services/{siteId}/sso は、クライアントがサインイン済みの状態で直接自身のアカウントにアクセスできる、1回限りの 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> でオープンソースとして公開されているほか、ダッシュボードの プラグイン からダウンロードできます。

6. 本番環境への移行

実際の注文を受け付ける前に、以下をご確認ください。

• モジュールの接続テストに合格していること、または最初の curl がリストを返すこと。
• 価格表が設定されていること (再販 → お客様の価格)。
• 決済ゲートウェイが接続されていること (再販 → 決済ゲートウェイ) — クライアントはお客様独自のアカウントを通じてお客様に支払います。
• 会社情報が入力されていること (再販 → お客様の会社) — クライアントの請求書に弊社のものではなく、お客様の法人情報と VAT 番号が記載されるようになります。
• 実際に最初から最後まで注文を1件通して行い、サイトが作成されることを確認していること。

その他の情報

弊社の仕様から生成された、各エンドポイントに必要な権限を含む完全な API リファレンスは、<https://zinndigital.com/developers/api> でご確認いただけます。