垂直タクソノミーの翻訳

Audience

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

あなたのプラットフォームには独自の垂直タクソノミー（MCCコード、カテゴリID、内部スキーム）があり、Roktには約24の垂直と約152のサブ垂直の内部タクソノミーがあります。Partnerships APIは、あなたのタクソノミーを通信します。サーバーは、あなたのplatform_parent_account_idに基づく垂直マッピングテーブルを通じてRoktのIDに翻訳します。

翻訳が行われる場所: 登録とMCL PUT

垂直マッピングは、マーケットプレイスコントロールだけでなく、2つのパートナー向けの呼び出し形状で参照されます:

• POST /v1/accounts/register/partnership: リクエストボディのvertical_idとsub_vertical_idフィールドは、あなたのパートナーのタクソノミーの値であり、サーバー側でpartnership_vertical_mapに対して解決され、あなたのplatform_parent_account_idに基づきます。どちらかのIDにマッピング行がない場合、登録は400で失敗し、マーチャントが作成される前に終了します: This vertical isn't mapped yet (vertical_id=1500, sub_vertical_id=1610). Contact smb-partnerships@rokt.com to have it mapped.
• PUT /v1/partnership/accounts/{account_id}/marketplacecontrolslists: {partnerVerticalId, partnerSubVerticalId}ペアごとにblockedVerticalsが同じ方法で解決されます。次のセクションでatomic-400の動作を参照してください。

両方とも、あなたのpartnership_vertical_mapテーブルを共有し、あなたのplatform_parent_account_idにスコープされています。新しいパートナー側の垂直を一度オンボードすると、両方のサーフェスで即座に機能します。

注記

マッピング行は、管理者専用のPOST /v1/partnership/vertical-mappingsエンドポイントを通じてRoktがバンド外でシードします。パートナーAPIサーフェスでは行を作成することは公開されていません。ローンチ前に、smb-partnerships@rokt.comにあなたの全商人ネットワークで使用されているカテゴリとサブカテゴリIDと名前の完全なリストをメールで送信してください。すべての{sub_vertical_id, name}ペアであり、サンプルではありません（あなたのタクソノミーのCSVエクスポートが理想的です）。Rokt側のマッピングを提案することはありません。Roktのチームは、あなたの各カテゴリをあなたのplatform_parent_account_idに対してバンド外で独自のタクソノミーにマッピングし、マッピングがライブになったときに確認します。

結果を読み取ることはパートナーが呼び出すことができます。GET /v1/partnership/vertical-mappingsは、あなたの親アカウントにシードされたすべての行を返すので、シードが着地したことを確認できます。確認メールを信じる代わりに、Check what's mappedを参照してください。

マッピングされているものを確認する

GET /v1/partnership/vertical-mappingsは、あなたの親アカウントにシードされたすべてのマッピング行を、あなたのタクソノミーで返します。最初の登録呼び出しの前に、またあなたの側でカテゴリを追加するたびに呼び出してください。

curl "https://accounts.rokt.com/v1/partnership/vertical-mappings?parent_account_id=$PARENT" \
  -H "Authorization: Bearer $ROKT_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"
      },
      {
        "partner_vertical_id": 1500,
        "partner_vertical_name": "Apparel",
        "partner_sub_vertical_id": 1611,
        "partner_sub_vertical_name": "Menswear",
        "vertical_name": "Retail",
        "created_at": "2026-07-01T00:00:00Z"
      }
    ]
  }
}

このリストの任意のペアは、登録とマーケットプレイスコントロールPUTで送信しても安全です。欠如しているものは両方で400を返します。

• 行はpartner_vertical_id、次にpartner_sub_vertical_idで順序付けられています。
• ページネーションはありません。全セットが一度に返されます。
• vertical_nameは唯一のRokt側のフィールドです。表示のみで、入力として受け付けるエンドポイントはありません。
• 認証は、parent_account_idの同じ付与としてGET /v1/partnership/accountsです。他のプラットフォームのマッピングを読むことはできません。

