Aller au contenu principal

Démarrage rapide

Audience

Cette interface API est destinée aux partenaires d'intégration construisant sur le réseau Rokt. Les partenaires e-commerce de Rokt intégrant des emplacements sur leur propre page de paiement devraient utiliser plutôt la documentation développeur Rokt Ecommerce.

Ce guide vous emmène de zéro à un marchand enregistré avec des contrôles vérifiés et un partenariat actif, en utilisant dry_run=true afin que rien ne persiste. Supprimez le drapeau de simulation lorsque vous êtes prêt à passer en production.

Vous aurez besoin d'un jeton API et d'un terminal.

Avant de commencerLien direct vers Avant de commencer

Rassemblez les éléments suivants avant d'exécuter les appels ci-dessous. Chacun sera référencé par son nom dans les étapes qui suivent.

  • Identifiants API (client_id + client_secret) : délivrés une fois par Rokt lors de l'intégration, puis réutilisés chaque fois que vous les échangez contre le jeton d'accès à courte durée utilisé dans les appels ci-dessous. Voir Authentification si vous ne les avez pas encore.
  • ID de compte parent Rokt de la plateforme partenaire : le compte de niveau supérieur de votre plateforme dans la hiérarchie de Rokt. Votre contact d'intégration Rokt vous le fournit.
  • Un mappage vertical initialisé : Rokt mappe vos catégories à sa propre taxonomie avant que vous puissiez enregistrer quoi que ce soit, une fois par plateforme. Envoyez par email votre liste complète de catégories à smb-partnerships@rokt.com, puis vérifiez qu'elle est arrivée à l'étape 2. Ignorer cela est la raison la plus courante pour laquelle une nouvelle intégration ne peut rien enregistrer. Voir Vérifier ce qui est mappé.
  • vertical_id + sub_vertical_id pour le marchand : les IDs de catégorie de votre propre taxonomie, pas ceux de Rokt. Le serveur les traduit via le mappage vertical initialisé pour votre compte parent. Voir Taxonomie verticale.
  • URL de la boutique avec schéma : par exemple https://acme.myshopify.com. Les hôtes nus (acme.myshopify.com) sont rejetés avec un 400.
  • Un external_account_id stable : l'identifiant propre de votre plateforme pour ce marchand. L'enregistrement est idempotent sur cette valeur, elle doit donc être stable lors des réessais.
  • uuidgen (ou tout générateur UUID) : pour produire de nouvelles valeurs Idempotency-Key lors des écritures.
remarque

Deux contrats que chaque appel suit.

  1. Chaque réponse est enveloppée dans { "status", "error", "message", "request_id", "data": { ... } }. Les charges utiles spécifiques aux points de terminaison se trouvent à l'intérieur de data. Les exemples ci-dessous montrent l'enveloppe complète.
  2. Chaque écriture nécessite X-Platform-Parent-Account-Id défini sur l'ID de compte parent Rokt de votre plateforme partenaire. Son absence renvoie 422 lors des écritures. Les lectures l'acceptent comme optionnel mais recommandé.

Exportez les deux :

