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

ChampTypeObligatoireDescription
namestringOuiNom de l'annonce, et des niveaux créés qui n'en ont pas.
statusstringNonÉtat final de l'arbre (active ou paused). Tout est créé en pause et l'activation est la dernière étape.
campaignobjectNon{"id": ...} utilise une campagne existante ; sans id, décrit celle à créer. Interdit quand adset.id est envoyé.
adsetobjectOui{"id": ...} utilise un ensemble existant ; sans id, décrit celui à créer.
ad.formatstringOuiimage ou video.
ad.link_urlstringOuiURL de destination de l'annonce.
ad.call_to_actionstringNonBouton de l'annonce. Valeurs dans GET /ads/options.
ad.mediaarrayOuiUn 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_idstringOuiPage qui publie l'annonce. Doit être une page du compte de la connexion. Meta Ads uniquement.
ad.facebook_ads.instagram_account_idstringNonCompte Instagram qui publie l'annonce.
campaign.google_adwords.typestringNonGoogle Ads, sur une nouvelle campagne : demand_gen ou performance_max. Un budget quotidien l'accompagne.
ad.titlesarrayNonGoogle Ads : les titres. Demand Gen, de 1 à 5 de 40 caractères maximum ; Performance Max, de 3 à 15 de 30 maximum.
ad.google_adwords.imagesarrayNonGoogle Ads : les images, chacune avec field (marketing, square, portrait, logo ou landscape_logo) et asset_id.
campaign.tiktok_ads.objectiveNonTikTok Ads, sur une nouvelle campagne : traffic, reach ou video_views.
ad.bodyNonTexte principal de l'annonce. Sur TikTok Ads, jusqu'à 100 caractères.
ad.tiktok_ads.identity_idNonTikTok 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_idNonTikTok Ads : l'id de la vidéo de POST /ads/tiktok_ads/media, une fois ready.
ad.tiktok_ads.cover_image_idNonTikTok 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.

Voir aussi

Voir tout ce que vous pouvez faire avec Ads

Voyez Connect appliqué à votre produit.

Essayez-le pendant 15 jours sans carte, ou présentez votre cas à notre équipe.