空の配列はシードされていないことを意味します

{ "data": { "vertical_mappings": [] } }

何もマッピングされていないため、すべての登録呼び出しは400で失敗します。新しい統合が何も登録できない場合は、まずこれを確認してください。

smb-partnerships@rokt.comに完全なカテゴリリストをメールで送り、確認を待ってください。それを通過するために、商人が属していないカテゴリを代用しないでください。

転送翻訳（PUT時）

PUT /…/marketplacecontrolslistsを送信するとき:

{
  "blockedVerticals": [
    { "partnerVerticalId": 1500, "partnerSubVerticalId": 1610, "policy": "Block" }
  ]
}

各{partnerVerticalId, partnerSubVerticalId}ペアについて、サーバーはplatform_parent_account_idにスコープされた垂直マッピングの行を検索し、それをRoktのvertical_idに解決します。このマッピングは多対一です。複数のパートナーペアが同じRoktの垂直に正当に解決されることがあり、それは問題ありません。あなたの分類法はRoktのものよりも細かいか粗いかのいずれかであり、両側を保存することで忠実性を保ちます。

your taxonomy                       vertical mapping                                    rokt taxonomy
{ 1500, 1610 }    ─────translate────▶  parent_account_id=<your-platform-parent-account-id>  ───▶  → Rokt internal mapping (not returned to partners)
{ 1500, 1611 }    ─────translate────▶  parent_account_id=<your-platform-parent-account-id>  ───▶  → Rokt internal mapping (not returned to partners)
{ 1502, 1620 }    ─────translate────▶  parent_account_id=<your-platform-parent-account-id>  ───▶  → Rokt internal mapping (not returned to partners)

マッピングがない場合 = アトミック400

blockedVerticals配列のいずれかのペアに垂直マッピングに対応する行がない場合、全リクエストが拒否され、400が返されます。部分的な書き込みはありません。リクエストはアトミックです。

{
  "status": 400,
  "error": "BadRequest",
  "message": "No vertical mapping found for the following partner vertical(s): (partner_vertical_id=1500, partner_sub_vertical_id=1610). Call GET /v1/partnership/vertical-mappings to see which verticals are currently mapped, and contact smb-partnerships@rokt.com to request additions. The MCL write was rejected atomically; no partial update was applied.",
  "request_id": "req_01HX9F2J7M3K8N5VYBQZP4R6T2",
  "data": null
}

メッセージは、最初のペアだけでなく、マッピングされていないすべてのペアを名前で示します。これにより、配列を二分するのではなく、一度のパスでマッピングされたものと比較できます。

警告

ローンチ前に完全な分類法を送信してください。 smb-partnerships@rokt.comに、マーチャントネットワークのどこかで使用されるカテゴリ/サブカテゴリIDと名前の完全なリストをメールで送信してください: すべての{sub_vertical_id, name}ペアを、ローンチ予定のものだけでなく。なぜ完全である必要があるのか: マッピングされていないIDの下で登録されたマーチャントは、垂直マッピング400で登録に失敗し、マッピングされていないカテゴリのマーチャントは、ネットワークに設定されたブランド安全性のコントロールの外に出てしまいます。RoktはRokt側のマッピングを内部で処理し、行がライブになったときに確認します。行の追加はバンド外で行われます。APIには自己サービスの作成ルートはありませんが、現在の状態をいつでも確認できます。マッピングされたものを確認を参照してください。

dry_run=trueを使用して、コミットせずに安全に400を表示できます。これは、実際の保存の前にマーチャントのカテゴリ選択を検証するためにオンボーディングUIで役立ちます。

逆翻訳（GET時）

マーケットプレイスコントロールをGETすると、レスポンスはRoktのIDではなく、あなたの分類法のIDで表現されます。translated_verticalsは、各マッピングされたサブバーティカルの有効なポリシーを、あなたのサブバーティカルID（vertical_id）でキー化して持ちます:

