API de conversion Meta (CAPI) : installer, dédupliquer et fiabiliser vos événements

Qu’est-ce que l’API de conversion Meta ?

L’API de conversion Meta (Conversions API, ou CAPI) est une connexion qui envoie vos événements marketing directement depuis votre serveur, votre plateforme e-commerce ou votre CRM vers les systèmes de Meta, sans passer par le navigateur de l’internaute. Là où le Pixel Meta s’exécute dans la page et dépend du navigateur, l’API transmet un achat, un lead ou une inscription de serveur à serveur.

Meta décrit l’API comme un pont entre vos données marketing et ses systèmes, utilisé pour optimiser la diffusion des publicités et mesurer leurs résultats (voir la documentation Conversions API). Les événements serveur sont rattachés au même identifiant de jeu de données que le Pixel et traités de la même façon.

Concrètement, l’API ne remplace pas le Pixel : elle le complète. C’est la pièce centrale d’un dispositif de tracking publicitaire solide, parce qu’elle donne à Meta un second canal pour recevoir les conversions qui comptent vraiment pour votre activité.

Pourquoi utiliser l’API Conversions en plus du Pixel Meta ?

Parce que le Pixel seul perd une partie des événements, et que Meta recommande explicitement une configuration redondante où les mêmes événements sont envoyés par le Pixel et par l’API. Selon les {ext('best', 'bonnes pratiques Meta')}, ce double envoi permet de récupérer des événements que le Pixel manque à cause de problèmes de connexion ou d’erreurs de chargement de page.

Dans nos audits, les causes de perte côté navigateur reviennent toujours : bloqueurs de publicité, page de confirmation qui ne se charge pas complètement, paiement finalisé sur un domaine tiers, application mobile qui ouvre un navigateur intégré. Le serveur, lui, sait qu’une commande a été payée, quelle que soit la façon dont la page s’est affichée.

Le bénéfice ne se limite pas au volume. Un événement serveur peut porter des informations fiables issues du back-office (valeur réelle de la commande, identifiant client, statut) et des paramètres clients hachés qui améliorent la correspondance avec les comptes Meta. C’est ce signal plus riche qui aide l’algorithme à trouver des acheteurs, et donc le travail de notre agence Meta Ads à reposer sur des résultats exploitables.

Comment dédupliquer les événements du Pixel et de l’API ?

Pour que Meta ne compte pas deux fois le même achat, le Pixel et l’API doivent envoyer le même nom d’événement et le même identifiant : eventID côté Pixel, event_id côté serveur. C’est la méthode recommandée dans la {ext('dedup', 'documentation Meta sur la déduplication')}.

Les règles à connaître

• Le nom d’événement du Pixel (event) doit correspondre à event_name côté API, par exemple Purchase des deux côtés.
• L’identifiant doit distinguer chaque événement : pour un achat, le numéro de commande est le choix le plus robuste.
• Meta ne déduplique que les événements reçus dans les 48 heures qui suivent la réception du premier événement portant cet event_id.
• Quand les deux versions ne diffèrent pas réellement, Meta indique conserver en général celle reçue en premier.

Une méthode alternative existe, fondée sur event_name combiné à fbp ou external_id. Elle est moins fiable : Meta précise qu’un événement serveur n’est pas écarté si aucun événement navigateur identique n’a été reçu au cours des 48 heures précédentes, même si ce dernier arrive ensuite. Nous l’utilisons seulement en dernier recours.

L’erreur la plus fréquente

Générer l’identifiant deux fois : une valeur aléatoire dans le navigateur, une autre sur le serveur. Les deux événements arrivent, aucun ne se reconnaît, et les achats sont doublés dans le gestionnaire de publicités. L’identifiant doit être créé une seule fois (idéalement à partir de la commande) puis transmis aux deux canaux.

Qu’est-ce que la qualité de correspondance des événements et comment l’améliorer ?

