vtexads-api-docs

5.5. Consulta de Anuncios

Con el catálogo sincronizado, su plataforma solicita anuncios para completar los espacios publicitarios (placements). La solicitud es un POST y el publisher_id debe ser informado en la URL.

Endpoint: POST https://newtail-media.newtail.com.br/v1/rma/:publisher_id
Content-Type: Todas las solicitudes deben incluir el encabezado Content-Type: application/json

Buenas Prácticas de Solicitud

Persistencia HTTP: Prefiera conexiones persistentes (Connection: keep-alive).
Timeout: Aplique un timeout de 500–600 ms en la consulta (ver 5.6 para eventos).

Parámetros de la Solicitud

Campo	Descripción	Tipo	Obligatoriedad
`session_id`	Identificador persistente del visitante (≥ 14 días).	String	Sí
`user_id`	ID único del usuario logueado (alfanumérico).	String	No (Recomendado)
`store_id`	Filtra anuncios por stock de una tienda específica.	String	No
`channel`	Canal de acceso: `site`, `msite`, `app` (para consulta).	String	Sí
`context`	Contexto: `home`, `category`, `search`, `product_page`, `brand_page`, `digital_signage`.	String	Sí
`term`	Término buscado por el usuario.	String	Solo `context: 'search'`
`category_name`	Categoría navegada (breadcrumb completo).	String	Solo `context: 'category'`
`product_sku`	SKU del producto que se está visualizando.	String	Solo `context: 'product_page'`
`brand_name`	Nombre de la marca que se está visualizando.	String	Solo `context: 'brand_page'`
`device_id`	ID único del dispositivo (pantalla, tótem).	String	Solo `context: 'digital_signage'`
`store_name`	Nombre de la tienda donde está ubicado el dispositivo.	String	Solo `context: 'digital_signage'`
`placements`	Objeto que define los espacios (`placements`) de anuncio.	Object	Sí
`placements.{name}.quantity`	Cantidad de anuncios deseada.	Integer	Sí
`placements.{name}.size`	Tamaño esperado (Imagen: `desktop`/`mobile`; Video: `1080p`/`720p`/`480p`/`360p`/`320p`).	String	Solo `types: ['banner', 'sponsored_brand']`
`placements.{name}.types`	Tipos permitidos (`product`, `banner`, etc.).	Array[String]	Sí
`placements.{name}.assets_type`	Medios aceptados (`image`, `video`). Por defecto: `["image"]`.	Array[String]	Solo `types: ['banner', 'sponsored_brand']`
`placements.{name}.allow_sku_duplications`	Permite mostrar el mismo SKU más de una vez dentro del mismo placement.	Boolean	No (Default=false)
`userAgent`	Identificación del entorno del cliente (campo en el cuerpo, no el header HTTP `User-Agent`).	String	No
`segmentation`	Datos para segmentación en tiempo real.	Array[Object]	No
`segmentation.#.key`	El tipo de segmentación.	String	No
`segmentation.#.values`	Array de valores para la segmentación.	Array[String]	No
`tags`	“Etiquetas” para contextualizar búsquedas (principalmente en `search`). Máx. 10 por SKU, 64 caracteres por tag. Solo para campañas de `product`.	Array[String]	No
`brand`	Nombre del sitio del publisher.	String	Obligatorio cuando el publisher tiene múltiples sitios
`dedup_campaign_ads`	Deduplicar por campaña (máximo 1 anuncio por campaña en la respuesta).	Boolean	No (Default=false)
`dedup_ads`	Deduplicar por `ad_id` entre múltiples placements (usar solo al consultar múltiples placements al mismo tiempo).	Boolean	No (Default=false)

Campos por Contexto

Contexto	Campos adicionales obligatorios
`home`	—
`search`	`term`
`category`	`category_name`
`product_page`	`product_sku`
`brand_page`	`brand_name`
`digital_signage`	`device_id`, `store_name`

⚠️ Reglas Importantes de Contexto y Elegibilidad de Anuncios

Limitaciones de Filtro

Importante: No es posible hacer filtro por placement específico. La selección de anuncios se basa en el context y en los parámetros de la solicitud.

Elegibilidad por Contexto

Contexto `home`

En el contexto home, pueden ser retornados:

✅ Anuncios de Banner/Video/Sponsored Brands que utilicen categoría como criterio de segmentación
✅ Anuncios de Productos (Sponsored Products) también son elegibles