{
  "account_id": "<your-account-id>",
  "marketplace_controls_list": {
    "marketplace_controls_list_id": "8c8e1c12-...",
    "domains": [],
    "content_hash": "h_abc123"
  },
  "translated_verticals": [
    {
      "vertical_id": 1610,
      "policy": "Block",
      "position_1_policy": "Block"
    },
    {
      "vertical_id": 1611,
      "policy": "Allow",
      "position_1_policy": "Allow"
    }
  ]
}

UIでtranslated_verticalsを使用してください。エンドユーザーは彼らの分類法で考えます。vertical_idはあなたのサブバーティカルIDです（PUTで送信したpartnerSubVerticalId）。Roktの内部IDはレスポンスに表示されません。

ヒント

translated_verticalsは、あなたの分類法のマッピング行ごとに1つのエントリを返し、その有効なポリシーを含みます。PUTで送信しなかったサブバーティカルも現在の有効な状態として表示されます。多くのサブバーティカルが同じRoktの垂直にマッピングされている場合でも、サブバーティカルごとに1つのエントリが表示されます。ラウンドトリップ全体で情報の損失はありません。

ウォークスルー: フルラウンドトリップ

1. 1
   PUT with a partner-taxonomy pair

   curl -X PUT https://accounts.rokt.com/v1/partnership/accounts/<your-account-id>/marketplacecontrolslists \
     -H "Authorization: Bearer $ROKT_TOKEN" \
     -H "Idempotency-Key: $(uuidgen)" \
     -H "Content-Type: application/json" \
     -d '{
       "name": "Acme Network Controls",
       "blockedVerticals": [
         {"partnerVerticalId": 1500, "partnerSubVerticalId": 1610, "policy": "Block", "position1Policy": "Block"}
       ],
       "domains": []
     }'

   サーバーは{1500, 1610} → rokt_vertical_id: 42を解決し、両方を永続化し、200を返します。

2. 2
   GET the controls back

   curl https://accounts.rokt.com/v1/partnership/accounts/<your-account-id>/marketplacecontrolslists \
     -H "Authorization: Bearer $ROKT_TOKEN"

3. 3
   Observe the translation round-trip

   レスポンスには以下が含まれます:

   • translated_verticals[].vertical_id = 1610（あなたのサブバーティカルID、送信したpartnerSubVerticalId）
   • translated_verticals[].policy = "Block" と position_1_policy = "Block"（サーバーが永続化した有効な状態）

   Roktの内部垂直IDはサーバー側に留まります。ダッシュボードにtranslated_verticalsを表示してください。マーチャントは理解できるカテゴリを見ます。

ローンチ前のチェックリスト

• smb-partnerships@rokt.com に完全なカテゴリー/サブカテゴリーリスト（マーチャントネットワークのどこかで使用されているすべての {sub_vertical_id, name} ペア）を送信し、Roktがマッピングがライブであることを確認しました。
• 親アカウントに対して GET /v1/partnership/vertical-mappings を呼び出し、返されたセットがマーチャントを登録するすべてのカテゴリーをカバーしていることを確認しました。空でないレスポンスがシーディングが成功した唯一の実際の確認です。マッピングされているものを確認を参照してください。
• オンボーディングUIはマッピングされたパートナーバーティカルのみを表示するか、マーチャントが保存する前に dry_run=true を使用して検証します。
• ダッシュボードは translated_verticals からレンダリングされます。
• パートナー側のタクソノミーを所有し、変更があった際には更新された完全なリストをsmb-partnershipsにメールで送信する内部の担当者がいます。

関連

SET Semantics

なぜすべてのPUTで完全な blockedVerticals 配列を送信する必要があるのか。

Dry-Run Mode

ステートに触れずにマッピング不足の400を表示します。