Ads
Criar anúncio no Meta Ads, no Google Ads e no TikTok Ads pela API
Um único POST /ads cria o anúncio e, se você quiser, a campanha e o conjunto acima dele. Cada nível usa um existente ({"id": ...}) ou descreve o novo. Se algo falhar no meio, o que foi criado é desfeito, e nada fica gastando. No Google Ads, o mesmo POST /ads cria anúncios Demand Gen e grupos de recursos Performance Max. No TikTok Ads, ele cria um anúncio de vídeo numa campanha de Tráfego, Alcance ou Visualizações de vídeo.
A chamada
POST /api/ads?customer_integration=<connection uuid>
Authorization: Bearer <merchant token>
x-customer-token: <customer token>
Idempotency-Key: <unique key>
{
"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
- Criar campanha, conjunto e anúncio em uma só chamada.
- Reaproveitar uma campanha ou um conjunto existente passando {"id": ...}.
- Anunciar imagem (por url ou hash) ou vídeo (por url ou id, com thumbnail_url).
- Usar dois arquivos do mesmo criativo, um para o feed e outro para stories e reels, com placements.
- Definir página e conta do Instagram que assinam o anúncio no bloco facebook_ads.
- Pedir status active para ativar a árvore no final.
- No Google Ads, criar um anúncio Demand Gen, com campanha e grupo de anúncios novos ou existentes.
- No Google Ads, criar um grupo de recursos Performance Max, ou somar recursos a um existente, com títulos, títulos longos, descrições, imagens, vídeos e logo no bloco google_adwords.
- No TikTok Ads, criar um anúncio de vídeo com capa, numa campanha de Tráfego, Alcance ou Visualizações de vídeo e num grupo de anúncios novos ou existentes, rodando como uma das contas do TikTok de GET /ads/tiktok_ads/identities.
Regras e limites
- Tudo é criado pausado. O status pedido é aplicado no último passo, depois que a árvore inteira existe.
- Idempotency-Key é obrigatório no header. Repetir com a mesma chave devolve 200 com Idempotent-Replay: true.
- Se um passo falhar na criação, o que foi criado é desfeito em ordem inversa; o que não pôde ser desfeito vem em created. Repetir com a mesma chave retoma de onde parou.
- Na ativação só são ativados os níveis que a própria chamada criou; níveis referenciados por id não são tocados.
- Vídeo ainda em processamento responde 409 ads_video_not_ready. Repita com a mesma chave: o vídeo e os níveis já criados são reaproveitados.
- campaign é proibido quando adset.id é enviado. A página precisa ser da conta da conexão.
- A resposta é síncrona: 201 com o resultado.
- No Google Ads, imagens, vídeos e logos entram pelo asset_id de POST /ads/google_adwords/media. Uma campanha nova leva budget diário e google_adwords.type: demand_gen ou performance_max.
- Na Performance Max não há anúncio: o grupo de recursos carrega o criativo, então a resposta é o conjunto. Uma campanha que não seja Demand Gen nem Performance Max responde 422 ads_unsupported_operation.
- No TikTok Ads, o anúncio é um vídeo: ad.body (até 100 caracteres), link_url, call_to_action e, no bloco tiktok_ads, identity_id, identity_type, video_id e cover_image_id, estes dois de POST /ads/tiktok_ads/media. A campanha nova leva tiktok_ads.objective (traffic, reach ou video_views) e, se quiser, budget, que ela reparte entre os grupos (CBO); sem ele, o grupo novo leva budget diário ou total. O grupo novo leva também targeting.countries ou tiktok_ads.location_ids. Antes da primeira escrita, tudo é conferido na conta só com leituras.
Campos principais
| Campo | Tipo | Obrigatório | Descrição |
|---|---|---|---|
| name | string | Sim | Nome do anúncio, e dos níveis criados que não tiverem nome. |
| status | string | Não | Estado final da árvore (active ou paused). Tudo nasce pausado e a ativação é o último passo. |
| campaign | object | Não | {"id": ...} usa uma campanha existente; sem id, descreve a que será criada. Proibido quando adset.id é enviado. |
| adset | object | Sim | {"id": ...} usa um conjunto existente; sem id, descreve o que será criado. |
| ad.format | string | Sim | image ou video. |
| ad.link_url | string | Sim | URL de destino do anúncio. |
| ad.call_to_action | string | Não | Botão do anúncio. Valores em GET /ads/options. |
| ad.media | array | Sim | Um arquivo para todos os posicionamentos, ou dois (versão feed e versão story) com placements. Imagem por url ou hash; vídeo por url ou id. Só no Meta Ads. |
| ad.facebook_ads.page_id | string | Sim | Página que assina o anúncio. Deve ser uma página da conta da conexão. Só no Meta Ads. |
| ad.facebook_ads.instagram_account_id | string | Não | Conta do Instagram que assina o anúncio. |
| campaign.google_adwords.type | string | Não | Google Ads, numa campanha nova: demand_gen ou performance_max. Com ela vai um budget diário. |
| ad.titles | array | Não | Google Ads: os títulos. Demand Gen, de 1 a 5 com até 40 caracteres; Performance Max, de 3 a 15 com até 30. |
| ad.google_adwords.images | array | Não | Google Ads: as imagens, cada uma com field (marketing, square, portrait, logo ou landscape_logo) e asset_id. |
| campaign.tiktok_ads.objective | Não | TikTok Ads, numa campanha nova: traffic, reach ou video_views. | |
| ad.body | Não | Texto principal do anúncio. No TikTok Ads, até 100 caracteres. | |
| ad.tiktok_ads.identity_id | Não | TikTok Ads: a conta do TikTok que assina o anúncio, de GET /ads/tiktok_ads/identities, com o type dela em identity_type. | |
| ad.tiktok_ads.video_id | Não | TikTok Ads: o id do vídeo de POST /ads/tiktok_ads/media, já ready. | |
| ad.tiktok_ads.cover_image_id | Não | TikTok Ads: o image_id da capa, de POST /ads/tiktok_ads/media, na proporção do vídeo. |
Para quem
Criador de anúncios dentro do seu produto
O cliente escolhe criativo, texto e público e você publica o anúncio completo na conta dele, sem montar o fluxo de OAuth do Meta.
Agência que sobe criativos em escala
Reaproveite uma campanha e um conjunto existentes e crie dezenas de anúncios novos só mudando a mídia e o texto.
Agente de IA que gera criativos
O agente cria o anúncio pausado, valida antes com POST /ads/validate e só ativa depois da aprovação.
Funciona com
Meta Ads
Google Ads
TikTok Ads
Perguntas frequentes
O anúncio vai ao ar assim que a chamada termina?
Só se você enviar status active. Mesmo assim, tudo é criado pausado e a ativação é o último passo.
E se a chamada falhar no meio?
O que já foi criado é desfeito e nada fica gastando. O que não pôde ser desfeito vem em created. Repetindo com o mesmo Idempotency-Key, a chamada retoma de onde parou.
Funciona no Google Ads e no TikTok Ads?
Sim, em campanhas Demand Gen e Performance Max. O corpo é o mesmo POST /ads, com os campos do Google no bloco google_adwords. Na Performance Max, a resposta é o grupo de recursos, porque ela não tem anúncio. No TikTok Ads, em campanhas de Tráfego, Alcance e Visualizações de vídeo com um anúncio de vídeo, com os campos da TikTok no bloco tiktok_ads.
Veja o Connect aplicado ao seu produto.
Teste por 15 dias sem cartão, ou mostre seu cenário ao nosso time.
