Comptes Manager & Managed

Audience

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

Chaque appel API de Partenariats résout deux identités de compte : le manager (votre plateforme partenaire) et le compte géré (le marchand que vous avez intégré). La relation manager-géré est la frontière d'authentification : votre jeton API prouve l'identité du manager, et le {account_id} dans le chemin identifie le compte géré.

Les deux rôlesLien direct vers Les deux rôles

Compte manager : le compte parent de votre plateforme partenaire sur Rokt. Il y en a exactement un par intégration de partenariat. Votre jeton API est limité à ce compte.
Compte géré : chaque marchand que vous avez intégré via l'API. Créé par POST /v1/accounts/register/partnership et identifié par l'account_id émis par Rokt et retourné dans cette réponse.

Manager Account  (your partner platform's parent)
        │
        │  manages
        ▼
┌───────┬───────────────┬───────────────┐
│       │               │               │
Managed A      Managed B       Managed C
(merchant)     (merchant)      (merchant)

Votre clé de marchand : `external_account_id`Lien direct vers your-merchant-key-external_account_id

external_account_id est votre identifiant stable pour le marchand : la clé primaire propre à votre plateforme pour ce magasin, quel que soit le format que vous choisissez. Rokt le conserve dans l'enregistrement du compte géré et l'utilise à deux fins distinctes :

Idempotence lors de l'enregistrement. POST /v1/accounts/register/partnership est idempotent sur (platform_parent_account_id, external_account_id). Réenvoyer la même charge utile d'enregistrement avec le même external_account_id retourne l'account_id original au lieu de créer un doublon ; l'enregistrement n'a pas d'exigence de Idempotency-Key, ce champ est la clé de déduplication.
Surface de conflit en cas de collision. Si un magasin différent a été enregistré plus tôt sous le même external_account_id (pour votre platform_parent_account_id), ou si une plateforme partenaire différente possède déjà l'store_identifier de ce marchand, l'enregistrement retourne 409. Les deux clés de collision sont indépendantes : les collisions de external_account_id sont des doublons de votre côté ; les collisions de store_identifier sont des conflits inter-plateformes.

Choisir un bon `external_account_id`Lien direct vers choosing-a-good-external_account_id

Stable. Choisissez une valeur qui ne change pas pendant la durée de vie du marchand sur votre plateforme. L'enregistrement est idempotent sur cette chaîne exacte ; la changer lors d'une nouvelle tentative crée un compte Rokt en double.
Unique par manager. La portée est (platform_parent_account_id, external_account_id). La même chaîne sous deux plateformes partenaires différentes est acceptable ; la même chaîne deux fois sous votre propre plateforme est le cas 409 ci-dessus. Vous n'avez pas besoin d'un identifiant globalement unique.
Non sensible. Cette valeur apparaît dans les journaux de serveur Rokt, les tickets de support, et l'enveloppe de réponse. Utilisez un ID marchand opaque interne à la plateforme ; n'y mettez pas l'email du marchand, l'identifiant de facturation, ou toute autre information personnelle identifiable (PII).
Choisissez une valeur canonique par marchand dans votre système et ne la réutilisez jamais entre marchands.

Comment vous indiquez au serveur qui vous êtesLien direct vers Comment vous indiquez au serveur qui vous êtes

Chaque appel d'écriture doit inclure l'en-tête X-Platform-Parent-Account-Id avec l'ID de compte parent de votre plateforme partenaire :

X-Platform-Parent-Account-Id: <your-platform-parent-account-id>

Le serveur l'utilise pour vérifier que vous gérez réellement le account_id cible dans le chemin. Son absence lors d'une écriture retourne 422. Envoyer une valeur qui ne correspond pas au véritable parent du compte géré retourne 403. Les lectures acceptent l'en-tête comme optionnel mais recommandé à chaque appel pour plus de clarté.

POST /v1/accounts/register/partnership est un cas particulier : platform_parent_account_id fait partie du corps de la requête (le compte géré n'existe pas encore, donc il n'y a pas de compte de chemin à vérifier), et vous devriez également envoyer X-Platform-Parent-Account-Id comme en-tête pour la cohérence.

remarque

Une future version vous permettra de supprimer l'en-tête. Votre contact Rokt vous informera lorsque cela se produira.

Énumération de vos comptes gérésLien direct vers Énumération de vos comptes gérés

Listez chaque marchand que vous gérez actuellement. Le point de terminaison de la liste nécessite ?parent_account_id=<your-parent> comme paramètre de requête (la même valeur que vous avez mise dans l'en-tête) :

curl
python
node

curl 'https://accounts.rokt.com/v1/partnership/accounts?parent_account_id=<your-platform-parent-account-id>' \
  -H "Authorization: Bearer $ROKT_TOKEN" \
  -H "X-Platform-Parent-Account-Id: <your-platform-parent-account-id>"

import requests

resp = requests.get(
    "https://accounts.rokt.com/v1/partnership/accounts",
    params={"parent_account_id": parent},
    headers={
        "Authorization": f"Bearer {token}",
        "X-Platform-Parent-Account-Id": parent,
    },
)
managed_accounts = resp.json()["data"]

const url = new URL("https://accounts.rokt.com/v1/partnership/accounts");
url.searchParams.set("parent_account_id", parent);
const resp = await fetch(url, {
  headers: {
    Authorization: `Bearer ${token}`,
    "X-Platform-Parent-Account-Id": parent,
  },
});
const { data: managedAccounts } = await resp.json();

La réponse encapsule la liste dans l'enveloppe standard ; le tableau se trouve dans data :

{
  "status": 200,
  "error": null,
  "message": "ok",
  "request_id": "0e3a1b9c-...",
  "data": [
    {
      "account_id": "<your-account-id>",
      "brand": "Acme Apparel",
      "country_code": "US",
      "external_account_id": "partner-merchant-abc123",
      "status": "active",
      "created_at": "2026-04-12T18:21:09Z",
      "updated_at": "2026-05-02T14:00:00Z"
    }
  ]
}

Inspection d'un compte géré uniqueLien direct vers Inspection d'un compte géré unique

Un point de terminaison consolidé pour un seul compte (GET /v1/partnership/accounts/{account_id}) n'est pas encore exposé sur la surface partenaire. Pour inspecter un marchand, interrogez les lectures par ressource :

Chacune vérifie que l'appelant (résolu à partir de votre jeton API, éventuellement vérifié par recoupement avec X-Platform-Parent-Account-Id) est le gestionnaire actuel du compte du chemin avant de retourner. Toute autre personne reçoit 403.

Quand vous recevez un 403Lien direct vers Quand vous recevez un 403

Si vous appelez un point de terminaison de lecture ou d'écriture sur un compte géré que vous ne gérez pas, ou dont la relation de gestion a été révoquée, vous recevez 403 Forbidden avec cette enveloppe :

{
  "error": "API token valid but missing required relationship grant",
  "request_id": "req_01HX9F2J7M3K8N5VYBQZP4R6T2"
}

Le jeton API est correct ; c'est la relation qui pose problème. Causes courantes :

Le compte géré a été migré vers une autre plateforme partenaire.
Le marchand a déconnecté votre intégration depuis son administration Rokt.
Vous avez codé en dur un account_id appartenant à un autre partenaire.

attention

Ne réessayez pas un 403. Ce n'est pas transitoire. Transmettez le request_id à smb-partnerships@rokt.com si la relation devrait encore être active.

Idempotency Keys

En-tête requis pour chaque appel d'écriture.

SET Semantics

Pourquoi PUT remplace, ne fusionne jamais.

Les deux rôlesLien direct vers Les deux rôles

Votre clé de marchand : external_account_idLien direct vers your-merchant-key-external_account_id

Choisir un bon external_account_idLien direct vers choosing-a-good-external_account_id