Conversions API

Avis de Dépréciation

L'API Conversions documentée ci-dessous est désormais obsolète et ne recevra plus de nouvelles mises à jour ou améliorations. Nous encourageons fortement tous les clients à migrer vers le Guide d'Intégration de l'API Événements, qui offre une fiabilité améliorée, une structure de données enrichie et des capacités étendues pour le suivi des conversions et la gestion des audiences.

Pourquoi ce changement ? L'Intégration de l'API Événements et Audiences fournit une interface modernisée et unifiée pour l'envoi de données de conversion et d'audience, permettant :

• Une structure de données améliorée avec une gestion améliorée de l'identité et des attributs des utilisateurs
• Un meilleur support pour les informations sur les appareils et les identifiants publicitaires mobiles
• Une gestion des erreurs et des capacités de limitation de débit améliorées
• Une interface unifiée pour les événements de conversion et les données d'audience
• Un support évolutif pour les futurs types de données et modèles d'intégration

Support de Migration Pour vous aider dans votre migration, consultez le Guide d'Intégration de l'API Événements, qui inclut :

• Une référence complète de l'API avec des exemples de requêtes/réponses
• Le mapping des champs de l'API Conversions vers la nouvelle intégration
• Les meilleures pratiques en matière d'authentification et de sécurité
• Des conseils sur la gestion des erreurs et la limitation de débit
• Des procédures de test et de validation

L'API Conversions fournit un moyen structuré d'envoyer des données de conversion à Rokt similaire à l'API Événement existante. Elle utilise un ensemble défini de champs au lieu de paires clé-valeur arbitraires, valide les formats de données et fournit des retours détaillés sur les problèmes sans rejeter des requêtes entières.

Endpoint

POST https://api.rokt.com/v1/conversions

Pour la référence complète de l'API, voir la documentation Swagger.

Authentification

Contactez votre gestionnaire de compte Rokt pour créer une paire de clés publique et secrète pour les comptes pour lesquels vous souhaitez soumettre des événements de conversion. Ces clés prennent la forme de rpub- et rsec- respectivement.

Nom	Valeur
Clé Publique Rokt	rpub-********-****-****-****-************
Clé Secrète Rokt	rsec-********-****-****-****-************

Requête

En-têtes

Nom	Valeur	Description
Content-Type	application/json	Doit être application/json.
Authorization	Basic base64(rpub-...:rsec-...)	En-tête standard d'authentification de base, avec la valeur des informations d'identification étant un encodage base64 de rpub- et rsec- joints par un deux-points.

Corps

Le corps de la requête doit être fourni au format JSON avec les champs suivants :

Champ	Type	Longueur max	Description
accountId*	Chaîne	64	ID de compte Rokt
test	Booléen	—	Lorsqu'il est défini sur true, la requête est validée sans traiter ni ingérer aucun événement. Utilisez pour tester votre intégration.
events*	Liste[Objet]	100 éléments	Tableau d'événements de conversion. Doit contenir au moins un événement.

Chaque objet dans le tableau events peut contenir les champs suivants :

