Mise à jour des contrôles du Marketplace

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.

Cette recette couvre les modifications continues des contrôles du marketplace pour un marchand déjà intégré. Le modèle est : GET, modifier localement, PUT le résultat complet.

attention

PUT remplace l'état complet. Les points de terminaison des contrôles (MCL, statut) utilisent PUT-remplacement ; il n'y a pas de PATCH ou de fusion sur cette surface. Toujours GET d'abord, modifier localement, et PUT la liste complète modifiée. Tout ce que vous omettez du PUT devient débloqué. Le point de terminaison d'édition de mise en page (PATCH /v1/partnership/accounts/{id}/layouts/{layout_id}) est le seul point de terminaison PATCH dans l'API de partenariat ; il ne s'applique pas aux contrôles. Voir SET Semantics.

GET the current state

Récupérez l'actuel MCL et capturez marketplace_controls_list.content_hash pour la concurrence optimiste à l'étape 3.

curl https://accounts.rokt.com/v1/partnership/accounts/<your-account-id>/marketplacecontrolslists \
  -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>",
    "marketplace_controls_list": {
      "marketplace_controls_list_id": "8c6f2a1e-...",
      "domains": [ { "domain": "competitor.example.com", "policy": "Block" } ],
      "content_hash": "v7-1a9e3f4c"
    },
    "translated_verticals": [
      { "vertical_id": 1610, "policy": "Block", "position_1_policy": "Block" },
      { "vertical_id": 1611, "policy": "Allow", "position_1_policy": "Allow" }
    ]
  }
}

translated_verticals porte la politique effective pour chaque sous-verticale mappée dans votre taxonomie ; vertical_id est votre ID de sous-verticale, pas un ID Rokt.

Modify locally

Ajoutez une nouvelle verticale bloquée tout en préservant tout ce que vous aviez déjà. Construisez le corps de la requête à partir de la réponse GET de translated_verticals : gardez les entrées dont policy est Block. La réponse renvoie votre ID de sous-verticale (vertical_id) ; résolvez chacun à son ID de verticale parent à partir de votre propre taxonomie, car le corps PUT nécessite le {partnerVerticalId, partnerSubVerticalId} complet.

javascript
python

const envelope = await getMcl(accountId); // GET above
const current = envelope.data;            // unwrap the envelope

const next = {
  name: "Acme Network Controls",
  blockedVerticals: [
    ...current.translated_verticals
      .filter(v => v.policy === "Block")
      .map(v => ({
        partnerVerticalId: parentVerticalOf(v.vertical_id), // your taxonomy lookup
        partnerSubVerticalId: v.vertical_id,
        policy: "Block",
        position1Policy: v.position_1_policy ?? "Block",
      })),
    // append the new one
    { partnerVerticalId: 1500, partnerSubVerticalId: 1612, policy: "Block", position1Policy: "Block" },
  ],
  domains: current.marketplace_controls_list.domains,
  contentHash: current.marketplace_controls_list.content_hash, // pass back for optimistic concurrency
};

envelope = get_mcl(account_id)  # GET above
current = envelope["data"]      # unwrap the envelope

next_body = {
    "name": "Acme Network Controls",
    "blockedVerticals": [
        {
            "partnerVerticalId": parent_vertical_of(v["vertical_id"]),  # your taxonomy lookup
            "partnerSubVerticalId": v["vertical_id"],
            "policy": "Block",
            "position1Policy": v.get("position_1_policy") or "Block",
        }
        for v in current["translated_verticals"]
        if v["policy"] == "Block"
    ] + [
        {"partnerVerticalId": 1500, "partnerSubVerticalId": 1612, "policy": "Block", "position1Policy": "Block"}
    ],
    "domains": current["marketplace_controls_list"]["domains"],
    "contentHash": current["marketplace_controls_list"]["content_hash"],
}

