クイックスタート

対象

このAPIは、Roktネットワーク上で構築する統合パートナー向けです。自社のチェックアウトにプレースメントを統合するRoktのeコマースパートナーは、代わりにRokt Ecommerce開発者ドキュメントを使用してください。

このウォークスルーでは、dry_run=trueを使用して、何も永続化されない状態で、登録済みのマーチャントと検証済みのコントロール、アクティブなパートナーシップを持つ状態に到達します。本番環境に移行する準備ができたら、ドライランフラグを外してください。

APIトークンとターミナルが必要です。

始める前に始める前にへの直接リンク

以下のコールを実行する前に、以下のものを集めてください。それぞれは、後続のステップで名前で参照されます。

APIクレデンシャル (client_id + client_secret): Roktによるオンボーディング時に一度発行され、その後、以下のコールで使用される短命のアクセストークンと交換するたびに再利用されます。まだ持っていない場合は、認証を参照してください。
パートナープラットフォームのRokt親アカウントID: Roktの階層内でのプラットフォームのトップレベルアカウントです。Roktのオンボーディング担当者が提供します。
シードされた垂直マッピング: あなたのカテゴリをRoktの分類にマッピングします。プラットフォームごとに一度だけ、何かを登録する前に行います。完全なカテゴリリストをsmb-partnerships@rokt.comにメールで送信し、ステップ2で到達したことを確認してください。これをスキップすることは、新しい統合が何も登録できない最も一般的な理由です。マッピングされたものを確認するを参照してください。
マーチャントのためのvertical_id + sub_vertical_id: あなた自身の分類のカテゴリIDであり、Roktのものではありません。サーバーは、親アカウントのためにシードされた垂直マッピングを通じてそれらを変換します。垂直分類を参照してください。
スキーム付きのストアURL: 例: https://acme.myshopify.com。ホストのみ (acme.myshopify.com) は400で拒否されます。
安定したexternal_account_id: このマーチャントのためのプラットフォーム独自の識別子です。登録はこの値で冪等であるため、再試行時にも安定している必要があります。
uuidgen (または任意のUUIDジェネレーター): 書き込み時に新しいIdempotency-Key値を生成するため。

注記

すべてのコールが従う2つの契約。

すべてのレスポンスは{ "status", "error", "message", "request_id", "data": { ... } }でラップされます。 エンドポイント固有のペイロードはdata内にあります。以下の例では、完全なエンベロープを示しています。
すべての書き込みにはX-Platform-Parent-Account-Idが必要です。 パートナープラットフォームのRokt親アカウントIDに設定してください。これがないと、書き込み時に422が返されます。読み取りではオプションですが、推奨されます。

両方をエクスポートします:

# Replace with YOUR partner platform's Rokt parent account ID (obtained from your Rokt onboarding contact).
export PARENT="<your-platform-parent-account-id>"

