SET Sémantique

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

PUT sur les routes Controls et Status remplace l'état complet. Il n'y a pas de fusion, pas de diff, pas de PATCH. Le bug d'intégration le plus courant que nous voyons est que les partenaires traitent PUT comme une mise à jour incrémentale. Lisez cette page avant de toucher à putMarketplaceControls ou putPartnershipStatus.

attention

PUT remplace. Si vous envoyez blockedVerticals: [{partnerVerticalId: 1500, ...}], seul ce vertical est bloqué. Tout vertical que vous aviez précédemment bloqué et que vous n'avez pas inclus est maintenant autorisé. Même chose pour domains. Toujours GET → modifier → PUT la liste complète.

Pourquoi PUT remplace

Un PUT dit "c'est l'état de contrôle complet souhaité par le marchand en ce moment." Le serveur réconcilie son état stocké pour correspondre au vôtre. Tout ce qui n'est pas dans votre corps de requête n'est, par définition, pas dans l'état souhaité, donc il est supprimé.

Le flux de travail correct est toujours :

GET /…/marketplacecontrolslists      ──▶  current full list + content_hash
       │
       ▼
modify locally (add/remove/change)
       │
       ▼
PUT /…/marketplacecontrolslists      ──▶  send the full modified list

Mauvais vs bon

Un marchand a actuellement les verticals 1500 et 1502 bloqués. Le partenaire veut ajouter un bloc sur 1504.

wrong.json

{
  "name": "Acme Network Controls",
  "blockedVerticals": [
    { "partnerVerticalId": 1504, "partnerSubVerticalId": 1612, "policy": "Block" }
  ]
}

right.json

{
  "name": "Acme Network Controls",
  "blockedVerticals": [
    { "partnerVerticalId": 1500, "partnerSubVerticalId": 1610, "policy": "Block" },
    { "partnerVerticalId": 1502, "partnerSubVerticalId": 1620, "policy": "Block" },
    { "partnerVerticalId": 1504, "partnerSubVerticalId": 1612, "policy": "Block" }
  ],
  "contentHash": "h_abc123"
}

wrong.json débloque 1500 et 1502. Le serveur remplace fidèlement l'état par ce que vous avez envoyé. Il n'y a pas d'erreur, pas d'avertissement ; le marchand se réveille simplement demain avec deux catégories précédemment bloquées maintenant actives.

right.json fait ce que le partenaire avait l'intention de faire : ajoute 1504 à l'ensemble bloqué, préserve 1500 et 1502, inclut le contentHash du GET précédent pour la sécurité de la concurrence optimiste.

Points de terminaison qui suivent les sémantiques SET

Point de terminaison	Qu'est-ce qui est SET
PUT /v1/partnership/accounts/{account_id}/marketplacecontrolslists	blockedVerticals, domains
PUT /v1/partnership/accounts/{account_id}/status	l'état actif/en pause pour chaque variante non archivée

Pour le statut : PUT status=paused met en pause chaque variante de page non archivée. Il n'y a pas de "mettre en pause seulement la variante X" ; ce serait un état partiel, ce que le modèle SET interdit. Si vous avez besoin de contrôle par variante, cela n'est pas dans la surface API des Partenariats aujourd'hui.

Concurrence optimiste avec contentHash

Chaque réponse GET inclut marketplace_controls_list.content_hash. Renvoyez-le comme champ contentHash de votre PUT pour détecter en toute sécurité les modifications concurrentes. Si un autre appelant (ou un outil d'administration côté Rokt) a mis à jour la ligne entre votre GET et PUT, le serveur rejette le PUT avec un conflit. Sans contentHash, le dernier écrit gagne.

{
  "name": "Acme Network Controls",
  "blockedVerticals": [...],
  "contentHash": "h_abc123"
}

Utilisez ceci lorsque :

• Plusieurs personnes dans votre tableau de bord pourraient modifier le même marchand simultanément.
• Un travail par lots de longue durée et une interface utilisateur en temps réel pourraient se concurrencer sur le même compte.

Ignorez-le lorsque :

• Vous scriptz une migration ponctuelle avec un seul rédacteur.

Démonstration : ajouter un bloc de domaine

1. 1
   GET the current MCL state

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

   Réponse data (abrégée) :

   {
     "marketplace_controls_list": {
       "domains": [
         { "domain": "competitor.example.com", "policy": "Block" }
       ],
       "content_hash": "h_abc123"
     },
     "translated_verticals": [
       { "vertical_id": 1610, "policy": "Block", "position_1_policy": "Block" }
     ]
   }

2. 2
   Append the new domain block locally

   Ajoutez { "domain": "competitor-two.example.com", "policy": "Block" } au tableau domains. Gardez tout le reste.

3. 3
   PUT the FULL modified state back

   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 '{
       "name": "Acme Network Controls",
       "blockedVerticals": [
         {"partnerVerticalId": 1500, "partnerSubVerticalId": 1610, "policy": "Block"}
       ],
       "domains": [
         {"domain": "competitor.example.com", "policy": "Block"},
         {"domain": "competitor-two.example.com", "policy": "Block"}
       ],
       "contentHash": "h_abc123"
     }'

   Les deux domaines sont maintenant bloqués. Le bloc vertical sur 1500/1610 est préservé parce que vous l'avez envoyé.

Related

Vertical Taxonomy

Comment les identifiants verticaux des partenaires se traduisent dans la taxonomie de Rokt sur PUT.

Operation Polling

Récupérer des réponses PUT perdues sans renvoyer le corps.