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

ChampTypeObligatoireDescription
namestringOuiNom de la campagne.
statusstringNonactive ou paused. Sans ce champ, la campagne est créée en pause.
budget.amountnumberOuiMontant dans la devise du compte publicitaire, jamais en centimes. Envoyer le budget ici rend la campagne CBO.
budget.typestringNondaily ou lifetime. lifetime exige schedule.end sur l'ensemble.
facebook_ads.objectivestringOuiawareness, traffic, engagement, leads, app_promotion ou sales. Obligatoire à la création, non modifiable ensuite. Meta Ads uniquement.
facebook_ads.special_ad_categoriesarrayNonObligatoire pour le crédit, l'emploi, le logement et la politique.
facebook_ads.spend_capnumberNonPlafond de dépense de la campagne, dans la devise du compte. null le supprime.
google_adwords.typestringNonGoogle Ads : demand_gen ou performance_max. Obligatoire sur Google.
google_adwords.biddingobjectNonGoogle Ads : strategy (maximize_conversions, par défaut, ou maximize_conversion_value) et, en option, target_cpa ou target_roas (4 vaut 400 %).
tiktok_ads.objectiveNonTikTok 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.

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.