Cómo conectar etiquetas ESL a artículos mediante API

El planograma está actualizado. Los precios son correctos en el ERP, correctos en la plantilla de la etiqueta de lineal, correctos en el maestro de productos. Y, sin embargo, tres horas después, un pasillo sigue mostrando el precio antiguo, porque la etiqueta electrónica de lineal fijada a esa posición de estantería sigue vinculada al artículo que solía estar allí. Alguien tiene que recorrer el pasillo con un terminal portátil, escanear la etiqueta, escanear el artículo y repetirlo unos cientos de veces.

Ese paso de vinculación manual es la última pieza del etiquetado de lineal que se resiste a la automatización. No tiene por qué ser así. Con la API de Vinculación de ESL del Next Generation Label Printing System (LPSNG), puedes asociar etiquetas ESL a artículos mediante programación, enviar los datos de los artículos a las pantallas a través de una interfaz JSON neutra respecto al proveedor y solo recurrir a un escáner cuando algo haya fallado de verdad.

Este artículo recorre la automatización de principio a fin: la configuración inicial única, el pipeline que realiza la vinculación, qué monitorizar y cómo mantenerlo fiable.

Configuración inicial única: preparar tu entorno ESL

Esto se hace una vez por tienda, estación base o unidad MDE (mobile data entry). Todo lo que viene después es un trabajo programado.

1. Registra tu sistema externo

LPSNG utiliza un protocolo de registro OAuth2 simplificado: conectas un sistema externo —una estación base ESL, una unidad MDE portátil, un servicio de middleware— con una única URL. LPSNG gestiona el intercambio de tokens detrás de ese registro, así que no tienes que implementar un cliente OAuth2 desde cero.

En la práctica, eso significa que la configuración de tu integración contiene una URL de registro y una credencial, no una máquina de estados de refresco de tokens:

# lpSng-integration.yaml
esl:
  registration_url: "https://lpsng.rsj.de/..."   # from your LPSNG registration
  client_id: "${LPSNG_CLIENT_ID}"
  client_secret: "${LPSNG_CLIENT_SECRET}"        # keep in a secret store, not in git
  store_id: "store-0417"

Guarda estos valores en un gestor de secretos. El registro es el único paso en el que un error resulta caro de deshacer.

2. Asegúrate de que el hardware sea accesible

Tus etiquetas ESL deben estar instaladas y dentro del alcance de su estación base o gateway antes de que cualquier llamada a la API pueda tener éxito. Si utilizas hardware ESL de CATIC, sigue las instrucciones de instalación de CATIC: la colocación de la antena y el direccionamiento de las etiquetas son las dos cosas que más a menudo provocan que “la API funcionó pero nada cambió en la estantería”.

3. Confirma tu ruta de actualización de pantallas

El contenido de las pantallas se actualiza a través de la interfaz de archivos JSON neutra respecto al proveedor (ESLSEND). Esa es la parte que merece la pena tener en cuenta a nivel arquitectónico: la carga útil es JSON, no un formato binario propietario, así que tu integración no queda soldada a un único proveedor de etiquetas. Cubrimos las implicaciones en Qué significa una interfaz ESL neutra respecto al proveedor para los desarrolladores.

4. Apunta LPSNG a tus datos de artículos

El paso de vinculación necesita algo a lo que vincular. LPSNG puede usar archivos de Excel como archivos de datos y de búsqueda, un complemento de Google Sheets para equipos que viven en hojas de cálculo, o tu ERP como fuente upstream. A la lógica de vinculación en sí le da igual: necesita una clave estable (SKU o EAN) y los campos que quieres en la pantalla.

Si quieres hacerlo por la vía difícil, puedes crear a mano los archivos JSON de ESLSEND y ejecutar tú mismo el intercambio de tokens OAuth2. El flujo gestionado de LPSNG existe precisamente para que no tengas que hacerlo.

El pipeline automatizado: vincular etiquetas a artículos

Este es el flujo, paso a paso.

Paso 1 — Activar el proceso de vinculación

La API de Vinculación de ESL es un servicio web creado específicamente para unidades MDE que no tienen interfaz web: un terminal portátil puede llamarlo, un trabajo cron puede llamarlo, un webhook puede llamarlo. Una ejecución de vinculación comienza con una única petición HTTP.

curl -X POST "$LPSNG_BASE/binding/jobs" \
  -H "Authorization: Bearer $LPSNG_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
        "store_id": "store-0417",
        "source": "erp-sync-2026-10-18",
        "mode": "reconcile"
      }'

