9- Fuentes de Datos (API JSON)

Las Fuentes de datos te permiten traer contenido de una API JSON externa y mostrarlo en tus pantallas. Conectas una API una sola vez en los ajustes de tu cuenta y luego la reutilizas en tantas plantillas como quieras.

EasySignage obtiene los datos en sus servidores y guarda una copia, así que:

• Tus pantallas (reproductores) nunca llaman directamente a tu API: solo muestran la copia.
• Tu API no recibe una llamada por cada pantalla.
• Las credenciales (tokens, claves de API) se guardan cifradas y nunca se envían de vuelta a un navegador ni a un reproductor.

Nota: Las Fuentes de datos son una función BETA disponible en el plan Enterprise. En otros planes la página muestra un aviso y no se puede cambiar. Hoy permiten mostrar una lista repetida de registros como una tabla dinámica.

Cómo funciona

1. Agregas una API JSON como fuente de datos (URL + autenticación opcional).
2. EasySignage obtiene la API y guarda una copia de la respuesta.
3. En el editor de plantillas eliges la fuente de datos, qué lista repetir y qué columnas mostrar, y añades una tabla dinámica a tu diseño.
4. Al guardar la plantilla, la tabla se llena con la última copia de la fuente de datos.

Parte 1 — Configurar una fuente de datos

Abrir la página de Fuentes de datos

1. Haz clic en Ajustes en el menú de la izquierda.
2. Elige Fuentes de datos.
3. Haz clic en Agregar fuente de datos.

Completar los datos de conexión

Importante: La URL debe usar HTTPS. No se permiten direcciones http://, enlaces que redirigen a otro sitio, direcciones con usuario y contraseña ni direcciones internas/privadas.

Opciones de autenticación

• Sin autenticación: la API es pública; no se envía nada extra.
• Bearer Token: EasySignage envía un encabezado Authorization: Bearer <token>. Pega tu token en el campo Bearer Token.
• API Key: EasySignage envía tu clave en el encabezado que elijas. Ingresa el Header Name (por ejemplo, X-API-Key) y el valor de API Key.

Nota: Las credenciales, los valores de los encabezados personalizados y los de los parámetros de consulta se cifran al guardar y no se vuelven a mostrar. Al editar una fuente, deja el campo del token/clave en blanco para mantener el actual, o escribe un valor nuevo para reemplazarlo.

Probar la conexión

Ingresa la URL y haz clic en Probar conexión antes de guardar. EasySignage hace una solicitud en vivo y muestra:

• Conectado o Failed, el código de estado HTTP, el tiempo de respuesta (ms) y el tamaño de la respuesta (bytes).
• Un explorador de campos del JSON devuelto para que compruebes que los datos se ven bien.

En el explorador de campos puedes:

• Expandir objetos y listas para ver su estructura.
• Ver el tipo de cada campo y un valor de ejemplo.
• Identificar las colecciones (listas de registros): aparecen marcadas como collection y son lo que repetirás en una tabla.
• Buscar un campo por su nombre.
• Copiar la ruta de un campo con el icono de copiar.
• Cambiar entre Explorar campos y Ver JSON sin procesar.

Cuando todo se vea bien, haz clic en Guardar.

Administrar las fuentes existentes

En la lista de Fuentes de datos cada fuente muestra su tipo, si está activa o desactivada, su intervalo de actualización y la hora de su Última sincronización. Los iconos de la derecha te permiten Explorar datos (ver los últimos datos obtenidos), Editar, Duplicar (la copia empieza desactivada), Desactivar/Habilitar o Eliminar una fuente.

Otros tipos

Google Sheets también aparece en la lista Tipo: pega el enlace de la hoja y compártela con la dirección de correo que se muestra. El CMS indica que la hoja se conecta al guardar, pero sus pestañas y la sincronización de datos aún no están disponibles. Para mostrar una hoja de Google en una plantilla hoy, usa el conector Google Sheets del editor de plantillas.

Parte 2 — Usar una fuente de datos en una plantilla

1. Abre o crea una plantilla y haz clic en Abrir editor.
2. En el menú de la izquierda elige Fuentes de datos y abre el conector JSON API.

3. En Elegir una fuente de datos, selecciona la fuente que configuraste.
4. Si la fuente aún no se ha obtenido, haz clic en Obtener ahora para cargar sus datos.
5. Si la fuente tiene más de una lista, elige la Lista a repetir (la colección de registros).
6. En Columnas, desmarca los campos que no quieras (todos empiezan marcados).
7. Haz clic en Agregar a la plantilla. Se añade una tabla dinámica a tu diseño: una fila por registro y una columna por cada campo que dejaste.
8. Coloca y da estilo a la tabla como a cualquier otro objeto, y luego haz clic en Guardar.

Importante: Una vez que guardas una plantilla con una fuente de datos, esa plantilla queda vinculada a esa fuente. Al volver a abrir el editor la fuente ya está seleccionada y no se puede cambiar. Sí puedes cambiar la lista y las columnas. Para usar otra fuente, quita la tabla del diseño y añade una nueva.

Mostrar datos más recientes

La tabla se llena con la última copia de la fuente de datos cuando guardas la plantilla. Si los datos cambiaron desde entonces, abre la plantilla en el editor y guárdala de nuevo.

Detalles técnicos

Flujo de datos

Configuras una fuente  ─▶  EasySignage la obtiene y guarda una copia
                                     │
      Guardas la plantilla ─▶  las filas se crean a partir de la copia
                                     │
                              Los reproductores muestran las filas
                              (ninguna pantalla llama a tu API)

• Obtención en el servidor: EasySignage obtiene la API, no tus pantallas, así que tu API solo recibe las solicitudes de EasySignage.

• Una colección por tabla: cada tabla repite una lista de registros (como una hoja/pestaña). Si tu JSON tiene varias listas, añade una tabla para cada una.

• Columnas: la primera fila es el encabezado, con los nombres de los campos. Las columnas aparecen en el orden en que los campos aparecen en tus datos.

Seguridad y límites

• Solo HTTPS. Se rechazan http://, las URL que redirigen, las credenciales incluidas (usuario:contraseña@…) y los hosts internos/privados.

• Las credenciales se cifran en reposo con claves de cifrado administradas y nunca se devuelven al navegador ni se envían a los reproductores.

• Límite de tamaño: se rechazan las respuestas de más de 10 MB.

• Tiempo de espera: las solicitudes se cancelan después de 30 segundos.

Formatos de respuesta compatibles

EasySignage funciona mejor con un objeto JSON que contiene una lista de registros, por ejemplo:

{
  "resource": [
    { "name": "Cereals", "price": "3.00", "day": "Monday" },
    { "name": "Toast",   "price": "2.50", "day": "Monday" }
  ]
}

Aquí resource es la colección que repetirías, y name, price y day son las columnas. Los registros a los que les falta un campo muestran una celda vacía. Un objeto sin ninguna lista se muestra como un solo registro.

Solución de problemas

Consejo: Si una celda muestra JSON sin procesar en lugar de un valor, ese campo es un objeto o una lista anidada. Elige un subcampo específico (por ejemplo, un precio dentro de un objeto de detalles) como columna.