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 dá para fazer

  • 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.
  • Enviar públicos personalizados (segmentos de conta) por upload de arquivo CSV.
  • Extrair relatórios de analytics, domínios, regiões, dispositivos e conversões.

Como pensar na API (modelo mental)

Tudo na Ads API gira em torno de uma hierarquia simples. Você começa com uma Campanha, adiciona Grupos dentro dela (onde ficam o orçamento e as regras de veiculação) e, por fim, coloca os Criativos (Native ou Display) dentro dos grupos. Um atalho chamado Criação Simplificada monta essa estrutura inteira em uma única chamada.

Antes de qualquer coisa, porém, você precisa de uma chave de API para se autenticar. Vamos por partes — comece pelo Início Rápido.

Início Rápido

Este é o caminho mais curto entre "não tenho nada" e "meu 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.",
    "ctaText": "Saiba mais",
    "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", "ctaText": "Comprar", "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 mergulhar nos endpoints, vale entender como os recursos se relacionam. Todo o restante do guia parte desses 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

Existem dois "eixos" de status na plataforma:

  • Estado operacional (Campanha e Grupo): ATIVO ou PAUSADO. Você controla isso pelos endpoints de changeStatus com as ações RESUME (retomar) e PAUSE (pausar).
  • Estado de moderação (Native e Display): PENDENTE → APROVADO ou REPROVADO. Um criativo novo entra como PENDENTE; se reprovado, a API retorna o motivo no campo reason.

Segmentos de audiência

Você pode direcionar a veiculação para públicos personalizados — os account segments. Eles são criados na sua conta e depois vinculados a um grupo no momento da criação ou edição. É possível popular um segmento com uma lista de usuários via upload de CSV em lote. Veja Segmentação de Audiência.

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 serviço ads-user-manager, através da rota POST /ads-api-keys/{idt_person}.
  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. As chaves são do tipo SHA-1.
  5. É permitida apenas uma chave por idtPerson.

Documentação interna de autenticação: Confluence — Autenticação da API.

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)

Alguns caminhos são liberados e não exigem o cabeçalho Authorization:

  • /health
  • /favicon.ico
  • /swagger-ui
  • /v3/api-docs

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).

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 é o coração operacional da veiculação. É nele que você define quanto, quando e para quem os anúncios serão exibidos. Todo grupo pertence a uma campanha.

O que um grupo controla

  • budget — orçamento do grupo (mínimo: 1).
  • rate — taxa de CPM (custo por mil impressões).
  • startDate / endDate — período de veiculação (YYYY-MM-DD). O fim é opcional.
  • adult — marca o grupo como conteúdo adulto (padrão: false).
  • accountSegments — segmentos de audiência vinculados (opcional).

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"
  }'

Com segmentação de audiência:

{
  "name": "Grupo com público-alvo",
  "campaign": { "id": 1 },
  "budget": 150,
  "rate": 1.5,
  "adult": false,
  "startDate": "2025-01-17",
  "endDate": "2025-12-31",
  "accountSegments": [
    { "id": 0, "name": "accountSegment1", "accountId": 0, "xandrId": 0 }
  ]
}

Ajustar, pausar/retomar, listar

# 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" }'

# 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"

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

Criativos — Native

O Native é o anúncio que se integra visualmente ao conteúdo da página, parecendo parte dela. É o formato mais rico em campos.

Anatomia de um Native

Campo Obrigatório Regra
name Sim Nome interno do anúncio (1–25 caracteres)
group.id Sim Grupo ao qual pertence
destinationUrl Sim Página de destino (9–1017 caracteres)
title Sim Título exibido (1–25 caracteres)
description Sim Descrição (65–90 caracteres)
brand Sim Marca (1–25 caracteres)
ctaText Sim Texto do botão de ação (1–15 caracteres)
imageBase64 Sim Imagem principal em Base64
secondaryImageBase64 Não Imagem secundária em Base64
logoBase64 Não Logo em Base64

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",
    "ctaText": "Comprar agora",
    "imageBase64": "..."
  }'

Editar, pausar/retomar, listar

# 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" }'

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

# 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 é o formato de banner: mais simples que o Native, focado em uma imagem e uma URL de destino.

Anatomia de um Display

Campo Obrigatório Regra
name Sim Nome interno (1–25 caracteres)
group.id Sim Grupo ao qual pertence
destinationUrl Sim Página de destino (9–1017 caracteres)
imageBase64 Sim Imagem do banner em Base64

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.

