ChatGPT Ads
Publicité ChatGPT

Conversions API (mesure de conversion côté serveur)

Idée centrale

La Conversions API permet d'envoyer des événements de conversion directement depuis le serveur d'un annonceur ou d'un partenaire de mesure vers OpenAI, en complément du Pixel de mesure JavaScript (Measurement Pixel) côté navigateur. La documentation la présente comme « une source de suivi plus fiable que le pixel seul » (« a more reliable tracking source than the pixel alone »), avec une recommandation explicite de l'utiliser autant que possible.

Définition

Le point de terminaison POST https://bzr.openai.com/v1/events, distinct de l'API REST api.ads.openai.com documentée par les pages « api-reference/* », qui reçoit des lots d'événements de conversion envoyés uniquement depuis un serveur (jamais depuis un navigateur).

Contexte

Documente la page « Conversions API » de la documentation développeur Ads. Architecture cible hybride : le pixel et la Conversions API sont conçus comme des canaux complémentaires, pas concurrents, avec un mécanisme de déduplication explicite et un champ (obref) conçu pour faire le pont entre les deux. Les identifiants consommés ici (Pixel ID, clé Conversions API) sont provisionnés via Configuration de la mesure de conversion dans l'API Ads (Conversion Setup). Capturée le 2026-08-08.

Fonctionnement

Envoi des événements

Requête POST vers https://bzr.openai.com/v1/events?pid=<PIXEL-ID>, en-têtes Authorization: Bearer <API-KEY> et Content-Type: application/json :

curl -X POST "https://bzr.openai.com/v1/events?pid=<PIXEL-ID>" \
  -H "Authorization: Bearer <API-KEY>" \
  -H "Content-Type: application/json" \
  --data '{
    "validate_only": false,
    "events": []
  }'

Le Pixel ID et la clé Conversions API se provisionnent depuis l'onglet « conversions » d'Ads Manager, ou par programmation via Configuration de la mesure de conversion dans l'API Ads (Conversion Setup) pour les partenaires API approuvés.

Champs de premier niveau de la requête

ChampRequisDescription
pidOuiPixel ID, en paramètre de requête dans l'URL (pas dans le corps).
validate_onlyNonValide les événements sans les enregistrer lorsque true.
integration_sourceNonIdentifiant stable de l'intégration qui envoie le lot (voir ci-dessous).
eventsOuiLe tableau des événements à envoyer.

Limite de lot : jusqu'à 1 000 événements. Si un seul événement du lot échoue, tout le lot échoue.

Identifier les intégrations partenaires (integration_source)

Si des événements sont envoyés pour le compte d'annonceurs, inclure integration_source au niveau racine de chaque requête. Les partenaires de mesure mobile (MMP, voir Intégrations de partenaires de mesure dans Ads Manager) et autres intégrations doivent utiliser le même identifiant stable sur chaque requête (exemples : acme_measurement, example_analytics). Format : 1 à 64 caractères ASCII, commençant par une lettre ou un chiffre, composés de lettres, chiffres, points, tirets bas ou traits d'union. L'API supprime les espaces superflus et convertit en minuscules avant validation. Ce champ n'affecte ni l'authentification ni l'autorisation — c'est un identifiant déclaratif, pas un mécanisme de sécurité.

Structure d'un événement (events[])

ChampRequisDescription
idOuiIdentifiant unique de l'événement, propre à l'annonceur. Utilisé avec type pour la déduplication.
typeOuiUn nom d'événement standard pris en charge, ou custom — voir Événements de conversion pris en charge par l'API Ads (Supported Events).
timestamp_msOuiHeure de l'événement en millisecondes. Dans les 7 derniers jours, au maximum 10 minutes dans le futur.
custom_event_nameSelon casRequis lorsque type vaut custom.
opprefNonIdentifiant préservant la confidentialité, fourni par OpenAI. Contrairement au pixel, l'API ne le capture pas automatiquement : sa valeur doit être capturée et transmise par l'appelant.
source_urlSelon casRequis lorsque action_source vaut web.
action_sourceSelon casweb, mobile_app, offline, physical_store, phone_call, email, other. Pour app_installed et app_opened : obligatoirement mobile_app.
userNonChamps utilisateur optionnels — voir ci-dessous.
opt_outNontrue pour exclure l'événement de la personnalisation future. Défaut false.
dataOuiDonnées de l'événement, forme attendue selon le type — voir Événements de conversion pris en charge par l'API Ads (Supported Events).

Envoi de données utilisateur (events[].user)

Optionnel, imbriqué à l'intérieur de chaque événement (pas à la racine de la requête) :

