Ads
Créer un ensemble ou groupe d'annonces Meta, Google et TikTok Ads via l'API
Créez l'ensemble dans une campagne existante, dans le compte que le client a connecté : audience, calendrier, emplacements, objectif d'optimisation et enchère. Les champs communs à toute plateforme sont au premier niveau et ce qui est propre à Meta va dans le bloc facebook_ads. Sans revue d'app ni gestion de tokens. Sur Google Ads, la même route crée un groupe d'annonces dans une campagne Demand Gen. Sur TikTok Ads, elle crée un groupe d'annonces dans une campagne Trafic, Couverture ou Vues de vidéo, avec un budget quotidien ou total, un lieu, une audience et un calendrier.
L'appel
POST /api/ads/adsets?customer_integration=<connection uuid>
Authorization: Bearer <merchant token>
x-customer-token: <customer token>
Idempotency-Key: <unique key>
{
"campaign_id": "120250000000000001",
"name": "BR 25-45",
"budget": {
"amount": 20,
"type": "daily"
},
"targeting": {
"countries": [
"BR"
],
"age_min": 25,
"age_max": 45
},
"facebook_ads": {
"optimization_goal": "link_clicks",
"billing_event": "impressions"
}
}Ce que vous pouvez faire
- Cibler par pays, âge (age_min et age_max) et genres.
- Cibler par centres d'intérêt et audiences personnalisées, exclusions comprises, dans facebook_ads.targeting.
- Définir un calendrier avec schedule.start et schedule.end.
- Choisir les emplacements avec facebook_ads.placements.
- Choisir une enchère avec bid_strategy (lowest_cost, bid_cap, cost_cap) et bid_amount.
- Envoyer promoted_object, destination_type et attribution_spec à la création.
- Sur Google Ads, créer un groupe d'annonces dans une campagne Demand Gen avec seulement campaign_id, name et status.
- Sur TikTok Ads, créer un groupe d'annonces dans une campagne Trafic, Couverture ou Vues de vidéo, avec lieu, âge, genre, audiences, calendrier et objectif d'optimisation.
Règles et limites
- Idempotency-Key est obligatoire dans le header ; répéter avec la même clé renvoie 200 avec Idempotent-Replay: true.
- Sans status, l'ensemble est créé en pause.
- Le budget est sur la campagne (CBO) ou sur l'ensemble (ABO), jamais sur les deux. Un budget sur un ensemble d'une campagne CBO renvoie 409 budget_level_mismatch.
- budget.type lifetime exige schedule.end.
- facebook_ads.optimization_goal et facebook_ads.billing_event sont obligatoires ; les valeurs acceptées sont dans GET /ads/options.
- promoted_object (pixel, page ou conversion personnalisée) doit appartenir au compte de la connexion et ne vaut qu'à la création.
- bid_amount exige bid_strategy.
- Sur Google Ads, budget, schedule, targeting et facebook_ads sont refusés : le budget est sur la campagne. Sous une campagne Performance Max, la route répond 422 ads_unsupported_operation, et le groupe d'éléments est créé avec ses éléments par POST /ads.
- Sur TikTok Ads, targeting.countries ou tiktok_ads.location_ids est obligatoire, et facebook_ads est refusé. Si la campagne répartit le budget (CBO), le groupe ne prend pas de budget ; sans CBO, budget est obligatoire, quotidien ou total, et le total exige schedule.end. Sous une campagne avec CBO, budget sur le groupe répond 409 budget_level_mismatch. L'âge, le genre, tiktok_ads.audience_ids et schedule sont facultatifs ; sans schedule.start, il démarre maintenant. L'objectif vient de tiktok_ads.optimization_goal et l'enchère de tiktok_ads.bid_strategy (lowest_cost ou cost_cap avec bid_amount) ; tiktok_ads.frequency ne vaut que sur Couverture. Le groupe diffuse uniquement sur l'emplacement TikTok. Sous une campagne d'un autre objectif, la route répond 422 ads_unsupported_operation.
Champs principaux
| Champ | Type | Obligatoire | Description |
|---|---|---|---|
| campaign_id | string | Oui | La campagne, par son id ou par l'uuid Connect. |
| name | string | Oui | Nom de l'ensemble de publicités. |
| budget.amount | number | Non | Budget de l'ensemble (ABO), dans la devise du compte. Valable seulement si la campagne n'a pas de budget. |
| schedule.end | string | Non | Date de fin. Obligatoire quand budget.type vaut lifetime. |
| targeting.countries | array | Oui | Pays de l'audience, par exemple ["BR"]. Le reste du ciblage va dans facebook_ads.targeting. |
| facebook_ads.optimization_goal | string | Oui | Objectif d'optimisation. Obligatoire à la création ; valeurs dans GET /ads/options. Meta Ads uniquement. |
| facebook_ads.billing_event | string | Oui | Événement de facturation. Obligatoire à la création. Meta Ads uniquement. |
| facebook_ads.bid_strategy | string | Non | lowest_cost, bid_cap ou cost_cap. |
| facebook_ads.bid_amount | number | Non | Montant de l'enchère. Exige bid_strategy. |
| facebook_ads.targeting.interests | array | Non | Centres d'intérêt de l'audience, avec id et name. |
| tiktok_ads.location_ids | Non | Sur TikTok Ads : ids de lieu TikTok (États et régions), de GET /ads/targeting/search (type geo). Dans la réponse, les pays du groupe reviennent ici aussi, en ids de lieu. |
Pour qui
Constructeur de campagnes dans votre SaaS
Votre produit collecte l'audience (pays, âge, intérêts) dans son propre écran et crée l'ensemble dans le compte du client en un appel.
Tests A/B d'audience
Créez plusieurs ensembles dans la même campagne, en ne changeant que le ciblage, puis comparez les performances.
Agent IA qui suggère des audiences
L'agent propose le ciblage, crée l'ensemble en pause et le soumet à validation avant activation.
Fonctionne avec
Meta Ads
Google Ads
TikTok Ads
Questions fréquentes
Dois-je créer la campagne avant ?
Pour cette route, oui : campaign_id est obligatoire. Pour créer campagne, ensemble et annonce d'un coup, utilisez POST /ads.
Où mettre le budget ?
Sur l'ensemble seulement si la campagne n'a pas de budget (ABO). Si la campagne a un budget (CBO), envoyer budget sur l'ensemble renvoie 409 budget_level_mismatch.
Comment connaître les valeurs valides d'optimisation et de facturation ?
Dans GET /ads/options?integration_slug=facebook_ads. Une valeur invalide renvoie 422 validation_error avec supported_values.
Voyez Connect appliqué à votre produit.
Essayez-le pendant 15 jours sans carte, ou présentez votre cas à notre équipe.
