Ads

Valider une annonce Meta Ads, Google Ads ou TikTok Ads sans la créer via l'API

POST /ads/validate reçoit exactement le corps de POST /ads et valide chaque niveau sans rien créer dans le compte du client. Vous détectez les erreurs de champ, de page ou de média avant de perdre du temps et avant tout risque pour le budget. Sur TikTok Ads, qui n'a pas de dry run, Connect vérifie chaque niveau dans le compte par des lectures seulement.

L'appel

POST /api/ads/validate?customer_integration=<connection uuid>
Authorization: Bearer <merchant token>
x-customer-token: <customer token>

{
  "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

  • Valider tout l'arbre (campagne, ensemble et annonce) avant de créer.
  • Valider une annonce sur une campagne et un ensemble existants, en passant {"id": ...}.
  • Obtenir le résultat par niveau.
  • Réutiliser ensuite le même corps dans POST /ads, sans rien adapter.
  • Valider sur Google Ads une annonce Demand Gen ou un groupe d'éléments Performance Max, avec le même corps que POST /ads.
  • Valider sur TikTok Ads une annonce vidéo : campagne et groupe cités, objectif, budget entre les niveaux, objectif d'optimisation, pays, identité, vidéo et couverture.

Règles et limites

  • Ne crée rien dans le compte du client et n'enregistre aucune opération.
  • N'a pas besoin d'Idempotency-Key.
  • Chaque niveau est validé par l'intégration ; ceux qui dépendent d'un parent qui n'existe pas encore reviennent en skipped.
  • Les erreurs de champ renvoient 422 validation_error avec errors et, pour les enums, supported_values.
  • N'utilise que la connexion de customer_integration, dans la query, et vérifie qu'elle appartient au client.
  • Sur Google Ads, le résultat vient par niveau, comme sur Meta Ads. Performance Max n'a pas de niveau ad : le groupe d'éléments est l'ensemble.
  • Sur TikTok Ads, chaque niveau revient validated et la réponse porte integration_dry_run: false. Ce que seule la création révèle, comme un budget sous le minimum de TikTok, apparaît sur POST /ads.

Champs principaux

ChampTypeObligatoireDescription
namestringOuiNom de l'annonce, et des niveaux qui n'en ont pas.
statusstringNonÉtat final prévu de l'arbre (active ou paused).
campaignobjectNon{"id": ...} pour une campagne existante ; sans id, décrit celle qui serait créée.
adsetobjectOui{"id": ...} pour un ensemble existant ; sans id, décrit celui qui serait créé.
ad.formatstringOuiimage ou video.
ad.link_urlstringOuiURL de destination de l'annonce.
ad.mediaarrayOuiFichier(s) du visuel, par url, hash ou id. Meta Ads uniquement.
ad.facebook_ads.page_idstringOuiPage qui publie l'annonce. Doit appartenir au compte de la connexion. Meta Ads uniquement.
integration_dry_runNonDans la réponse, sur TikTok Ads : false. TikTok n'a pas de dry run, et Connect vérifie chaque niveau par des lectures seulement.

Pour qui

  • Formulaire avec retour immédiat

    Validez ce que l'utilisateur a saisi avant qu'il clique sur publier et affichez les erreurs de chaque niveau à l'écran.

  • Approbation en lot

    Validez des centaines d'annonces générées par modèle et ne créez que celles qui ont passé.

  • Agent IA qui se corrige

    L'agent construit le corps, valide, lit les erreurs, les corrige et n'appelle POST /ads qu'ensuite.

Fonctionne avec

  • Meta Ads
  • Google Ads
  • TikTok Ads

Questions fréquentes

Valider dépense-t-il du budget ou crée-t-il des objets ?

Non. La route ne crée rien dans le compte et n'enregistre aucune opération.

Le corps est-il différent de POST /ads ?

Non, c'est le même. Vous pouvez valider puis, si cela passe, l'envoyer tel quel à POST /ads avec une Idempotency-Key.

Que signifie skipped dans le résultat ?

Ce niveau dépend d'un parent qui n'existe pas encore, il ne peut donc pas être validé seul. Sur TikTok Ads, il n'y a pas de skipped : chaque niveau est vérifié dans le compte et revient validated.

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.