Feeds JSON personalizados: especificación técnica y mapeo de campos

Introducción a los feeds JSON personalizados

Los feeds JSON personalizados ofrecen flexibilidad máxima para distribuir datos de productos a través de canales de marketing digital. A diferencia de formatos predefinidos como CSV o XML, el JSON personalizado permite que los comerciantes definan la estructura de datos según sus necesidades específicas y los requisitos de cada plataforma de distribución.

Este documento proporciona la especificación técnica completa para implementar feeds JSON, incluyendo la estructura de esquema, validación de campos, y directrices de mapeo que garantizan la aprobación de anuncios y la calidad de los datos en tiempo real.

Estructura fundamental del formato JSON personalizado

Un feed JSON personalizado se compone de una estructura jerárquica que organiza los datos de productos en objetos y matrices. La estructura base sigue este patrón:

{
  "productos": [
    {
      "id": "SKU-001",
      "title": "Nombre del producto",
      "description": "Descripción completa",
      "price": 99.99,
      "availability": "in_stock",
      "image_link": "https://ejemplo.com/imagen.jpg",
      "link": "https://ejemplo.com/producto",
      "brand": "Marca",
      "condition": "new"
    }
  ]
}

Cada producto debe ser un objeto JSON válido dentro de la matriz principal. Los navegadores y plataformas de distribución validan esta estructura antes de procesar los datos. Si la sintaxis JSON es incorrecta, el feed completo será rechazado y no se publicarán anuncios.

Campos obligatorios y su impacto en la aprobación

Los campos obligatorios varían según el canal de distribución destino, pero existen campos fundamentales que prácticamente todos los canales requieren:

Tipos de datos y validación

El JSON personalizado requiere tipado estricto. Los errores de tipo común que causan rechazo incluyen:

Números: El campo price debe ser un número, no una cadena. "price": 99.99 es válido; "price": "99.99" causa error de validación.

Booleanos: Los campos de estado deben usar valores booleanos verdaderos. "in_stock": true es correcto; "in_stock": "true" es incorrecto.

