Opération de Polling

Audience

Cette surface d'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 réponse d'écriture transporte un en-tête X-Operation-Id. Capturez-le. Si votre client HTTP a expiré avant de lire la réponse, vous pouvez récupérer le résultat original en sondant GET /v1/partnership/operations/{operation_id}; la machine d'état côté serveur a l'enregistrement canonique, y compris le corps complet de la réponse de l'écriture originale.

Quand le polling est important

L'API Partnerships est principalement synchrone : les écritures en chemin heureux retournent en bien moins d'une seconde. Vous n'avez besoin de polling que lorsque :

• Votre client HTTP a expiré et vous n'avez jamais lu la réponse.
• Une interruption réseau a coupé la connexion en cours d'écriture.
• Vous orchestrez depuis un environnement sans serveur / lambda où la ré-invocation est moins coûteuse que les sockets maintenus longtemps.

Si vous avez reçu un 200, ne faites pas de polling ; vous avez déjà la réponse.

Capturez l'ID de l'opération à chaque écriture

resp = requests.put(
    f"https://accounts.rokt.com/v1/partnership/accounts/{account_id}/marketplacecontrolslists",
    headers={
        "Authorization": f"Bearer {token}",
        "X-Platform-Parent-Account-Id": parent_account_id,
        "Idempotency-Key": idem_key,
    },
    json=payload,
    timeout=10,
)
operation_id = resp.headers.get("X-Operation-Id")
# Persist `operation_id` to durable storage BEFORE acting on resp.json().

L'en-tête X-Operation-Id est défini dès que le serveur alloue la ligne d'opération, même en cas d'erreurs. Enregistrez-le avant de parser le corps pour qu'il survive à un crash de désérialisation.

Les IDs d'opération sont limités à votre gestionnaire

Les IDs d'opération sont des chaînes opaques ; ne les parsez pas et n'assumez aucune structure. Ils sont lisibles uniquement par le compte gestionnaire autorisé qui a émis l'écriture. Toute lecture inter-locataire (que le parent authentifié de l'appelant ne possède pas l'opération ou que l'en-tête X-Platform-Parent-Account-Id ne correspond pas au propriétaire de l'opération) retourne 403. La possession d'un ID d'opération seul ne confère jamais de visibilité inter-comptes. X-Platform-Parent-Account-Id est requis à chaque sondage ; manquant ou non correspondant retourne 403.

États de l'opération

pending  ──▶  in_progress  ──▶  completed
                            ╲
                             ╲─▶  failed

État	Signification
pending	Ligne d'opération créée ; le traitement n'a pas encore commencé. Rare à observer ; généralement transitoire.
in_progress	L'opération exécute des étapes. Continuez le polling.
completed	Toutes les étapes ont réussi. response_body contient la charge utile de la réponse de l'écriture originale.
failed	Au moins une étape a échoué et l'opération a annulé ce qu'elle pouvait. response_body contient l'enveloppe d'erreur.

Cadence de polling

Utilisez un backoff exponentiel, plafonné, avec une échéance. Recommandé : commencez à 1s, doublez chaque tentative jusqu'à 30s, abandonnez après 5 minutes.

python

import time, requests

def poll_operation(operation_id, token, parent_account_id, *, deadline_s=300):
    delay = 1.0
    start = time.monotonic()
    while time.monotonic() - start < deadline_s:
        resp = requests.get(
            f"https://accounts.rokt.com/v1/partnership/operations/{operation_id}",
            headers={
                "Authorization": f"Bearer {token}",
                "X-Platform-Parent-Account-Id": parent_account_id,
            },
            timeout=10,
        )
        envelope = resp.json()
        op = envelope["data"]
        if op["status"] in ("completed", "failed"):
            return op
        time.sleep(delay)
        delay = min(delay * 2, 30.0)
    raise TimeoutError(f"operation {operation_id} did not settle in {deadline_s}s")

node