La ruta y los parámetros exactos están en la documentación de la interfaz del servicio web; lo importante es que una ejecución de vinculación es un trabajo que envías, no una sesión a la que te sientas a asistir.

Paso 2 — Deja que LPSNG asigne artículos a IDs de etiqueta

Este es el paso que sustituye al escáner. LPSNG toma los identificadores de artículo (SKU, EAN) de tu fuente de datos y los empareja con los IDs de etiqueta ESL, usando la relación etiqueta-posición de estantería que el sistema ya conoce. Tu código nunca tiene que saber qué etiqueta física cuelga sobre qué estantería.

Si estás gestionando tú mismo la reconciliación, el bucle es pequeño:

import os, requests

BASE = os.environ["LPSNG_BASE"]
HEADERS = {"Authorization": f"Bearer {os.environ['LPSNG_TOKEN']}"}

def reconcile(store_id: str, items: list[dict]):
    """items: [{"sku": "...", "ean": "...", "price": "...", "name": "..."}]"""
    resp = requests.post(
        f"{BASE}/binding/jobs",
        headers=HEADERS,
        json={"store_id": store_id, "items": items, "mode": "reconcile"},
        timeout=30,
    )
    resp.raise_for_status()
    return resp.json()["job_id"]

Paso 3 — Enviar los datos del artículo a las pantallas

Una vez vinculada una etiqueta, LPSNG actualiza la pantalla ESL con los valores específicos del artículo que proporciones —precio, nombre, código de barras, lo que use el diseño— a través de la interfaz JSON de ESLSEND. Una carga útil mínima se parece más o menos a esto (consulta la documentación de la interfaz ESL para el esquema completo):

{
  "esl_id": "TAG-0042-1188",
  "item": {
    "sku": "SKU-88213",
    "ean": "4012345678901",
    "name": "Organic Coffee 500g",
    "price": "8.49"
  }
}

Como el formato es neutro respecto al proveedor, cambiar de hardware de etiquetas más adelante es una cuestión de despliegue, no una reescritura.

Paso 4 — Imprimir las etiquetas que aún haya que imprimir

Algunas cosas siguen siendo físicas: carteles promocionales de estantería, tiras de lineal, etiquetas de cajas. Se pueden generar a partir de los mismos datos de artículo, porque la API del servicio web de LPSNG puede enviar trabajos de impresión y renderizar etiquetas individuales como PDF o PNG, y el Player independiente puede emitir PDF, PNG, JSON, trabajos de impresión o actualizaciones de ESL a partir de la misma entrada de paquete más datos. Una fuente de datos, dos canales de salida.

Todo el conjunto como flujo de trabajo programado

Una reconciliación nocturna suele ser suficiente:

# crontab: every night at 02:15, after the ERP export lands
15 2 * * * /usr/local/bin/python /opt/esl/sync.py --store store-0417 >> /var/log/esl-sync.log 2>&1

# sync.py (sketch)
items = load_from_erp()          # or read the Excel/Sheets export
job_id = reconcile("store-0417", items)
wait_for_job(job_id)             # poll LPSNG for job status
handle_failures(job_id)          # retry or flag

Cron está bien. Un webhook desde tu ERP es mejor: vincula las etiquetas en el momento en que cambian los precios en lugar de horas después.

Monitorización y gestión de fallos

La automatización que no puedes ver es automatización en la que no puedes confiar.

• Sigue los trabajos en la cola de trabajos. La cola de trabajos de LPSNG forma parte de la funcionalidad principal en todas las ediciones. Las ejecuciones de vinculación y las actualizaciones de pantalla aparecen allí, y los trabajos fallidos quedan registrados para su revisión.
• Reintenta, no entres en pánico. Si una etiqueta no es accesible, la API devuelve un error. Configura lógica de reintento para fallos transitorios (una etiqueta temporalmente fuera de alcance) y marca el resto para que los revise una persona.
• Vigila el estado de las etiquetas. El estado de la batería y de la señal es visible a través de la interfaz ESL. Sondear esto es cómo encuentras la etiqueta que morirá la semana que viene en lugar de la que ya lo ha hecho.
• Configura alertas por tu parte. Sondea el servicio web de LPSNG para conocer el estado de los trabajos y envía los fallos a lo que ya uses para alertas. No necesitas una segunda pila de monitorización.
• Mantén un mecanismo manual de reserva. Si una etiqueta sigue sin ser accesible, vuelve a vincularla manualmente en la interfaz web de LPSNG cuando vuelva a estar en línea. La misma plataforma gestiona tanto la vía automatizada como la manual, así que no hay cerebro dividido entre ambas.

