Mode Dry-Run

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 plutôt les docs développeur Rokt Ecommerce.

La plupart des points de terminaison d'écriture acceptent ?dry_run=true; voir le tableau des points de terminaison pris en charge pour les exceptions. Rokt valide la requête complète (authentification, forme de la charge utile, mappages verticaux, vérifications de relation) et renvoie une réponse identique à un véritable engagement, mais aucun état n'est persisté. Le corps de la réponse est identique à un appel réel ; les effets secondaires ne le sont pas.

Quand l'utiliser

• Valider la forme d'une charge utile avant de s'engager. Afficher 400s, les mappages verticaux manquants, ou les relations 403 sans toucher à l'état.
• Tests d'intégration contre la scène. Confirmer que votre build fonctionne de bout en bout sans polluer les données de votre compte sandbox.
• Vérifications préalables dans votre interface utilisateur d'intégration. Montrer au marchand exactement ce qui se passerait avant qu'il ne clique sur Enregistrer.

Ce que le dry-run ne fait pas

Le dry-run n'est pas un contournement de permission ou un chemin rapide : c'est une requête complète et réelle qui renvoie la réponse potentielle sans persister l'état.

• L'authentification fonctionne toujours. Un mauvais jeton API ou une relation révoquée renvoie 401 / 403 exactement comme cela se produirait lors d'un appel réel.
• La traduction verticale fonctionne toujours. Une ligne de mappage vertical manquante renvoie 400 exactement comme cela se produirait lors d'un appel réel.
• Les clés d'idempotence s'appliquent toujours. Un dry-run est enregistré dans le cache d'idempotence, indexé par votre Idempotency-Key.

Ce que le dry-run supprime

Le dry-run supprime à la fois le changement d'état persistant et les effets secondaires qui en découleraient autrement. Spécifiquement, un dry-run ne fait pas :

• Envoyer un e-mail sortant au marchand ou aux opérateurs Rokt.
• Effectuer des appels API externes qui modifieraient l'état sur des systèmes tiers (par exemple, la création de compte Stripe Connect sur payout-setup, c'est pourquoi ce point de terminaison ne prend pas du tout en charge le dry-run).
• Émettre des webhooks vers la plateforme partenaire ou les services Rokt en aval.
• Déclencher des pipelines de traitement en aval ou des notifications.
• Créer une opération sondée : les réponses de dry-run ne portent pas de X-Operation-Id, car aucun travail n'a été persisté pour être sondé.

La seule trace durable qu'un dry-run laisse est la réponse mise en cache sous votre Idempotency-Key (donc réessayer la même clé rejoue le dry-run) et une entrée de journal d'audit côté serveur étiquetée dry_run=true pour le diagnostic. Ni l'un ni l'autre n'est observable par le partenaire via l'API.

attention

Les dry-runs consomment des clés d'idempotence. Si vous effectuez un dry-run avec la clé K, le serveur met en cache la réponse du dry-run sous K. Si vous envoyez ensuite l'écriture réelle avec la même K, vous obtenez la réponse du dry-run mise en cache ; aucun engagement ne se produit. Utilisez une nouvelle Idempotency-Key pour l'appel réel.

Points de terminaison pris en charge

Point de terminaison	Méthode	Dry-run ?
/v1/partnership/accounts/{account_id}/marketplacecontrolslists	PUT	Oui
/v1/partnership/accounts/{account_id}/status	PUT	Oui
Tout GET	N/A	Aucun effet (ignoré)
POST /v1/accounts/register/partnership	POST	Non
POST /v1/partnership/accounts/{account_id}/payout-setup	POST	Non

Walkthrough : valider un MCL PUT, confirmer que l'état n'a pas changé

1. 1
   GET current MCL state: capture the content_hash

   curl https://accounts.rokt.com/v1/partnership/accounts/<your-account-id>/marketplacecontrolslists \
     -H "Authorization: Bearer $ROKT_TOKEN"

   La réponse inclut "content_hash": "h_abc123" (à l'intérieur de marketplace_controls_list) et vos blocs actuels dans translated_verticals.

2. 2
   Dry-run a PUT with a new blocked vertical

   curl

   curl -X PUT "https://accounts.rokt.com/v1/partnership/accounts/<your-account-id>/marketplacecontrolslists?dry_run=true" \
     -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"},
         {"partnerVerticalId": 1500, "partnerSubVerticalId": 1611, "policy": "Block"}
       ],
       "domains": [],
       "contentHash": "h_abc123"
     }'

   python

   import requests, uuid
   
   resp = requests.put(
       f"https://accounts.rokt.com/v1/partnership/accounts/{account_id}/marketplacecontrolslists",
       params={"dry_run": "true"},
       headers={
           "Authorization": f"Bearer {token}",
           "Idempotency-Key": str(uuid.uuid4()),
       },
       json={
           "name": "Acme Network Controls",
           "blockedVerticals": [
               {"partnerVerticalId": 1500, "partnerSubVerticalId": 1610, "policy": "Block"},
               {"partnerVerticalId": 1500, "partnerSubVerticalId": 1611, "policy": "Block"},
           ],
           "domains": [],
           "contentHash": "h_abc123",
       },
   )
   assert resp.status_code == 200, resp.json()

   node

   import { randomUUID } from "node:crypto";
   
   const resp = await fetch(
     `https://accounts.rokt.com/v1/partnership/accounts/${accountId}/marketplacecontrolslists?dry_run=true`,
     {
       method: "PUT",
       headers: {
         Authorization: `Bearer ${token}`,
         "Idempotency-Key": randomUUID(),
         "Content-Type": "application/json",
       },
       body: JSON.stringify({
         name: "Acme Network Controls",
         blockedVerticals: [
           { partnerVerticalId: 1500, partnerSubVerticalId: 1610, policy: "Block" },
           { partnerVerticalId: 1500, partnerSubVerticalId: 1611, policy: "Block" },
         ],
         domains: [],
         contentHash: "h_abc123",
       }),
     }
   );

   Réponse : 200 avec la forme complète MarketplaceControlsResponse, comme si elle avait été validée.

3. 3
   GET again: confirm state is unchanged

   curl https://accounts.rokt.com/v1/partnership/accounts/<your-account-id>/marketplacecontrolslists \
     -H "Authorization: Bearer $ROKT_TOKEN"

   content_hash est toujours h_abc123. translated_verticals montre toujours l'état avant le dry-run. Aucun état n'a été persisté.

4. 4
   Real commit: use a FRESH Idempotency-Key

   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 @mcl.json

   Maintenant, vous obtiendrez une nouvelle écriture, pas le dry-run mis en cache.

Connexes

Idempotency Keys

Pourquoi les dry-runs nécessitent une nouvelle clé pour l'appel réel.

Vertical Taxonomy

Les dry-runs révèlent les mappages manquants avant la validation.