Mettre en pause et reprendre un partenariat

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 emplacements sur leur propre page de paiement devraient utiliser à la place les documents développeur Rokt Ecommerce.

Le PUT de statut est un commutateur grossier unique qui répercute actif/en pause sur chaque variante de page non archivée sur le compte. Les variantes archivées ne sont pas affectées. Il n'y a pas de pause par page ou par variante via l'API des Partenariats ; c'est une opération interne à Rokt.

Utilisez ceci pour : pauses temporaires demandées par le marchand, blocages pour fraude, résolution de litiges, maintenance planifiée de la plateforme.

1. 1
   Mettre en pause le partenariat

   PUT /v1/partnership/accounts/{account_id}/status avec { "status": "paused" }. Chaque variante non archivée est désactivée en une seule transaction.

   curl -X PUT https://accounts.rokt.com/v1/partnership/accounts/<your-account-id>/status \
     -H "Authorization: Bearer $TOKEN" \
     -H "X-Platform-Parent-Account-Id: $PARENT" \
     -H "Content-Type: application/json" \
     -H "Idempotency-Key: $(uuidgen)" \
     -d '{ "status": "paused" }'

   La réponse est le même enveloppe enveloppant StatusCascadeResponse que vous obtenez de GET : agrégat plus détail par variante sous data.

2. 2
   Vérifier la pause

   Effectuez un aller-retour avec le statut GET. Le status agrégé devrait être "paused", et chaque entrée dans variants devrait afficher "paused".

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

   {
     "status": 200,
     "error": null,
     "message": "ok",
     "request_id": "0e3a1b9c-...",
     "data": {
       "account_id": "<your-account-id>",
       "status": "paused",
       "variants": [
         { "page_id": "...", "name": "Confirmation - Default", "status": "paused" },
         { "page_id": "...", "name": "Confirmation - Mobile",  "status": "paused" }
       ]
     }
   }

3. 3
   Reprendre le partenariat

   Lorsque vous êtes prêt à réactiver, PUT status: "active". Même cascade dans la direction opposée.

   curl -X PUT https://accounts.rokt.com/v1/partnership/accounts/<your-account-id>/status \
     -H "Authorization: Bearer $TOKEN" \
     -H "X-Platform-Parent-Account-Id: $PARENT" \
     -H "Content-Type: application/json" \
     -H "Idempotency-Key: $(uuidgen)" \
     -d '{ "status": "active" }'

4. 4
   Vérifier la reprise

   GET status. L'agrégat devrait être "active" et chaque variante non archivée devrait afficher "active".

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

Identité aller-retour

Après un PUT status=paused réussi, GET status doit retourner "paused". Après PUT status=active, GET status doit retourner "active".

attention

L'interprétation de "mixed" dépend de si cela provient de la réponse PUT ou d'un GET.

• "mixed" retourné par le PUT lui-même (ou par un GET status émis immédiatement après un PUT, avant que tout autre acteur ait pu toucher le compte) est une condition de bug : la cascade n'a pas réussi à mettre à jour certaines variantes. Déposez un ticket de support avec votre Idempotency-Key et le request_id de l'enveloppe de réponse PUT. Incluez la répartition par variante du GET afin que le support puisse cibler les variantes spécifiques bloquées.
• "mixed" retourné par un GET status en état stable (c'est-à-dire que vous n'avez pas juste émis un PUT, ou suffisamment de temps s'est écoulé pour que d'autres acteurs aient pu changer les choses) n'est pas nécessairement un bug ; voir la section suivante pour des causes légitimes.

Que signifie "mixed" sur un GET

En dehors de la fenêtre immédiate post-PUT, "mixed" est une valeur légitime en état stable ; elle n'apparaît pas seulement après un échec de cascade. Vous la verrez sur GET status lorsque :

• Le partenaire a archivé certaines variantes de page et pas d'autres, et l'ensemble non archivé est divisé.
• Le support de Rokt a manuellement basculé des variantes individuelles en dehors de l'API Partnerships (par exemple, lors d'un incident).
• Une cascade de statut précédente a partiellement échoué et n'a jamais été réessayée.

L'status agrégé est calculé uniquement sur les variantes non archivées. Le tableau variants vous montre exactement quelle variante est dans quel état ; utilisez-le pour décider si "mixed" est attendu (archivage piloté par le partenaire, basculement côté Rokt) ou un problème (bug de cascade, auquel cas escaladez comme décrit dans l'avertissement ci-dessus).

Idempotence

Le PUT de statut est entièrement idempotent sur Idempotency-Key :

• Ré-envoyer le même { "status": "paused" } avec la même clé dans la fenêtre de déduplication de 24 heures renvoie le résultat mis en cache.
• Après la fenêtre de 24h, la clé expire ; la réutiliser déclenche une nouvelle exécution. Utilisez un UUID frais par groupe de tentative logique.
• Ré-envoyer la même charge utile avec une nouvelle clé est une écriture sans effet : les variantes déjà en pause restent en pause, et le serveur renvoie la réponse actuelle de la cascade dans data.

Les réessais sont gratuits. Utilisez le retrait exponentiel si vous rencontrez un 5xx.

Pourquoi à gros grains ?

L'API Partnerships expose intentionnellement uniquement une pause au niveau du compte. Le contrôle par page et par variante appartient à l'interface utilisateur de la Rokt One Platform, où les opérations de Rokt et les outils internes du partenaire peuvent se coordonner. Garder la surface orientée partenaire à gros grains évite deux modes d'échec :

1. Les partenaires construisant des interfaces utilisateur qui se désynchronisent des changements de variantes côté Rokt.
2. Des états de pause partielle difficiles à déboguer où les revenus diminuent silencieusement de moitié parce que la moitié des variantes sont inactives.

Si vous avez besoin d'un contrôle par variante, déposez une demande d'ingénierie des partenariats ; nous évaluerons si cela doit être intégré dans l'API ou dans un canal secondaire pris en charge.