Ads
Validar anúncio do Meta Ads, Google Ads ou TikTok Ads sem criar pela API
POST /ads/validate recebe exatamente o corpo do POST /ads e valida cada nível sem criar nada na conta do cliente. Você descobre erros de campo, de página ou de mídia antes de gastar tempo e antes de qualquer risco de verba. No TikTok Ads, que não tem dry run, o Connect confere cada nível na conta só com leituras.
A chamada
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"
}
}
}O que dá para fazer
- Validar a árvore inteira (campanha, conjunto e anúncio) antes de criar.
- Validar um anúncio sobre campanha e conjunto existentes, passando {"id": ...}.
- Receber o resultado por nível.
- Usar o mesmo corpo depois no POST /ads, sem adaptar nada.
- Validar no Google Ads um anúncio Demand Gen ou um grupo de recursos Performance Max, com o mesmo corpo do POST /ads.
- Validar no TikTok Ads um anúncio de vídeo: campanha e grupo citados, objetivo, orçamento entre os níveis, meta, países, identidade, vídeo e capa.
Regras e limites
- Não cria nada na conta do cliente e não registra operação.
- Não precisa de Idempotency-Key.
- Cada nível é validado pela integração; os que dependem de um pai que ainda não existe voltam como skipped.
- Erros de campo respondem 422 validation_error com errors e supported_values quando o campo é um enum.
- Usa só a conexão em customer_integration, na query, e confere que ela pertence ao cliente.
- No Google Ads, o resultado vem por nível como no Meta Ads. Na Performance Max não há nível ad: o grupo de recursos é o conjunto.
- No TikTok Ads, cada nível volta validated e a resposta traz integration_dry_run: false. O que só a criação revela, como um orçamento abaixo do mínimo da TikTok, aparece no POST /ads.
Campos principais
| Campo | Tipo | Obrigatório | Descrição |
|---|---|---|---|
| name | string | Sim | Nome do anúncio, e dos níveis que não tiverem nome. |
| status | string | Não | Estado final pretendido da árvore (active ou paused). |
| campaign | object | Não | {"id": ...} para uma campanha existente; sem id, descreve a que seria criada. |
| adset | object | Sim | {"id": ...} para um conjunto existente; sem id, descreve o que seria criado. |
| ad.format | string | Sim | image ou video. |
| ad.link_url | string | Sim | URL de destino do anúncio. |
| ad.media | array | Sim | Arquivo(s) do criativo, por url, hash ou id. Só no Meta Ads. |
| ad.facebook_ads.page_id | string | Sim | Página que assina o anúncio. Deve ser da conta da conexão. Só no Meta Ads. |
| integration_dry_run | Não | Na resposta, no TikTok Ads: false. A TikTok não tem dry run, e o Connect confere cada nível só com leituras. |
Para quem
Formulário com feedback imediato
Valide o que o usuário preencheu antes de ele clicar em publicar e mostre os erros de cada nível na tela.
Aprovação em lote
Valide centenas de anúncios gerados por template e só crie os que passaram.
Agente de IA que se autocorrige
O agente monta o corpo, valida, lê os erros, corrige e só então chama POST /ads.
Funciona com
Meta Ads
Google Ads
TikTok Ads
Perguntas frequentes
Validar consome verba ou cria objetos?
Não. A rota não cria nada na conta e não registra operação.
O corpo é diferente do POST /ads?
Não, é o mesmo corpo. Você pode validar e, se passar, enviar igual ao POST /ads com um Idempotency-Key.
O que significa skipped no resultado?
Que aquele nível depende de um pai que ainda não existe, então não dá para validá-lo isoladamente. No TikTok Ads não há skipped: cada nível é conferido na conta e volta validated.
Veja o Connect aplicado ao seu produto.
Teste por 15 dias sem cartão, ou mostre seu cenário ao nosso time.
