Ads
Créer une campagne sur Meta Ads, Google Ads et TikTok Ads via l'API
Un appel crée la campagne dans le compte publicitaire que le client a connecté, sans implémenter l'API Meta ni passer par la revue d'app. Vous décrivez objectif et budget dans un vocabulaire unique et Connect gère le token et la traduction. La campagne est créée en pause : rien ne dépense avant que vous l'activiez. Sur Google Ads, la même route crée des campagnes Demand Gen et Performance Max, avec un budget quotidien et une stratégie d'enchères. Sur TikTok Ads, la route crée des campagnes Trafic, Couverture et Vues de vidéo, avec un budget quotidien ou total facultatif : avec lui, la campagne répartit le budget entre ses groupes (CBO) ; sans lui, chaque groupe d'annonces a le sien.
L'appel
POST /api/ads/campaigns?customer_integration=<connection uuid>
Authorization: Bearer <merchant token>
x-customer-token: <customer token>
Idempotency-Key: <unique key>
{
"name": "Black Friday",
"budget": {
"amount": 50,
"type": "daily"
},
"facebook_ads": {
"objective": "traffic",
"special_ad_categories": []
}
}Ce que vous pouvez faire
- Choisir l'objectif : awareness, traffic, engagement, leads, app_promotion ou sales.
- Définir le budget sur la campagne (CBO) ou le laisser à chaque ensemble (ABO).
- Utiliser un budget daily ou lifetime, dans la devise du compte du client.
- Envoyer special_ad_categories pour le crédit, l'emploi, le logement et la politique.
- Définir un plafond de dépense avec facebook_ads.spend_cap.
- Lire les valeurs acceptées via GET /ads/options?integration_slug=facebook_ads.
- Sur Google Ads, créer une campagne Demand Gen ou Performance Max avec google_adwords.type et son propre budget quotidien.
- Sur Google Ads, choisir les enchères dans google_adwords.bidding : maximize_conversions, avec target_cpa facultatif, ou maximize_conversion_value, avec target_roas facultatif.
- Sur Google Ads, lister les actions de conversion actives du compte avec GET /ads/google_adwords/conversion-actions ; les enchères optimisent pour celles qui ont primary_for_goal.
- Sur TikTok Ads, créer une campagne Trafic, Couverture ou Vues de vidéo avec tiktok_ads.objective: traffic, reach ou video_views.
Règles et limites
- Sans status, la campagne est créée en pause.
- Idempotency-Key est obligatoire dans le header. Répéter l'appel avec la même clé et le même corps renvoie 200 avec Idempotent-Replay: true, sans créer une autre campagne.
- Le budget est sur la campagne (CBO) ou sur chaque ensemble (ABO), jamais sur les deux. Il n'y a pas de champ level : le niveau est l'endroit où se trouve le budget.
- budget.amount est dans la devise du compte, jamais en centimes.
- facebook_ads.objective est obligatoire et ne change plus après la création.
- La réponse est synchrone : 201 avec la campagne créée. Réutiliser la clé avec un autre corps renvoie 422 idempotency_key_reused.
- Sur Google Ads, budget est obligatoire et uniquement daily : le budget est toujours sur la campagne. facebook_ads est refusé.
- Sur TikTok Ads, tiktok_ads.objective vaut traffic, reach ou video_views, et budget est facultatif sur la campagne, quotidien ou total : avec lui, la campagne répartit le budget entre ses groupes (CBO), qui ne prennent pas de budget ; le total exige schedule.end sur le groupe. facebook_ads est refusé aussi.
Champs principaux
| Champ | Type | Obligatoire | Description |
|---|---|---|---|
| name | string | Oui | Nom de la campagne. |
| status | string | Non | active ou paused. Sans ce champ, la campagne est créée en pause. |
| budget.amount | number | Oui | Montant dans la devise du compte publicitaire, jamais en centimes. Envoyer le budget ici rend la campagne CBO. |
| budget.type | string | Non | daily ou lifetime. lifetime exige schedule.end sur l'ensemble. |
| facebook_ads.objective | string | Oui | awareness, traffic, engagement, leads, app_promotion ou sales. Obligatoire à la création, non modifiable ensuite. Meta Ads uniquement. |
| facebook_ads.special_ad_categories | array | Non | Obligatoire pour le crédit, l'emploi, le logement et la politique. |
| facebook_ads.spend_cap | number | Non | Plafond de dépense de la campagne, dans la devise du compte. null le supprime. |
| google_adwords.type | string | Non | Google Ads : demand_gen ou performance_max. Obligatoire sur Google. |
| google_adwords.bidding | object | Non | Google Ads : strategy (maximize_conversions, par défaut, ou maximize_conversion_value) et, en option, target_cpa ou target_roas (4 vaut 400 %). |
| tiktok_ads.objective | Non | TikTok Ads : traffic, reach ou video_views. Obligatoire sur TikTok ; le budget de la campagne est facultatif (CBO). |
Pour qui
Plateforme publicitaire pour PME
Le client final renseigne objectif et budget dans votre produit et vous créez la campagne dans son compte, sans monter un flux OAuth avec Meta.
Agence avec son propre tableau de bord
Créez des campagnes standardisées pour plusieurs clients depuis un modèle, en ne changeant que le nom, l'objectif et le budget.
Agent IA de média payant
L'agent lit le vocabulaire dans GET /ads/options, construit la campagne et la laisse en pause pour qu'un humain la relise avant activation.
Fonctionne avec
Meta Ads
Google Ads
TikTok Ads
Questions fréquentes
La campagne dépense-t-elle dès sa création ?
Non. Sans status, elle est créée en pause. Vous l'activez quand vous voulez avec PATCH /ads/campaigns/{id} et status active.
Puis-je rejouer l'appel sans créer de doublon ?
Oui. Envoyez toujours la même Idempotency-Key. Si le premier appel a réussi, la répétition renvoie la même réponse avec Idempotent-Replay: true.
Le budget va-t-il sur la campagne ou sur l'ensemble ?
Sur l'un des deux. Avec budget sur la campagne, c'est du CBO ; sans, chaque ensemble porte le sien (ABO). L'envoyer au mauvais niveau renvoie 409 budget_level_mismatch.
Voyez Connect appliqué à votre produit.
Essayez-le pendant 15 jours sans carte, ou présentez votre cas à notre équipe.
