Documentação da API de UOL ads

Introdução

A UOL Ads API é a interface programática da plataforma de publicidade do UOL. Ela permite que anunciantes, agências e sistemas parceiros criem, gerenciem e acompanhem campanhas de mídia display e native sem depender da interface visual — tudo via requisições HTTP com respostas em JSON.

Para quem é este guia

  • Anunciantes e agências que querem integrar seus próprios sistemas de gestão de mídia.
  • Desenvolvedores que vão automatizar a criação de campanhas, o envio de criativos e a extração de relatórios de performance.
  • Equipes de dados que precisam consumir métricas (impressões, cliques, conversões) de forma programática.

O que a API disponibiliza

  • Criar e organizar campanhas e grupos de anúncios.
  • Enviar criativos nos formatos Native (anúncio integrado ao conteúdo) e Display (banner com imagem).
  • Definir orçamento, CPM (custo por mil impressões), período de veiculação e segmentação de audiência.
  • Pausar e retomar campanhas, grupos e criativos a qualquer momento.
  • Extrair relatórios de analytics, domínios, regiões, dispositivos e conversões.

Configurações da API

Tudo na Ads API é organizado em uma estrutura hierárquica clara e encadeada. Cada nível tem uma responsabilidade específica no fluxo de veiculação:

  • Campanha: É o topo da estrutura. Aqui você define as configurações iniciais como Objetivo e escolha do formato

  • Grupo de Anúncios: Fica dentro da campanha. É onde você gerencia as regras práticas de veiculação, como o público-alvo (segmentação), as estratégias de lance e os limites de orçamento desse grupo

  • Criativos: Ficam associados aos grupos. São formatos publicitárias que serão entregues ao usuário final, operando nos formatos Native (conteúdo integrado) ou Display (banners tradicionais)

Se você preferir não estruturar cada uma dessas entidades de forma isolada, a API oferece o recurso de Criação Simplificada. Com ele, você consegue instanciar a estrutura completa — Campanha, Grupo e Criativos — enviando todos os dados em uma única requisição. O acesso a todos os endpoints exige autenticação prévia baseada em tokens de segurança. Para obter suas credenciais, configurar as chaves de acesso e realizar sua primeira chamada de teste, acesse o guia do Início Rápido.

Início Rápido

Bem-vindo ao guia de integração. Este tutorial apresenta o caminho mais simples e direto para configurar o seu ambiente e colocar o seu primeiro anúncio no ar.

Pré-requisitos

  • Uma API key válida (veja Autenticação para saber como obter).
  • Um cliente HTTP qualquer: curl, Postman, ou o próprio Swagger.

Passo 1 — Teste sua autenticação

Toda requisição (exceto rotas públicas como /health e o Swagger) exige o cabeçalho Authorization com a sua chave. Faça uma listagem simples de campanhas para validar:

curl -X GET "https://api.ads.uol.com.br/campaigns" \
  -H "Authorization: SUA_API_KEY"

Se você receber 200 OK (mesmo que a lista venha vazia), sua chave está funcionando. Se receber um erro de autenticação, revise a seção Autenticação.

Passo 2 — Crie sua primeira estrutura em uma única chamada

O jeito mais rápido de colocar um anúncio no ar é a Criação Simplificada: uma requisição cria Campanha + Grupo + Native de uma vez.

curl -X POST "https://api.ads.uol.com.br/natives/simpleCreate" \
  -H "Authorization: SUA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "nativeName": "Meu primeiro anúncio",
    "budget": 150,
    "rate": 1.5,
    "startDate": "17-01-2025",
    "title": "Conheça nossa oferta",
    "description": "Uma descrição atraente do seu produto com o tamanho ideal aqui.",
    "imageBase64": "..."
  }'

O nativeName é reaproveitado como nome da campanha e do grupo quando você não informa campaignName/groupName. Atenção ao formato de data deste endpoint: dd-MM-yyyy.

A resposta traz campaignId, groupId e nativeId da estrutura recém-criada.

Passo 3 — Ou monte manualmente, passo a passo

Se preferir controle total, crie cada recurso separadamente:

