Ads
Créer une annonce sur Meta Ads, Google Ads et TikTok Ads via l'API
Un seul POST /ads crée l'annonce et, si vous le souhaitez, la campagne et l'ensemble au-dessus. Chaque niveau utilise un niveau existant ({"id": ...}) ou décrit le nouveau. Si une étape échoue, ce qui a été créé est annulé et rien ne reste en train de dépenser. Sur Google Ads, le même POST /ads crée des annonces Demand Gen et des groupes d'éléments Performance Max. Sur TikTok Ads, il crée une annonce vidéo dans une campagne Trafic, Couverture ou Vues de vidéo.
L'appel
POST /api/ads?customer_integration=<connection uuid>
Authorization: Bearer <merchant token>
x-customer-token: <customer token>
Idempotency-Key: <unique key>
{
"name": "Black Friday, imagem",
"status": "active",
"campaign": {
"name": "Black Friday",
"budget": {
"amount": 50,
"type": "daily"
},
"facebook_ads": {
"objective": "traffic",
"special_ad_categories": []
}
},
"adset": {
"name": "BR 25-45",
"schedule": {
"start": "2026-11-20T00:00:00-03:00"
},
"targeting": {
"countries": [
"BR"
],
"age_min": 25,
"age_max": 45
},
"facebook_ads": {
"optimization_goal": "link_clicks",
"billing_event": "impressions",
"placements": {
"publisher_platforms": [
"facebook",
"instagram"
]
},
"targeting": {
"interests": [
{
"id": "6003139266461",
"name": "Moda"
}
],
"advantage_audience": false
}
}
},
"ad": {
"format": "image",
"headline": "Black Friday",
"body": "Up to 50% off",
"link_url": "https://loja.com/bf",
"call_to_action": "shop_now",
"media": [
{
"type": "image",
"url": "https://cdn.loja.com/bf.jpg"
}
],
"facebook_ads": {
"page_id": "1068595869664481"
}
}
}Ce que vous pouvez faire
- Créer campagne, ensemble et annonce en un seul appel.
- Réutiliser une campagne ou un ensemble existant en passant {"id": ...}.
- Diffuser une image (par url ou hash) ou une vidéo (par url ou id, avec thumbnail_url).
- Utiliser deux fichiers du même visuel, un pour le feed et un pour stories et reels, avec placements.
- Définir la page et le compte Instagram qui publient l'annonce dans le bloc facebook_ads.
- Demander status active pour activer l'arbre à la fin.
- Sur Google Ads, créer une annonce Demand Gen, avec une campagne et un groupe d'annonces nouveaux ou existants.
- Sur Google Ads, créer un groupe d'éléments Performance Max, ou ajouter des éléments à un groupe existant, avec titres, titres longs, descriptions, images, vidéos et logo dans le bloc google_adwords.
- Sur TikTok Ads, créer une annonce vidéo avec couverture, dans une campagne Trafic, Couverture ou Vues de vidéo et un groupe d'annonces nouveaux ou existants, diffusée sous l'un des comptes TikTok de GET /ads/tiktok_ads/identities.
Règles et limites
- Tout est créé en pause. Le status demandé est appliqué à la dernière étape, quand tout l'arbre existe.
- Idempotency-Key est obligatoire dans le header. Répéter avec la même clé renvoie 200 avec Idempotent-Replay: true.
- Si une étape de création échoue, ce qui a été créé est annulé dans l'ordre inverse ; ce qui n'a pas pu l'être figure dans created. Répéter avec la même clé reprend là où cela s'est arrêté.
- À l'activation, seuls les niveaux créés par cet appel sont activés ; les niveaux référencés par id ne sont pas touchés.
- Une vidéo encore en traitement renvoie 409 ads_video_not_ready. Répétez avec la même clé : la vidéo et les niveaux déjà créés sont réutilisés.
- campaign est interdit quand adset.id est envoyé. La page doit appartenir au compte de la connexion.
- La réponse est synchrone : 201 avec le résultat.
- Sur Google Ads, images, vidéos et logos passent par l'asset_id de POST /ads/google_adwords/media. Une nouvelle campagne prend un budget quotidien et google_adwords.type : demand_gen ou performance_max.
- Performance Max n'a pas d'annonces : le groupe d'éléments porte le visuel, donc la réponse est l'ensemble. Une campagne qui n'est ni Demand Gen ni Performance Max répond 422 ads_unsupported_operation.
- Sur TikTok Ads, l'annonce est une vidéo : ad.body (jusqu'à 100 caractères), link_url, call_to_action et, dans le bloc tiktok_ads, identity_id, identity_type, video_id et cover_image_id, ces deux derniers venant de POST /ads/tiktok_ads/media. Une nouvelle campagne prend tiktok_ads.objective (traffic, reach ou video_views) et, si vous le souhaitez, un budget, qu'elle répartit entre ses groupes (CBO) ; sans lui, le nouveau groupe prend un budget quotidien ou total. Le nouveau groupe prend aussi targeting.countries ou tiktok_ads.location_ids. Avant la première écriture, tout est vérifié dans le compte par des lectures seulement.
Champs principaux
| Champ | Type | Obligatoire | Description |
|---|---|---|---|
| name | string | Oui | Nom de l'annonce, et des niveaux créés qui n'en ont pas. |
| status | string | Non | État final de l'arbre (active ou paused). Tout est créé en pause et l'activation est la dernière étape. |
| campaign | object | Non | {"id": ...} utilise une campagne existante ; sans id, décrit celle à créer. Interdit quand adset.id est envoyé. |
| adset | object | Oui | {"id": ...} utilise un ensemble existant ; sans id, décrit celui à créer. |
| ad.format | string | Oui | image ou video. |
| ad.link_url | string | Oui | URL de destination de l'annonce. |
| ad.call_to_action | string | Non | Bouton de l'annonce. Valeurs dans GET /ads/options. |
| ad.media | array | Oui | Un fichier pour tous les emplacements, ou deux (version feed et version story) avec placements. Image par url ou hash ; vidéo par url ou id. Meta Ads uniquement. |
| ad.facebook_ads.page_id | string | Oui | Page qui publie l'annonce. Doit être une page du compte de la connexion. Meta Ads uniquement. |
| ad.facebook_ads.instagram_account_id | string | Non | Compte Instagram qui publie l'annonce. |
| campaign.google_adwords.type | string | Non | Google Ads, sur une nouvelle campagne : demand_gen ou performance_max. Un budget quotidien l'accompagne. |
| ad.titles | array | Non | Google Ads : les titres. Demand Gen, de 1 à 5 de 40 caractères maximum ; Performance Max, de 3 à 15 de 30 maximum. |
| ad.google_adwords.images | array | Non | Google Ads : les images, chacune avec field (marketing, square, portrait, logo ou landscape_logo) et asset_id. |
| campaign.tiktok_ads.objective | Non | TikTok Ads, sur une nouvelle campagne : traffic, reach ou video_views. | |
| ad.body | Non | Texte principal de l'annonce. Sur TikTok Ads, jusqu'à 100 caractères. | |
| ad.tiktok_ads.identity_id | Non | TikTok Ads : le compte TikTok sous lequel l'annonce est diffusée, de GET /ads/tiktok_ads/identities, avec son type dans identity_type. | |
| ad.tiktok_ads.video_id | Non | TikTok Ads : l'id de la vidéo de POST /ads/tiktok_ads/media, une fois ready. | |
| ad.tiktok_ads.cover_image_id | Non | TikTok Ads : l'image_id de la couverture, de POST /ads/tiktok_ads/media, au format de la vidéo. |
Pour qui
Créateur d'annonces dans votre produit
Le client choisit visuel, texte et audience et vous publiez l'annonce complète dans son compte, sans construire le flux OAuth de Meta.
Agence qui charge des visuels à grande échelle
Réutilisez une campagne et un ensemble existants et créez des dizaines d'annonces en ne changeant que le média et le texte.
Agent IA qui génère des visuels
L'agent crée l'annonce en pause, valide d'abord avec POST /ads/validate et n'active qu'après approbation.
Fonctionne avec
Meta Ads
Google Ads
TikTok Ads
Questions fréquentes
L'annonce est-elle diffusée dès la fin de l'appel ?
Seulement si vous envoyez status active. Même dans ce cas, tout est créé en pause et l'activation est la dernière étape.
Et si l'appel échoue en cours de route ?
Ce qui a déjà été créé est annulé et rien ne reste en dépense. Ce qui n'a pas pu l'être figure dans created. En rejouant avec la même Idempotency-Key, l'appel reprend là où il s'est arrêté.
Est-ce que ça fonctionne sur Google Ads et TikTok Ads ?
Oui, sur les campagnes Demand Gen et Performance Max. Le corps est le même POST /ads, avec les champs de Google dans le bloc google_adwords. Sur Performance Max, la réponse est le groupe d'éléments, car il n'y a pas d'annonce. Sur TikTok Ads, sur les campagnes Trafic, Couverture et Vues de vidéo avec une annonce vidéo, avec les champs de TikTok dans le bloc tiktok_ads.
Voyez Connect appliqué à votre produit.
Essayez-le pendant 15 jours sans carte, ou présentez votre cas à notre équipe.