1
Get your API token
Roktから付与されたAPIクレデンシャルをアクセストークンと交換します。認証を参照してください。このガイドの残りの部分では、それをエクスポートします:
- bash
export TOKEN="eyJhbGc..."
2
Confirm your taxonomy is mapped
GET /v1/partnership/vertical-mappingsは、親アカウントのためにRoktがシードしたカテゴリマッピングを返します。最初の登録コールの前に一度実行してください。登録は、送信するvertical_idとsub_vertical_idをこのマッピングを通じて解決するため、シードされていない親アカウントはすべての登録試行で400で失敗します。
- curl
curl "https://accounts.rokt.com/v1/partnership/vertical-mappings?parent_account_id=$PARENT" \ -H "Authorization: Bearer $TOKEN"
レスポンス:
{ "status": 200, "error": null, "message": "ok", "request_id": "0e3a1b9c-...", "data": { "vertical_mappings": [ { "partner_vertical_id": 1500, "partner_vertical_name": "Apparel", "partner_sub_vertical_id": 1610, "partner_sub_vertical_name": "Womenswear", "vertical_name": "Retail", "created_at": "2026-07-01T00:00:00Z" } ] } }
次のステップで送信するvertical_idとsub_vertical_idは、ここでpartner_vertical_id / partner_sub_vertical_idペアとして表示される必要があります。vertical_nameは、ペアが解決するRoktカテゴリを示し、予期しない場所にマッピングされたものを見つけるのに役立ちます。
警告
空の vertical_mappings 配列は、あなたの分類がシードされていないことを意味します。 ここで停止してください。Roktがシードするまで、すべての登録呼び出しは 400 を返します。完全なカテゴリリストを smb-partnerships@rokt.com にメールで送信し、確認を待ってください。マッピングされているものを確認するを参照してください。
3
Register a merchant
POST /v1/accounts/register/partnership は、あなたのプラットフォームを通じてオンボードされたマーチャントのためにRoktアカウントを作成（または一致）します。この呼び出しは、あなたのシステム内でのマーチャントの安定した識別子である external_account_id に対して冪等です。
store_identifier はスキームを含む有効なURL（3–400文字）でなければなりません。https://acme.myshopify.com は機能しますが、acme.myshopify.com は400を返します。
レスポンスから data.account_id を取得してください。これを今後のすべての呼び出しで使用します。もし pages も渡した場合、各エントリの page_identifier を取得してください。その文字列をWeb SDKの selectPlacements 呼び出しに渡して各サーフェスをターゲットにします。ページとレイアウトを参照してください。
注記
register は唯一、Idempotency-Key ヘッダーを必要としない書き込みです。それは代わりに external_account_id に対して冪等です。すべての後続の書き込み（コントロール、ステータス、支払い設定など）は Idempotency-Key を必要とします。
- curl
# pages[].surface: confirmation | tracking | returns # pages[].layout_type: Overlay | Embedded # Every integration ships a default; omit `pages` to use it, or pass an array to override. See pages-and-layouts. curl -X POST https://accounts.rokt.com/v1/accounts/register/partnership \ -H "Authorization: Bearer $TOKEN" \ -H "X-Platform-Parent-Account-Id: $PARENT" \ -H "Content-Type: application/json" \ -d '{ "brand": "Acme Apparel", "vertical_id": 1500, "sub_vertical_id": 1610, "country_code": "US", "platform_parent_account_id": "<your-platform-parent-account-id>", "store_identifier": "https://acme-apparel.example.com", "external_account_id": "partner-merchant-abc123", "pages": [ { "surface": "confirmation", "layout_type": "Overlay" }, { "surface": "tracking", "layout_type": "Embedded" }, { "surface": "returns", "layout_type": "Embedded" } ] }'
レスポンス:
{ "status": 200, "error": null, "message": "ok", "request_id": "0e3a1b9c-1234-4abc-9def-aaaabbbbcccc", "data": { "account_id": "<your-account-id>", "pages": [ { "surface": "confirmation", "page_id": "bfb5b9be-...", "layout_id": "9d11d8aa-...", "page_identifier": "confirmation_page" }, { "surface": "tracking", "page_id": "2b9d8a5e-...", "layout_id": "f8700369-...", "page_identifier": "tracking_page" }, { "surface": "returns", "page_id": "7a31963a-...", "layout_id": "4865f1ab-...", "page_identifier": "returns_page" } ] } }
ヒント
エクスポートする: export ACCOUNT_ID="<your-account-id>".
認証伝播の競合
新しく作成されたマーチャントアカウントのトークン認証は非同期で伝播します。 新しい account_id に対するコントロール、ステータス、または支払い設定エンドポイントへの即時呼び出しは、最大1〜2分間 401 または 403 を返すことがあります。新しいアカウントでの最初の認証失敗を致命的と見なさないでください。調査する前に15〜30秒ごとに最大2分間再試行してください。
4
Read current marketplace controls
GET /v1/partnership/accounts/{account_id}/marketplacecontrolslists は、マーチャントの現在のマーケットプレイスコントロール設定を返します。新しいアカウントでは、これはあなたのパートナーシッププリセットから継承されたデフォルトの垂直ブロックリストを反映します。
- curl
curl https://accounts.rokt.com/v1/partnership/accounts/$ACCOUNT_ID/marketplacecontrolslists \ -H "Authorization: Bearer $TOKEN" \ -H "X-Platform-Parent-Account-Id: $PARENT"
data.translated_verticals と data.marketplace_controls_list.content_hash を確認してください。translated_verticals は、パートナーの分類で表現されたサブバーティカルごとの効果的なポリシーを示します（vertical_id はあなたのサブバーティカルIDです）、UIに戻すために便利です。生のRokt分類IDはレスポンスに公開されません。
5
Update marketplace controls (dry-run)
PUT は 望ましい状態 です: 毎回完全なリストを送信し、省略したものは解除されます。SETセマンティクスを参照してください。
- X-Platform-Parent-Account-Id はすべての書き込みに必須です。これがないと422を返します。
- Idempotency-Key はすべての書き込みに必須です。論理的な再試行グループごとに新しいUUIDを生成してください。24時間の重複排除ウィンドウは、同じキーを持つ再試行を単一の実行にまとめます。
- dry_run=true は状態を永続化せずに完全な検証を実行し、ペイロードの検証に最適です。レスポンスエンベロープは dry_run: true を data と共に追加します。
- curl
curl -X PUT "https://accounts.rokt.com/v1/partnership/accounts/$ACCOUNT_ID/marketplacecontrolslists?dry_run=true" \ -H "Authorization: Bearer $TOKEN" \ -H "X-Platform-Parent-Account-Id: $PARENT" \ -H "Content-Type: application/json" \ -H "Idempotency-Key: $(uuidgen)" \ -d '{ "name": "Acme Network Controls", "blockedVerticals": [ { "partnerVerticalId": 1500, "partnerSubVerticalId": 1610, "policy": "Block", "position1Policy": "Block" }, { "partnerVerticalId": 1500, "partnerSubVerticalId": 1611, "policy": "Block", "position1Policy": "Block" } ], "domains": [ { "domain": "competitor.example.com", "policy": "Block" } ], "contentHash": null }'
注記
contentHashは楽観的同時実行トークンです。新しいアカウントへの最初の書き込み時にはnullを渡し、以降の書き込み時には、前のGETまたはPUTレスポンスで返されたcontent_hashの値をエコーバックして、同時変更の上書きを防ぎます。
レスポンスペイロード（data内）は、GETと一致します：同じtranslated_verticalsとmarketplace_controls_list（domainsと新しいcontent_hashを含む）。ドライランでは、レスポンスは何が書き込まれるかを説明します。

