vtexads-api-docs

5.5. Consulta de Anúncios

Com o catálogo sincronizado, sua plataforma requisita anúncios para preencher os espaços publicitários (placements). A requisição é um POST e o publisher_id deve ser informado na URL.

Endpoint: POST https://newtail-media.newtail.com.br/v1/rma/:publisher_id
Content-Type: Todas as requisições devem incluir o header Content-Type: application/json

Boas Práticas de Requisição

Persistência HTTP: Prefira conexões persistentes (Connection: keep-alive).
Timeout: Aplique timeout de 500–600 ms para a consulta (ver 5.6 para eventos).

Parâmetros da Requisição

Campo	Descrição	Tipo	Obrigatoriedade
`session_id`	Identificador persistente do visitante (≥ 14 dias).	String	Sim
`user_id`	ID único do usuário logado (alfanumérico).	String	Não (Recomendado)
`store_id`	Filtra anúncios por estoque de uma loja específica.	String	Não
`channel`	Canal de acesso: `site`, `msite`, `app` (para consulta).	String	Sim
`context`	Contexto: `home`, `category`, `search`, `product_page`, `brand_page`, `digital_signage`.	String	Sim
`term`	Termo buscado pelo usuário.	String	Apenas `context: 'search'`
`category_name`	Categoria navegada (breadcrumb completo).	String	Apenas `context: 'category'`
`product_sku`	SKU do produto sendo visualizado.	String	Apenas `context: 'product_page'`
`brand_name`	Nome da marca sendo visualizada.	String	Apenas `context: 'brand_page'`
`device_id`	ID único do dispositivo (tela, totem).	String	Apenas `context: 'digital_signage'`
`store_name`	Nome da loja onde o dispositivo está localizado.	String	Apenas `context: 'digital_signage'`
`placements`	Objeto que define os espaços (`placements`) de anúncio.	Object	Sim
`placements.{name}.quantity`	Quantidade de anúncios desejada.	Integer	Sim
`placements.{name}.size`	Tamanho esperado (Imagem: `desktop`/`mobile`; Vídeo: `1080p`/`720p`/`480p`/`360p`/`320p`).	String	Apenas `types: ['banner', 'sponsored_brand']`
`placements.{name}.types`	Tipos permitidos (`product`, `banner`, etc.).	Array[String]	Sim
`placements.{name}.assets_type`	Mídias aceitas (`image`, `video`). Padrão: `["image"]`.	Array[String]	Apenas `types: ['banner', 'sponsored_brand']`
`placements.{name}.allow_sku_duplications`	Permite retornar o mesmo SKU mais de uma vez dentro do mesmo placement.	Boolean	Não (Default=false)
`userAgent`	Identificação do ambiente do cliente (campo no corpo, não o header HTTP `User-Agent`).	String	Não
`segmentation`	Dados para segmentação em tempo real.	Array[Object]	Não
`segmentation.#.key`	O tipo de segmentação.	String	Não
`segmentation.#.values`	Array de valores para a segmentação.	Array[String]	Não
`tags`	“Etiquetas” para contextualizar buscas (principalmente em `search`). Máx. 10 por SKU, 64 chars por tag. Apenas para campanhas de `product`.	Array[String]	Não
`brand`	Nome do site do publisher.	String	Obrigatório quando o publisher possui mais de um site
`dedup_campaign_ads`	Deduplica por campanha (no máximo 1 anúncio por campanha na resposta).	Boolean	Não (Default=false)
`dedup_ads`	Deduplica por `ad_id` entre múltiplos placements (use apenas ao consultar múltiplos placements ao mesmo tempo).	Boolean	Não (Default=false)

Campos por Contexto

Contexto	Campos adicionais obrigatórios
`home`	—
`search`	`term`
`category`	`category_name`
`product_page`	`product_sku`
`brand_page`	`brand_name`
`digital_signage`	`device_id`, `store_name`

