Aller au contenu principal

Traduction de Taxonomie Verticale

Audience

Cette surface API est destinée aux partenaires d'intégration construisant sur le réseau Rokt. Les partenaires de commerce électronique de Rokt intégrant des placements sur leur propre page de paiement devraient utiliser à la place les docs développeur Rokt Ecommerce.

Votre plateforme possède sa propre taxonomie verticale (codes MCC, identifiants de catégorie, votre schéma interne), et Rokt a sa propre taxonomie interne d'environ 24 verticales et 152 sous-verticales. L'API Partnerships parle votre taxonomie sur le fil. Le serveur traduit vers les identifiants de Rokt via une table de mappage vertical indexée par votre platform_parent_account_id.

Où la traduction a lieu : enregistrement et MCL PUTsLien direct vers Où la traduction a lieu : enregistrement et MCL PUTs

Le mappage vertical est consulté sur deux formes d'appel orientées partenaire, pas seulement les contrôles de marché :

  • POST /v1/accounts/register/partnership : les champs vertical_id et sub_vertical_id dans le corps de la requête sont des valeurs de votre taxonomie partenaire, résolues côté serveur contre partnership_vertical_map pour votre platform_parent_account_id. Si l'un des identifiants n'a pas de ligne de mappage, l'enregistrement échoue avec 400 avant que le marchand ne soit créé : 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 : chaque paire {partnerVerticalId, partnerSubVerticalId} dans blockedVerticals est résolue de la même manière. Voir la section suivante pour le comportement atomic-400.

Les deux partagent la même table partnership_vertical_map, limitée à votre platform_parent_account_id. Intégrez une nouvelle verticale côté partenaire une fois et elle fonctionne immédiatement sur les deux surfaces.

remarque

Les lignes de mappage sont semées par Rokt hors bande via un point de terminaison POST /v1/partnership/vertical-mappings réservé aux administrateurs ; la création de lignes n'est pas exposée sur la surface API partenaire. Avant le lancement, envoyez par email à smb-partnerships@rokt.com la liste complète des identifiants et noms de catégories et sous-catégories utilisés dans l'ensemble de votre réseau de marchands : chaque paire {sub_vertical_id, name}, pas un échantillon (une exportation CSV de votre taxonomie est idéale). Vous ne proposez pas de mappages côté Rokt : l'équipe de Rokt mappe chacune de vos catégories à sa propre taxonomie hors bande contre votre platform_parent_account_id et confirme lorsque les mappages sont actifs.

Lire le résultat en retour est appelable par le partenaire. GET /v1/partnership/vertical-mappings renvoie chaque ligne semée pour votre compte parent, afin que vous puissiez vérifier que le semis a eu lieu au lieu de vous fier à l'email de confirmation. Voir Vérifiez ce qui est mappé.

Vérifiez ce qui est mappéLien direct vers Vérifiez ce qui est mappé

GET /v1/partnership/vertical-mappings renvoie chaque ligne de mappage semée pour votre compte parent, dans votre taxonomie. Appelez-le avant votre premier appel d'enregistrement, et à nouveau chaque fois que vous ajoutez des catégories de votre côté.

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"
      }
    ]
  }
}

Chaque paire de cette liste est sûre à envoyer lors de l'enregistrement et sur le PUT des contrôles de marché. Tout ce qui est absent renvoie un 400 sur les deux.

  • Les lignes sont ordonnées par partner_vertical_id, puis partner_sub_vertical_id.
  • Pas de pagination. L'ensemble complet revient d'un coup.
  • vertical_name est le seul champ côté Rokt. Affichage uniquement ; aucun point de terminaison ne le prend en entrée.
  • L'authentification est le même parent_account_id grant que GET /v1/partnership/accounts. Vous ne pouvez pas lire les mappages d'une autre plateforme.
Un tableau vide signifie que vous n'êtes pas semé
{ "data": { "vertical_mappings": [] } }

Rien n'est mappé, donc chaque appel d'enregistrement échoue avec un 400. Vérifiez cela en premier lorsqu'une nouvelle intégration ne peut rien enregistrer.

Envoyez par email à smb-partnerships@rokt.com votre liste complète de catégories et attendez la confirmation. Ne substituez pas une catégorie dans laquelle le marchand n'est pas pour passer outre.

Traduction directe (sur PUT)Lien direct vers Traduction directe (sur PUT)

Lorsque vous envoyez un PUT /…/marketplacecontrolslists:

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

Pour chaque paire {partnerVerticalId, partnerSubVerticalId}, le serveur recherche la ligne dans le mappage vertical limité à votre platform_parent_account_id et la résout en un vertical_id de Rokt. Le mappage est plusieurs-à-un : plusieurs paires partenaires peuvent légitimement se résoudre à la même verticale de Rokt, et c'est bien. Votre taxonomie est plus fine ou plus grossière que celle de Rokt, et nous préservons la fidélité en stockant les deux côtés.

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)