La qualité de correspondance des événements (Event Match Quality, EMQ) est une note sur 10, visible dans le gestionnaire d’événements, qui indique dans quelle mesure les informations client d’un événement permettent à Meta de le rattacher à un compte. Meta précise dans ses bonnes pratiques qu’une meilleure correspondance produit de meilleurs résultats.

La note dépend des paramètres clients transmis avec chaque événement. Meta cite comme paramètres de qualité l’email (em), le téléphone (ph), l’adresse IP (client_ip_address), le prénom et le nom (fn, ln) ainsi que les cookies fbp et fbc, dont les valeurs doivent être rafraîchies régulièrement.

Ce qui doit être haché, et ce qui ne doit pas l’être

La page Customer Information Parameters fixe des règles précises. Les données personnelles comme l’email, le téléphone, le nom, la ville ou le code postal doivent être normalisées (espaces supprimés, minuscules, indicatif pays pour le téléphone) puis hachées en SHA-256. À l’inverse, l’adresse IP, le user agent, fbc et fbp ne doivent jamais être hachés.

Notre méthode : viser d’abord la conformité et la justesse, pas la note maximale. Nous ajoutons les paramètres réellement disponibles et autorisés, vérifions leur format, puis suivons l’évolution de la note événement par événement plutôt que de chercher un chiffre cible universel.

Quelles options d’intégration choisir : partenaire, Gateway ou GTM serveur ?

Le bon choix dépend de votre CMS, de vos ressources techniques et du nombre de plateformes publicitaires : l’intégration native d’un partenaire suffit souvent à une boutique Shopify, alors qu’un site sur mesure ou multi-plateformes justifie une intégration directe ou un conteneur serveur.

L’intégration partenaire

Sur Shopify, le canal Facebook & Instagram propose trois niveaux de partage de données. D’après l’aide Shopify, le niveau Standard repose sur le Pixel seul, tandis que les niveaux Enhanced et Maximum ajoutent l’API Conversions, dont les données transmises de serveur à serveur ne peuvent pas être bloquées par les bloqueurs de publicité du navigateur. C’est la voie la plus rapide, avec peu de maîtrise sur le détail des événements.

La Conversions API Gateway

La Conversions API Gateway est une option de configuration en libre-service depuis le gestionnaire d’événements, sans code. Elle est déployée dans un compte cloud appartenant à l’entreprise (AWS ou Google Cloud selon la documentation), et Meta indique que son seul coût correspond aux ressources cloud ou aux frais du partenaire d’hébergement. Pratique quand on veut un envoi serveur sans développement, elle reste centrée sur Meta.

L’intégration directe ou via Google Tag Manager côté serveur

L’intégration directe consiste à appeler l’API depuis votre back-office. Elle offre le plus de contrôle et convient aux sites sur mesure, aux tunnels de vente et aux leads qualifiés dans un CRM. Un conteneur Google Tag Manager côté serveur est une variante intéressante quand plusieurs plateformes (Meta, Google, TikTok) doivent recevoir les mêmes événements : un seul flux entrant, redistribué selon des règles communes.

L’API Conversions est-elle compatible avec le RGPD et le consentement ?

Oui, à condition qu’elle respecte exactement le choix exprimé dans votre bandeau cookies : sans consentement aux finalités publicitaires, aucun événement comportant des données personnelles ne doit partir vers Meta. Passer par un serveur ne change rien à cette règle. En France, la CNIL rappelle que le consentement préalable est requis avant de déposer ou de lire des traceurs non exemptés, et que refuser doit être aussi simple qu’accepter (CNIL, que dit la loi).

Le piège classique est l’envoi serveur « aveugle » : l’achat est transmis à Meta depuis le back-office alors que le client a refusé les cookies publicitaires. Techniquement, rien ne l’empêche ; juridiquement, c’est un contournement du refus. Chez Creapreneurs, nous faisons remonter l’état du consentement jusqu’au serveur et conditionnons l’envoi à cet état.

Deux précisions utiles. D’abord, l’option Limited Data Use de Meta concerne des États américains, pas l’Union européenne (Data Processing Options for US Users) : ce n’est pas une solution RGPD. Ensuite, la même logique s’applique côté Google avec le Consent Mode v2 : les deux dispositifs doivent lire le même signal de consentement.

