Generación de etiquetas de código de barras con Python: guía paso a paso
Si alguna vez has intentado generar una etiqueta de código de barras desde un script de Python, conoces el camino habitual: elegir una librería de códigos de barras, renderizar una imagen, construir tú mismo el diseño de la etiqueta y luego averiguar cómo comunicarte con una impresora térmica. Esta guía adopta un enfoque diferente y gestionado. Usarás el Sistema de Impresión de Etiquetas de Nueva Generación (LPSNG) como motor de renderizado e impresión, y lo controlarás desde Python con simples peticiones HTTP.
Al final, tendrás un script de Python que:
- Se autentica contra la API del servicio web de LPSNG
- Busca un diseño de etiqueta
- Envía datos dinámicos del artículo, incluido el contenido del código de barras
- Aplica personalizaciones de campos basadas en Python
- Renderiza la etiqueta como PDF o PNG
- La envía a una impresora o la guarda localmente
Esto es ideal para desarrolladores que necesitan generación de etiquetas basada en datos en flujos de trabajo de almacén, logística, comercio minorista o cumplimiento de pedidos, sin tener que construir y mantener una canalización personalizada de renderizado de etiquetas.
Requisitos previos
Antes de empezar, asegúrate de tener:
- Python 3.x instalado en tu máquina.
- Una cuenta de LPSNG, ya sea en la edición en la nube o en una edición integrada, con acceso a la API del servicio web.
- Un diseño de etiqueta creado en el estudio de etiquetas de LPSNG, o un diseño de muestra que puedas usar para probar. El diseño debe contener al menos un campo de código de barras.
- Credenciales de cliente OAuth2 para la autenticación de la API. Consulta la guía de OAuth2 para conocer el flujo de registro simplificado.
- Familiaridad básica con Python y las API REST. El servicio web de LPSNG es RESTful y devuelve JSON, por lo que basta con conocimientos estándar de HTTP.
No necesitas instalar fuentes de códigos de barras, controladores ZPL/EPL ni SDK específicos de impresoras. LPSNG se encarga de esos detalles detrás de su servicio web.
Paso a paso: generación de etiquetas de código de barras con Python
El flujo de trabajo es sencillo: autenticarse, identificar el diseño, preparar los datos, personalizar opcionalmente los campos con un bloque de script de Python, renderizar la etiqueta e imprimirla o guardarla.
Paso 1: Configura tu entorno de Python
Crea un directorio de proyecto e instala la librería requests. La API de LPSNG es RESTful, por lo que solo necesitas un cliente HTTP estándar.
mkdir lpsng-python-labeling
cd lpsng-python-labeling
python -m venv venv
source venv/bin/activate # o venv\Scripts\activate en Windows
pip install requests
Crea un archivo llamado generate_label.py. En la parte superior, define tu URL base de LPSNG y tus credenciales. Sustituye los valores de marcador de posición por los detalles reales de tu instancia.
import requests
import json
from pathlib import Path
# Sustituye por la URL de tu instancia de LPSNG, p. ej. https://your-instance.lpsng.rsj.de
LPSNG_BASE_URL = "https://your-instance.lpsng.rsj.de"
# Sustituye por las credenciales de tu registro OAuth2
CLIENT_ID = "your-client-id"
CLIENT_SECRET = "your-client-secret"
Paso 2: Obtén un token de acceso OAuth2
LPSNG utiliza un protocolo de registro OAuth2 simplificado. Una vez que tu aplicación externa está registrada, intercambias tus credenciales de cliente por un token de acceso.
El siguiente ejemplo mantiene el endpoint del token como variable, para que puedas apuntarlo a la URL exacta de la documentación de la API del servicio web de tu instancia.
def get_access_token():
# Usa el endpoint de token indicado en la guía de OAuth2 de LPSNG.
token_url = f"{LPSNG_BASE_URL}/oauth2/token"
response = requests.post(
token_url,
data={
"grant_type": "client_credentials",
"client_id": CLIENT_ID,
"client_secret": CLIENT_SECRET,
},
timeout=30,
)
response.raise_for_status()
return response.json()["access_token"]
En código de producción, almacena el token en caché y renuévalo antes de que caduque. Para este tutorial, puedes solicitar un token nuevo cada vez.
Paso 3: Obtén el ID de tu diseño de etiqueta
Cada diseño de etiqueta en LPSNG tiene un ID. Puedes copiarlo desde la interfaz web de LPSNG abriendo las propiedades del diseño, o puedes consultarlo a través de la API.
La ruta de la interfaz web es la más sencilla para una primera prueba. Abre tu diseño de etiqueta en el estudio de etiquetas y copia el ID del diseño desde la URL o desde la configuración del diseño.
Si quieres automatizar la búsqueda de diseños desde Python, usa el mismo patrón REST. El endpoint exacto puede variar según la instancia, así que complétalo a partir de tu referencia de API:
def find_layout_id(token, layout_name):
headers = {"Authorization": f"Bearer {token}"}
# Sustituye /layouts por el endpoint de listado documentado para tu instancia.
response = requests.get(
f"{LPSNG_BASE_URL}/layouts",
headers=headers,
timeout=30,
)
response.raise_for_status()
for layout in response.json():
if layout.get("name") == layout_name:
return layout["id"]
raise ValueError(f"Layout not found: {layout_name}")
Para un script rápido, un ID de diseño codificado de forma fija es suficiente:
LAYOUT_ID = "your-layout-id"
Paso 4: Prepara la carga útil de datos con el contenido del código de barras
La API del servicio web envía trabajos de impresión y renderiza etiquetas individuales. Tu carga útil normalmente contiene un conjunto de valores de campo para el diseño, incluido el valor que debe codificarse en el código de barras.
Aquí tienes un ejemplo de carga útil para una etiqueta de artículo con un código de barras Code 128:
label_data = {
"product_name": "Thermal Label Roll 100x150",
"sku": "THR-100-150",
"barcode": "4012345678901",
"quantity": 12,
"batch": "B20260831-04",
}
Los nombres de campo de tu carga útil deben coincidir con los nombres de campo que definiste en el estudio de etiquetas de LPSNG. Si tu diseño tiene un campo de código de barras llamado barcode, LPSNG codifica el valor que envíes para ese campo en el formato de código de barras configurado en el diseño.
Paso 5: Personaliza campos con la API de scripts de campo de Python
LPSNG incluye una API de scripts de campo de Python que te permite adjuntar pequeños bloques de script de Python a los campos de la etiqueta. Esos scripts se ejecutan antes de la impresión y pueden acceder a los valores de los campos o modificarlos.
Por ejemplo, supongamos que los datos de tu almacén a veces contienen códigos de barras en minúsculas o con espacios al final, y quieres normalizar el valor antes de que llegue al código de barras. En el estudio de etiquetas de LPSNG, adjunta un bloque de script al campo del código de barras similar a este:
# Adjunto al campo del código de barras en LPSNG Label Studio.
# El script se ejecuta antes de la impresión y puede acceder al valor actual.
if "barcode" in context:
value = str(context["barcode"]).strip().upper()
El punto de entrada exacto y los objetos disponibles están documentados en la referencia de la API de Python. Usa esa referencia para verificar la firma exacta del hook para tu versión de LPSNG. La idea clave es que los scripts de Python a nivel de campo mantienen la lógica de formato cerca de la etiqueta, mientras que tu aplicación Python externa se centra en la preparación de datos y las llamadas a la API.
Paso 6: Llama al endpoint del servicio web para renderizar la etiqueta
Ahora llama a LPSNG para renderizar la etiqueta como PDF o PNG. La API del servicio web puede renderizar etiquetas individuales, por lo que no necesitas ejecutar un renderizador local.
def render_label(token, layout_id, data, output_format="pdf"):
headers = {
"Authorization": f"Bearer {token}",
"Content-Type": "application/json",
}
# Usa el endpoint de renderizado de la documentación de la API del servicio web de LPSNG.
render_url = f"{LPSNG_BASE_URL}/render"
response = requests.post(
render_url,
headers=headers,
json={
"layout_id": layout_id,
"data": data,
"format": output_format,
},
timeout=60,
)
response.raise_for_status()
return response.content
Para la salida en PNG, pasa "png" como formato. La respuesta de la API contiene el contenido binario del archivo, que puedes guardar directamente.
token = get_access_token()
pdf_bytes = render_label(token, LAYOUT_ID, label_data, "pdf")
Path("label.pdf").write_bytes(pdf_bytes)
print("Label rendered: label.pdf")
Paso 7: Envía la etiqueta generada a una impresora o guárdala localmente
Si tu instancia de LPSNG está conectada a impresoras, puedes enviar un trabajo de impresión a través de la misma API del servicio web en lugar de descargar el archivo. La forma exacta de la petición está documentada en la interfaz del servicio web.
Una llamada típica de impresión directa sigue el mismo patrón REST:
def send_to_printer(token, layout_id, data, printer_name):
headers = {
"Authorization": f"Bearer {token}",
"Content-Type": "application/json",
}
# Usa el endpoint de impresión documentado para tu instancia de LPSNG.
print_url = f"{LPSNG_BASE_URL}/print"
response = requests.post(
print_url,
headers=headers,
json={
"layout_id": layout_id,
"data": data,
"printer": printer_name,
},
timeout=60,
)
response.raise_for_status()
return response.json()
Sustituye "printer" por el nombre o ID de la impresora configurado en tu entorno de LPSNG. Si prefieres conservar el archivo localmente, omite este paso y usa la salida PDF o PNG del paso 6.
Verificación de la salida de tu etiqueta
No des por sentado que el código de barras es correcto solo porque el PDF o PNG se abrió sin errores. Realiza estas comprobaciones:
- Abre visualmente el archivo generado. Confirma que los campos de texto están rellenados, que el código de barras es visible y que el diseño coincide con el diseño de tu estudio de etiquetas.
- Escanea el código de barras con una aplicación de escáner. Apunta un escáner de códigos de barras basado en teléfono a la etiqueta impresa o en pantalla. Verifica que los datos codificados coinciden con el valor que enviaste en la carga útil.
- Comprueba las personalizaciones de campos. Si añadiste un script de campo de Python que convierte a mayúsculas o recorta el valor del código de barras, envía datos de prueba en minúsculas o con espacios y confirma que la salida cambió como se esperaba.
- Prueba con múltiples conjuntos de datos. Ejecuta el script con diferentes SKU, cantidades y valores de código de barras para asegurarte de que ningún campo esté codificado de forma fija o desalineado.
Si tu salida es un PDF, imprímelo una vez en la impresora térmica de destino para confirmar las dimensiones de la etiqueta y la densidad de impresión.
Solución de problemas comunes
Errores de autenticación
Comprueba dos veces tus credenciales de cliente OAuth2 y el endpoint del token. Si el token ha caducado, solicita uno nuevo. Confirma que el cliente sigue registrado en tu cuenta de LPSNG y que la cuenta tiene acceso a la API.
No se encuentra el diseño de etiqueta
Verifica el ID del diseño y los permisos de usuario asociados a tu cliente OAuth2. Es posible que el cliente tenga acceso a la API pero no al diseño específico. Comprueba el nombre del diseño exactamente, incluidas mayúsculas y espacios en blanco.
El código de barras no se renderiza
Asegúrate de que el formato de código de barras es compatible con LPSNG y de que el valor del campo de código de barras es válido para ese formato. Por ejemplo, un campo Code 128 debe recibir datos que sean válidos para Code 128. Consulta la documentación de formatos de código de barras para ver la lista completa de formatos 1D y 2D compatibles.
Comprueba también que el campo de código de barras de tu diseño esté realmente asignado a la clave de carga útil que estás enviando. Una discrepancia entre los nombres de campo es una causa común de códigos de barras vacíos.
Errores de scripts de campo
Si tu script de campo de Python genera un error, la respuesta de la API normalmente contiene un mensaje de error. Léelo con atención; a menudo indica el número de línea o el tipo de excepción en el bloque de script. Usa la referencia de la API de Python para confirmar qué objetos están disponibles en el contexto del script.
Problemas de impresión
Si la etiqueta se renderiza pero no se imprime, confirma la conectividad de la impresora y la configuración del controlador en tu entorno de LPSNG. Comprueba que el nombre de la impresora en tu llamada de impresión coincide con el nombre configurado en LPSNG y que la impresora está en línea.
Preguntas frecuentes
¿Puedo generar etiquetas de código de barras en Python sin usar el servicio web de LPSNG?
Sí, podrías usar librerías básicas como python-barcode o reportlab, pero tendrías que encargarte tú mismo del diseño de etiquetas, la comunicación con la impresora y los estándares de códigos de barras. LPSNG proporciona un servicio gestionado con una API de Python que simplifica todo el proceso, incluida la personalización de campos y la impresión directa.
¿Qué formatos de código de barras admite LPSNG?
LPSNG admite una amplia gama de formatos de códigos de barras 1D y 2D. Consulta la documentación de formatos de código de barras para ver la lista completa, que incluye Code 128, código QR, Data Matrix y más.
¿Necesito instalar paquetes especiales de Python para usar la API de LPSNG?
Solo se necesitan librerías de cliente HTTP estándar como requests. La API es RESTful y devuelve respuestas JSON, lo que facilita la integración con cualquier entorno de Python.
¿Puedo usar la API de Python para actualizar también etiquetas electrónicas de estantería (ESL)?
Sí, LPSNG ofrece una interfaz ESL y una API de vinculación a la que se puede acceder mediante Python. Consulta la documentación de ESL para obtener detalles sobre cómo actualizar pantallas ESL de forma programática.
Conclusión
La generación de etiquetas de código de barras con Python se vuelve mucho más sencilla cuando dejas que un servicio gestionado se encargue del renderizado, los estándares de códigos de barras y los detalles de impresión. Con LPSNG, tu aplicación Python solo necesita autenticarse, enviar los datos de los campos y llamar a un endpoint REST. El diseño de la etiqueta permanece en el estudio de etiquetas, mientras que los scripts de campo de Python se encargan del formato a nivel de campo.
Este enfoque encaja perfectamente en flujos de trabajo de automatización más amplios. Si estás evaluando software de etiquetas como desarrollador, consulta El mejor software de diseño de etiquetas para desarrolladores: por qué destaca LPSNG. Si tu proyecto de etiquetado se extiende a las etiquetas electrónicas de estantería, continúa con Integración de ESL para el comercio minorista: una guía completa. Y si la mayoría de tus datos de origen viven en hojas de cálculo, no te pierdas Automatiza la impresión de etiquetas desde Excel: ahorra tiempo y reduce errores.
¿Listo para crear tu primera etiqueta de código de barras generada con Python? Consigue tus credenciales OAuth2, elige un diseño y ejecuta el script con un artículo real. El Sistema de Impresión de Etiquetas de Nueva Generación se encarga del trabajo pesado; tú escribes la integración.
Publicaciones relacionadas
- El mejor software de diseño de etiquetas para desarrolladores: por qué destaca LPSNG
- Integración de ESL para el comercio minorista: una guía completa
- Automatiza la impresión de etiquetas desde Excel: ahorra tiempo y reduce errores