Mapping manquant = atomique 400Lien direct vers Mapping manquant = atomique 400

Si n'importe quelle paire dans votre tableau blockedVerticals n'a pas de ligne correspondante dans le mapping vertical, toute la requête est rejetée avec 400. Il n'y a pas d'écritures partielles ; la requête est atomique.

{
  "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
}

Le message nomme chaque paire non mappée, pas seulement la première, afin que vous puissiez comparer l'ensemble avec ce qui est mappé en une seule passe au lieu de découper votre tableau.

attention

Envoyez votre taxonomie complète avant le lancement, pas après. Envoyez par email à smb-partnerships@rokt.com la liste exhaustive des IDs et noms de catégories/sous-catégories utilisés n'importe où dans votre réseau de marchands : chaque paire {sub_vertical_id, name}, pas seulement celles avec lesquelles vous prévoyez de lancer. Pourquoi exhaustive : tout marchand enregistré sous un ID qui n'était pas mappé échoue à l'enregistrement avec un 400 de mapping vertical, et les marchands sur des catégories non mappées seraient en dehors des contrôles de sécurité de marque configurés pour votre réseau. Rokt gère le mapping côté Rokt en interne et confirme lorsque les lignes sont actives. L'ajout de lignes reste hors bande ; il n'y a pas de route création en libre-service dans l'API, bien que vous puissiez lire l'état actuel à tout moment. Voir Vérifier ce qui est mappé.

Vous pouvez afficher un 400 en toute sécurité sans vous engager en utilisant dry_run=true. Cela est utile dans votre interface d'intégration pour valider la sélection de catégorie d'un marchand avant la sauvegarde réelle.

Traduction inverse (sur GET)Lien direct vers Traduction inverse (sur GET)

Lorsque vous effectuez un GET sur les contrôles du marché, la réponse est exprimée dans les IDs de votre taxonomie, pas ceux de Rokt. translated_verticals porte la politique effective de chaque sous-vertical mappé, indexée par votre ID de sous-vertical (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"
    }
  ]
}

Utilisez translated_verticals dans votre interface utilisateur ; vos utilisateurs finaux pensent en leur taxonomie. vertical_id est votre ID de sous-vertical (le partnerSubVerticalId que vous envoyez sur PUT) ; les IDs internes de Rokt n'apparaissent jamais dans la réponse.

astuce

translated_verticals retourne une entrée par ligne de mapping dans votre taxonomie avec sa politique effective, y compris les sous-verticales que vous n'avez pas envoyées sur le PUT (elles apparaissent dans leur état effectif actuel). Si beaucoup de vos sous-verticales se mappent au même vertical Rokt, vous voyez toujours une entrée par sous-verticale ; il n'y a pas de perte d'information à travers le cycle complet.

Guide : cycle completLien direct vers Guide : cycle complet

  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": []
      }'

    Le serveur résout {1500, 1610} → rokt_vertical_id: 42, persiste les deux, retourne 200.

  2. GET the controls back
    curl https://accounts.rokt.com/v1/partnership/accounts/<your-account-id>/marketplacecontrolslists \
      -H "Authorization: Bearer $ROKT_TOKEN"
  3. Observe the translation round-trip

    La réponse contient :

    • translated_verticals[].vertical_id = 1610 (votre ID de sous-vertical, le partnerSubVerticalId que vous avez envoyé)
    • translated_verticals[].policy = "Block" et position_1_policy = "Block" (l'état effectif que le serveur a persisté)

    Les IDs verticaux internes de Rokt restent côté serveur. Affichez translated_verticals dans votre tableau de bord ; le marchand voit les catégories qu'il comprend.

Liste de vérification avant le lancementLien direct vers Liste de vérification avant le lancement

  • Vous avez envoyé à smb-partnerships@rokt.com votre liste complète de catégories/sous-catégories (chaque paire {sub_vertical_id, name} utilisée n'importe où dans votre réseau de marchands), et Rokt a confirmé que les mappings sont actifs.
  • Vous avez appelé GET /v1/partnership/vertical-mappings contre votre compte parent et l'ensemble retourné couvre chaque catégorie sous laquelle vous enregistrerez des marchands. Une réponse non vide est la seule véritable confirmation que le semis a abouti. Voir Vérifier ce qui est mappé.
  • Votre interface d'intégration n'affiche que les verticaux partenaires mappés (ou utilise dry_run=true pour valider avant de permettre au marchand de sauvegarder).
  • Votre tableau de bord s'affiche à partir de translated_verticals.
  • Vous avez un propriétaire interne qui possède la taxonomie côté partenaire et envoie par email à smb-partnerships la liste complète mise à jour lorsqu'elle change.
SET Semantics

Pourquoi vous devez envoyer le tableau complet blockedVerticals à chaque PUT.

Dry-Run Mode

Afficher les erreurs 400 de mappage manquant sans toucher à l'état.

Cet article vous a-t-il été utile ?
Last updated Aug 4, 2026