# 1) Campanha
curl -X POST "https://api.ads.uol.com.br/campaigns" \
  -H "Authorization: SUA_API_KEY" -H "Content-Type: application/json" \
  -d '{ "name": "Campanha de Verão" }'

# 2) Grupo (use o id da campanha retornado acima)
curl -X POST "https://api.ads.uol.com.br/groups" \
  -H "Authorization: SUA_API_KEY" -H "Content-Type: application/json" \
  -d '{ "name": "Grupo SP", "campaign": { "id": 1 },
        "budget": 150, "rate": 1.5, "startDate": "2025-01-17" }'

# 3) Criativo Native (use o id do grupo)
curl -X POST "https://api.ads.uol.com.br/creatives/natives" \
  -H "Authorization: SUA_API_KEY" -H "Content-Type: application/json" \
  -d '{ "name": "Native 1", "group": { "id": 1 },
        "destinationUrl": "https://exemplo.com.br",
        "title": "Título do anúncio",
        "description": "Descrição com o tamanho recomendado entre 65 e 90 caracteres aqui.",
        "brand": "Minha Marca", "imageBase64": "..." }'

No cadastro manual de grupo, o formato de data é YYYY-MM-DD. Essa diferença em relação ao simpleCreate é esperada — veja o FAQ.

Passo 4 — Verifique o resultado

curl -X GET "https://api.ads.uol.com.br/creatives/natives?groupId=1" \
  -H "Authorization: SUA_API_KEY"

Um criativo recém-criado normalmente entra com status PENDENTE até passar pela moderação. Entenda o ciclo de vida em Conceitos Fundamentais.

Próximos passos

Conceitos Fundamentais

Antes de explorar os endpoints, é fundamental compreender a relação entre os recursos. Todo o conteúdo deste guia baseia-se nesses conceitos.

A hierarquia de recursos

Account (sua conta)
└── Campaign (campanha)
    └── Group (grupo de anúncios)
        ├── Native  (criativo integrado ao conteúdo)
        └── Display (criativo em banner/imagem)
  • Account — sua conta de anunciante. É determinada automaticamente pela API key que você usa; você não a informa manualmente nas requisições.
  • Campaign (Campanha) — o agrupador de mais alto nível. Serve para organizar iniciativas (ex.: "Black Friday", "Lançamento de Produto"). Guarda basicamente um nome e um status.
  • Group (Grupo) — onde vivem as regras de veiculação: orçamento, CPM, datas de início e fim, segmentação de audiência e a flag de conteúdo adulto. Uma campanha pode ter vários grupos.
  • Creative (Criativo) — o anúncio em si, que fica dentro de um grupo. Existe em dois formatos: Native e Display.

Native x Display

Aspecto Native Display
Formato Integra-se visualmente ao conteúdo da página Banner com imagem
Campos principais título, descrição, marca, CTA, imagens imagem + URL de destino
Imagens principal + secundária + logo (opcionais) uma imagem principal
Uso típico recomendações, conteúdo patrocinado mídia gráfica tradicional

Ambos passam por moderação antes de veicular.

Status e ciclo de vida

Campanha, Grupo, Native e Display têm um único campo status, que combina o estado operacional e o de moderação. Os valores possíveis são:

  • PENDENTE — criativo recém-criado, aguardando moderação (é o estado inicial de um Native/Display).
  • APROVADO — aprovado na moderação e apto a veicular.
  • REPROVADO — reprovado na moderação; o motivo vem no campo reason (múltiplos motivos são separados por |).
  • ATIVO — em veiculação.
  • PAUSADO — pausado.
  • FINALIZADO, ARQUIVADO, EXCLUIDO — estados finais/de encerramento.

Você controla pausa e retomada pelos endpoints de changeStatus com as ações RESUME (retomar) e PAUSE (pausar).

Formatos de data — atenção