Champ	Type	Longueur max	Description
conversionId	Chaîne	255	Identifiant unique pour la conversion. Les valeurs dupliquées dans une requête entraîneront le rejet des événements suivants.
conversionType*	Chaîne	255	Type de conversion (par exemple, achat, inscription, abonnement).
eventTime*	Chaîne	—	Heure à laquelle l'événement de conversion s'est produit (format RFC3339). Ne peut pas être dans le futur ou avoir plus de 12 mois.
roktId	Chaîne	255	Identifiant utilisateur Rokt.
email	Chaîne	255	Adresse e-mail de l'utilisateur (minuscule recommandée pour la cohérence avec les valeurs hachées).
emailsha256	Chaîne	64	Hachage SHA256 de l'adresse e-mail de l'utilisateur (chaîne hexadécimale de 64 caractères).
rclid	Chaîne	64	ID de clic Rokt (hachage SHA256, chaîne hexadécimale de 64 caractères).
mobile	Chaîne	255	Numéro de téléphone mobile de l'utilisateur.
mobilesha256	Chaîne	64	Hachage SHA256 du numéro de téléphone mobile de l'utilisateur (chaîne hexadécimale de 64 caractères).
firstName	Chaîne	255	Prénom de l'utilisateur.
lastName	Chaîne	255	Nom de famille de l'utilisateur.
billingZipcode	Chaîne	255	Code postal de facturation de l'utilisateur.
firstNamesha256	Chaîne	64	Hachage SHA256 du prénom de l'utilisateur (chaîne hexadécimale de 64 caractères).
lastNamesha256	Chaîne	64	Hachage SHA256 du nom de famille de l'utilisateur (chaîne hexadécimale de 64 caractères).
billingZipcodesha256	Chaîne	64	Hachage SHA256 du code postal de facturation de l'utilisateur (chaîne hexadécimale de 64 caractères).
ipAddress	String	255	Adresse IP de l'utilisateur.
userAgent	String	1024	Chaîne de l'agent utilisateur du navigateur.
value	Number	—	Valeur de la transaction (0 à 1000000).
ltv	Number	—	Valeur à vie du client (0 à 1000000).
predictedLTV	Number	—	Valeur à vie prédite du client (0 à 1000000).
currency	String	255	Code de devise (ISO 4217).
quantity	Integer	—	Quantité d'articles (minimum 0). Doit être un nombre entier.
productName	String	255	Nom du produit.
sku	String	255	Identifiant de l'unité de gestion des stocks.
paymentType	String	255	Type de méthode de paiement.
margin	Number	—	Marge bénéficiaire (0 à 1000000).
transactionId	String	100	Identifiant unique de la transaction.
confirmationRef	String	100	Numéro de référence de confirmation. Utilisé pour la déduplication.
customAttributes	Object	—	Paires clé-valeur personnalisées pour des données supplémentaires. • Maximum 10 clés • Les clés doivent être alphanumériques (pas d'espaces, de traits de soulignement ou de caractères spéciaux) • Les clés ne doivent pas entrer en conflit avec les noms de champs du schéma d'événement • Longueur maximale des clés 255 caractères • Valeurs de chaîne maximum 1024 caractères

Validation des Identifiants

Chaque événement de conversion doit inclure au moins une des combinaisons d'identifiants suivantes pour permettre une correspondance et une attribution correctes :

• N'importe lequel de : roktId, email, emailsha256, rclid, mobile, mobilesha256
• Tous de : firstName, lastName, billingZipcode
• Tous de : firstNamesha256, lastNamesha256, billingZipcodesha256
• Tous de : ipAddress, userAgent

Les événements qui ne répondent pas à ces exigences échoueront à la validation.

Exemples

Exemple minimal avec uniquement les champs requis :

{
  "accountId": "12345",
  "events": [
    {
      "conversionType": "purchase",
      "eventTime": "2024-12-11T10:00:00Z",
      "email": "user@example.com"
    }
  ]
}

Exemple avec plusieurs événements :

{
  "accountId": "12345",
  "events": [
    {
      "conversionId": "evt_001",
      "conversionType": "purchase",
      "eventTime": "2024-12-11T10:00:00Z",
      "email": "alice@example.com"
    },
    {
      "conversionId": "evt_002",
      "conversionType": "signup",
      "eventTime": "2024-12-11T10:15:30Z",
      "email": "bob@example.com"
    },
    {
      "conversionId": "evt_003",
      "conversionType": "purchase",
      "eventTime": "2024-12-11T10:30:45Z",
      "email": "carol@example.com"
    }
  ]
}

Exemple complet avec tous les champs disponibles :

{
  "accountId": "12345",
  "events": [
    {
      "conversionId": "evt_123456",
      "conversionType": "purchase",
      "eventTime": "2024-09-11T10:00:00Z",
      "roktId": "550e8400-e29b-41d4-a716-446655440000",
      "email": "user@example.com",
      "emailsha256": "d8a928b2043db77e340b523547bf16cb4aa483f0645fe0a290ed1f20aab76257",
      "rclid": "550e8400e29b41d4a716446655440001550e8400e29b41d4a716446655440001",
      "mobile": "+16175494599",
      "mobilesha256": "a1b2c3d4e5f6789012345678901234567890abcdef1234567890abcdef123456",
      "firstName": "John",
      "lastName": "Doe",
      "billingZipcode": "12345",
      "firstNamesha256": "f1e2d3c4b5a698765432109876543210fedcba9876543210fedcba9876543210",
      "lastNamesha256": "1234567890abcdef1234567890abcdef1234567890abcdef1234567890abcdef",
      "billingZipcodesha256": "fedcba0987654321fedcba0987654321fedcba0987654321fedcba0987654321",
      "ipAddress": "192.168.0.1",
      "userAgent": "Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36",
      "value": 99.99,
      "ltv": 499.99,
      "predictedLTV": 299.99,
      "currency": "USD",
      "quantity": 1,
      "productName": "Premium Widget",
      "sku": "WIDGET-001",
      "paymentType": "credit_card",
      "margin": 24.99,
      "transactionId": "txn_789012",
      "confirmationRef": "conf_456789",
      "customAttributes": {
        "source": "website",
        "campaignId": "summer2024",
        "isNewCustomer": true,
        "sessionId": "abc123def456",
        "couponCode": "SAVE20",
        "discountPercent": 15,
        "taxRate": 0.0825
      }
    }
  ]
}

Réponse

L'API valide les requêtes en deux étapes :

1. Validation de la requête : vérifie l'authentification, le format JSON et les champs requis
2. Validation des événements : traite les événements individuels si la validation de la requête est réussie

Codes de statut

Code de réponse HTTP	Description
200	Événements de conversion traités avec succès (tous ou partiels).
400	Mauvaise requête - erreurs de validation ou tous les événements ont échoué.
401	Non autorisé - jeton d'authentification invalide ou manquant.
403	Interdit - jeton non autorisé pour ce compte.
413	Entité de requête trop grande - le corps de la requête dépasse la limite de 1 Mo.
429	Trop de requêtes - limite de débit dépassée.
500	Erreur interne du serveur.
503	Service indisponible.

Erreurs de validation de la requête

La réponse contient un objet data avec :

Champ	Type	Description
code	String	Code d'erreur (par exemple, EventsRequiredError, AccountIDRequiredError, InvalidJSONError).
message	String	Message d'erreur détaillé.

Résultats du traitement des événements

Retourne 200 (Succès/Partiel) si au moins un événement est valide, ou 400 (Échec) si aucun événement n'est valide.

Toutes les réponses contiennent un objet data avec les champs suivants :

Champ	Type	Description
code	String	Code de statut de la réponse (Succès, Partiel ou Échec).
processedCount	Number	Nombre d'événements traités avec succès.
invalidCount	Number	Nombre d'événements ayant échoué à la validation.
errors	List[Object]	Tableau d'erreurs du traitement des événements. Chaque objet suit le schéma d'erreur/avertissement ci-dessous.
warnings	List[Object]	Tableau d'avertissements du traitement des événements. Chaque objet suit le schéma d'erreur/avertissement ci-dessous.

Le warnings dans la réponse inclura les vérifications qui ont échoué mais ne sont pas assez graves pour entraîner le rejet de l'ensemble de l'événement de conversion. Ils n'affecteront pas le invalidCount.

Chaque objet d'erreur et d'avertissement dans les tableaux errors et warnings inclura le champ conversionId s'il a été fourni dans l'événement de requête correspondant. Cela aide à identifier quel événement spécifique a causé le problème.

Schéma d'objet d'erreur/avertissement :

Champ	Type	Description
conversionId	String	ID de conversion si présent dans l'événement.
eventIndex	Number	Position de l'événement dans le tableau de requêtes (à partir de 0).
field	String	Nom du champ ayant causé l'erreur ou l'avertissement.
message	String	Message d'erreur ou d'avertissement.

Échantillons

Erreur de validation de la demande :

{
  "data": {
    "code": "InvalidAccountIDError",
    "message": "Account ID is invalid"
  }
}

Succès (tous les événements valides) :

{
  "data": {
    "code": "Success",
    "processedCount": 1,
    "invalidCount": 0
  }
}

Partiel (certains événements valides) :

{
  "data": {
    "code": "Partial",
    "processedCount": 1,
    "invalidCount": 1,
    "errors": [
      {
        "eventIndex": 1,
        "field": "conversionType",
        "message": "conversionType is required"
      },
      {
        "eventIndex": 1,
        "field": "eventTime",
        "message": "eventTime is required"
      }
    ]
  }
}

Échec (tous les événements invalides) :

{
  "data": {
    "code": "Failure",
    "processedCount": 0,
    "invalidCount": 1,
    "errors": [
      {
        "eventIndex": 0,
        "field": "eventTime",
        "message": "must be a valid RFC3339 timestamp"
      }
    ]
  }
}