Activate the partnership (dry-run)

PUT /v1/partnership/accounts/{account_id}/statusは、アカウント上のすべての非アーカイブページバリアントに対してアクティブ/一時停止をカスケードします。

curl

curl -X PUT "https://accounts.rokt.com/v1/partnership/accounts/$ACCOUNT_ID/status?dry_run=true" \
  -H "Authorization: Bearer $TOKEN" \
  -H "X-Platform-Parent-Account-Id: $PARENT" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{ "status": "active" }'

レスポンスdata.variants[]は、バリアントごとの内訳をリストします：

{
  "status": 200,
  "error": null,
  "message": "ok",
  "request_id": "0e3a1b9c-...",
  "data": {
    "account_id": "<your-account-id>",
    "status": "active",
    "variants": [
      { "page_id": "9d11...", "name": "Thanks", "status": "active" }
    ]
  }
}

7
Verify status
GET /v1/partnership/accounts/{account_id}/statusは、集約ステータスとバリアントごとの詳細を返します。
- curl
curl https://accounts.rokt.com/v1/partnership/accounts/$ACCOUNT_ID/status \ -H "Authorization: Bearer $TOKEN" \ -H "X-Platform-Parent-Account-Id: $PARENT"
本番環境では（dry_run=trueを削除）、data.statusは、直前にPUTした内容と一致するはずです。PUT status=activeの後に"mixed"が表示された場合、一部のバリアントが更新に失敗したことを意味します。request_idをキャプチャしてサポートチケットを提出してください。
集約ルール：
- "active": すべての非アーカイブバリアントが有効です。
- "paused": すべての非アーカイブバリアントが無効（または存在しない）。
- "mixed": 一部が有効、一部が無効。