概要
このAPIは、Roktネットワーク上に構築する統合パートナー向けです。自社のチェックアウトに配置を統合するRoktのeコマースパートナーは、代わりにRokt Ecommerce開発者ドキュメントを使用してください。
Rokt Partnerships APIは、Roktネットワーク上で加盟店をオンボードし管理するためのパートナープラットフォーム向けのREST APIです。これを使用して、加盟店を登録し、マーケットプレイスのコントロールを設定し、配置ステータスを管理し、Rokt UIを使用せずに支払いオンボーディングを開始できます。
アクセスはRoktによって付与されます。 Partnerships APIはまだセルフサービスではありません。Roktはオンボーディング時にプラットフォームの長期間有効なAPI資格情報 (client_id + client_secret) を発行し、すべてのアクセストークン交換に同じ資格情報を再利用します。プラットフォーム名、予想される加盟店数、および割り当てられたマネージャーアカウントIDを記載して、smb-partnerships@rokt.comにメールしてください。完全なフローについては認証を参照してください。
カテゴリ分類は登録前にシードされます。 Roktはオンボーディング時にプラットフォームのカテゴリを自身のカテゴリにマッピングします。未マッピングのカテゴリは400で登録に失敗するため、完全なカテゴリリストを早めにsmb-partnerships@rokt.comに送信し、GET /v1/partnership/vertical-mappingsで行が着地したことを確認してください。マッピングされているものを確認するを参照してください。
このAPIは開発中です。ペイロード、エンドポイント、動作は変更される可能性があります。Roktは重大な変更があった場合に通知します。
主要な概念主要な概念 への直接リンク
プラットフォームはマネージャーアカウントとして表されます。オンボードする加盟店は管理アカウントです。RoktはAPIトークンとリクエストパス内のターゲット{account_id}を使用してすべてのリクエストを承認します: ターゲットアカウントはマネージャーアカウントによって管理されている必要があり、無関係なアカウントへのリクエストはサーバー側で拒否されます。
your platform (manager)
│
├── merchant A (managed account)
├── merchant B (managed account)
└── merchant C (managed account)
安全に統合するためには、これら4つの概念が必要です。コードを書く前にこれらを読んでください。
RoktがAPIトークンから呼び出し元のコンテキストを導出し、ターゲットaccount_idに対して承認する方法。
すべての書き込み呼び出しにはIdempotency-Keyが必要です。同じキーを2回送信するとキャッシュされた応答が返されるため、再試行しても安全です。
PUTは完全なリストを置き換えます。コントロールエンドポイント（MCL、ステータス）にはPATCHやマージはありません。毎回望ましい状態を完全に送信してください。レイアウト編集エンドポイントはV1の唯一のPATCHサーフェスであり、5つのテーマトークンのスパースアップデートを受け入れます。
dry_run=trueは完全な検証を実行し、状態を永続化せずに想定される応答を返します。ライブにする前にペイロードを検証するために使用してください。
何ができるか何ができるか への直接リンク
- マーチャントを登録する:
POST /v1/accounts/register/partnership。external_account_id（マーチャントの安定した識別子; 非機密に保つ; 冪等性で一意性の範囲を参照）に対して冪等です。 - 管理アカウントの一覧を表示する:
GET /v1/partnership/accounts?parent_account_id=<your-parent>。単一アカウントの詳細エンドポイントはまだ公開されていません; 以下のリソースごとの読み取りを使用して、個々の管理アカウントを検査します。 - シードされた垂直マッピングを確認する:
GET /v1/partnership/vertical-mappings?parent_account_id=<your-parent>は、独自の分類法でシードされたカテゴリーマッピングを返します。読み取り専用; Roktが行を作成します。リストが空の場合、何もシードされておらず、すべての登録が400で失敗します。マッピングされているものを確認するを参照してください。 - マーケットプレイスコントロールを読み取り・更新する:
GET/PUT /v1/partnership/accounts/{account_id}/marketplacecontrolslists。パートナーの分類法で垂直をブロックします; Roktはサーバー側で翻訳します。 - 配置を一時停止または再開する:
PUT /v1/partnership/accounts/{account_id}/statusは、すべての非アーカイブページバリアントに対してアクティブ/一時停止をカスケードします。 - マーチャントのテーマを編集する:
PATCH /v1/partnership/accounts/{account_id}/layouts/{layout_id}は、5つのテーマトークン（primaryColor,backgroundColor,textColor,borderRadius,closeButtonColor）のスパース更新を受け入れます。ページとレイアウトおよびレイアウトのカスタマイズワークフローを参照してください。 - ローンチ後にサーフェスを追加する:
POST /v1/partnership/accounts/{account_id}/pagesは、再登録せずに既にオンボードされたマーチャントに別のサーフェス（確認、追跡、返品）を添付します。ページとレイアウトを参照してください。 - ページのレイアウトタイプを切り替える:
PUT /v1/partnership/accounts/{account_id}/pages/{page_id}は、既存のページをpage_identifierやURLターゲティングを変更せずにオーバーレイと埋め込みの間で移動します。ページとレイアウトおよびレイアウトのカスタマイズワークフローを参照してください。 - 支払いオンボーディングを開始する:
POST /v1/partnership/accounts/{account_id}/payout-setupは、マーチャントのためのStripe Connectオンボーディングを開始します。V1では、Roktはパートナー側の支払い（パートナーシップ契約に基づくプラットフォームの収益分配）をマネージャーアカウントに支払い、個々の管理アカウントには支払いません; 各マーチャントの部分を分配するのはプラットフォームの責任です。マーチャントオンボーディングワークフローを参照してください。 - 消費者ネットワークのプライバシーリクエストを提出する:
POST /v1/partnership/network-privacy-requestsは、消費者識別子によるネットワークオプトアウトとネットワークデータ削除を処理します。プライバシーリクエストを参照してください。 - 管理アカウントデータ削除を提出する:
POST /v1/partnership/accounts/{account_id}/data-deletion-requestsは、プラットフォームが管理するマーチャントのアカウントレベル削除を要求します。プライバシーリクエストを参照してください。 - 長時間実行操作をポーリングする: すべての書き込みは
X-Operation-Idを返します。GET /v1/partnership/operations/{operation_id}は、ネットワークタイムアウトから回復し、書き込みを再発行せずに済みます。操作IDは不透明であり、認可されたマネージャーのみが読み取れるため、ポーリングは無関係なアカウントのステータスを公開することはできません。