Ejemplo:

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

Contexto `search`

En el contexto search, pueden ser retornados:

✅ Anuncios de Banner/Video/Sponsored Brands que sean de keyword (palabra clave)
✅ Cualquier campaña de Producto (Sponsored Products)

⚠️ Match Exacto de Keywords:

El match de keywords en el contexto search es exacto (sin stemming/sinónimos). Esto significa que:

El anunciante necesita especificar exactamente cuáles keywords desea utilizar en la campaña de Banner/Video/Sponsored Brands
Si el usuario busca “zapatillas nike”, el anuncio solo será elegible si el anunciante registró exactamente la keyword “zapatillas nike”
No hay correspondencia aproximada o por palabras similares

Ejemplo:

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

Comportamiento esperado:

Banner/Sponsored Brand: Solo aparecerá si el anunciante registró la keyword exacta “zapatillas nike” en la campaña
Sponsored Products: Productos relacionados al término de búsqueda serán retornados

Contexto `brand_page`

En el contexto brand_page, pueden ser retornados:

✅ Anuncios de Banner/Video/Sponsored Brands de la marca
✅ Anuncios de Productos (Sponsored Products) de la marca

Ejemplo:

{
  "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`

En el contexto digital_signage, pueden ser retornados anuncios para pantallas/tótems físicos.

Ejemplo:

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

Contexto `category`

En el contexto category, pueden ser retornados:

✅ Anuncios de Banner/Video/Sponsored Brands que utilicen la categoría correspondiente
✅ Anuncios de Productos (Sponsored Products) de la categoría

Ejemplo:

{
  "context": "category",
  "category_name": "Deportes > Calzado > Zapatillas",
  "placements": {
    "site_category_top_banner": {
      "quantity": 1,
      "types": ["banner", "sponsored_brand"],
      "assets_type": ["image", "video"]
    }
  }
}

Contexto `product_page`

En el contexto product_page, pueden ser retornados:

✅ Anuncios de Productos (Sponsored Products) relacionados al producto visualizado

Ejemplo:

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

Respuesta de la Consulta

La respuesta es un JSON donde cada clave es un nombre de placement. La estructura de cada anuncio en la respuesta depende de su tipo.

Campos Comunes de Respuesta para Todos los Tipos de Anuncios

Estos campos están presentes en todos los tipos de anuncios:

Campo	Descripción
`{placementName}.#.ad_id`	ID único del anuncio.
`{placementName}.#.type`	Tipo del anuncio (`product`, `banner`, `sponsored_brand`, `digital_signage`).
`{placementName}.#.click_url`	URL para notificar el evento de clic.
`{placementName}.#.impression_url`	URL para notificar el evento de impresión.
`{placementName}.#.view_url`	URL para notificar el evento de visualización.
`{placementName}.#.seller_id`	ID del vendedor del producto anunciado (opcional).

Campos de Respuesta Específicos por Tipo

Anuncios de Producto

Campos adicionales para anuncios del tipo product:

Campo	Descripción
`{placementName}.#.product_sku`	SKU del producto anunciado.

Campos adicionales para anuncios del tipo banner:

Campo	Descripción
`{placementName}.#.media_url`	URL de la imagen o video a ser exhibido.

Anuncios de Marca Patrocinada

Campos adicionales para anuncios del tipo sponsored_brand:

Campo	Descripción
`{placementName}.#.media_url`	URL de la imagen o video a ser exhibido.
`{placementName}.#.products`	Array de productos asociados a la marca patrocinada.
`{placementName}.#.products.#.product_sku`	SKU del producto asociado.
`{placementName}.#.products.#.media_url`	URL de la imagen del producto.

Anuncios de Digital Signage

Campos adicionales para anuncios del tipo digital_signage:

Campo	Descripción
`{placementName}.#.media_url`	URL de la imagen o video a ser exhibido.
`{placementName}.#.duration`	Duración de la exhibición del anuncio en segundos.

Ejemplo de Respuesta (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_shelf_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"
    }
  ]
}

Buenas Prácticas

Nomenclatura de Placements

Adopte un estándar claro, como {canal}_{contexto}_{posicion}_{tipo} (ej: msite_search_top-shelf_product). Para recomendaciones detalladas, consulte es/docs/5.5.1-recomendacion-de-nombres-de-placements.md.