⚠️ Regras Importantes de Contexto e Elegibilidade de Anúncios

Limitações de Filtro

Importante: Não é possível fazer filtro por placement específico. A seleção de anúncios é baseada no context e nos parâmetros da requisição.

Elegibilidade por Contexto

Contexto `home`

No contexto home, podem ser retornados:

✅ Anúncios de Banner/Video/Sponsored Brands que utilizem categoria como critério de segmentação
✅ Anúncios de Produtos (Sponsored Products) também são elegíveis

Exemplo:

{
  "context": "home",
  "placements": {
    "site_home_middle_banner": {
      "quantity": 3,
      "types": ["banner", "sponsored_brand"],
      "assets_type": ["image", "video"],
      "size": "desktop"
    },
    "site_home_vitrine_product": {
      "quantity": 10,
      "types": ["product"]
    }
  }
}

Contexto `search`

No contexto search, podem ser retornados:

✅ Anúncios de Banner/Video/Sponsored Brands que sejam de keyword (palavra-chave)
✅ Qualquer campanha de Produto (Sponsored Products)

⚠️ Match Exato de Keywords:

O match de keywords no contexto search é exato (não há stemming/sinônimos). Isso significa que:

O anunciante precisa especificar exatamente quais keywords deseja utilizar na campanha de Banner/Video/Sponsored Brands
Se o usuário buscar “tênis nike”, o anúncio só será elegível se o anunciante cadastrou exatamente a keyword “tênis nike”
Não há correspondência aproximada ou por palavras semelhantes

Exemplo:

{
  "context": "search",
  "term": "tênis nike",
  "placements": {
    "site_search_top_banner": {
      "quantity": 1,
      "types": ["banner", "sponsored_brand"],
      "assets_type": ["image"],
      "size": "desktop"
    },
    "site_search_vitrine_product": {
      "quantity": 20,
      "types": ["product"]
    }
  }
}

Comportamento esperado:

Banner/Sponsored Brand: Só aparecerá se o anunciante cadastrou a keyword exata “tênis nike” na campanha
Sponsored Products: Produtos relacionados ao termo de busca serão retornados

Contexto `category`

No contexto category, podem ser retornados:

✅ Anúncios de Banner/Video/Sponsored Brands que utilizem a categoria correspondente
✅ Anúncios de Produtos (Sponsored Products) da categoria

Exemplo:

{
  "context": "category",
  "category_name": "Esportes > Calçados > Tênis",
  "placements": {
    "site_category_top_banner": {
      "quantity": 1,
      "types": ["banner", "sponsored_brand"],
      "assets_type": ["image", "video"]
    }
  }
}

Contexto `product_page`

No contexto product_page, podem ser retornados:

✅ Anúncios de Produtos (Sponsored Products) relacionados ao produto visualizado

Exemplo:

{
  "context": "product_page",
  "product_sku": "12345",
  "placements": {
    "site_product_recommendation": {
      "quantity": 5,
      "types": ["product"]
    }
  }
}

Contexto `brand_page`

No contexto brand_page, podem ser retornados:

✅ Anúncios de Banner/Video/Sponsored Brands da marca
✅ Anúncios de Produtos (Sponsored Products) da marca

Exemplo:

{
  "context": "brand_page",
  "brand_name": "Nike",
  "placements": {
    "site_brand_top_banner": {
      "quantity": 1,
      "types": ["banner", "sponsored_brand"],
      "assets_type": ["image"],
      "size": "desktop"
    },
    "site_brand_shelf_product": {
      "quantity": 12,
      "types": ["product"]
    }
  }
}

Contexto `digital_signage`

No contexto digital_signage, podem ser retornados anúncios para telas/totens físicos.

Exemplo:

{
  "context": "digital_signage",
  "device_id": "totem-abc-001",
  "store_name": "Loja Paulista",
  "placements": {
    "totem_home_main_video": {
      "quantity": 1,
      "types": ["banner"],
      "assets_type": ["video"],
      "size": "720p"
    }
  }
}

