Ads

Criar campanha no Meta Ads, no Google Ads e no TikTok Ads pela API

Uma chamada cria a campanha na conta de anúncios que o cliente conectou, sem você implementar a API do Meta nem passar pela revisão de app. Você descreve objetivo e orçamento em um vocabulário único e o Connect cuida do token e da tradução. A campanha nasce pausada, então nada gasta até você ativar. No Google Ads, a mesma rota cria campanhas Demand Gen e Performance Max, com orçamento diário e estratégia de lance. No TikTok Ads, a rota cria campanhas de Tráfego, Alcance e Visualizações de vídeo, com orçamento diário ou total opcional: com ele, a campanha reparte o orçamento entre os grupos (CBO); sem ele, cada grupo de anúncios leva o seu.

A chamada

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": []
  }
}

O que dá para fazer

  • Escolher o objetivo: awareness, traffic, engagement, leads, app_promotion ou sales.
  • Definir o orçamento na campanha (CBO) ou deixá-lo para cada conjunto (ABO).
  • Usar orçamento daily ou lifetime, na moeda da conta do cliente.
  • Informar special_ad_categories para crédito, emprego, moradia e política.
  • Definir um limite de gasto com facebook_ads.spend_cap.
  • Consultar os valores aceitos em GET /ads/options?integration_slug=facebook_ads.
  • No Google Ads, criar uma campanha Demand Gen ou Performance Max com google_adwords.type e orçamento diário próprio.
  • No Google Ads, escolher o lance em google_adwords.bidding: maximize_conversions, com target_cpa opcional, ou maximize_conversion_value, com target_roas opcional.
  • No Google Ads, listar as ações de conversão ativas da conta com GET /ads/google_adwords/conversion-actions; o lance otimiza pelas que têm primary_for_goal.
  • No TikTok Ads, criar uma campanha de Tráfego, Alcance ou Visualizações de vídeo com tiktok_ads.objective: traffic, reach ou video_views.

Regras e limites

  • Sem status, a campanha nasce pausada.
  • Idempotency-Key é obrigatório no header. Repetir a chamada com a mesma chave e o mesmo corpo devolve 200 com Idempotent-Replay: true, sem criar outra campanha.
  • O orçamento fica na campanha (CBO) ou em cada conjunto (ABO), nunca nos dois. Não existe campo level: o nível é onde o budget está.
  • budget.amount é na moeda da conta, nunca em centavos.
  • facebook_ads.objective é obrigatório e não muda depois de criado.
  • A resposta é síncrona: 201 com a campanha criada. Se a chave de idempotência já foi usada com outro corpo, a resposta é 422 idempotency_key_reused.
  • No Google Ads, budget é obrigatório e só daily: o orçamento fica sempre na campanha. facebook_ads é recusado.
  • No TikTok Ads, tiktok_ads.objective é traffic, reach ou video_views, e budget é opcional na campanha, diário ou total: com ele, a campanha reparte o orçamento entre os grupos (CBO), que não levam budget; o total exige schedule.end no grupo. facebook_ads também é recusado.

Campos principais

CampoTipoObrigatórioDescrição
namestringSimNome da campanha.
statusstringNãoactive ou paused. Sem o campo, a campanha nasce pausada.
budget.amountnumberSimValor na moeda da conta de anúncios, nunca em centavos. Mandar o budget aqui faz a campanha ser CBO.
budget.typestringNãodaily ou lifetime. lifetime exige schedule.end no conjunto.
facebook_ads.objectivestringSimawareness, traffic, engagement, leads, app_promotion ou sales. Obrigatório na criação e não muda depois. Só no Meta Ads.
facebook_ads.special_ad_categoriesarrayNãoObrigatório para crédito, emprego, moradia e política.
facebook_ads.spend_capnumberNãoLimite de gasto da campanha, na moeda da conta. null remove o limite.
google_adwords.typestringNãoGoogle Ads: demand_gen ou performance_max. Obrigatório no Google.
google_adwords.biddingobjectNãoGoogle Ads: strategy (maximize_conversions, o padrão, ou maximize_conversion_value) e, opcional, target_cpa ou target_roas (4 é 400%).
tiktok_ads.objectiveNãoTikTok Ads: traffic, reach ou video_views. Obrigatório no TikTok; o budget da campanha é opcional (CBO).

Para quem

  • Plataforma de anúncios para PMEs

    O cliente final preenche objetivo e verba no seu produto e você cria a campanha na conta dele, sem montar um fluxo OAuth com o Meta.

  • Agência com painel próprio

    Crie campanhas padronizadas para vários clientes a partir de um template, trocando só nome, objetivo e orçamento.

  • Agente de IA de mídia paga

    O agente lê o vocabulário em GET /ads/options, monta a campanha e a deixa pausada para um humano revisar antes de ativar.

Funciona com

  • Meta Ads
  • Google Ads
  • TikTok Ads

Perguntas frequentes

A campanha começa gastando dinheiro assim que é criada?

Não. Sem status, ela nasce pausada. Você ativa quando quiser com PATCH /ads/campaigns/{id} e status active.

Posso repetir a chamada sem criar uma campanha duplicada?

Sim. Mande sempre o mesmo Idempotency-Key. Se a primeira chamada deu certo, a repetição devolve a mesma resposta com Idempotent-Replay: true.

Onde o orçamento deve ficar, na campanha ou no conjunto?

Em um dos dois. Com budget na campanha o orçamento é CBO; sem ele, cada conjunto leva o seu (ABO). Mandar para o nível errado responde 409 budget_level_mismatch.

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.