Quels paramètres techniques vérifier avant de mettre en production ?

Avant la mise en production, vérifiez surtout action_source, event_source_url, event_time, event_id et la valeur de conversion, car ce sont eux qui conditionnent l’acceptation et l’utilité des événements. Les paramètres d’événement serveur documentés par Meta posent plusieurs contraintes.

• action_source est obligatoire et indique où la conversion a eu lieu (website, app, physical_store, system_generated…).
• event_source_url est exigé pour les événements web envoyés par l’API.
• event_time peut remonter jusqu’à 7 jours avant l’envoi : au-delà, l’événement n’est pas accepté. Un import tardif depuis un CRM doit en tenir compte.
• event_id est facultatif pour Meta, mais indispensable dès que le Pixel envoie le même événement.
• opt_out, s’il vaut true, limite l’usage de l’événement à l’attribution et l’exclut de l’optimisation de la diffusion.

Côté valeur, décidez une fois pour toutes ce que vous transmettez : chiffre d’affaires HT ou TTC, avec ou sans frais de port. Le choix importe moins que sa cohérence entre Pixel, API et reporting ; c’est lui qui rend votre calcul de ROAS comparable dans le temps.

Quelles erreurs faussent le plus souvent une intégration CAPI ?

Les erreurs qui coûtent le plus cher ne sont pas les pannes visibles, mais les intégrations qui semblent fonctionner tout en envoyant des données fausses : doublons, valeurs incohérentes ou événements déclenchés au mauvais moment. Voici celles que nous retrouvons le plus souvent en reprenant un compte.

• Deux intégrations en parallèle : l’application Shopify et un conteneur serveur envoient chacun leurs achats, avec des identifiants différents.
• Un Purchase envoyé à la création de commande plutôt qu’au paiement confirmé, ce qui gonfle les ventes avec des commandes abandonnées ou refusées.
• Une devise ou une valeur absente : l’événement est reçu, mais inutilisable pour optimiser sur la valeur.
• Des événements de test oubliés en production, ou un code de test laissé actif.
• Des emails non normalisés avant hachage (majuscules, espaces), qui dégradent silencieusement la correspondance.

Aucune de ces erreurs ne déclenche d’alerte bloquante. Elles se repèrent en comparant régulièrement les chiffres de Meta à ceux du back-office, ce que nous faisons avant toute décision d’augmenter un budget.

Check-list Creapreneurs pour une API de conversion Meta fiable

Une intégration CAPI est terminée quand chaque événement clé est reçu une seule fois, avec une valeur juste et des paramètres clients conformes, et que ce résultat a été vérifié sur des commandes réelles. Voici la liste que nous déroulons en recette.

1. Lister les événements utiles au pilotage : PageView, ViewContent, AddToCart, InitiateCheckout, Purchase ou Lead, pas davantage au départ.
2. Vérifier que le domaine est validé et que Pixel et API envoient vers le même jeu de données.
3. Contrôler, dans le gestionnaire d’événements, que chaque événement apparaît en « navigateur et serveur » et qu’il est bien dédupliqué.
4. Passer une commande test et retrouver le même event_id des deux côtés.
5. Comparer sur une semaine les achats remontés par Meta aux commandes du back-office, en gardant en tête que les règles d’attribution diffèrent.
6. Tester le parcours avec refus des cookies : aucun événement personnel ne doit partir.
7. Relire la note de qualité de correspondance par événement et corriger les formats de données.
8. Documenter le dispositif et prévoir un contrôle après chaque mise à jour de thème, d’application ou de tunnel.

Ce dernier point est souvent négligé. Une intégration fonctionne rarement mal dès le premier jour ; elle se dégrade silencieusement au fil des modifications du site. C’est pour cela que notre accompagnement en agence tracking publicitaire inclut un suivi dans la durée, et que nous relions ces contrôles aux décisions de budget prises en performance marketing.