canal	contexto	posición	tipo	ejemplo
site	home	middle	banner	site_home_middle_banner
msite	product	top-shelf	product	msite_product_top-shelf_product
app	search	top-shelf	product	app_search_top-shelf_product
app	search	top-shelf	banner	app_search_top-shelf_banner
site	category	bottom-shelf	banner	site_category_bottom-shelf_banner
site	product	filter-bar	product	site_product_filter-bar_product

Tamaños de Imagen Estándar IAB

Para anuncios de tipo banner, es importante utilizar imágenes en los formatos estándar definidos por el IAB (Interactive Advertising Bureau). Esto garantiza la compatibilidad y una mejor experiencia visual en diferentes sitios y dispositivos.

Formatos Principales:

Rectángulo Mediano: 300x250 píxeles
Leaderboard: 728x90 píxeles
Skyscraper Ancho: 160x600 píxeles
Leaderboard Móvil: 320x50 píxeles
Billboard: 970x250 píxeles
Media Página: 300x600 píxeles

Opciones de Tamaño para Videos

Para solicitudes de anuncios de video, debe especificar el parámetro de tamaño para filtrar por resolución de video. Las opciones disponibles son:

1080p (1920x1080 pixels) - Recomendado solo para videos en pantalla completa
720p (1280x720 pixels) - Recomendado solo para videos en pantalla completa
480p (854x480 pixels)
360p (640x360 pixels)
320p (568x320 pixels) - Recomendado para dispositivos móviles

Importante: Al solicitar anuncios de video, use solo el identificador de resolución (ej: "720p") en el parámetro size, no las dimensiones completas. Por ejemplo, para filtrar por resolución 1280x720, use "size": "720p" en su solicitud de anuncio.

Segmentación de Anuncios

Dirija anuncios a públicos específicos para aumentar la relevancia.

Segmentación en Tiempo Real

Envíe datos demográficos o de audiencia directamente en el cuerpo de la consulta de anuncios, en el campo segmentation.

El campo segmentation es un array de objetos, donde cada objeto contiene:

key: El tipo de segmentación (ej: “STATE”, “CITY”, “GENDER”)
values: Array de valores para la segmentación

Ejemplo de Segmentación:

[
    {
        "key": "STATE",
        "values": [
            "CABA"
        ]
    },
    {
        "key": "CITY",
        "values": [
            "Buenos Aires"
        ]
    }
]

Tipos de Segmentación Disponibles:

Clave (key)	Descripción	Ejemplos de Valores
`STATE`	Provincia/Estado del usuario	“CABA”, “Buenos Aires”, “Córdoba”
`CITY`	Ciudad del usuario	“Buenos Aires”, “Córdoba”, “Rosario”
`GENDER`	Género del usuario	“M”, “F”
`AGE`	Edad del usuario	“22”, “35”
`AUDIENCES`	Audiencia personalizada	“clientes_alto_valor”, “abandonadores_carrito”
`NBO_CATEGORIES`	Indica las posibles categorías que el usuario tiene intención de comprar	“Electrónica”, “Libros”

Códigos de Respuesta y Errores

200 OK: Consulta procesada con éxito (retorna JSON por placement).
422 Unprocessable Entity: Error de validación de campos (formato compatible con JSON Schema/Ajv).
400 Bad Request / 404 Not Found: Solicitud inválida o recurso no encontrado.
429 Too Many Requests: Límite de solicitudes excedido.
5xx: Errores internos.

Ejemplo 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 Anuncios

Buenas Prácticas de Solicitud

Parámetros de la Solicitud

Campos por Contexto

⚠️ Reglas Importantes de Contexto y Elegibilidad de Anuncios

Limitaciones de Filtro

Elegibilidad por Contexto

Contexto home

Contexto search

Contexto brand_page

Contexto digital_signage

Contexto category

Contexto product_page

Respuesta de la Consulta

Campos Comunes de Respuesta para Todos los Tipos de Anuncios

Campos de Respuesta Específicos por Tipo

Anuncios de Producto

Anuncios de Banner

Anuncios de Marca Patrocinada

Anuncios de Digital Signage

Ejemplo de Respuesta (multi-placement)

Buenas Prácticas

Nomenclatura de Placements

Tamaños de Imagen Estándar IAB

Opciones de Tamaño para Videos

Segmentación de Anuncios

Segmentación en Tiempo Real

Códigos de Respuesta y Errores

Contexto `home`

Contexto `search`

Contexto `brand_page`

Contexto `digital_signage`

Contexto `category`

Contexto `product_page`