Automatización con Python en Text2 Barcode
Ejecuta lógica personalizada justo antes y después de cada impresión: ajusta impresoras, valida contenido, notifica por correo o convierte imágenes a ZPL, todo con un script de Python integrado en el servicio de impresión.
Introducción
Cada servicio de impresión de Text2 Barcode puede ejecutar un script de Python propio mediante una clase
PrintHandler con dos métodos: beforePrint() (antes de imprimir) y
afterPrint() (después de imprimir).
Por dentro, Text2 Barcode inicia un proceso de Python y establece automáticamente el puente
Py4J entre Java y tu script —
no necesitas escribir código de conexión: solo defines la clase PrintHandler y el programa se encarga del resto.
Requisitos
- Instala Python desde la web oficial: https://www.python.org/downloads/
- Instala Py4J (comunicación entre Python y Text2 Barcode):
pip install py4j
Text2 Barcode detecta automáticamente la ruta de tu ejecutable de Python (where python en Windows,
which python3 / which python en Mac y Linux). Si necesitas usar una instalación específica,
puedes indicar la ruta manualmente en la pestaña Environment del editor de Python, o definir la variable de entorno
PYTHON_EXECUTABLE_PATH con la ruta completa al ejecutable.
Activar el script en un servicio
El script de Python se configura por servicio, no de forma global:
- Abre o edita un Servicio en Text2 Barcode (Servicios > Agregar servicio o edita uno existente).
- Ve a la sección "Integra scripts de Python" y activa la casilla "Activar script".
- Da clic en "Abrir editor" para escribir tu código en la pestaña Script.
- Usa la pestaña Output para ver la salida de tu script mientras lo pruebas con ▶ Iniciar.
Dónde se ejecuta el script
El script de un servicio se ejecuta en cada trabajo de impresión que pasa por ese servicio:
| Origen del trabajo | type_service |
|---|---|
| Servicio de carpetas (archivos detectados en la carpeta vigilada) | "file-scan" |
| LAN Share (datos crudos recibidos por el puerto 9100) | "lan-share" |
API web / Browser Print SDK, al imprimir a un servicio (connection: "ttb") | "web-print" |
driver, network,
usb o bluetooth) no interviene ningún servicio, así que no se ejecuta ningún script.
Para que el script corra por la API web, el servicio debe tener la casilla "Activar script" marcada;
no hace falta que el servicio esté iniciado.
Cambios al script y avisos
- Editar el script: al guardar el servicio, el cambio se aplica en la siguiente impresión, sin reiniciar Text2 Barcode ni detener y volver a iniciar los servicios. Text2 Barcode avisa con "El script de Python de «nombre» se actualizó".
- Desmarcar "Activar script": el script deja de ejecutarse en la siguiente impresión.
-
El script no arranca (Python o
py4jsin instalar, error de sintaxis, etc.): la impresión se detiene con un mensaje que indica el servicio afectado y el detalle del error. Al corregirlo, la siguiente impresión vuelve a intentarlo sola.
Estructura básica
Tu script debe definir una clase llamada exactamente PrintHandler, con los métodos
beforePrint(event, service) y afterPrint(event, service):
class PrintHandler:
"""
La clase PrintHandler gestiona eventos relacionados con el proceso de impresión.
Incluye métodos que se ejecutan antes y después de la impresión.
"""
def beforePrint(self, event, service):
"""
Esta función se ejecuta antes de que comience el proceso de impresión.
:param event: PrintEvent
:param service: PrintService
"""
pass # Aquí se agrega la lógica para el manejo previo a la impresión
def afterPrint(self, event, service):
"""
Esta función se ejecuta después de que se ha completado el proceso de impresión.
:param event: PrintEvent
:param service: PrintService
"""
pass # Aquí se agrega la lógica para el manejo después de la impresión
Este es el mismo código de ejemplo que ves al abrir el editor por primera vez para un servicio nuevo.
Clase PrintEvent
event expone la información del trabajo de impresión: contenido, impresoras y parámetros del servicio que lo generó.
content() str
Si necesitas verlo como texto, decodifica el Base64 primero (por ejemplo con base64.b64decode(...)).
{{folio}}), llama a event.cancel() en beforePrint y reenvía el contenido ya
modificado con service.send(). Mira el ejemplo Folio consecutivo desde un CSV.
printers() list[dict]
Cada impresora es un dict con al menos uid, name y connection. Los campos adicionales dependen del valor de connection:
| connection | Campos adicionales |
|---|---|
| driver |
manufacturer, driverConnection (descripción del backend de impresión del sistema operativo),
resolution (DPI, solo si el driver lo reporta), isDefault (bool),
queuedJobs (int), statusText (str), printProcessor
(str: "PRINT_RAW", "PRINT_DIRECT" o "PRINT_ALT_CUPS")
|
| network | port (int) |
| usb |
deviceAddress, busNumber, portNumber, serialNumber,
manufacturerName, productId, productName, vendorId
|
| file | charset (str) |
| unknown | sin campos adicionales |
printProcessor viaja incluido en cada impresora driver — puedes reenviar el mismo
dict de event.printers() directo a service.send() / service.sendBase64()
sin agregarle nada.
parameters() dict
parameters['type_service'].| Campo | Cuándo aparece | Descripción |
|---|---|---|
| type_service | siempre | "file-scan", "lan-share" o "web-print", según el origen que disparó la impresión. |
| directory_scanned | file-scan | Carpeta que el servicio está vigilando. |
| file_detected | file-scan | Ruta del archivo (o zip) detectado en la carpeta. |
| current_file | file-scan | Ruta del archivo que se va a imprimir (puede venir de dentro de un zip). |
| current_file_index | file-scan | Índice del archivo actual dentro del lote. |
| total_file_count | file-scan | Total de archivos detectados en este lote. |
| lan_host | lan-share | Host/IP del dispositivo que envió la petición de impresión. |
| lan_port | lan-share | Puerto del dispositivo que envió la petición. |
Con "web-print" (API web) no hay campos adicionales: parameters() solo trae type_service.
cancel() / isCancelled()
beforePrint, ese archivo no se imprime; si se llama dentro de afterPrint, se detiene el procesamiento posterior (por ejemplo, la acción configurada después de imprimir).cancel()).Clase PrintService
service permite ejecutar acciones durante el flujo de impresión: enviar datos, pausar el proceso o convertir imágenes a ZPL.
send(content, charset, printers)
content (texto) a las impresoras indicadas, usando el charset especificado (por ejemplo "UTF-8").class PrintHandler:
def beforePrint(self, event, service):
# Ajusta velocidad y densidad antes de imprimir
service.send("^XA^PR3^MD15^XZ", "UTF-8", event.printers())
sendBase64(contentBase64, printers)
event.content(), sin decodificarlo.pause(message)
message. Si el usuario elige "No", el trabajo se cancela.convert_img_zpl(props) str
^XA...^XZ con la imagen comprimida como gráfico).| Campo | Tipo | Requerido | Descripción |
|---|---|---|---|
| uri | str | Sí | Ruta o URI de la imagen, por ejemplo "file://C:/imagenes/logo.png". |
| w | int | No | Ancho en milímetros. Por defecto 102. |
| h | int | No | Alto en milímetros. Por defecto 0 (se calcula automáticamente según la proporción de la imagen). |
| dpi | int | No | Resolución de la impresora en DPI. Por defecto 200. |
| angle | float | No | Ángulo de rotación en grados. Por defecto 0. |
| imageFilterType | int | No | Filtro aplicado a la imagen: 0 escala de grises, 1 difuminado/dithered (por defecto), 2 binario (blanco y negro puro). |
class PrintHandler:
def beforePrint(self, event, service):
zpl = service.convert_img_zpl({
"uri": "file://C:/imagenes/logo.png",
"w": 60,
"h": 60,
"dpi": 200,
})
service.send(zpl, "UTF-8", event.printers())
Ejemplos completos
Enviar un correo después de imprimir
import smtplib
from email.mime.text import MIMEText
class PrintHandler:
def afterPrint(self, event, service):
# Construir detalles de las impresoras donde se imprimió
printer_details = ""
for printer in event.printers():
printer_details += f"Impresora: {printer['name']}\n"
printer_details += f"UID: {printer['uid']}\n"
printer_details += f"Conexión: {printer['connection']}\n\n"
# Obtener el contenido impreso (Base64)
content_b64 = event.content()
msg_details = (
"Se ha completado una impresión.\n\n"
f"Contenido (Base64):\n{content_b64}\n\n"
f"Impresoras utilizadas:\n{printer_details}"
)
msg = MIMEText(msg_details)
msg['Subject'] = 'Etiqueta impresa'
msg['From'] = 'tuemail@example.com'
msg['To'] = 'destinatario@example.com'
with smtplib.SMTP('smtp.example.com', 587) as server:
server.starttls()
server.login('tuemail@example.com', 'tupassword')
server.sendmail(msg['From'], [msg['To']], msg.as_string())
print("Correo enviado con éxito")
Folio consecutivo desde un CSV
Reemplaza {{folio}} en la etiqueta por el número guardado en un CSV
(Documentos/folio.csv) y lo incrementa en cada impresión. El CSV tiene el encabezado
folio y una fila con el número; si no existe, se crea empezando en 1, y se respetan los ceros a la izquierda
(0099 → 0100). Funciona con cualquiera de los tres orígenes, incluida la API web.
import base64
import os
import threading
FOLIO_CSV = os.path.join(os.path.expanduser("~"), "Documents", "folio.csv")
_lock = threading.Lock()
class PrintHandler:
def beforePrint(self, event, service):
zpl = base64.b64decode(event.content()).decode("utf-8")
if "{{folio}}" not in zpl:
return # etiqueta sin {{folio}}: se imprime normal
with _lock:
folio = self._read()
event.cancel() # el contenido es de solo lectura: se cancela y se reenvía ya rellenado
service.send(zpl.replace("{{folio}}", folio), "UTF-8", event.printers())
# Solo se avanza el folio si el envío no lanzó excepción
self._write(str(int(folio) + 1).zfill(len(folio)))
def afterPrint(self, event, service):
pass
def _read(self):
if not os.path.exists(FOLIO_CSV):
self._write("1")
with open(FOLIO_CSV, encoding="utf-8-sig") as f:
return f.read().split()[1] # línea "folio" + línea con el número
def _write(self, value):
os.makedirs(os.path.dirname(FOLIO_CSV), exist_ok=True)
with open(FOLIO_CSV, "w", encoding="utf-8") as f:
f.write(f"folio\n{value}\n")
Cruzar un Excel de pedidos con la etiqueta que se imprime
Carga un Excel una sola vez (con openpyxl), y en cada etiqueta busca la fila que corresponde por número de guía para imprimir una segunda etiqueta con los detalles del pedido.
import os, glob
from openpyxl import load_workbook # pip install openpyxl
class PrintHandler:
def __init__(self):
self.orders = None # se carga una sola vez y se reutiliza en cada impresión
def beforePrint(self, event, service):
if self.orders is None:
base_path = event.parameters()['directory_scanned']
excel_path = glob.glob(os.path.join(base_path, '*.xlsx'))[0]
sheet = load_workbook(excel_path, read_only=True, data_only=True).active
headers = [c.value for c in sheet[1]]
self.orders = [dict(zip(headers, row)) for row in sheet.iter_rows(min_row=2, values_only=True)]
def afterPrint(self, event, service):
# El nombre del archivo impreso suele ser el número de guía, ej. "705871797965170A06.pdf"
tracking_number = os.path.splitext(os.path.basename(event.parameters()['current_file']))[0]
order = next((o for o in self.orders if tracking_number in str(o.get('Número de guía', ''))), None)
if order:
zpl = f"^XA^FO20,20^A0N,30,30^FD{order['Producto']} x{order['Cantidad']}^FS^XZ"
service.send(zpl, "UTF-8", event.printers())
Solución de problemas
-
"The value for 'printProcessor' must not be null": la impresora que le pasaste a
service.send()/service.sendBase64()es undictdriverconstruido a mano (no salió deevent.printers()) y le falta la claveprintProcessor. Agrégala con uno de estos valores:"PRINT_RAW","PRINT_DIRECT"o"PRINT_ALT_CUPS". - El script no imprime nada / se queda esperando: revisa la pestaña Output del editor — cualquier excepción de Python se muestra ahí en rojo.
-
Imprimo por la API web y el script no se ejecuta: el script solo corre si imprimes a un
servicio (
connection: "ttb") con "Activar script" marcado. Imprimir directo a una impresoradriver,network,usbobluetoothno lo ejecuta. Los cambios del script se aplican solos en la siguiente impresión; no necesitas reiniciar Text2 Barcode. -
No encuentra el ejecutable de Python: define la ruta manualmente en la pestaña
Environment del editor, o crea la variable de entorno
PYTHON_EXECUTABLE_PATH.
¿Tienes dudas o algo no funciona como esperas? Contáctanos y con gusto te ayudamos.