{
  "obref": "123e4567-e89b-42d3-a456-426614174000",
  "email_sha256": "b4c9a289323b21a01c3e940f150eb9b8c542587f1abfd8f0e1cc1ffc5e475514",
  "external_id_sha256": "73d83a078369bb4f0971b317aa7797a91cf5c0df1b62161c2e47d75c33ab5b6e",
  "country": "US",
  "city": "San Francisco",
  "zip_code": "94107",
  "ip_address": "203.0.113.1",
  "user_agent": "Mozilla/5.0"
}
ChampDescription
obrefRéférence navigateur opaque provenant du cookie __obref du pixel. À transmettre sans la hacher.
email_sha256Hash SHA-256 de l'e-mail, minuscules, espaces supprimés.
external_id_sha256Hash SHA-256 d'un identifiant client pseudonyme stable propre à l'annonceur.
countryCode pays ISO 3166-1 à deux lettres.
cityNom de ville, 128 caractères max, minuscules, espaces supprimés côté OpenAI.
zip_codeCode postal, 32 caractères max.
ip_addressAdresse IPv4 ou IPv6 valide.
user_agentChaîne user-agent non vide du client ayant généré l'événement.

Intégration hybride pixel + API : lire le cookie first-party __obref côté navigateur, le transmettre au serveur, l'inclure inchangé comme events[].user.obref. Respecter les exigences de consentement du site avant de collecter ou transmettre ce cookie ; arrêter son envoi si l'utilisateur révoque son consentement. À la différence de oppref (niveau événement), obref appartient à l'intérieur de user (niveau utilisateur).

Format : hachages en chaînes hexadécimales de 64 caractères minuscules ; champs géographiques, IP et user-agent en valeurs brutes. Ne jamais envoyer d'adresses e-mail brutes, d'identifiants externes bruts, de numéros de téléphone, ni de hashs de numéros de téléphone.

Exemple complet de requête

curl -X POST "https://bzr.openai.com/v1/events?pid=<PIXEL-ID>" \
  -H "Authorization: Bearer <API-KEY>" \
  -H "Content-Type: application/json" \
  --data '{
    "validate_only": false,
    "events": [
      {
        "id": "order_12345",
        "type": "order_created",
        "timestamp_ms": 1773892800000,
        "oppref": "oppref_abc",
        "source_url": "https://shop.example.com/checkout/confirmation",
        "action_source": "web",
        "user": {
          "obref": "123e4567-e89b-42d3-a456-426614174000",
          "email_sha256": "b4c9a289323b21a01c3e940f150eb9b8c542587f1abfd8f0e1cc1ffc5e475514",
          "country": "US",
          "city": "San Francisco",
          "zip_code": "94107",
          "ip_address": "203.0.113.1",
          "user_agent": "Mozilla/5.0"
        },
        "data": {
          "type": "contents",
          "amount": 2599,
          "currency": "USD",
          "contents": [
            { "id": "sku_123", "name": "Starter bundle", "content_type": "product", "quantity": 1 }
          ]
        }
      }
    ]
  }'

Événements de cycle de vie applicatif (app_installed, app_opened)

Utiliser le Pixel ID d'une source de données web existante ; envoyer ces deux événements depuis le serveur avec action_source: "mobile_app", forme de données customer_action :

{
  "id": "app_installed_123",
  "type": "app_installed",
  "timestamp_ms": 1773892800000,
  "action_source": "mobile_app",
  "data": { "type": "customer_action" }
}

La configuration native d'un SDK mobile et les sources de données mobiles ne sont pas actuellement prises en charge — ces deux événements passent exclusivement par la Conversions API, jamais par le pixel navigateur.

Déduplication entre événements navigateur et serveur

Si le même événement de conversion est envoyé par le pixel et par la Conversions API : réutiliser la même valeur comme id côté API et event_id côté pixel ; envoyer les deux événements avec le même Pixel ID ; pour un événement personnalisé, utiliser aussi le même custom_event_name des deux côtés.

Éléments essentiels

Distinctions importantes

Ne pas confondre oppref (niveau événement, capturé automatiquement par le pixel mais pas par la Conversions API) et obref (niveau utilisateur, capturé par le pixel via cookie __obref, transmis manuellement à l'API).

Ne pas confondre l'authentification de cette API (Pixel ID en paramètre d'URL + clé Conversions API en Bearer token, toutes deux issues de Configuration de la mesure de conversion dans l'API Ads (Conversion Setup)) avec l'authentification de l'API REST api.ads.openai.com ($OPENAI_ADS_API_KEY, documentée dans Authentification, compte publicitaire et fichiers dans l'API Ads) : deux mécanismes distincts, malgré la présence du mot « Bearer » dans les deux cas.

Cas pratiques

Aucun cas pratique disponible : identifiants et valeurs d'exemple (order_12345, Acme) manifestement fictifs et illustratifs.

Erreurs fréquentes

Ne pas envoyer app_installed ou app_opened via le pixel JavaScript : ces deux événements ne sont pris en charge que par la Conversions API, avec action_source: "mobile_app".

Ne pas s'attendre à ce que oppref soit capturé automatiquement par cette API comme il l'est par le pixel : sa valeur doit être capturée et transmise explicitement par l'appelant.

Ne pas envoyer un lot de 1 000 événements en production sans validation préalable : si un seul événement échoue, tout le lot échoue — envisager validate_only: true en amont pour les envois à fort volume.

Limites et nuances

Relations

Points à vérifier

Sources