A plataforma usa dois formatos de data dependendo do endpoint:

  • /groups e afins: YYYY-MM-DD (ex.: 2025-01-17).
  • /natives/simpleCreate: dd-MM-yyyy (ex.: 17-01-2025).
  • Relatórios (/report/metrics/*): yyyy-MM-dd.

Guarde essa diferença — ela é a causa mais comum de erro 400 para quem está começando.

Autenticação

Toda a comunicação com a Ads API é autenticada por API key. Sem uma chave válida, as requisições a recursos protegidos são rejeitadas.

Como funciona

  1. A chave é gerada pelo nosso time de atendimento após a solicitação da mesmo através do nosso Formulário
  2. A cada requisição, a Ads API lê o cabeçalho Authorization e verifica se a chave existe.
  3. Se a chave for encontrada, ela é associada ao idtPerson correspondente, que passa a ser o usuário autenticado da requisição — e a conta (Account) dele é resolvida automaticamente.
  4. É permitida apenas uma chave por idtPerson.

Como enviar a chave

A chave vai diretamente no cabeçalho Authorization (sem prefixo Bearer):

curl -X GET "https://api.ads.uol.com.br/campaigns" \
  -H "Authorization: SUA_API_KEY"

No Swagger, clique em Authorize e cole a chave no campo value.

Rotas públicas (sem autenticação)

O único caminho liberado e que não exige o cabeçalho Authorization:

  • /health - Ele vai retornar o status de funcionamento da API

Erros de autenticação

Se o cabeçalho Authorization estiver ausente/vazio ou a chave não for encontrada, a autenticação falha e a requisição não é atendida como usuário válido. Confira o formato de resposta de erro em Tratamento de Erros.

Campanhas

A campanha é o nível mais alto de organização. Na prática, é uma "pasta" que agrupa seus grupos de anúncios sob um mesmo objetivo. Uma campanha carrega essencialmente um nome e um status (ATIVO/PAUSADO).

Anatomia de uma campanha

Campo Obrigatório Regra
name Sim Nome da campanha (até 120 caracteres)
status Não Estado operacional: ATIVO ou PAUSADO (padrão: ATIVO)
groups Não Lista de grupos vinculados (retornada na resposta)

O id é gerado pela API na criação e retornado na resposta, junto com o status e a lista de groups vinculados.

A jornada com campanhas

  1. Criar a campanha com um nome.
  2. Adicionar grupos a ela (veja Grupos).
  3. Renomear quando necessário.
  4. Pausar/retomar a campanha inteira quando quiser interromper ou reativar a veiculação.
  5. Listar/filtrar campanhas para acompanhar o portfólio.

Criar uma campanha

curl -X POST "https://api.ads.uol.com.br/campaigns" \
  -H "Authorization: SUA_API_KEY" -H "Content-Type: application/json" \
  -d '{ "name": "Campanha de Verão" }'

O nome deve ter entre 1 e 80 caracteres. A resposta traz o id gerado, o status e a lista de groups vinculados.

Renomear (atualização parcial)

curl -X PATCH "https://api.ads.uol.com.br/campaigns/1" \
  -H "Authorization: SUA_API_KEY" -H "Content-Type: application/json" \
  -d '{ "name": "Campanha de Verão 2025" }'

Pausar ou retomar

Você pode alterar o status de uma ou várias campanhas de uma vez, passando os IDs separados por vírgula e a ação (RESUME ou PAUSE):

# Pausar as campanhas 1, 2 e 3
curl -X PUT "https://api.ads.uol.com.br/campaigns/1,2,3/changeStatus/PAUSE" \
  -H "Authorization: SUA_API_KEY"

Consultar e listar

# Detalhes de uma campanha
curl "https://api.ads.uol.com.br/campaigns/1" -H "Authorization: SUA_API_KEY"

# Lista com filtros opcionais (por IDs e/ou status)
curl "https://api.ads.uol.com.br/campaigns?status=ATIVO" -H "Authorization: SUA_API_KEY"

Grupos

O grupo centraliza as configurações operacionais da veiculação. É neste nível que você define o orçamento, o período de veiculação e o público-alvo dos anúncios. Lembre-se de que cada grupo deve pertencer a uma campanha.

Anatomia de um grupo

Campo Obrigatório Regra
name Sim Nome do grupo
campaign.id Sim Campanha à qual o grupo pertence
budget Sim Orçamento do grupo (o mínimo aceito depende do tipo de orçamento)
rate Sim Valor da taxa (o modelo de cobrança depende do chargingType do grupo, ex.: CPC ou CPM)
startDate Sim Início da veiculação (YYYY-MM-DD)
endDate Não Fim da veiculação (YYYY-MM-DD); opcional
adult Não Marca o grupo como conteúdo adulto (padrão: false)
status Não Estado operacional: ATIVO ou PAUSADO (padrão: ATIVO)

O id é gerado pela API na criação. As datas usam o formato YYYY-MM-DD.

O que um grupo controla

  • budget — orçamento do grupo (o mínimo aceito varia conforme o tipo de orçamento).
  • rate — valor da taxa, conforme o modelo de cobrança (chargingType) do grupo (ex.: CPC ou CPM).
  • startDate / endDate — período de veiculação (YYYY-MM-DD). O fim é opcional.
  • adult — marca o grupo como conteúdo adulto (padrão: false).

A jornada com grupos

  1. Criar o grupo dentro de uma campanha, definindo orçamento, CPM e datas.
  2. (Opcional) Vincular segmentos de audiência.
  3. Adicionar criativos (Native/Display) ao grupo.
  4. Ajustar orçamento, taxa ou data fim conforme a campanha evolui.
  5. Pausar/retomar o grupo isoladamente.

Criar um grupo

curl -X POST "https://api.ads.uol.com.br/groups" \
  -H "Authorization: SUA_API_KEY" -H "Content-Type: application/json" \
  -d '{
    "name": "Grupo São Paulo",
    "campaign": { "id": 1 },
    "budget": 150,
    "rate": 1.5,
    "startDate": "2025-01-17",
    "endDate": "2025-12-31"
  }'

Atualização

# Atualização parcial
curl -X PATCH "https://api.ads.uol.com.br/groups/1" \
  -H "Authorization: SUA_API_KEY" -H "Content-Type: application/json" \
  -d '{ "budget": 300, "rate": 2.0, "endDate": "2026-01-31" }'

Mudança de status (pausar/retomar)

# Pausar/retomar um ou vários grupos
curl -X PUT "https://api.ads.uol.com.br/groups/1,2/changeStatus/PAUSE" \
  -H "Authorization: SUA_API_KEY"

Listagem

# Listar filtrando por campanha
curl "https://api.ads.uol.com.br/groups?campaignId=1&status=ATIVO" \
  -H "Authorization: SUA_API_KEY"

Criativos — Native

O formato Native é projetado para se integrar ao conteúdo da página, proporcionando uma experiência fluída ao usuário.

Anatomia de um Native

Campo Obrigatório Regra
name Sim Nome interno do anúncio (até 60 caracteres)
group.id Sim Grupo ao qual pertence
destinationUrl Sim Página de destino (9–1017 caracteres)
title Sim Título exibido (até 25 caracteres)
description Sim Descrição (65–90 caracteres)
brand Sim Marca (até 25 caracteres)
imageBase64 Sim Imagem principal em Base64
secondaryImageBase64 Não Imagem secundária em Base64
logoBase64 Não Logo em Base64
status Não Estado do criativo (campo único). Um criativo novo entra como PENDENTE; após moderação vira APROVADO ou REPROVADO; em veiculação/pausa fica ATIVO/PAUSADO
reason — Motivo(s) da reprovação, preenchido pela plataforma quando status é REPROVADO (múltiplos motivos separados por |)

As imagens são enviadas em Base64 no corpo da requisição. Na resposta, a API devolve as URLs já processadas (image, secondaryImage, logo).

A jornada com Native

  1. Criar o criativo dentro de um grupo, respeitando os limites de caracteres.
  2. Ele entra como PENDENTE e passa por moderação.
  3. Se REPROVADO, a resposta traz o reason explicando o motivo — ajuste e reenvie.
  4. Editar campos a qualquer momento (atualização parcial).
  5. Pausar/retomar ou listar conforme a operação.

Criar um Native

curl -X POST "https://api.ads.uol.com.br/creatives/natives" \
  -H "Authorization: SUA_API_KEY" -H "Content-Type: application/json" \
  -d '{
    "name": "Native Verão",
    "group": { "id": 1 },
    "destinationUrl": "https://exemplo.com.br/oferta",
    "title": "Oferta imperdível",
    "description": "Aproveite condições especiais por tempo limitado neste verão incrível.",
    "brand": "Minha Marca",
    "imageBase64": "..."
  }'

Atualização

# Atualização parcial (todos os campos são opcionais)
curl -X PATCH "https://api.ads.uol.com.br/creatives/natives/1" \
  -H "Authorization: SUA_API_KEY" -H "Content-Type: application/json" \
  -d '{ "title": "Novo título" }'

Mudança de status (pausar/retomar)

curl -X PUT "https://api.ads.uol.com.br/creatives/natives/1,2/changeStatus/PAUSE" \
  -H "Authorization: SUA_API_KEY"

Listagem

# Listar por grupo e status
curl "https://api.ads.uol.com.br/creatives/natives?groupId=1&status=APROVADO" \
  -H "Authorization: SUA_API_KEY"

Criativos — Display

O Display representa o formato tradicional de banner. Trata-se de uma estrutura mais simplificada em comparação ao formato Native, cujo escopo técnico é centrado essencialmente em um arquivo de imagem e uma URL de redirecionamento.

Anatomia de um Display

Campo Obrigatório Regra
name Sim Nome interno do banner (deve ser único no grupo; na plataforma é derivado do nome do arquivo da imagem)
group.id Sim Grupo ao qual pertence
destinationUrl Sim Página de destino (9–1017 caracteres)
imageBase64 Sim Imagem do banner em Base64
status Não Estado do criativo (campo único). Um criativo novo entra como PENDENTE; após moderação vira APROVADO ou REPROVADO; em veiculação/pausa fica ATIVO/PAUSADO
reason — Motivo(s) da reprovação, preenchido pela plataforma quando status é REPROVADO (múltiplos motivos separados por |)

Na resposta, a API devolve a URL processada em image e, se reprovado, o reason.

A jornada com Display

Idêntica à do Native, com menos campos: criar → moderação (PENDENTE → APROVADO/REPROVADO) → editar → pausar/retomar → listar.

Criação de um Display

# Criar
curl -X POST "https://api.ads.uol.com.br/creatives/displays" \
  -H "Authorization: SUA_API_KEY" -H "Content-Type: application/json" \
  -d '{ "name": "Banner Home", "group": { "id": 1 },
        "destinationUrl": "https://ads.uol.com.br", "imageBase64": "..." }'

Edição

# Editar parcialmente
curl -X PATCH "https://api.ads.uol.com.br/creatives/displays/1" \
  -H "Authorization: SUA_API_KEY" -H "Content-Type: application/json" \
  -d '{ "destinationUrl": "https://ads.uol.com.br/promo" }'

Mudança de status (pausar/retomar)

curl -X PUT "https://api.ads.uol.com.br/creatives/displays/1/changeStatus/PAUSE" \
  -H "Authorization: SUA_API_KEY"

Listagem

# Listar por grupo e status
curl "https://api.ads.uol.com.br/creatives/displays?groupId=1" \
  -H "Authorization: SUA_API_KEY"

Criação Simplificada

O endpoint POST /natives/simpleCreate unifica o fluxo de setup de campanhas. Ele possibilita a criação simultânea de toda a estrutura hierárquica (Campanha, Grupo e Native) em uma única chamada, eliminando a necessidade de múltiplos requests sequenciais.

Quando usar

  • Primeiros testes e provas de conceito.
  • Fluxos onde cada anúncio já corresponde a uma campanha/grupo próprios.
  • Integrações que priorizam simplicidade em vez de reaproveitar campanhas existentes.

Regras importantes

  • Se você informar apenas nativeName, ele será usado também como campaignName e groupName.
  • O formato de data aqui é dd-MM-yyyy (diferente do /groups, que usa YYYY-MM-DD).
  • Rollback parcial: se ocorrer erro durante a criação, a campanha recém-criada é removida automaticamente, para não deixar lixo na sua conta.

Campos principais

Campo Obrigatório Observação
nativeName Sim Também vira campanha/grupo se estes não forem informados (máx. 25)
campaignName Não Máx. 80
groupName Não Máx. 80
budget Sim Orçamento do grupo
rate Sim Valor da taxa — neste fluxo o modelo de cobrança é CPC
startDate Sim Início (dd-MM-yyyy)
endDate Não Fim (dd-MM-yyyy)
adult Não Padrão false
title Sim Título do Native (máx. 25)
description Sim 65–90 caracteres
brand Sim Máx. 25
imageBase64 Sim Imagem principal
secondaryImageBase64 Não Imagem secundária

Exemplo

curl -X POST "https://api.ads.uol.com.br/natives/simpleCreate" \
  -H "Authorization: SUA_API_KEY" -H "Content-Type: application/json" \
  -d '{
    "nativeName": "Lançamento Rápido",
    "budget": 200,
    "rate": 1.8,
    "startDate": "17-01-2025",
    "endDate": "31-12-2025",
    "title": "Novidade chegando",
    "description": "Descubra o que preparamos para você nesta temporada de novidades exclusivas.",
    "imageBase64": "..."
  }'

A resposta traz campaignId, groupId e nativeId com todos os dados criados.

Relatórios e Métricas

Após o início da veiculação dos anúncios, o monitoramento de desempenho é realizado por meio dos endpoints agrupados sob o caminho /report/metrics/*. Todas as consultas utilizam o método GET e exigem obrigatoriamente os parâmetros de consulta startDate e endDate formatados no padrão ISO yyyy-MM-dd.

A jornada de análise

  1. Comece pelo relatório analítico geral para ter a visão macro (impressões, cliques etc.).
  2. Aprofunde por domínio, região, dispositivo ou conversões conforme a pergunta que você quer responder.
  3. Use dimensões para agrupar e filtros (campanhas, grupos, criativos) para recortar.

Relatórios disponíveis

Relatório Endpoint Para responder
Analítico geral GET /report/metrics/analytics Visão consolidada por múltiplas dimensões
Domínios GET /report/metrics/domains Em quais sites/URLs os anúncios apareceram
Regiões GET /report/metrics/regions Performance por estado (ex.: SP, RJ)
Dispositivos GET /report/metrics/devices Mobile vs desktop etc.
Conversões GET /report/metrics/conversions Resultados de conversão

Filtros e dimensões

  • dimensions — como agrupar os dados. No relatório analítico e no de conversões é necessário informar ao menos uma dimensão; nos demais é opcional.
  • Filtros por escopo: campaignIds, groupIds, displayIds, nativeIds.
  • Filtros específicos: formats (native/display), domains, regions (siglas de estado), deviceTypes, conversionIds.

Exemplos

# Relatório analítico agrupado por dia
curl "https://api.ads.uol.com.br/report/metrics/analytics?startDate=2025-01-01&endDate=2025-01-31&dimensions=DAY" \
  -H "Authorization: SUA_API_KEY"

# Métricas por região, filtrando por campanha e por SP
curl "https://api.ads.uol.com.br/report/metrics/regions?startDate=2025-01-01&endDate=2025-01-31&campaignIds=1&regions=SP" \
  -H "Authorization: SUA_API_KEY"

# Métricas por dispositivo
curl "https://api.ads.uol.com.br/report/metrics/devices?startDate=2025-01-01&endDate=2025-01-31" \
  -H "Authorization: SUA_API_KEY"

A lista completa de dimensões e enums (por exemplo, os valores válidos de dimensions, deviceTypes e regions) fica sempre atualizada no Swagger

Tratamento de Erros

Em cenários de falha na requisição, a API retorna o código de status HTTP apropriado acompanhado de um payload JSON descritivo no corpo da resposta. Compreender a estrutura dessas mensagens de erro otimiza o processo de depuração e acelera o ciclo de desenvolvimento da sua integração.

Formato do erro

Os erros seguem, em geral, a estrutura do objeto AdsError:

{
  "status": 400,
  "error": "Bad Request",
  "message": "Descrição do que ocorreu",
  "path": "/groups",
  "exception": "MethodArgumentNotValidException"
}
  • status — código HTTP numérico.
  • error — nome do status HTTP.
  • message — detalhe do erro (inclui as mensagens de validação de campos).
  • path — endpoint que gerou o erro.
  • exception — nome técnico da exceção (útil para depurar).

Principais situações

Código Quando ocorre Como resolver
400 Bad Request Validação de campos falhou, parâmetro obrigatório ausente ou tipo inválido Cheque limites de caracteres, campos obrigatórios e formatos de data
415 Unsupported Media Type Content-Type incorreto ou arquivo de tipo não aceito no upload Use application/json
503 Service Unavailable Erro de negócio (AdsException), falha de integração com serviços internos ou erro inesperado Verifique a message; se persistir, é falha temporária de backend

Erros de validação de campo (ex.: descrição fora da faixa de 65–90 caracteres) chegam como 400 com as mensagens detalhadas dentro de message.

Referência de Status

Tabela consolidada dos status usados na plataforma.

Recurso Status possíveis Como muda
Campanha ATIVO, PAUSADO PUT .../changeStatus/{RESUME|PAUSE}
Grupo ATIVO, PAUSADO PUT .../changeStatus/{RESUME|PAUSE}
Native PENDENTE, APROVADO, REPROVADO, ATIVO, PAUSADO, FINALIZADO, ARQUIVADO, EXCLUIDO (campo único status) Pausa/retomada via PUT .../changeStatus/{RESUME|PAUSE}; moderação definida pela plataforma (com reason se reprovado)
Display PENDENTE, APROVADO, REPROVADO, ATIVO, PAUSADO, FINALIZADO, ARQUIVADO, EXCLUIDO (campo único status) Pausa/retomada via PUT .../changeStatus/{RESUME|PAUSE}; moderação definida pela plataforma (com reason se reprovado)

Ações de mudança de estado: RESUME (retomar) e PAUSE (pausar).

Mapa rápido de recursos

Recurso Base Documentado em
Campanhas /campaigns Campanhas
Grupos /groups Grupos
Criativos Native /creatives/natives Native
Criativos Display /creatives/displays Display
Criação Simplificada /natives/simpleCreate Criação Simplificada
Segmentos de Conta /account-segments Segmentação
Relatórios /report/metrics/* Relatórios

Perguntas Frequentes (FAQ)

Como envio imagens? Preciso hospedar em algum lugar antes? Não. As imagens vão em Base64 no corpo da requisição (imageBase64, secondaryImageBase64, logoBase64). A API processa e devolve as URLs prontas na resposta (image, secondaryImage, logo).

Por que às vezes a data é YYYY-MM-DD e às vezes dd-MM-yyyy? É uma diferença real por endpoint: /groups usa YYYY-MM-DD, o /natives/simpleCreate usa dd-MM-yyyy e os relatórios usam yyyy-MM-dd. Enviar o formato errado é a causa mais comum de erro 400.

Meu criativo foi criado como PENDENTE. E agora? É o comportamento normal: todo criativo passa por moderação. Ele vira APROVADO ou REPROVADO. Se reprovado, leia o campo reason da resposta, corrija e reenvie.

Recebi erro na criação simplificada. A campanha ficou criada parcialmente? Não. O simpleCreate faz rollback parcial: se der erro durante a criação, a campanha recém-criada é removida automaticamente.

Quais são os limites de caracteres dos criativos Native? name até 60, title até 25, brand até 25, description 65–90, destinationUrl 9–1017. Fora dessas faixas, a API retorna 400 com o detalhe em message.

Posso pausar várias campanhas/grupos/criativos de uma vez? Sim. Os endpoints de changeStatus aceitam múltiplos IDs separados por vírgula, por exemplo PUT /campaigns/1,2,3/changeStatus/PAUSE.

Como faço para testar rápido sem escrever código? Use o Swagger: clique em Authorize, informe sua API key e dispare as chamadas direto pelo navegador.

Não encontrou o que precisava?

Entre em contato nos nossos principais canais.

whatsapp
WhatsApp 4003-1838 (de segunda à sexta, das 9h às 17h)
email
E-mail uolads@uol.com.br