3
PUT the modified list
Envoyez l'état complet souhaité. Incluez contentHash pour que le serveur puisse rejeter l'écriture si quelqu'un d'autre a mis à jour la ligne entre votre GET et votre PUT.
curl -X PUT https://accounts.rokt.com/v1/partnership/accounts/<your-account-id>/marketplacecontrolslists \ -H "Authorization: Bearer $TOKEN" \ -H "X-Platform-Parent-Account-Id: $PARENT" \ -H "Content-Type: application/json" \ -H "Idempotency-Key: $(uuidgen)" \ -d @next.json
Si le serveur renvoie une erreur contentHash, quelqu'un a modifié la ligne entre votre GET et PUT. Re-GET, réappliquez votre changement à l'état frais, et réessayez. Voir Idempotency Keys pour comprendre pourquoi vous pouvez réessayer en toute sécurité avec la même clé.
remarque
Le rejet de hachage obsolète de bout en bout est en phase de prévisualisation : vérifié à travers le schéma mais pas encore observé en direct sur cette surface partenaire. Traitez le chemin 409 comme un effort maximal jusqu'à la GA.
4
Optionally dry-run first
Ajoutez ?dry_run=true pour valider le payload (validation complète et traduction de taxonomie) sans engagement. Aucun état n'est conservé.
curl -X PUT 'https://accounts.rokt.com/v1/partnership/accounts/<your-account-id>/marketplacecontrolslists?dry_run=true' \ -H "Authorization: Bearer $TOKEN" \ -H "X-Platform-Parent-Account-Id: $PARENT" \ -H "Content-Type: application/json" \ -H "Idempotency-Key: $(uuidgen)" \ -d @next.json
remarque
Lorsque vous rappelez sans dry_run pour l'écriture réelle, utilisez une nouvelle clé d'idempotence. La clé de simulation est maintenant mise en cache. Voir Mode Simulation.

Verify

GET à nouveau et confirmez que la nouvelle verticale est présente, que vos blocages précédents sont toujours là, et que domains est inchangé.

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

Common piègesLien direct vers Common pièges

J'ai envoyé un nouveau vertical et perdu tous mes blocs précédents

Les sémantiques SET. PUT est un état désiré, pas un patch. Toujours GET-modifier-PUT la liste complète. Il n'y a pas de fusion sur le serveur. Si vous envoyez seulement [{ vertical: 1612 }], vous avez dit au serveur "1612 est la liste entière" et débloqué tout le reste.

PUT retourne 409 avec une erreur de contentHash

Quelqu'un d'autre (ou une autre instance de votre service) a modifié la ligne entre votre GET et votre PUT. Le contentHash que vous avez envoyé ne correspond plus à l'état actuel du serveur.

Résolution : re-GET, réappliquez votre changement à l'état frais, et réessayez le PUT. Vous pouvez garder le même Idempotency-Key; le serveur traitera la nouvelle charge utile comme une nouvelle opération car la tentative précédente a été rejetée, non validée.

Le serveur retourne 400 : 'Aucun mappage vertical trouvé pour le(s) vertical(aux) partenaire suivant(s)'

Un ou plusieurs de vos paires partnerVerticalId / partnerSubVerticalId ne sont pas dans la table de mappage vertical de Rokt. Le PUT est rejeté de manière atomique : pas d'écritures partielles.

Le message nomme chaque paire non mappée, afin que vous puissiez les corriger en une seule fois :

No vertical mapping found for the following partner vertical(s):
(partner_vertical_id=1500, partner_sub_vertical_id=1610). Call GET
/v1/partnership/vertical-mappings to see which verticals are currently
mapped, and contact smb-partnerships@rokt.com to request additions. The
MCL write was rejected atomically; no partial update was applied.

Résolution : appelez GET /v1/partnership/vertical-mappings?parent_account_id=<your-parent> pour voir l'ensemble actuel (voir Vérifiez ce qui est mappé), puis envoyez un email à smb-partnerships@rokt.com avec les IDs non mappés et nous ajouterons les lignes. En attendant, omettez les verticaux non mappés de votre PUT.

Je veux effacer tous les blocs

Envoyez blockedVerticals: [] et domains: []. Le serveur traite un tableau vide comme "aucun bloc"; c'est le point fixe des sémantiques SET.