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
| Campo | Tipo | Obrigatório | Descrição |
|---|---|---|---|
| name | string | Sim | Nome da campanha. |
| status | string | Não | active ou paused. Sem o campo, a campanha nasce pausada. |
| budget.amount | number | Sim | Valor na moeda da conta de anúncios, nunca em centavos. Mandar o budget aqui faz a campanha ser CBO. |
| budget.type | string | Não | daily ou lifetime. lifetime exige schedule.end no conjunto. |
| facebook_ads.objective | string | Sim | awareness, 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_categories | array | Não | Obrigatório para crédito, emprego, moradia e política. |
| facebook_ads.spend_cap | number | Não | Limite de gasto da campanha, na moeda da conta. null remove o limite. |
| google_adwords.type | string | Não | Google Ads: demand_gen ou performance_max. Obrigatório no Google. |
| google_adwords.bidding | object | Não | Google Ads: strategy (maximize_conversions, o padrão, ou maximize_conversion_value) e, opcional, target_cpa ou target_roas (4 é 400%). |
| tiktok_ads.objective | Não | TikTok 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.
Veja o Connect aplicado ao seu produto.
Teste por 15 dias sem cartão, ou mostre seu cenário ao nosso time.
