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

CampoTipoObrigatórioDescrição
namestringSimNome do anúncio, e dos níveis criados que não tiverem nome.
statusstringNãoEstado final da árvore (active ou paused). Tudo nasce pausado e a ativação é o último passo.
campaignobjectNão{"id": ...} usa uma campanha existente; sem id, descreve a que será criada. Proibido quando adset.id é enviado.
adsetobjectSim{"id": ...} usa um conjunto existente; sem id, descreve o que será criado.
ad.formatstringSimimage ou video.
ad.link_urlstringSimURL de destino do anúncio.
ad.call_to_actionstringNãoBotão do anúncio. Valores em GET /ads/options.
ad.mediaarraySimUm 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_idstringSimPá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_idstringNãoConta do Instagram que assina o anúncio.
campaign.google_adwords.typestringNãoGoogle Ads, numa campanha nova: demand_gen ou performance_max. Com ela vai um budget diário.
ad.titlesarrayNãoGoogle 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.imagesarrayNãoGoogle Ads: as imagens, cada uma com field (marketing, square, portrait, logo ou landscape_logo) e asset_id.
campaign.tiktok_ads.objectiveNãoTikTok Ads, numa campanha nova: traffic, reach ou video_views.
ad.bodyNãoTexto principal do anúncio. No TikTok Ads, até 100 caracteres.
ad.tiktok_ads.identity_idNãoTikTok 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_idNãoTikTok Ads: o id do vídeo de POST /ads/tiktok_ads/media, já ready.
ad.tiktok_ads.cover_image_idNãoTikTok 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.

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.