async function pollOperation(operationId, token, parentAccountId, { deadlineMs = 300_000 } = {}) {
  let delay = 1000;
  const start = Date.now();
  while (Date.now() - start < deadlineMs) {
    const resp = await fetch(
      `https://accounts.rokt.com/v1/partnership/operations/${operationId}`,
      {
        headers: {
          Authorization: `Bearer ${token}`,
          "X-Platform-Parent-Account-Id": parentAccountId,
        },
      }
    );
    const envelope = await resp.json();
    const op = envelope.data;
    if (op.status === "completed" || op.status === "failed") return op;
    await new Promise((r) => setTimeout(r, delay));
    delay = Math.min(delay * 2, 30_000);
  }
  throw new Error(`operation ${operationId} did not settle`);
}

curl

# One-shot poll
curl https://accounts.rokt.com/v1/partnership/operations/9c7b1d2e-3a4f-4b5c-9d8e-1f2a3b4c5d6e \
  -H "Authorization: Bearer $ROKT_TOKEN" \
  -H "X-Platform-Parent-Account-Id: $PARENT"

Forme de la réponse

Les lectures d'opération retournent l'enveloppe standard ; l'enregistrement de l'opération se trouve dans data. Le champ status de niveau supérieur est le code de statut HTTP ; l'état du cycle de vie de l'opération (pending / in_progress / completed / failed) est data.status.

{
  "status": 200,
  "error": null,
  "message": "ok",
  "request_id": "0e3a1b9c-1234-4abc-9def-aaaabbbbcccc",
  "data": {
    "operation_id": "9c7b1d2e-3a4f-4b5c-9d8e-1f2a3b4c5d6e",
    "status": "completed",
    "mode": "sync",
    "operation_type": "configure_partnership",
    "created_at": "2026-05-14T18:21:09Z",
    "completed_at": "2026-05-14T18:21:11Z",
    "next_retry_at": null,
    "retry_count": 0,
    "request_id": "0e3a1b9c-1234-4abc-9def-aaaabbbbcccc",
    "response_body": {
      "account_id": "<your-account-id>",
      "marketplace_controls_list_id": "8c8e1c12-...",
      "content_hash": "h_xyz789"
    },
    "error": null
  }
}

Pour les opérations completed ou failed, data.response_body est la charge utile exacte que l'écriture originale a retournée. Vous pouvez la prendre et continuer votre flux de travail ; il n'est pas nécessaire de réémettre le PUT.

remarque

Les clés snake_case sont le contrat canonique pour response_body, correspondant aux points de terminaison en direct.

Walkthrough : récupération après un délai d'attente côté client

1. 1
   Register a merchant; client times out

   Votre appel POST /v1/accounts/register/partnership atteint un délai d'attente client de 5 secondes. Vous ne lisez jamais la réponse.

2. 2
   But you logged the operation ID

   Votre client HTTP a mis en mémoire tampon les en-têtes de réponse avant le délai d'attente du corps. Vous avez :

   X-Operation-Id: 9c7b1d2e-3a4f-4b5c-9d8e-1f2a3b4c5d6e

   (Si vous n'avez pas non plus l'en-tête, revenez à Idempotency-Key replay : même clé, même écriture.)

3. 3
   Poll until terminal

   curl https://accounts.rokt.com/v1/partnership/operations/9c7b1d2e-3a4f-4b5c-9d8e-1f2a3b4c5d6e \
     -H "Authorization: Bearer $ROKT_TOKEN" \
     -H "X-Platform-Parent-Account-Id: $PARENT"

   Réponse après ~2s :

   {
     "status": 200,
     "error": null,
     "message": "ok",
     "request_id": "0e3a1b9c-...",
     "data": {
       "operation_id": "9c7b1d2e-...",
       "status": "completed",
       "operation_type": "register_partnership",
       "response_body": { "account_id": "<your-account-id>" }
     }
   }

4. 4
   Use data.response_body as if it were the original response

   Traitez data.response_body.account_id exactement comme vous auriez traité le corps original 200. L'écriture a déjà eu lieu ; vous venez juste de récupérer le reçu.

astuce

Le polling et l'Idempotency-Key replay sont deux chemins vers la même récupération. Le polling est préféré lorsque vous avez l'ID de l'opération ; c'est un GET peu coûteux qui ne relance pas la validation. Le replay est le recours lorsque seule la clé a survécu à votre crash.

Connexes

Idempotency Keys

L'autre chemin de récupération pour les réponses perdues.

Operations API

Référence de l'endpoint pour GET /v1/partnership/operations/{operation_id}.