Aperçu
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 à la place la documentation développeur Rokt Ecommerce.
L'API Rokt Partnerships est une API REST pour les plateformes partenaires qui intègrent et gèrent les marchands sur le réseau Rokt. Utilisez-la pour enregistrer des marchands, configurer les contrôles du marché, gérer le statut des placements et commencer l'intégration des paiements sans utiliser l'interface utilisateur de Rokt.
L'accès est accordé par Rokt. L'API Partnerships n'est pas encore en libre-service. Rokt émet les identifiants API à longue durée de votre plateforme (client_id + client_secret) une fois, lors de l'intégration, et vous réutilisez les mêmes identifiants pour chaque échange de jeton d'accès. Envoyez un e-mail à smb-partnerships@rokt.com avec le nom de votre plateforme, le volume de marchands attendu et l'ID de compte gestionnaire qui vous a été attribué ; voir Authentification pour le flux complet.
Votre taxonomie de catégories est initialisée avant que vous n'enregistriez quoi que ce soit. Rokt associe les catégories de votre plateforme aux siennes, une fois par plateforme, lors de l'intégration. Une catégorie non mappée échoue à l'enregistrement avec un 400, alors envoyez votre liste complète de catégories à smb-partnerships@rokt.com tôt et confirmez que les lignes ont atterri avec GET /v1/partnership/vertical-mappings. Voir Vérifier ce qui est mappé.
Cette surface API est en développement actif. Les charges utiles, les points d'extrémité et le comportement peuvent changer. Rokt vous informera de toute modification majeure.
Concepts clésLien direct vers Concepts clés
Votre plateforme est représentée comme un compte gestionnaire. Les marchands que vous intégrez sont des comptes gérés. Rokt autorise chaque requête en utilisant votre jeton API et le {account_id} cible dans le chemin de la requête : le compte cible doit être géré par votre compte gestionnaire, et les requêtes pour des comptes non liés sont rejetées côté serveur.
your platform (manager)
│
├── merchant A (managed account)
├── merchant B (managed account)
└── merchant C (managed account)
Ces quatre concepts sont nécessaires pour intégrer en toute sécurité. Lisez-les avant d'écrire du code.
Comment Rokt dérive le contexte de l'appelant à partir de votre jeton API et autorise contre le account_id cible.
Chaque appel d'écriture nécessite un Idempotency-Key. Envoyer la même clé deux fois renvoie la réponse mise en cache, il est donc sûr de réessayer.
PUT remplace la liste complète. Les points d'extrémité de contrôle (MCL, statut) n'ont pas de PATCH ou de fusion. Envoyez l'état souhaité complet à chaque fois. Le point d'extrémité d'édition de mise en page est la seule surface PATCH dans V1 ; il accepte les mises à jour partielles des cinq jetons de thème.
dry_run=true exécute la validation complète et renvoie la réponse potentielle sans persister l'état. Utilisez-le pour valider les charges utiles avant de passer en production.
Ce que vous pouvez faireLien direct vers Ce que vous pouvez faire
- Enregistrer un marchand :
POST /v1/accounts/register/partnership. Idempotent surexternal_account_id(votre identifiant stable pour le marchand ; gardez-le non sensible ; voir Idempotency pour le périmètre d'unicité). - Lister les comptes gérés :
GET /v1/partnership/accounts?parent_account_id=<your-parent>. Un point de terminaison pour les détails d'un compte unique n'est pas encore exposé ; utilisez les lectures par ressource ci-dessous pour inspecter un compte géré individuel. - Vérifier vos mappages verticaux préétablis :
GET /v1/partnership/vertical-mappings?parent_account_id=<your-parent>retourne vos mappages de catégories préétablis, dans votre propre taxonomie. Lecture seule ; Rokt crée les lignes. Une liste vide signifie que rien n'est préétabli et chaque enregistrement échouera avec un400. Voir Vérifier ce qui est mappé. - Lire et mettre à jour les contrôles de marché :
GET/PUT /v1/partnership/accounts/{account_id}/marketplacecontrolslists. Bloquez les verticaux dans votre taxonomie partenaire ; Rokt traduit côté serveur. - Suspendre ou reprendre les placements :
PUT /v1/partnership/accounts/{account_id}/statuscascade actif/suspendu à travers chaque variante de page non archivée. - Modifier le thème d'un marchand :
PATCH /v1/partnership/accounts/{account_id}/layouts/{layout_id}accepte une mise à jour partielle des cinq jetons de thème (primaryColor,backgroundColor,textColor,borderRadius,closeButtonColor). Voir Pages et Dispositions et le flux de travail Personnaliser les Dispositions. - Ajouter une surface après le lancement :
POST /v1/partnership/accounts/{account_id}/pagesattache une autre surface (confirmation, suivi, retours) à un marchand déjà intégré sans réenregistrement. Voir Pages et Dispositions. - Changer le type de disposition d'une page :
PUT /v1/partnership/accounts/{account_id}/pages/{page_id}déplace une page existante entre Overlay et Embedded sans changer sonpage_identifierou le ciblage URL. Voir Pages et Dispositions et le flux de travail Personnaliser les Dispositions. - Commencer l'intégration des paiements :
POST /v1/partnership/accounts/{account_id}/payout-setupinitie l'intégration Stripe Connect pour un marchand. En V1, Rokt paie le paiement côté partenaire (la part de revenu de votre plateforme, selon votre accord de partenariat) à votre compte gestionnaire, pas aux comptes gérés individuels ; la distribution de la part de chaque marchand est la responsabilité de votre plateforme. Voir le flux de travail d'intégration des marchands. - Soumettre des demandes de confidentialité du réseau consommateur :
POST /v1/partnership/network-privacy-requestsgère le désabonnement du réseau et la suppression des données du réseau par identifiant consommateur. Voir Demandes de Confidentialité. - Soumettre la suppression des données de compte géré :
POST /v1/partnership/accounts/{account_id}/data-deletion-requestsdemande la suppression au niveau du compte pour un marchand géré par votre plateforme. Voir Demandes de Confidentialité. - Sonder les opérations de longue durée : chaque écriture retourne
X-Operation-Id.GET /v1/partnership/operations/{operation_id}récupère des délais d'attente réseau sans réémettre l'écriture. Les identifiants d'opération sont opaques et uniquement lisibles par le gestionnaire autorisé, donc le sondage ne peut pas exposer le statut pour des comptes non liés.