Ads
Criar conjunto ou grupo de anúncios no Meta, Google e TikTok Ads pela API
Crie o conjunto dentro de uma campanha existente na conta que o cliente conectou: público, agenda, posicionamentos, meta de otimização e lance. Os campos comuns a qualquer plataforma ficam no topo e o que é específico do Meta vai no bloco facebook_ads. Sem app review e sem lidar com tokens. No Google Ads, a mesma rota cria um grupo de anúncios numa campanha Demand Gen. No TikTok Ads, ela cria um grupo de anúncios numa campanha de Tráfego, Alcance ou Visualizações de vídeo, com orçamento diário ou total, local, público e agenda.
A chamada
POST /api/ads/adsets?customer_integration=<connection uuid>
Authorization: Bearer <merchant token>
x-customer-token: <customer token>
Idempotency-Key: <unique key>
{
"campaign_id": "120250000000000001",
"name": "BR 25-45",
"budget": {
"amount": 20,
"type": "daily"
},
"targeting": {
"countries": [
"BR"
],
"age_min": 25,
"age_max": 45
},
"facebook_ads": {
"optimization_goal": "link_clicks",
"billing_event": "impressions"
}
}O que dá para fazer
- Segmentar por países, idade (age_min e age_max) e gêneros.
- Segmentar por interesses e públicos personalizados, incluindo exclusões, em facebook_ads.targeting.
- Definir agenda com schedule.start e schedule.end.
- Escolher posicionamentos com facebook_ads.placements.
- Escolher lance com bid_strategy (lowest_cost, bid_cap, cost_cap) e bid_amount.
- Informar promoted_object, destination_type e attribution_spec na criação.
- No Google Ads, criar um grupo de anúncios numa campanha Demand Gen só com campaign_id, name e status.
- No TikTok Ads, criar um grupo de anúncios numa campanha de Tráfego, Alcance ou Visualizações de vídeo, com local, idade, gênero, públicos, agenda e meta de otimização.
Regras e limites
- Idempotency-Key é obrigatório no header; repetir com a mesma chave devolve 200 com Idempotent-Replay: true.
- Sem status, o conjunto nasce pausado.
- O orçamento fica na campanha (CBO) ou no conjunto (ABO), nunca nos dois. Orçamento num conjunto de campanha CBO responde 409 budget_level_mismatch.
- budget.type lifetime exige schedule.end.
- facebook_ads.optimization_goal e facebook_ads.billing_event são obrigatórios; os valores aceitos estão em GET /ads/options.
- promoted_object (pixel, página ou conversão personalizada) deve pertencer à conta da conexão, e vale só na criação.
- bid_amount exige bid_strategy.
- No Google Ads, budget, schedule, targeting e facebook_ads são recusados: o orçamento fica na campanha. Numa campanha Performance Max, a rota responde 422 ads_unsupported_operation, e o grupo de recursos é criado com os recursos pelo POST /ads.
- No TikTok Ads, targeting.countries ou tiktok_ads.location_ids é obrigatório, e facebook_ads é recusado. Se a campanha reparte o orçamento (CBO), o grupo não leva budget; sem CBO, budget é obrigatório, diário ou total, e o total exige schedule.end. Numa campanha com CBO, budget no grupo responde 409 budget_level_mismatch. Idade, gênero, tiktok_ads.audience_ids e schedule são opcionais; sem schedule.start, começa agora. A meta vem de tiktok_ads.optimization_goal e o lance de tiktok_ads.bid_strategy (lowest_cost ou cost_cap com bid_amount); tiktok_ads.frequency vale só no Alcance. O grupo roda só no posicionamento TikTok. Numa campanha de outro objetivo, a rota responde 422 ads_unsupported_operation.
Campos principais
| Campo | Tipo | Obrigatório | Descrição |
|---|---|---|---|
| campaign_id | string | Sim | A campanha, pelo id dela ou pelo uuid do Connect. |
| name | string | Sim | Nome do conjunto de anúncios. |
| budget.amount | number | Não | Orçamento do conjunto (ABO), na moeda da conta. Só vale se a campanha não tem orçamento. |
| schedule.end | string | Não | Data de término. Obrigatória quando budget.type é lifetime. |
| targeting.countries | array | Sim | Países do público, por exemplo ["BR"]. O restante da segmentação vai em facebook_ads.targeting. |
| facebook_ads.optimization_goal | string | Sim | Meta de otimização. Obrigatório na criação; valores em GET /ads/options. Só no Meta Ads. |
| facebook_ads.billing_event | string | Sim | Evento de cobrança. Obrigatório na criação. Só no Meta Ads. |
| facebook_ads.bid_strategy | string | Não | lowest_cost, bid_cap ou cost_cap. |
| facebook_ads.bid_amount | number | Não | Valor do lance. Exige bid_strategy. |
| facebook_ads.targeting.interests | array | Não | Interesses do público, com id e name. |
| tiktok_ads.location_ids | Não | No TikTok Ads: ids de local da TikTok (estados e regiões), de GET /ads/targeting/search (type geo). Na resposta, os países do grupo também voltam aqui, como ids de local. |
Para quem
Construtor de campanhas dentro do SaaS
Seu produto monta o público (país, idade, interesses) numa tela própria e cria o conjunto na conta do cliente com uma chamada.
Testes A/B de público
Crie vários conjuntos na mesma campanha, mudando só a segmentação, e compare o desempenho depois.
Agente de IA que sugere públicos
O agente propõe a segmentação, cria o conjunto pausado e entrega para aprovação antes de ativar.
Funciona com
Meta Ads
Google Ads
TikTok Ads
Perguntas frequentes
Preciso criar a campanha antes?
Para esta rota sim: campaign_id é obrigatório. Para criar campanha, conjunto e anúncio de uma vez, use POST /ads.
Onde coloco o orçamento?
No conjunto só se a campanha não tiver orçamento (ABO). Se a campanha tem budget (CBO), mandar budget no conjunto responde 409 budget_level_mismatch.
Como descubro os valores válidos de otimização e cobrança?
Em GET /ads/options?integration_slug=facebook_ads. Valor inválido responde 422 validation_error com supported_values.
Veja o Connect aplicado ao seu produto.
Teste por 15 dias sem cartão, ou mostre seu cenário ao nosso time.