Resposta da Consulta

A resposta é um JSON onde cada chave é um nome de placement. A estrutura de cada anúncio na resposta depende do seu tipo.

Campos Comuns de Resposta para Todos os Tipos de Anúncios

Estes campos estão presentes em todos os tipos de anúncios:

Campo	Descrição
`{placementName}.#.ad_id`	ID único do anúncio.
`{placementName}.#.type`	Tipo do anúncio (`product`, `banner`, `sponsored_brand`, `digital_signage`).
`{placementName}.#.click_url`	URL para notificar o evento de clique.
`{placementName}.#.impression_url`	URL para notificar o evento de impressão.
`{placementName}.#.view_url`	URL para notificar o evento de visualização.
`{placementName}.#.seller_id`	ID do vendedor do produto anunciado (opcional).

Campos de Resposta Específicos por Tipo

Anúncios de Produto

Campos adicionais para anúncios do tipo product:

Campo	Descrição
`{placementName}.#.product_sku`	SKU do produto anunciado.

Campos adicionais para anúncios do tipo banner:

Campo	Descrição
`{placementName}.#.media_url`	URL da imagem ou vídeo a ser exibido.

Anúncios de Marca Patrocinada

Campos adicionais para anúncios do tipo sponsored_brand:

Campo	Descrição
`{placementName}.#.media_url`	URL da imagem ou vídeo a ser exibido.
`{placementName}.#.products`	Array de produtos associados à marca patrocinada.
`{placementName}.#.products.#.product_sku`	SKU do produto associado.
`{placementName}.#.products.#.media_url`	URL da imagem do produto.

Anúncios de Digital Signage

Campos adicionais para anúncios do tipo digital_signage:

Campo	Descrição
`{placementName}.#.media_url`	URL da imagem ou vídeo a ser exibido.
`{placementName}.#.duration`	Duração da exibição do anúncio em segundos.

Exemplo de Resposta (multi-placement)

{
  "site_home_middle_banner": [
    {
      "ad_id": "ad-001",
      "type": "banner",
      "media_url": "https://cdn.example.com/banner1.jpg",
      "impression_url": "https://events.../impression/abc",
      "view_url": "https://events.../view/abc",
      "click_url": "https://events.../click/abc"
    }
  ],
  "site_home_vitrine_product": [
    {
      "ad_id": "ad-101",
      "type": "product",
      "product_sku": "SKU-123",
      "seller_id": "SELLER-9",
      "impression_url": "https://events.../impression/def",
      "view_url": "https://events.../view/def",
      "click_url": "https://events.../click/def"
    }
  ]
}

Boas Práticas

Nomenclatura de Placements

Adote um padrão claro, como {canal}_{contexto}_{posicao}_{tipo} (ex: msite_search_top-shelf_product). Para recomendações detalhadas, consulte pt/docs/5.5.1-recomendacao-de-nomes-de-placements.md.

canal	contexto	posição	tipo	exemplo
site	home	middle	banner	site_home_middle_banner
msite	product	top-vitrine	product	msite_product_top-vitrine_product
app	search	top-vitrine	product	app_search_top-vitrine_product
app	search	top-vitrine	banner	app_search_top-vitrine_banner
site	category	bottom-vitrine	banner	site_category_bottom-vitrine_banner
site	product	filter-bar	product	site_product_filter-bar_product

Tamanhos de Imagem Padrão IAB

Para anúncios do tipo banner, é importante utilizar imagens nos formatos padrão definidos pelo IAB (Interactive Advertising Bureau). Isso garante a compatibilidade e uma melhor experiência visual em diferentes sites e dispositivos.

Formatos Principais:

Retângulo Médio: 300x250 pixels
Leaderboard: 728x90 pixels
Skyscraper Largo: 160x600 pixels
Leaderboard Móvel: 320x50 pixels
Billboard: 970x250 pixels
Meia Página: 300x600 pixels

