Impresión de etiquetas con Kafka: el stream como disparador

El stream ya está ahí

Tu ERP o MES ya publica eventos de pedidos, mensajes de picking y números de serie en Kafka. Normalmente ese stream termina en una pantalla y una persona pulsa imprimir.

La pestaña Data Streaming convierte el stream en el disparador: suscríbete a un topic, y cada mensaje se renderiza con un diseño de etiqueta y se envía a una impresora. Sin middleware, sin trabajos de polling, sin servidor de impresión.

Dos despliegues:

• Cloud - la plataforma consume el topic por sí misma (Confluent Cloud, MSK, cualquier broker accesible por internet).
• On-prem - un broker dentro de tu red, consumido por el agente CLI de zplCloud. Las credenciales del broker nunca salen de tu red.

Qué vincula una suscripción

Cuatro cosas: un topic, un diseño de etiqueta, una impresora y - en modo cloud - la configuración de conexión del broker. Por cada mensaje la plataforma:

1. analiza el valor como JSON y usa las claves del objeto como bindings de campos,

2. renderiza el diseño con el mismo motor que usa el diseñador,

3. envía el ZPL resultante a la impresora (Weblink, o una impresora remota en un agente CLI vía TCP 9100 / USB).

Si el valor no es JSON, todo el texto se vincula a $message - suficiente para una etiqueta de un solo campo.

Configuración de conexión

La configuración es una cadena clave=valor;, almacenada cifrada con AES en reposo:

BootstrapServers=pkc-xxxxx.eu-central-1.aws.confluent.cloud:9092;
GroupId=zplCloudPrinter;
SecurityProtocol=SaslSsl;SaslMechanism=Plain;
SaslUsername=<api-key>;SaslPassword=<api-secret>

Valores por defecto cuando no los configuras:

AutoOffsetReset=Earliest es la opción deliberada para reproducir un topic. Actívala solo cuando lo quieras decir en serio: en un topic con historial, el primer arranque lo imprime todo.

Se admiten SCRAM (SaslMechanism=ScramSha256 / ScramSha512) y una CA personalizada (SslCaLocation=…). Las claves desconocidas se pasan a la configuración del consumidor tal cual.

Para un broker on-prem, regístralo en el agente:

zplcloud proxy --agent "Lager" \
  --kafka LOKAL="BootstrapServers=10.0.0.10:9092;GroupId=zplCloudConsumer"

El agente informa de Kafka brokers: LOKAL. Cuando una suscripción lo necesita, la plataforma pide al agente que ejecute el consumidor - el broker permanece inaccesible desde internet.

La semántica de entrega, con precisión

Esta es la parte en la que la mayoría de las integraciones de streaming se vuelven vagas, así que aquí está exactamente como está implementado:

• El consumidor hace polling con un timeout de 30 segundos.

• Ante un mensaje: renderizar, imprimir y luego Commit(msg) solo si la impresión ha tenido éxito.
• Si la impresión falla, el offset no se confirma y el consumidor se detiene. La suscripción pasa a desconectada y muestra Print failed: <error>. No se salta el mensaje ni entra en un bucle de reintentos.
• Como el valor por defecto es AutoOffsetReset=Latest, reiniciar tras un fallo no reentrega automáticamente el mensaje fallido. Si quieres que el mensaje fallido se reintente al reiniciar, pon AutoOffsetReset=Earliest en la configuración - entonces el offset sin confirmar se retoma.

El razonamiento: una etiqueta que no se imprimió es un hecho operativo que alguien tiene que ver. Avanzar en silencio perdería una etiqueta física; reintentar eternamente bloquearía la partición. Detenerse lo hace visible y deja el offset donde está.

ConsumeException - broker inaccesible, autenticación rechazada, topic eliminado - se trata de forma distinta. Eso no es un fallo de impresión, así que el consumidor reintenta con un backoff exponencial que empieza en 5 s y tiene un tope de 60 s, y el último error del broker se muestra en la suscripción.

Mantenimiento en inactividad

Si no llega ningún mensaje durante 60 segundos, la plataforma envía un comando de activación a la impresora de destino. Las impresoras Link-OS pasan a un estado de bajo consumo; sin el keepalive, el primer mensaje tras un periodo de silencio paga la latencia de activación antes de imprimir. El keepalive toca la impresora, no el topic - no se consume ni confirma ningún offset.

Crear la suscripción

Pulsa Iniciar. La suscripción muestra entonces el estado en vivo - conectada, hora del último mensaje, último offset, número de mensajes - y un registro con los valores recientes de los mensajes y su resultado de impresión.

Forma del mensaje

{ "ean": "40063813", "qty": 2, "dest": "Ramp 4" }

Las claves se asignan a los bindings por nombre. Las claves que ningún binding usa se ignoran; los bindings sin clave correspondiente se renderizan vacíos. Diseña la etiqueta contra un mensaje real antes de pasar a producción - Datos de prueba en el diseñador acepta JSON pegado.

Comportamiento al reiniciar

Las suscripciones activas se reinician cuando se reinicia la plataforma, y las suscripciones on-prem se reinician cuando el agente CLI se reconecta. Una ventana de mantenimiento nocturno o una conexión caída no requieren que nadie pulse Iniciar de nuevo - con la excepción anterior: una suscripción detenida por un fallo de impresión permanece detenida hasta que arregles la impresora y la inicies.

Planes

El streaming de datos se mide por uso. Starter lo incluye para pruebas, con un tope de 100 etiquetas en streaming al mes. Pro incluye 2 endpoints de streaming (Kafka / Azure Service Bus); cada endpoint adicional cuesta 10 € al mes. Consulta la página de precios.

Relacionado

• CLI de zplCloud - agente, brokers, instalación de servicio
• Agente como contenedor Docker
• Cloud Integration / Connections