Ads
Lister campagnes, ensembles et annonces Meta Ads via l'API
Trois routes GET listent les campagnes, ensembles et annonces du compte publicitaire d'un client, avec statut, statut effectif, problèmes et budget. Vous choisissez de lire ce que Connect stocke ou le compte en direct, sans OAuth à développer ni app review Meta.
L'appel
GET /api/ads/campaigns?customer_integration=<connection uuid>&source=external&status=active&per_page=50 Authorization: Bearer <merchant token> x-customer-token: <customer token>
Ce que vous pouvez faire
- Lister campagnes, ensembles d'annonces et annonces avec GET /ads/campaigns, /ads/adsets et /ads.
- Lire le compte en direct avec source=external, y compris ce qui a été créé hors de Connect.
- Filtrer par status (active ou paused) et, avec source=connect, par effective_status, comme pending_review ou disapproved.
- Voir dans issues pourquoi la plateforme retient un objet, comme un refus ou un problème de diffusion.
- Filtrer ensembles et annonces par campaign_id et annonces par adset_id, et paginer avec page et per_page.
Règles et limites
- La valeur par défaut est source=connect : ce que Connect a créé ou déjà écrit dans le compte, sans appeler la plateforme. Un compte avec d'anciennes campagnes liste vide jusqu'à la première écriture via Connect.
- Pour voir tout le compte, utilisez source=external. La lecture en direct est mise en cache 120 s, et refresh=true ignore le cache.
- Chaque réponse contient synced_at, la dernière vérification de l'objet par Connect. Avec source=connect, refresh=true relit statut et nom des éléments de la page.
- per_page va de 1 à 100 (15 par défaut) et la réponse est {data, links, meta}. Avec source=external, pas de meta.total, et avec status la page peut dépasser un peu per_page.
- Les éléments stockés par Connect ont un uuid. Ceux qui n'existent que dans le compte ont uuid null. Le budget est dans la devise du compte, jamais en centimes.
Champs principaux
| Champ | Type | Obligatoire | Description |
|---|---|---|---|
| customer_integration | string | Oui | L'uuid de la connexion du client. Il définit le compte publicitaire. Toujours dans la query. |
| source | string | Non | connect (par défaut) lit ce que Connect a créé ou déjà écrit dans le compte. external lit le compte en direct, y compris ce qui a été créé hors de Connect. |
| status | string | Non | Filtre par active ou paused. |
| effective_status | string | Non | Uniquement avec source=connect. Filtre par le statut réellement appliqué par la plateforme, comme pending_review, disapproved ou with_issues. |
| refresh | boolean | Non | Avec source=external, ignore le cache de 120 s. Avec source=connect, relit statut et nom des éléments de la page et met Connect à jour. |
| per_page | integer | Non | Éléments par page, de 1 à 100. La valeur par défaut est 15. |
| campaign_id | string | Non | Uniquement sur /ads/adsets et /ads : filtre par l'id de la campagne ou l'uuid Connect. |
| include_deleted | boolean | Non | Uniquement avec source=connect. Inclut les objets supprimés, avec deleted_at. |
Pour qui
Tableau de bord de campagnes dans votre SaaS
Montrez au client ses campagnes actives, le budget et le statut effectif sans qu'il ouvre le Gestionnaire de publicités.
Alerte d'annonce refusée
Interrogez régulièrement avec effective_status=disapproved et prévenez l'équipe quand une annonce est refusée, avec le motif dans issues.
Agent IA qui audite les comptes
Un agent liste le compte en direct, repère les ensembles avec des problèmes de diffusion et propose de mettre en pause ou d'ajuster le budget.
Fonctionne avec
Meta Ads
Questions fréquentes
Pourquoi la liste est-elle vide sur un compte qui avait déjà des campagnes ?
Parce que la valeur par défaut est source=connect, qui ne montre que ce que Connect a créé ou déjà écrit dans le compte. Pour voir ce qui a été créé hors de Connect, utilisez source=external.
Les données sont-elles en temps réel ?
Avec source=external oui, avec un cache de 120 s que refresh=true ignore. Avec source=connect, vous voyez le dernier état connu, indiqué dans synced_at, et refresh=true le met à jour.
Comment filtrer uniquement ce qui pose problème ?
Utilisez effective_status avec des valeurs comme with_issues, disapproved ou pending_review (uniquement avec source=connect). Le motif est dans le champ issues.
Voyez Connect appliqué à votre produit.
Essayez-le pendant 15 jours sans carte, ou présentez votre cas à notre équipe.
