Cómo imprimir etiquetas desde una API de servicio web: una guía para desarrolladores
Tu aplicación ya sabe qué debe decir la etiqueta: el número de pedido, el SKU, el valor del código de barras, la lista de empaque. La parte molesta nunca han sido los datos. Es la salida: controladores, lenguajes de impresora, colas de impresión y una impresora de almacén que insiste en renderizar tu fuente dos puntos más grande.
Esta guía omite por completo esa pila. Aprenderás cómo imprimir etiquetas desde una API de servicio web: registrar tu sistema externo una vez, diseñar la etiqueta una vez en un navegador y luego enviar trabajos de impresión —o extraer PDF y PNG renderizados— desde tu propio código. Sin controlador de impresora, sin SDK, sin comandos de impresora sin procesar.
Qué vas a construir: imprimir etiquetas desde una API de servicio web
Hay dos resultados que normalmente querrás, y la buena noticia es que comparten la misma forma de solicitud:
- Enviar un trabajo de impresión. Tu aplicación envía una referencia de etiqueta más una carga útil de datos. El trabajo entra en una cola y se despacha a la impresora configurada.
- Renderizar una sola etiqueta. La misma etiqueta y los mismos datos vuelven como PDF o PNG —para vistas previas en tu interfaz, adjuntos de correo, aprobaciones o un archivo de auditoría.
Next Generation Label Printing System (LPSNG) expone exactamente esto como una API de servicio web gestionada. Tú llamas a un endpoint; el servicio se encarga de la pila de impresión. La misma superficie de API también cubre la impresión directa (directamente a un dispositivo, sin pasar por la cola) y las actualizaciones de etiquetas electrónicas de estantería, de modo que la integración que construyas hoy sigue funcionando cuando crezcan tus requisitos.
Esta es la ruta que seguiremos:
- Registrar el sistema externo con OAuth2.
- Diseñar la etiqueta una vez en el estudio de etiquetas.
- Enviar un trabajo de impresión desde tu aplicación.
- Renderizar una sola etiqueta como PDF o PNG.
- Verificar que el trabajo realmente llegó al papel.
Las rutas exactas de los endpoints y los nombres de los parámetros están en la documentación de Web Service Interface y External Application Integration: este artículo te da la forma y el orden de las operaciones, y la documentación te da los detalles a nivel de byte.
Requisitos previos antes de llamar a la API
Antes de la primera solicitud, prepara lo siguiente:
- Una cuenta o edición de LPSNG que incluya la interfaz de servicio web. La Cloud Solution, la Embedded Edition en un ordenador de placa única y las Enterprise Features multiusuario incluyen la misma funcionalidad principal descrita en Use Cases: interfaz web, estudio de etiquetas, cola de trabajos, generación de PDF y la interfaz de servicio web.
- Un diseño de etiqueta que ya exista en el estudio de etiquetas, con campos asignados a los datos que pretendes enviar. La API hace referencia al diseño por identificador; no construye diseños sobre la marcha.
- Credenciales OAuth2 del flujo de registro que se usa para conectar sistemas externos.
- Cualquier cliente HTTP compatible con HTTPS. Python, Node, Go, curl: al protocolo le da igual.
- Opcional: una impresora de prueba, o el LPSNG Player si quieres una ruta de renderizado local antes de conectar un dispositivo.
Paso 1: Registrar tu sistema externo con OAuth2
LPSNG usa un protocolo de registro OAuth2 simplificado que conecta sistemas externos con una sola URL. Esta es la parte que la mayoría de las integraciones hacen mal cuando la implementan por su cuenta: crear a mano la renovación de tokens y la autenticación de dispositivos contra un protocolo de impresión sin procesar son semanas de trabajo que no tienen nada que ver con las etiquetas.
El flujo gestionado es un solo paso:
# 1. Open the registration URL that LPSNG generates for your external system.
# You complete the consent step once, in a browser.
open "$REGISTRATION_URL"
# 2. Store the credentials LPSNG hands back for that registered system.
export LPSNG_CLIENT_ID="<client-id>"
export LPSNG_CLIENT_SECRET="<client-secret>"
# 3. Exchange them for a token your API calls will use.
# Exact parameter names: see https://lpsng.rsj.de/en/oauth2.md
Dos cosas que vale la pena señalar:
- El consentimiento es un paso único. Después del registro, tu aplicación usa las credenciales resultantes en cada llamada posterior a la API: no estás enviando a una persona por un flujo de navegador por cada trabajo de impresión.
- Es el mismo modelo que se usa para las estaciones base ESL. Si más adelante conectas etiquetas de estantería, reconocerás el patrón de inmediato. Los detalles están en la documentación de ESL y ESL Interface.
Guarda el token como guardarías cualquier otro secreto: variable de entorno o gestor de secretos, nunca en el repositorio.
Paso 2: Diseñar la etiqueta una vez en el estudio de etiquetas
Abre la interfaz web y construye el diseño como construirías un documento: bloques de texto, imágenes, códigos de barras y marcadores de posición de campos donde aterrizarán los datos de la API.
Algunas decisiones que dan sus frutos más adelante:
- Usa simbologías de código de barras compatibles. LPSNG renderiza formatos 1D y 2D de forma nativa: la página Barcode Formats enumera lo que está disponible. Si eliges un formato compatible, la API lo renderiza sin ningún trabajo adicional por tu parte.
- Adjunta bloques de script de Python a los campos cuando necesites lógica. La Field Script API permite que un bloque de script acceda al valor de un campo y lo modifique antes de imprimir: útil para formatear fechas, truncar nombres de proveedores largos o derivar un dígito de control.
# Example: a script block attached to a field, formatting a raw value
# before it reaches the printer. See https://lpsng.rsj.de/api.html
value = str(value).strip().upper()
if len(value) > 30:
value = value[:27] + "..."
- Guarda el diseño y anota su identificador. Ese identificador es al que hace referencia tu llamada a la API: trátalo como un valor de configuración, no como una cadena mágica enterrada en el código.
- Mantén el diseño separado de los datos. El diseño define cómo se ve una etiqueta; la solicitud define qué dice. Esa separación es lo que permite que un diseño sirva a miles de trabajos.
Paso 3: Enviar un trabajo de impresión desde tu aplicación
Ahora la llamada en sí. La forma es siempre la misma: autenticar, referenciar la etiqueta, pasar la carga útil de datos para los campos.
import os
import requests
BASE = os.environ["LPSNG_BASE_URL"] # your LPSNG instance
TOKEN = os.environ["LPSNG_ACCESS_TOKEN"] # from the OAuth2 registration
job = {
"label": "shipping-label-4x6", # identifier from the label studio
"printer": "warehouse-01", # a printer configured in LPSNG
"data": {
"order_no": "SO-10432",
"customer": "Nordwind Handel GmbH",
"sku": "HND-2200-BLK",
"qty": "12",
"barcode": "SO-10432-HND-2200-BLK",
},
}
resp = requests.post(
f"{BASE}/<print-job-endpoint>", # exact path: see the Web Service Interface docs
json=job,
headers={"Authorization": f"Bearer {TOKEN}"},
timeout=30,
)
resp.raise_for_status()
print(resp.json()) # job identifier + status
Del lado del servidor, el trabajo entra en la cola y se despacha a la impresora configurada. Tu aplicación no mantiene una conexión abierta con un dispositivo, y no necesita saber si esa impresora habla ZPL, EPL o cualquier otra cosa.
Variantes que vale la pena conocer:
- Impresión directa. Cuando quieres que la etiqueta vaya directamente a un dispositivo en lugar de esperar su turno en la cola, la interfaz expone una ruta de impresión directa.
- Procesamiento por lotes. Cada llamada es una referencia de etiqueta más datos, así que recorrer líneas de pedido es solo un bucle en tu código: un trabajo por línea, en el orden que necesita tu estación de empaque.
Para endpoints exactos, nombres de parámetros y campos de respuesta, usa las referencias de Web Service Interface y External Application Integration.
Paso 4: Renderizar una sola etiqueta como PDF o PNG
El renderizado supera a la impresión cuando una persona necesita ver la etiqueta primero, o cuando necesitas un registro de que existió:
- Vistas previas dentro de tu propia interfaz antes de que alguien confirme una tirada.
- Adjuntos de correo para proveedores o clientes.
- Pasos de aprobación en los que un revisor da el visto bueno al arte.
- Archivos de auditoría que sobreviven independientemente de una impresora.
La llamada se parece al trabajo de impresión, excepto que devuelve bytes en lugar de poner trabajo en cola:
# PDF for archiving or attaching
curl -sS -X POST "$LPSNG_BASE_URL/<render-endpoint>" \
-H "Authorization: Bearer $LPSNG_ACCESS_TOKEN" \
-H "Content-Type: application/json" \
-d '{"label":"shipping-label-4x6","format":"pdf",
"data":{"order_no":"SO-10432","sku":"HND-2200-BLK"}}' \
-o label-SO-10432.pdf
# PNG for a preview thumbnail — same layout, same data, same output geometry
curl -sS -X POST "$LPSNG_BASE_URL/<render-endpoint>" \
-H "Authorization: Bearer $LPSNG_ACCESS_TOKEN" \
-H "Content-Type: application/json" \
-d '{"label":"shipping-label-4x6","format":"png",
"data":{"order_no":"SO-10432","sku":"HND-2200-BLK"}}' \
-o label-SO-10432.png
Como ambas rutas usan el mismo diseño y los mismos datos, lo que previsualizas es lo que imprimes. Ese es el sentido de hacerlo en un solo sistema en lugar de coser una biblioteca de PDF a un controlador de impresora.
Dos notas prácticas:
- Renderizado offline o embebido. El LPSNG Player es un motor de impresión de línea de comandos independiente que recibe un paquete y datos y produce PDF, PNG, JSON, salida de impresión o una actualización ESL. Es la herramienta adecuada cuando necesitas salida sin un viaje de ida y vuelta al servidor.
- Cachea de forma agresiva. Las etiquetas repetidas —la misma etiqueta de estantería, el mismo ID de palé— no necesitan un renderizado nuevo cada vez. Guarda el PDF con clave de diseño + hash de datos y omite la llamada a la API.
Paso 5: Verificar que el trabajo de impresión funcionó
Un HTTP 200 significa que el trabajo fue aceptado. No significa que salió una etiqueta de una impresora. Verifica en este orden:
- Comprueba la cola de trabajos en la interfaz web. Confirma que el trabajo fue aceptado y completado, y que fue a la impresora que esperabas.
- Compara el renderizado con la realidad. Pon el PDF o PNG junto a la etiqueta física. Aquí es donde aparecen los problemas de escalado y las zonas de silencio de los códigos de barras, y es mucho más barato detectarlos ahora que en la sede de un cliente.
- Escanea el código de barras. Un lector es la única prueba honesta de si los datos hacen el recorrido completo: comprueba que el valor escaneado coincide con lo que envió tu aplicación, carácter por carácter.
- Registra la respuesta y el identificador del trabajo. Guarda ambos junto a tu registro interno de pedido o envío. Cuando alguien pregunte «¿esto se envió con una etiqueta?», querrás una respuesta de una base de datos, no una suposición.
- Si usas ESL, comprueba también la pantalla. Una pantalla de estantería actualizada es una segunda señal independiente de que los mismos datos llegaron al servicio. La ESL Interface y la ESL Binding API cubren ese lado.
Solución de problemas comunes
Fallos de autenticación. Si las llamadas empiezan a devolver errores de autenticación, es probable que el token haya sido revocado o que haya cambiado el registro del sistema externo. Vuelve a ejecutar el registro OAuth2: es un flujo de un solo paso por diseño, así que la recuperación es barata. Consulta la página de OAuth2.
Campos en blanco o faltantes en la etiqueta. Casi siempre es un desajuste de claves: las claves de tu carga útil data deben coincidir exactamente con los nombres de los campos del diseño, incluida la distinción entre mayúsculas y minúsculas. Renderiza la etiqueta a PNG e inspecciónala antes de culpar a la impresora.
Salida de código de barras incorrecta. Comprueba dos cosas: que el formato que elegiste esté en la lista de Barcode Formats compatibles, y que el tipo de dato coincida con lo que espera la simbología. Los formatos solo numéricos renderizarán encantados basura a partir de una cadena con letras.
La impresora no recibe trabajos. El trabajo solo puede despacharse a una impresora que esté configurada y en línea en LPSNG. Si la cola muestra el trabajo ahí parado, el problema es el destino, no tu solicitud.
El renderizado se ve distinto de la impresión. Compara el DPI y el tamaño de etiqueta entre el diseño y el soporte físico. Un diseño pensado para un tamaño y enviado a un material de tamaño distinto se escalará de formas que rompen la legibilidad del código de barras.
FAQ
¿Necesito un controlador de impresora o un SDK en mi servidor para imprimir etiquetas desde la API de servicio web?
No. Next Generation Label Printing System se encarga de la pila de impresión por ti: envías un trabajo o solicitas un renderizado a través de la API de servicio web, y el servicio gestionado se ocupa del resto. El LPSNG Player está disponible si necesitas un motor de línea de comandos independiente para salida local.
¿Cuál es la diferencia entre enviar un trabajo de impresión y renderizar una sola etiqueta?
Enviar un trabajo de impresión manda la etiqueta a la impresora configurada a través de la cola de trabajos. Renderizar devuelve la etiqueta como PDF o PNG para que puedas previsualizarla, archivarla o adjuntarla sin imprimir. Ambas usan el mismo diseño y los mismos datos, así que la salida es consistente.
¿Cómo funciona el registro OAuth2 para sistemas externos?
LPSNG usa un protocolo de registro OAuth2 simplificado que conecta sistemas externos con una sola URL. Completas el paso de consentimiento una vez, y las credenciales resultantes se usan para las llamadas posteriores a la API. El mismo modelo se usa para las estaciones base ESL, así que el patrón es consistente entre integraciones.
¿Puede la misma API actualizar también etiquetas electrónicas de estantería?
Sí. LPSNG incluye una interfaz JSON neutral respecto al proveedor (ESLSEND) y una API de vinculación para etiquetas ESL, de modo que puedes gestionar tanto etiquetas impresas como etiquetas electrónicas de estantería desde la misma integración. Para una mirada más profunda, consulta nuestros artículos complementarios sobre la ESL Binding API y las API de integración de etiquetas electrónicas de estantería.
Conclusión
El patrón es lo bastante corto para tenerlo en la cabeza: regístrate una vez con OAuth2, diseña la etiqueta una vez en el estudio de etiquetas y luego envía un trabajo o solicita un renderizado desde tu aplicación. Todo lo que antes era un problema específico de la impresora —controladores, lenguajes de comandos, escalado de fuentes, bibliotecas de códigos de barras— se gestiona detrás de una única superficie de API que cubre trabajos de impresión, impresión directa, renderizado de PDF y PNG, y actualizaciones ESL.
Next Generation Label Printing System es el servicio gestionado que hace que esta sea toda la integración en lugar de solo una parte. Empieza con la documentación de Web Service Interface para los endpoints exactos, diseña tu primer diseño en el estudio de etiquetas y envía un trabajo de prueba a una sola impresora antes de automatizar el resto. Si todavía estás sopesando tus opciones, nuestra comparativa de alternativas a Zebra Designer es una lectura siguiente razonable.
Entradas relacionadas
- Alternativa a Zebra Designer: software de impresión de etiquetas para comparar
- ESL Binding API: documentación y ejemplos
- Entender las API de integración de etiquetas electrónicas de estantería