Opções de Tamanho para Vídeos

Para solicitações de anúncios de vídeo, você deve especificar o parâmetro de tamanho para filtrar por resolução de vídeo. As opções disponíveis são:

1080p (1920x1080 pixels) - Recomendado apenas para vídeos em tela cheia
720p (1280x720 pixels) - Recomendado apenas para vídeos em tela cheia
480p (854x480 pixels)
360p (640x360 pixels)
320p (568x320 pixels) - Recomendado para dispositivos móveis

Importante: Ao solicitar anúncios de vídeo, use apenas o identificador de resolução (ex: "720p") no parâmetro size, não as dimensões completas. Por exemplo, para filtrar por resolução 1280x720, use "size": "720p" na sua solicitação de anúncio.

Segmentação de Anúncios

Direcione anúncios para públicos específicos para aumentar a relevância.

Segmentação em Tempo Real

Envie dados demográficos ou de audiência diretamente no corpo da consulta de anúncios, no campo segmentation.

O campo segmentation é um array de objetos, onde cada objeto contém:

key: O tipo de segmentação (ex: “STATE”, “CITY”, “GENDER”)
values: Array de valores para a segmentação

Exemplo de Segmentação:

[
    {
        "key": "STATE",
        "values": [
            "RJ"
        ]
    },
    {
        "key": "CITY",
        "values": [
            "Rio de Janeiro"
        ]
    }
]

Tipos de Segmentação Disponíveis:

Chave (key)	Descrição	Exemplo de Valores
`STATE`	Estado do usuário	“SP”, “RJ”, “MG”
`CITY`	Cidade do usuário	“São Paulo”, “Rio de Janeiro”
`GENDER`	Gênero do usuário	“M”, “F”
`AGE`	Idade do usuário	“22”, “35”
`AUDIENCES`	Audiência personalizada	“high_value_customers”, “cart_abandoners”
`NBO_CATEGORIES`	Indica quais as possíveis categorias que o usuário tem intenção de comprar	“Eletrônicos”, “Livros”

Códigos de Resposta e Erros

200 OK: Consulta processada com sucesso (retorna JSON por placement).
422 Unprocessable Entity: Erro de validação de campos (formato compatível com JSON Schema/Ajv).
400 Bad Request / 404 Not Found: Requisição inválida ou recurso inexistente.
429 Too Many Requests: Limite de requisições excedido.
5xx: Erros internos.

Exemplo de 422 (parcial):

[
  {
    "instancePath": "/context",
    "keyword": "enum",
    "message": "must be equal to one of the allowed values",
    "params": {"allowedValues": ["home","category","search","product_page","brand_page","digital_signage"]},
    "schemaPath": "#/properties/context/enum"
  }
]

vtexads-api-docs

5.5. Consulta de Anúncios

Boas Práticas de Requisição

Parâmetros da Requisição

Campos por Contexto

⚠️ Regras Importantes de Contexto e Elegibilidade de Anúncios

Limitações de Filtro

Elegibilidade por Contexto

Contexto home

Contexto search

Contexto category

Contexto product_page

Contexto brand_page

Contexto digital_signage

Resposta da Consulta

Campos Comuns de Resposta para Todos os Tipos de Anúncios

Campos de Resposta Específicos por Tipo

Anúncios de Produto

Anúncios de Banner

Anúncios de Marca Patrocinada

Anúncios de Digital Signage

Exemplo de Resposta (multi-placement)

Boas Práticas

Nomenclatura de Placements

Tamanhos de Imagem Padrão IAB

Opções de Tamanho para Vídeos

Segmentação de Anúncios

Segmentação em Tempo Real

Códigos de Resposta e Erros

Contexto `home`

Contexto `search`

Contexto `category`

Contexto `product_page`

Contexto `brand_page`

Contexto `digital_signage`