Una comprobación de estado sencilla:

curl -s "$LPSNG_BASE/jobs/$JOB_ID" \
  -H "Authorization: Bearer $LPSNG_TOKEN" | jq '{status, failed: [.results[] | select(.status=="failed")]}'

Buenas prácticas para una automatización ESL fiable

• Mantén los identificadores limpios. Tu clave del ERP y tu clave de ESL deberían ser la misma cadena, generada en un único lugar. La mayoría de los tickets de “falló la vinculación” son en realidad tickets de “el SKU cambió de formato”.
• Quédate con la interfaz JSON. Las cargas útiles neutras respecto al proveedor convierten los cambios de hardware en una tarea de despliegue. También significa que la misma estructura de carga útil funciona en todas las tiendas.
• Prueba primero en staging. Una ejecución de vinculación contra una tienda de prueba detecta errores de mapeo antes de que lleguen a 400 etiquetas en un pasillo real.
• Rota las credenciales. Guarda las credenciales OAuth2 y los tokens de refresco en un gestor de secretos, documenta quién es su propietario y rótalos según un calendario.
• Considera el despliegue en el edge. Para tiendas con conectividad inestable, la Edición Embebida ejecuta LPSNG completo en un ordenador de placa única como una Raspberry Pi, de modo que los trabajos de vinculación se ejecutan localmente y se sincronizan cuando el enlace está disponible.
• Verifica los códigos de barras antes de enviarlos. Un EAN incorrecto en una pantalla es peor que un precio desactualizado; consulta Cómo verificar códigos de barras antes de imprimir etiquetas.

Preguntas frecuentes

¿Necesito escribir código para conectar etiquetas ESL a artículos?

No necesariamente. LPSNG proporciona una API de servicio web y un flujo de trabajo gestionado que se puede activar mediante simples peticiones HTTP. Para una automatización completa, sin embargo, es probable que escribas scripts que llamen a la API de Vinculación de ESL. La interfaz JSON neutra respecto al proveedor (ESLSEND) hace que sea sencillo integrarla con tus sistemas existentes.

¿Puedo usar la API de Vinculación de ESL con cualquier hardware ESL?

La API de Vinculación de ESL está diseñada para ser neutra respecto al proveedor, usando una interfaz de archivos JSON (ESLSEND) para actualizar las pantallas ESL. Puede funcionar con diversos hardware ESL siempre que admitan el formato JSON. LPSNG también proporciona instrucciones de instalación específicas para el hardware ESL de CATIC.

¿Cómo gestiona LPSNG la autenticación de sistemas externos?

LPSNG utiliza un protocolo de registro OAuth2 simplificado. Conectas tu sistema externo (como una unidad MDE) con una única URL, y LPSNG gestiona el intercambio de tokens. Eso evita tener que implementar OAuth2 desde cero en cada integración.

¿Qué ocurre si una etiqueta ESL se desconecta durante una actualización?

Si una etiqueta no es accesible, la API devuelve un error. La cola de trabajos de LPSNG registra el fallo, y puedes configurar lógica de reintento o recibir alertas. Para actualizaciones críticas, puedes volver a vincular la etiqueta manualmente usando la interfaz web de LPSNG cuando vuelva a estar en línea.

Conclusión: automatiza una vez, benefíciate continuamente

Conectar etiquetas ESL a artículos mediante API elimina el paso de recorrer el pasillo de tu proceso. Envías un trabajo de vinculación, LPSNG empareja tus identificadores de artículo con los IDs de etiqueta y las pantallas se actualizan a través de una interfaz JSON que no te ata a un único proveedor de hardware. Los precios se mantienen precisos entre cambios de planograma en lugar de desviarse hasta que alguien se da cuenta.

El camino práctico es el gestionado: registra cada tienda con una única URL, deja que Next Generation Label Printing System se encargue del intercambio de tokens y del seguimiento de trabajos, y limita tu propio código a la parte que realmente es tuya: decidir qué artículos van dónde.

Empieza leyendo la documentación de la interfaz ESL y la referencia de la API de Vinculación de ESL. Luego haz un prototipo contra la edición cloud, o descarga la Edición Embebida si quieres que el trabajo de vinculación se ejecute dentro de la tienda desde el primer día.

Entradas relacionadas

• Qué significa una interfaz ESL neutra respecto al proveedor para los desarrolladores
• Precios del software de impresión de etiquetas en la nube: qué buscar
• Cómo verificar códigos de barras antes de imprimir etiquetas