Ads

Créer des conversions personnalisées Meta Ads via l'API

Deux routes créent et listent les conversions personnalisées du compte publicitaire du client. Vous définissez la conversion par la règle qui la déclenche, une URL ou un événement du pixel, et utilisez l'id dans l'ensemble d'annonces, sans implémenter l'API Meta ni passer par l'app review.

L'appel

POST /api/ads/facebook_ads/custom-conversions?customer_integration=<connection uuid>
Authorization: Bearer <merchant token>
x-customer-token: <customer token>
Idempotency-Key: <unique key>

{
  "name": "Purchase completed",
  "pixel_id": "900000000000001",
  "rule": {
    "url_contains": "/obrigado"
  },
  "event_type": "purchase"
}

Ce que vous pouvez faire

  • Créer une conversion avec POST /ads/facebook_ads/custom-conversions, par la règle rule.url_contains ou rule.event.
  • Choisir la catégorie avec event_type, comme purchase, lead, add_to_cart ou subscribe.
  • Lister les conversions du compte avec GET /ads/facebook_ads/custom-conversions.
  • Utiliser l'id dans adset.facebook_ads.promoted_object.custom_conversion_id sur un ensemble d'annonces.

Règles et limites

  • La conversion est définie par la règle, et rule accepte exactement l'une des clés : url_contains ou event. pixel_id est obligatoire.
  • La règle par URL est celle vérifiée sur un compte réel. La règle par événement existe dans le contrat, mais la plateforme la refuse sur certains pixels, et ce refus arrive sous forme d'ads_integration_error.
  • event_type accepte un ensemble fermé de valeurs. En dehors, la réponse est 422 avec la liste. Sans event_type, la plateforme reçoit other.
  • Idempotency-Key est obligatoire et va dans le header. La conversion créée apparaît dans la liste suivante sans refresh.
  • La liste n'est pas paginée (200 éléments maximum) et mise en cache 600 s par connexion.

Champs principaux

ChampTypeObligatoireDescription
namestringOuiNom de la conversion personnalisée, 255 caractères maximum.
pixel_idstringOuiLe pixel derrière la règle. Obligatoire : sans lui la plateforme refuse la création. Il vient de GET /ads/facebook_ads/pixels.
rule.url_containsstringNonSe déclenche quand l'adresse visitée contient ce fragment. Utilisez cette clé ou rule.event, jamais les deux.
rule.eventstringNonSe déclenche quand le pixel signale cet événement. Utilisez cette clé ou rule.url_contains, jamais les deux.
event_typestringNonLa catégorie de la conversion, comme purchase, lead ou add_to_cart. Omis, la plateforme reçoit other.
Idempotency-KeystringOuiHeader obligatoire, 255 caractères maximum. Générez-la une fois et renvoyez la même à chaque nouvelle tentative.

Pour qui

  • Conversion de page de remerciement

    Votre SaaS crée une conversion avec url_contains "/obrigado" pour que le client optimise ses annonces sur les achats terminés.

  • Onboarding de campagnes en agence

    Une agence crée les conversions standard du client e-commerce (achat, lead), un appel idempotent par conversion.

  • Agent IA qui prépare la mesure

    Un agent liste les conversions, crée celle qui manque et utilise son id dans le nouvel ensemble d'annonces.

Fonctionne avec

  • Meta Ads

Questions fréquentes

Puis-je créer la conversion à partir d'un événement du pixel ?

Le contrat accepte rule.event, mais la plateforme refuse cette forme sur certains pixels, et le refus arrive sous forme d'ads_integration_error. La règle par URL (rule.url_contains) est celle vérifiée sur un compte réel.

Dois-je fournir le pixel ?

Oui. pixel_id est obligatoire, car la plateforme refuse la création sans le pixel derrière la règle. Listez les pixels avec GET /ads/facebook_ads/pixels.

Où utiliser l'id de la conversion ?

Dans adset.facebook_ads.promoted_object.custom_conversion_id, sur l'ensemble d'annonces.

Voir aussi

Voir tout ce que vous pouvez faire avec Ads

Voyez Connect appliqué à votre produit.

Essayez-le pendant 15 jours sans carte, ou présentez votre cas à notre équipe.