vtexads-api-docs

El primer paso es la sincronización, que ocurre en dos frentes:

Nota para tiendas VTEX: Para tiendas en la plataforma VTEX, la sincronización del catálogo ocurre de forma transparente, no siendo necesaria ninguna integración adicional para este fin.

Sincronización de Productos

Envío de la información de registro de los productos. Requiere autenticación.

Campo Descrição Tipo ¿Obligatorio?
product_sku ID/SKU único del producto. String Sí
parent_sku SKU del producto padre (para variaciones). String No
name Nombre del producto. String Sí
url URL canónica de la página del producto. String Sí
image_url URL de la imagen principal del producto. String No
categories Lista de categorías. Array[String] Sí
brand Marca del producto. String No
gtins Códigos de barras (EAN). Obligatorio para campañas en la VTEX Ads Network. Array[String] No/Sí
tags “Etiquetas” para contextualizar búsquedas. Máx. 10 por SKU, 64 caracteres por tag. Solo para campañas de product. Array[String] No
sellers Lista de sellers que venden el producto (en un marketplace). Array[String] No
metadata Objeto para información adicional (clave-valor). Object No

Estructuración de Categorías

Importante: El campo categories es crucial para la segmentación de campañas y la organización de productos. Debe ser estructurado jerárquicamente, representando la ruta completa desde la categoría raíz hasta la categoría específica del producto.

El campo categories debe ser un array de strings, donde cada string es un nivel del árbol de categorías. La jerarquía se construye enviando todas las categorías padre hasta la más específica.

Ejemplo Correcto:

Para un producto en la categoría de perfumes “Para Mujer”, el array categories debería ser:

"categories": [
    "Belleza",
    "Belleza > Fragancias",
    "Belleza > Fragancias > Perfume",
    "Belleza > Fragancias > Perfume > Para Mujer"
]

Esta estructura permite a la plataforma entender el contexto del producto en todos los niveles, desde el más amplio (“Belleza”) hasta el más específico (“Para Mujer”).

Ejemplo de Solicitud:

curl --location 'https://api-retail-media.newtail.com.br/product/bulk/products' \
--header 'x-app-id: XXXX' \
--header 'x-api-key: YYYY' \
--header 'Content-Type: application/json' \
--data '[
    {
        "product_sku": "allan",
        "name": "allan",
        "url": "https://www.panvel.com/panvel/eau-de-dali-salvador-dali-eau-de-toilette-perfume-feminino-30ml/p-10007616",
        "image_url": "https://panvelprd.vteximg.com.br/arquivos/ids/177629",
        "categories": [
            "Belleza",
            "Belleza > Fragancias",
            "Belleza > Fragancias > Perfume",
            "Belleza > Fragancias > Perfume > Para Mujer"
        ],
        "brand": "SALVADOR DALÍ",
        "profit_margin": null,
        "gtins": [
            "3331438450103"
        ],
        "sellers": [],
        "skus": []
    },
    {
        "product_sku": "allan2",
        "name": "allan2",
        "url": "https://www.panvel.com/panvel/eau-de-dali-salvador-dali-eau-de-toilette-perfume-feminino-30ml/p-10007616",
        "image_url": "https://panvelprd.vteximg.com.br/arquivos/ids/177629",
        "categories": [
            "Belleza",
            "Belleza > Fragancias",
            "Belleza > Fragancias > Perfume",
            "Belleza > Fragancias > Perfume > Para Mujer"
        ],
        "brand": "SALVADOR DALÍ",
        "profit_margin": null,
        "gtins": [
            "3331438450103"
        ],
        "sellers": [],
        "skus": [],
        "tags": ["Abart", "Mega Maio"]
    }
]'

Ejemplo de Respuesta Exitosa:

Status: 202 Accepted
Content-Type: application/json

{
    "messages": [
        "products will be processed soon"
    ]
}

Sincronización de Inventario

Envío de la información de precio y stock de los productos. Requiere autenticación.

Campo Descripción Tipo ¿Obligatorio?
product_sku ID/SKU único del producto. String Sí
price Precio actual del producto. Float Sí
promotional_price Precio “de” (listado/original). Float Sí
is_available Producto disponible (en stock). Boolean Sí
store_id ID de la tienda. Si no se proporciona el ID de la tienda, se interpretará como que esta información de inventario se utilizará para todas las tiendas. String No
metadata Objeto para información adicional (clave-valor). Object No

Ejemplo de Solicitud:

curl --location 'https://api-retail-media.newtail.com.br/product/bulk/inventories' \
--header 'x-app-id: XXXX' \
--header 'x-api-key: YYYY' \
--header 'Content-Type: application/json' \
--data '[
    {
      "product_sku": "120210",
      "store_id": "1",
      "price": 18.20,
      "promotional_price": 16.32,
      "is_available": true
    },
    {
      "product_sku": "120212",
      "price": 18.20,
      "promotional_price": 0, // Eliminar precio promocional
      "is_available": true
    }
]'

Ejemplo de Respuesta Exitosa:

Status: 202 Accepted
Content-Type: application/json

{
    "messages": [
        "inventory will be processed soon"
    ]
}

Buenas Prácticas para Sincronización

  1. Sincronización Inicial Completa:
    • Envíe todo el catálogo en la primera sincronización.
    • Divida en lotes de hasta 500 productos para evitar timeouts.
  2. Actualizaciones Incrementales:
    • Después de la sincronización inicial, envíe solo productos nuevos o modificados.
    • Mantenga un registro de la última fecha de modificación de cada producto.
  3. Frecuencia de Actualización:
    • Precios y stock: Actualice al menos una vez al día, idealmente en tiempo real para cambios significativos.
    • Información de registro: Actualice cuando haya cambios.
  4. Tratamiento de Errores:
    • Implemente reintentos con backoff exponencial para fallos temporales.
    • Monitoree las respuestas de la API para identificar problemas persistentes.
  5. Validación de Datos:
    • Verifique que todos los campos obligatorios estén completos.
    • Asegúrese de que las URLs de productos e imágenes sean válidas y accesibles.
    • Asegúrese de que las categorías sigan la estructura jerárquica recomendada.