Tutorial de la API de vinculación ESL: conecta etiquetas a artículos

2026-09-21 pdf labels barcodes label merge browser based graphical layout editor google sheets addin microsoft excel addon electronic shelf labels esl barcode3 labels label editor

Tutorial de la API de vinculación ESL: conecte etiquetas a artículos

Tiene en la mano una etiqueta electrónica de estantería y un artículo en su catálogo. Necesita que esa etiqueta muestre el precio correcto, el nombre del producto y datos adicionales sin pasar por un flujo de trabajo propietario con dispositivo portátil. Este tutorial muestra cómo usar la API de vinculación ESL en el sistema de impresión de etiquetas de nueva generación (LPSNG) para conectar una etiqueta ESL a un artículo mediante una simple llamada HTTPS.

Al finalizar, podrá vincular programáticamente una etiqueta desde un sistema externo, como una unidad de entrada de datos móvil (MDE), verificar la vinculación y desvincular o revincular una etiqueta cuando se asigne a un artículo diferente.

Requisitos previos

Antes de comenzar, asegúrese de contar con lo siguiente:

Una cuenta LPSNG con acceso a la API de vinculación ESL. La API de vinculación forma parte de la funcionalidad principal de LPSNG y está disponible en todas las ediciones.
Hardware ESL compatible que admita la interfaz de vinculación, por ejemplo, dispositivos ESL CATIC.
Una estación base ESL alimentada con las etiquetas que desea vincular dentro del alcance.
Conocimientos básicos de API REST y JSON.
La URL base de su servicio web LPSNG, tal como se muestra en la configuración de su cuenta.
Credenciales de cliente OAuth2 para la autenticación. Si aún no ha registrado un sistema externo, siga primero la documentación de OAuth2.

No necesita comunicarse directamente con un protocolo de estación base específico del proveedor. El camino difícil sería aplicar ingeniería inversa a la comunicación de bajo nivel utilizada por su hardware ESL. La ruta compatible es dejar que el servicio gestionado de LPSNG se encargue de esa traducción mientras usted utiliza una única API HTTPS.

Paso a paso: vincular una etiqueta ESL a un artículo

Paso 1: obtener un token de acceso OAuth2

LPSNG utiliza un protocolo de registro OAuth2 simplificado para sistemas externos. Una vez registrada su integración, solicite un token de acceso desde el endpoint de tokens de su inquilino e inclúyalo en cada llamada a la API.

El endpoint exacto y el flujo de registro dependen de su cuenta. En la mayoría de las configuraciones, una solicitud de credenciales de cliente tiene este aspecto:

curl -s -X POST "https://<SU-BASE-LPSNG>/oauth2/token" \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -u "<CLIENT_ID>:<CLIENT_SECRET>" \
  -d "grant_type=client_credentials"

Una respuesta exitosa incluye un token de portador:

{
  "access_token": "eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9...",
  "token_type": "Bearer",
  "expires_in": 3600
}

Utilice ese valor access_token en el encabezado Authorization para la solicitud de vinculación. Consulte la guía de OAuth2 si su inquilino utiliza una forma de solicitud de token diferente.

Paso 2: identificar el artículo y la etiqueta

Necesita dos identificadores antes de poder vincular cualquier cosa:

Identificador del artículo: normalmente el SKU, EAN o número de material interno que ya existe en su fuente de datos LPSNG.
Identificador de la etiqueta: el ID único de la etiqueta ESL. Suele estar impreso en la propia etiqueta o se captura escaneando la etiqueta con una unidad MDE.

Por ejemplo, un artículo podría identificarse como EAN-4001234567890 y una etiqueta como CATIC-001234. Tenga ambos valores a mano para el payload JSON.

Paso 3: construir la solicitud de vinculación

Una solicitud de vinculación es un objeto JSON enviado al endpoint de vinculación. Los campos obligatorios son el identificador del artículo y el identificador de la etiqueta. Según el diseño de su etiqueta y la configuración ESL, también puede enviar campos opcionales como price o un objeto labelData.

{
  "itemId": "EAN-4001234567890",
  "tagId": "CATIC-001234",
  "price": "19.90",
  "labelData": {
    "name": "Bebida de avena ecológica 1L",
    "unit": "L"
  }
}