# 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

    Échangez vos identifiants API accordés par Rokt contre un jeton d'accès ; voir Authentification. Pour le reste de ce guide, exportez-le :

    export TOKEN="eyJhbGc..."
  2. Confirm your taxonomy is mapped

    GET /v1/partnership/vertical-mappings renvoie les mappages de catégories que Rokt a initialisés pour votre compte parent. Exécutez-le une fois avant votre premier appel d'enregistrement. L'enregistrement résout les vertical_id et sub_vertical_id que vous envoyez via ce mappage, donc un compte parent non initialisé échoue à chaque tentative d'enregistrement avec un 400.

    curl "https://accounts.rokt.com/v1/partnership/vertical-mappings?parent_account_id=$PARENT" \
      -H "Authorization: Bearer $TOKEN"

    Réponse :

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

    Les vertical_id et sub_vertical_id que vous envoyez à l'étape suivante doivent apparaître ici en tant que paire partner_vertical_id / partner_sub_vertical_id. vertical_name montre à quelle catégorie Rokt la paire se résout, utile pour repérer un mappage qui a abouti à un endroit inattendu.

    attention

    Un tableau vertical_mappings vide signifie que votre taxonomie n'est pas initialisée. Arrêtez ici ; chaque appel d'enregistrement renvoie un 400 jusqu'à ce que Rokt l'initialise. Envoyez votre liste complète de catégories à smb-partnerships@rokt.com et attendez la confirmation. Voir Vérifiez ce qui est mappé.

  3. Register a merchant

    POST /v1/accounts/register/partnership crée (ou correspond à) un compte Rokt pour un marchand intégré via votre plateforme. L'appel est idempotent sur external_account_id : votre identifiant stable pour le marchand dans votre propre système.

    store_identifier doit être une URL valide (3–400 caractères) incluant le schéma. https://acme.myshopify.com fonctionne ; acme.myshopify.com renvoie 400.

    Capturez data.account_id de la réponse. Vous l'utiliserez dans chaque appel ultérieur. Si vous avez également passé pages, capturez page_identifier de chaque entrée ; vous passerez cette chaîne dans l'appel selectPlacements du SDK Web pour cibler chaque surface. Voir Pages et Dispositions.

    remarque

    register est la seule écriture qui ne nécessite pas d'en-tête Idempotency-Key ; elle est idempotente sur external_account_id à la place. Toutes les écritures ultérieures (contrôles, statut, configuration de paiement, etc.) nécessitent Idempotency-Key.

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

    Réponse :

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

    Exportez-le : export ACCOUNT_ID="<your-account-id>".

    Course à la propagation de l'authentification

    L'authentification par jeton pour les comptes marchands nouvellement créés se propage de manière asynchrone. Les appels immédiats aux points de terminaison de contrôles, de statut ou de configuration de paiement sur le nouveau account_id peuvent renvoyer 401 ou 403 pendant 1 à 2 minutes. Ne considérez pas le premier échec d'authentification sur un compte frais comme définitif ; réessayez toutes les 15 à 30 secondes pendant jusqu'à deux minutes avant d'enquêter.

  4. Read current marketplace controls

    GET /v1/partnership/accounts/{account_id}/marketplacecontrolslists renvoie la configuration actuelle de contrôle du marché du marchand. Sur un compte frais, cela reflète la liste de blocage verticale par défaut héritée de votre préréglage de partenariat.

    curl https://accounts.rokt.com/v1/partnership/accounts/$ACCOUNT_ID/marketplacecontrolslists \
      -H "Authorization: Bearer $TOKEN" \
      -H "X-Platform-Parent-Account-Id: $PARENT"

    Regardez data.translated_verticals et data.marketplace_controls_list.content_hash. translated_verticals montre la politique effective par sous-verticale exprimée dans votre taxonomie de partenaire (vertical_id est votre ID de sous-verticale), utile pour le retour à votre interface utilisateur. Les ID de taxonomie brute de Rokt ne sont pas exposés dans la réponse.

  5. Update marketplace controls (dry-run)

    PUT est état souhaité : envoyez la liste complète à chaque fois, tout ce que vous omettez devient débloqué. Voir Sémantique SET.

    • X-Platform-Parent-Account-Id est requis pour toutes les écritures ; son absence renvoie 422.
    • Idempotency-Key est requis pour toutes les écritures. Générez un UUID frais par groupe de réessai logique. La fenêtre de déduplication de 24 heures regroupe les réessais avec la même clé en une seule exécution.
    • dry_run=true exécute la validation complète sans persister l'état, parfait pour valider une charge utile. L'enveloppe de réponse ajoute dry_run: true à côté de data.
    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
      }'
    remarque

    contentHash est un jeton de concurrence optimiste. Passez null lors de la première écriture sur un nouveau compte ; lors des écritures suivantes, renvoyez la valeur content_hash retournée par la réponse GET ou PUT précédente pour éviter d'écraser les modifications concurrentes.

    La charge utile de la réponse (à l'intérieur de data) correspond à GET : même translated_verticals et marketplace_controls_list (avec domains et un nouveau content_hash). En mode simulation, la réponse décrit ce qui serait écrit.

  6. Activate the partnership (dry-run)

    PUT /v1/partnership/accounts/{account_id}/status cascade actif/en pause sur chaque variante de page non archivée sur le compte.

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

    La réponse data.variants[] liste la répartition par variante :

    {
      "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 renvoie le statut global plus le détail par variante.

    curl https://accounts.rokt.com/v1/partnership/accounts/$ACCOUNT_ID/status \
      -H "Authorization: Bearer $TOKEN" \
      -H "X-Platform-Parent-Account-Id: $PARENT"

    En production (supprimez dry_run=true), data.status doit correspondre à ce que vous venez de PUT. Si vous voyez "mixed" après un PUT status=active, certaines variantes n'ont pas réussi à se mettre à jour ; capturez le request_id et déposez un ticket de support.

    La règle d'agrégation :

    • "active" : chaque variante non archivée est activée.
    • "paused" : chaque variante non archivée est désactivée (ou aucune n'existe).
    • "mixed" : certaines sont activées, d'autres désactivées.

Prochaines étapesLien direct vers Prochaines étapes

Commencez ici :

Onboarding workflow

Recette de bout en bout : intégration d'un marchand, mise à jour des contrôles, mise en pause et gestion des échecs.

Ensuite :

Core Concepts

Lisez les quatre concepts porteurs : manager/managed, idempotence, sémantique SET, exécution à blanc (dry-run).

SDK Integration

Si vous rendez les placements sur la page du marchand vous-même, consultez l'intégration SDK (pages, mises en page, et selectPlacements).

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