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

CampoTipoObrigatórioDescrição
namestringSimNome do anúncio, e dos níveis que não tiverem nome.
statusstringNãoEstado final pretendido da árvore (active ou paused).
campaignobjectNão{"id": ...} para uma campanha existente; sem id, descreve a que seria criada.
adsetobjectSim{"id": ...} para um conjunto existente; sem id, descreve o que seria criado.
ad.formatstringSimimage ou video.
ad.link_urlstringSimURL de destino do anúncio.
ad.mediaarraySimArquivo(s) do criativo, por url, hash ou id. Só no Meta Ads.
ad.facebook_ads.page_idstringSimPágina que assina o anúncio. Deve ser da conta da conexão. Só no Meta Ads.
integration_dry_runNãoNa 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.

Relacionadas

Ver tudo que dá para fazer em Ads

Veja o Connect aplicado ao seu produto.

Teste por 15 dias sem cartão, ou mostre seu cenário ao nosso time.