No todas las implementaciones utilizan price y labelData. Si sus etiquetas se generan completamente a partir de los datos maestros del artículo en LPSNG, puede enviar solo itemId y tagId. Revise el diseño de su etiqueta para ver qué campos adicionales debe mostrar la etiqueta.

Paso 4: enviar una solicitud POST al endpoint de vinculación

Para este tutorial usamos /api/esl/bind como endpoint de vinculación. Su instalación de LPSNG puede exponer la misma ruta o una ruta específica del inquilino, así que confirme el endpoint exacto en la documentación de la API de vinculación ESL para su entorno.

Guarde el payload en un archivo para que el comando curl sea legible:

{
  "itemId": "EAN-4001234567890",
  "tagId": "CATIC-001234",
  "price": "19.90",
  "labelData": {
    "name": "Bebida de avena ecológica 1L",
    "unit": "L"
  }
}

Luego envíe la solicitud:

curl -s -X POST "https://<SU-BASE-LPSNG>/api/esl/bind" \
  -H "Authorization: Bearer <ACCESS_TOKEN>" \
  -H "Content-Type: application/json" \
  --data @binding-payload.json

LPSNG recibe la solicitud, resuelve los datos del artículo en su fuente de datos e indica a la estación base ESL que actualice la etiqueta.

Paso 5: gestionar la respuesta

Una vinculación exitosa normalmente devuelve una respuesta 200 OK con un objeto de estado:

{
  "status": "bound",
  "tagId": "CATIC-001234",
  "itemId": "EAN-4001234567890",
  "updatedAt": "2026-09-21T10:15:00Z"
}

Las respuestas de error comunes incluyen:

400 para datos no válidos, como un cuerpo JSON mal formado o un campo obligatorio faltante.
401 para fallos de autenticación, por ejemplo, un token de acceso caducado o ausente.

Inspeccione el cuerpo de la respuesta para ver un mensaje de error que explique qué campo falló. Si la API devuelve otro estado 4xx, compruebe si la etiqueta o el artículo son desconocidos o si la etiqueta ya está vinculada en otro lugar.

Paso 6: verificar la vinculación consultando el estado de la etiqueta

Si su implementación expone un endpoint de estado de etiqueta, puede consultar la vinculación actual. El endpoint exacto puede variar; el siguiente es un ejemplo de su forma:

curl -s "https://<SU-BASE-LPSNG>/api/esl/status/CATIC-001234" \
  -H "Authorization: Bearer <ACCESS_TOKEN>"

Una respuesta similar a esta confirma que la etiqueta está vinculada al artículo esperado:

{
  "tagId": "CATIC-001234",
  "boundItemId": "EAN-4001234567890",
  "lastSeen": "2026-09-21T10:15:00Z"
}

Si su inquilino no expone un endpoint de estado, utilice el panel de gestión ESL en LPSNG para ver el estado de la etiqueta.

Paso 7: opcional — desvincular o revincular una etiqueta

Cuando un artículo se traslada a una nueva ubicación o se reutiliza una etiqueta, debe desvincularla o revincularla. El método exacto depende de su endpoint de vinculación LPSNG.

Una solicitud de desvinculación común utiliza DELETE:

curl -s -X DELETE "https://<SU-BASE-LPSNG>/api/esl/bind/CATIC-001234" \
  -H "Authorization: Bearer <ACCESS_TOKEN>"

Para revincular la misma etiqueta a un artículo diferente, envíe una solicitud PUT:

curl -s -X PUT "https://<SU-BASE-LPSNG>/api/esl/bind/CATIC-001234" \
  -H "Authorization: Bearer <ACCESS_TOKEN>" \
  -H "Content-Type: application/json" \
  -d '{"itemId":"EAN-4001234567891"}'

Consulte la documentación de la API de vinculación ESL para conocer el comportamiento exacto de desvinculación y revinculación en su instalación.

Verificación de la vinculación

Después de que la llamada a la API devuelva éxito, confirme la vinculación de más de una manera:

Compruebe físicamente la pantalla ESL: la etiqueta debería mostrar ahora el precio y el nombre del artículo. Si la pantalla sigue en blanco o muestra datos antiguos, espere unos segundos y vuelva a comprobarlo.
Consulte el estado de la etiqueta a través de la interfaz ESL si su implementación la proporciona. La respuesta de estado debería mostrar el boundItemId esperado.
Abra el panel de gestión ESL en LPSNG y busque la etiqueta. Su estado debería cambiar de no vinculada o artículo anterior al nuevo artículo.
Pruebe con un artículo diferente y revincule la misma etiqueta. Si la pantalla se actualiza correctamente, su integración funciona de extremo a extremo.

Solución de problemas comunes

Errores de autenticación

Verifique dos veces su ID de cliente y secreto OAuth2. Los tokens de acceso caducan, así que renueve el token si recibe una respuesta 401 después de un período de tiempo.

Etiqueta no encontrada

Asegúrese de que el ID de la etiqueta sea exactamente correcto, incluidos los prefijos o ceros iniciales. Confirme también que la etiqueta esté encendida y dentro del alcance de la estación base ESL. Una etiqueta que no se ha reportado recientemente puede no estar disponible para la vinculación.

Artículo no encontrado

Verifique que el identificador del artículo exista en su fuente de datos LPSNG. La API de vinculación resuelve contra los mismos datos que usan sus etiquetas, por lo que un error tipográfico en el EAN o SKU impedirá la vinculación.

Conflicto de vinculación

La etiqueta puede estar ya vinculada a otro artículo. Desvincule primero la etiqueta y luego envíe una nueva solicitud de vinculación. Algunas instalaciones rechazan una revinculación directa sin un paso de desvinculación explícito.

Problemas de red

Si la solicitud agota el tiempo de espera, compruebe la conectividad entre su cliente, el servicio web LPSNG y la estación base ESL. La estación base debe ser accesible desde LPSNG, no directamente desde su cliente.

Preguntas frecuentes

¿Qué es la API de vinculación ESL?

La API de vinculación ESL es un servicio web proporcionado por el sistema de impresión de etiquetas de nueva generación (LPSNG) que permite a sistemas externos, como unidades de entrada de datos móviles, vincular etiquetas electrónicas de estantería a artículos específicos. Utiliza una simple solicitud JSON sobre HTTPS.

¿Puedo vincular varias etiquetas a un artículo?

Normalmente, una etiqueta se vincula a un artículo. Sin embargo, según su hardware ESL y la configuración de LPSNG, es posible vincular varias etiquetas al mismo artículo por redundancia o para diferentes ubicaciones de visualización. Consulte la documentación de su hardware.

¿Cómo desvinculo una etiqueta?

Para desvincular una etiqueta, puede enviar una solicitud al endpoint de vinculación con un identificador de artículo vacío o nulo, o utilizar un método de desvinculación dedicado si está disponible. Consulte la documentación de la API para conocer el endpoint y el payload exactos.

¿La API de vinculación está disponible en todas las ediciones de LPSNG?

Sí, la API de vinculación ESL forma parte de la funcionalidad principal de LPSNG y está disponible en todas las ediciones, incluida la solución en la nube y la edición integrada. Sin embargo, necesita hardware ESL compatible para utilizarla.

Conclusión

El flujo de trabajo de vinculación es un bucle pequeño: autenticarse, recopilar los ID del artículo y de la etiqueta, enviar la solicitud de vinculación y verificar la pantalla. Una vez que ese bucle funciona, puede llamarlo desde una unidad MDE, un proceso de cumplimiento o cualquier otro sistema externo que necesite asignar etiquetas ESL a artículos.

La API de vinculación ESL es solo una parte de la solución ESL más amplia de LPSNG. LPSNG también proporciona la interfaz ESL independiente del proveedor para actualizar pantallas, la guía de OAuth2 para la autenticación y el LPSNG Player para flujos de trabajo de salida ESL por línea de comandos.

Si está integrando hardware ESL por primera vez, comience con la documentación de la API de vinculación ESL y pruebe con una etiqueta de repuesto antes de pasar a producción.

Publicaciones relacionadas

Tutorial de la API de vinculación ESL: conecta etiquetas a artículos