Ads
Voir les annonces Meta Ads de tous vos clients via l'API
Trois routes sous /merchants/ads donnent la vue d'ensemble des campagnes, ensembles et annonces de tous vos clients, avec le seul token du merchant et sans x-customer-token. Vous surveillez toute la base en un appel, sans parcourir client par client et sans implémenter l'API Meta.
L'appel
GET /api/merchants/ads/campaigns?customer=<customer uuid>&effective_status=disapproved&per_page=50 Authorization: Bearer <merchant token>
Ce que vous pouvez faire
- Lister campagnes, ensembles et annonces de tous les clients avec GET /merchants/ads/campaigns, /merchants/ads/adsets et /merchants/ads.
- Restreindre à un client avec customer ou à un compte avec customer_integration.
- Filtrer par status et par effective_status, comme disapproved, with_issues ou pending_review.
- Identifier le propriétaire de chaque objet via customer_uuid et customer_integration_uuid.
- Inclure les supprimés avec include_deleted=true et paginer avec page et per_page.
Règles et limites
- Ces routes n'utilisent que Authorization: Bearer. Pas de x-customer-token, et customer et customer_integration sont des filtres, jamais un identifiant.
- Elles montrent ce que Connect stocke : ce qu'il a créé ou déjà écrit dans les comptes. Un compte avec d'anciennes campagnes n'apparaît qu'après la première écriture via Connect.
- Les données sont le dernier état connu, avec synced_at. refresh=true relit les objets de la réponse, mais exige customer_integration.
- Le customer et la connexion fournis doivent appartenir au merchant du token. Avec les deux, la connexion doit appartenir à ce client.
- per_page va de 1 à 100 (15 par défaut) et la réponse est {data, links, meta}.
Champs principaux
| Champ | Type | Obligatoire | Description |
|---|---|---|---|
| customer | string | Non | L'uuid d'un de vos clients. Sans lui, la réponse inclut tous les clients. |
| customer_integration | string | Non | L'uuid d'une connexion de l'un de vos clients, pour se limiter à un seul compte. Avec customer, la connexion doit appartenir à ce client. |
| status | string | Non | Filtre par le dernier statut connu : active ou paused. |
| effective_status | string | Non | Filtre par le dernier statut effectif vu, comme pending_review, disapproved ou with_issues. |
| refresh | boolean | Non | Relit les objets de la réponse sur la plateforme et met Connect à jour. Exige customer_integration. |
| include_deleted | boolean | Non | Inclut les objets supprimés, avec deleted_at. |
| per_page | integer | Non | Éléments par page, de 1 à 100. La valeur par défaut est 15. |
| customer_uuid | string | Non | Dans la réponse : le client propriétaire du compte de chaque objet. |
Pour qui
Surveiller les annonces refusées sur toute la base
Un SaaS de trafic liste avec effective_status=disapproved et prévient chaque client concerné, sans interroger compte par compte.
Vue du gestionnaire dans une agence
Une agence voit les campagnes actives de tous les clients sur un seul écran, en filtrant par client pour approfondir.
Agent IA de support
Un agent reçoit la question d'un client, filtre par customer et répond ce qui est actif, en pause ou en difficulté.
Fonctionne avec
Meta Ads
Questions fréquentes
Ai-je besoin de x-customer-token sur ces routes ?
Non. Elles n'utilisent que le Bearer du merchant. Le client et la connexion sont des filtres (customer et customer_integration), vérifiés par rapport à votre merchant.
En quoi est-ce différent de GET /ads/campaigns ?
GET /ads/campaigns concerne un client, avec x-customer-token et une connexion obligatoire. La route /merchants/ads couvre tous les clients et montre ce que Connect stocke.
Les données sont-elles à jour ?
C'est le dernier état connu, indiqué dans synced_at. Pour le mettre à jour, utilisez refresh=true avec customer_integration.
Voyez Connect appliqué à votre produit.
Essayez-le pendant 15 jours sans carte, ou présentez votre cas à notre équipe.