Exemplos

# 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": "..." }'

# 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" }'

# Pausar/retomar e listar
curl -X PUT "https://api.ads.uol.com.br/creatives/displays/1/changeStatus/PAUSE" \
  -H "Authorization: SUA_API_KEY"
curl "https://api.ads.uol.com.br/creatives/displays?groupId=1" \
  -H "Authorization: SUA_API_KEY"

Criação Simplificada

Quando você só quer colocar um anúncio no ar rapidamente, não precisa criar campanha, grupo e criativo em três chamadas. O endpoint POST /natives/simpleCreate monta toda a estrutura (Campanha + Grupo + Native) em uma única requisição.

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 CPM
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 Não Máx. 25
ctaText Sim Máx. 15
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.",
    "ctaText": "Ver mais",
    "imageBase64": "..."
  }'

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

Segmentação de Audiência

Segmentar é escolher para quem seus anúncios aparecem. Na Ads API isso é feito com segmentos de conta (account segments): listas de audiência que você cria na sua conta e depois vincula a grupos (veja Grupos).

A jornada com segmentação

  1. Criar um segmento na sua conta.
  2. Popular o segmento com uma lista de usuários via upload de CSV em lote.
  3. Acompanhar o job de importação até concluir.
  4. Vincular o segmento a um grupo (no POST /groups ou PATCH /groups/{id}).

Criar um segmento

curl -X POST "https://api.ads.uol.com.br/account-segments" \
  -H "Authorization: SUA_API_KEY" -H "Content-Type: application/json" \
  -d '{ "name": "Clientes VIP", "accountId": 0, "xandrId": 0 }'

Enviar usuários em lote (CSV)

O envio é feito por multipart/form-data, no campo file. Tipos aceitos: text/csv, text/plain, application/vnd.ms-excel, application/octet-stream.

curl -X POST "https://api.ads.uol.com.br/account-segments/123/batch" \
  -H "Authorization: SUA_API_KEY" \
  -F "file=@usuarios.csv"

A resposta é um AccountSegmentJob com o status do processamento iniciado. Como o upload é assíncrono, você consulta o andamento depois:

curl "https://api.ads.uol.com.br/account-segments/batch/456" \
  -H "Authorization: SUA_API_KEY"

Listar segmentos

curl "https://api.ads.uol.com.br/account-segments" -H "Authorization: SUA_API_KEY"

Retorna todos os segmentos associados à conta do usuário autenticado.

Relatórios e Métricas

Depois que os anúncios estão veiculando, é hora de medir. Os relatórios ficam sob /report/metrics/*. Todos são requisições GET e exigem startDate e endDate no formato 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 e na Referência de Endpoints.

Tratamento de Erros

Quando algo dá errado, a API responde com um código HTTP e um corpo JSON descrevendo o problema. Entender esse formato acelera muito a 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 (ou os tipos de CSV aceitos no batch)
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 Definido pela moderação (com reason se reprovado)
Display PENDENTE, APROVADO, REPROVADO Definido pela moderação (com reason se reprovado)

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

Referência de Endpoints

Este guia foca na jornada e nos conceitos. Para a referência detalhada de cada endpoint — todos os campos, tipos, obrigatoriedades e parâmetros de query — use:

  • 📄 API_DOCUMENTATION.md — referência completa dos endpoints.
  • 🔎 Swagger UI — documentação interativa e sempre atualizada, onde você também pode testar as chamadas (clique em Authorize e informe sua API key).

Mapa rápido de recursos

Recurso Base Documentado em
Campanhas /campaigns Campanhas · API_DOCUMENTATION.md
Grupos /groups Grupos · API_DOCUMENTATION.md
Criativos Native /creatives/natives Native · API_DOCUMENTATION.md
Criativos Display /creatives/displays Display · API_DOCUMENTATION.md
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 "meio criada"? 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 1–25, title 1–25, brand 1–25, ctaText 1–15, 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.

Como rodar a API localmente (para desenvolvedores)? Defina a variável de ambiente SWAGGER_CONTEXT_URL=http://localhost:8080. Veja o README.md do projeto para detalhes.

Este guia é a "parte escrita" da documentação. Para os detalhes técnicos de cada endpoint, consulte sempre a Referência de Endpoints.

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