URLs: Todas las URLs deben incluir protocolo (http:// o https://). URLs relativas son rechazadas por validadores de feed.

Fechas: Si utiliza campos de fecha, el formato ISO 8601 (AAAA-MM-DD) es estándar. Formatos localizados causan errores de parseo.

Matrices anidadas: Los atributos múltiples (colores, tallas, imágenes adicionales) se representan como matrices dentro del objeto del producto:

{
  "id": "SKU-001",
  "title": "Camiseta de algodón",
  "colors": ["rojo", "azul", "verde"],
  "images": [
    {"url": "https://ejemplo.com/img1.jpg", "alt": "Vista frontal"},
    {"url": "https://ejemplo.com/img2.jpg", "alt": "Vista trasera"}
  ]
}

Mapeo de campos personalizados a canales de distribución

Cuando configura un feed JSON personalizado, debe asignar sus campos personalizados a los campos esperados por cada canal de distribución. Este mapeo es crítico para la aprobación de anuncios.

Mapeo de campos de producto:

Validación y prueba antes de distribución

Antes de enviar un feed JSON personalizado a cualquier canal, debe validar su estructura completa. Las herramientas de validación JSON verifican:

• Sintaxis correcta (llaves, comas, comillas balanceadas).
• Tipos de datos consistentes en todos los productos.
• Ausencia de caracteres especiales no escapados en cadenas.
• Longitudes de campo dentro de límites permitidos.
• Presencia de campos obligatorios en cada producto.

Un validador JSON gratuito en línea puede identificar errores de sintaxis antes de que afecten la distribución. Los errores comunes incluyen comas faltantes entre propiedades, comillas sin cerrar, y caracteres especiales (como tildes) sin codificación UTF-8 correcta.

Configuración de actualización y frecuencia de feed

Los feeds JSON personalizados pueden configurarse para actualización automática o manual:

Actualización automática: El servidor de distribución consulta la URL del feed a intervalos regulares (generalmente cada 24 horas). Si el feed contiene cambios de precio o disponibilidad, se actualizan automáticamente en los anuncios.

Actualización manual: Usted carga el archivo JSON directamente en la plataforma. Esta opción es útil para cambios puntuales o cuando el feed es pequeño.

La frecuencia de actualización afecta la precisión de los datos. Un feed que se actualiza cada 24 horas puede mostrar precios desactualizados si cambian varias veces al día. Algunos canales permiten actualización cada hora o incluso en tiempo real mediante API.

Inclusión de campos opcionales para mejorar la calidad

Más allá de los campos obligatorios, incluir campos opcionales mejora significativamente el rendimiento del anuncio y la aprobación:

• google_product_category: Categoría del producto según taxonomía de Google. Ejemplo: "Ropa y accesorios > Ropa > Camisetas". Mejora la relevancia en búsquedas.
• product_type: Su categoría interna. Ejemplo: "Camisetas de algodón". Complementa la categoría de Google.
• item_group_id: Agrupa variantes (colores, tallas) bajo un producto padre. Crítico para productos con múltiples opciones.
• gtin: Código de barras (EAN, UPC). Aumenta confianza y permite validación de datos.
• mpn: Número de parte del fabricante. Identifica productos únicos sin ambigüedad.
• sale_price: Precio con descuento. Muestra ahorros en anuncios.
• sale_price_effective_date: Rango de fechas para promoción. Formato: "AAAA-MM-DD/AAAA-MM-DD".

Manejo de caracteres especiales y codificación

El JSON requiere codificación UTF-8. Los caracteres especiales deben escaparse correctamente:

• Comillas: " se escribe como \"
• Barras invertidas: \ se escribe como \\
• Saltos de línea: se escriben como \n
• Tabulaciones: se escriben como \t

Ejemplo correcto:

{
  "title": "Camiseta con frase \"Viaje al paraíso\"",
  "description": "Descripción con salto\nde línea"
}

Los acentos y caracteres latinos (á, é, í, ó, ú, ñ) no requieren escape si el archivo está codificado en UTF-8. Sin embargo, algunos sistemas legados requieren codificación HTML de caracteres especiales (ejemplo: á en lugar de á). Verifique los requisitos del canal destino.

Integración con sistemas de inventario

Para comerciantes con inventario dinámico, el feed JSON personalizado debe conectarse a un sistema de gestión de inventario. Esta integración asegura que:

• El availability se actualiza automáticamente cuando el stock cambia.
• Los precios reflejan cambios en tiempo real.
• Los productos agotados se pausan automáticamente en anuncios.

La mayoría de plataformas de distribución ofrecen webhooks o API para actualizar campos específicos sin recargar el feed completo. Esto reduce la latencia y mejora la precisión.

Errores comunes y resolución

Error: "Feed inválido"
Causa: Sintaxis JSON incorrecta. Solución: Valide con un herramienta JSON validator. Busque comas faltantes, comillas sin cerrar, o caracteres especiales sin escape.

Error: "Campo obligatorio faltante"
Causa: Un producto no incluye un campo requerido (ejemplo: id, price, image_link). Solución: Agregue el campo a todos los productos. Si algunos productos no tienen valor, use un valor por defecto o excluya el producto.

Error: "Precio inválido"
Causa: El precio está en formato de cadena o contiene caracteres no numéricos. Solución: Asegúrese de que price es un número sin comillas: "price": 99.99, no "price": "99.99".

Error: "URL rota"
Causa: El campo link o image_link apunta a una URL que no responde o devuelve error 404. Solución: Verifique que todas las URLs sean accesibles y usen protocolo https://.

Error: "Disponibilidad no reconocida"
Causa: El campo availability contiene un valor que el canal no reconoce. Solución: Use valores estándar: "in_stock", "out_of_stock", "preorder". Verifique la documentación del canal específico.

Mejores prácticas para feeds JSON de alto rendimiento

Optimización de tamaño: Los feeds grandes (más de 100 MB) pueden ser lentos de procesar. Comprima el archivo con gzip si la plataforma lo soporta. Divida feeds muy grandes en múltiples archivos por categoría.

Consistencia de datos: Asegúrese de que los títulos, descripciones y precios sean consistentes con su sitio web. Datos inconsistentes generan desaprobaciones por engaño.

Imágenes de calidad: Incluya imágenes de alta resolución (mínimo 800x800 píxeles). Imágenes borrosas o de baja calidad causan rechazo manual.

Descripciones únicas: No copie descripciones de competidores. Cada producto debe tener descripción original que destaque características y beneficios.

Prueba incremental: Si distribuye a múltiples canales, comience con uno para validar el mapeo de campos. Luego expanda a otros canales.

Resumen y próximos pasos

Los feeds JSON personalizados requieren atención cuidadosa a la estructura, tipado de datos y mapeo de campos. Una configuración correcta asegura aprobación rápida de anuncios, datos precisos en tiempo real, y mejor rendimiento en campañas de marketing.

Antes de distribuir su feed, valide la sintaxis JSON, verifique que todos los campos obligatorios estén presentes, y pruebe el mapeo con un producto de ejemplo en cada canal destino. Esto minimiza rechazos y acelera el tiempo para activar anuncios.

Si distribuye a canales específicos como Amazon, Criteo o Awin, consulte las guías técnicas de esos canales para requisitos adicionales que pueden diferir del estándar JSON básico.