Impressão de etiquetas com Kafka: o fluxo como gatilho

O fluxo já existe

Seu ERP ou MES já publica eventos de pedidos, mensagens de separação e números de série no Kafka. Normalmente esse fluxo termina em uma tela e um humano aperta imprimir.

A aba Data Streaming transforma o fluxo no gatilho: assine um tópico, e cada mensagem é renderizada com um design de etiqueta e enviada a uma impressora. Sem middleware, sem trabalho de polling, sem servidor de impressão.

Dois deployments:

• Cloud - a plataforma consome o tópico sozinha (Confluent Cloud, MSK, qualquer broker acessível pela internet).
• On-prem - um broker dentro da sua rede, consumido pelo agente CLI zplCloud. As credenciais do broker nunca saem da sua rede.

O que uma assinatura vincula

Quatro coisas: um tópico, um design de etiqueta, uma impressora e - no modo cloud - a configuração de conexão do broker. Para cada mensagem, a plataforma:

1. analisa o valor como JSON e usa as chaves do objeto como bindings de campos,

2. renderiza o design com o mesmo mecanismo que o designer usa,

3. envia o ZPL resultante para a impressora (Weblink, ou uma impressora remota em um agente CLI via TCP 9100 / USB).

Se o valor não for JSON, todo o texto é vinculado a $message - suficiente para uma etiqueta de campo único.

Configuração de conexão

A configuração é uma string chave=valor;, armazenada criptografada com AES em repouso:

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

Padrões aplicados quando você não os define:

AutoOffsetReset=Earliest é o opt-in deliberado para reproduzir um tópico. Defina-o apenas se realmente quiser: em um tópico com histórico, o primeiro início imprime tudo.

SCRAM (SaslMechanism=ScramSha256 / ScramSha512) e uma CA personalizada (SslCaLocation=…) são suportados. Chaves desconhecidas são repassadas à configuração do consumidor como estão.

Para um broker on-prem, registre-o no agente:

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

O agente reporta Kafka brokers: LOKAL. Quando uma assinatura precisa, a plataforma pede ao agente para rodar o consumidor - o broker permanece inacessível pela internet.

A semântica de entrega, com precisão

Esta é a parte em que a maioria das integrações de streaming fica vaga, então aqui está exatamente como implementado:

• O consumidor faz polling com um timeout de 30 segundos.
• Em uma mensagem: renderizar, imprimir e então Commit(msg) somente se a impressão for bem-sucedida.
• Se a impressão falhar, o offset não é confirmado e o consumidor para. A assinatura muda para desconectada e mostra Print failed: <error>. Ela não pula a mensagem e não gira em um loop de tentativas.
• Como o padrão é AutoOffsetReset=Latest, reiniciar após uma falha não reentrega automaticamente a mensagem falha. Se você quiser que a mensagem falha seja tentada novamente na reinicialização, coloque AutoOffsetReset=Earliest na configuração - então o offset não confirmado é retomado.

O raciocínio: uma etiqueta que não foi impressa é um fato operacional que alguém precisa ver. Avançar em silêncio perderia uma etiqueta física; tentar para sempre travaria a partição. Parar a torna visível e deixa o offset onde está.

ConsumeException - broker inacessível, auth rejeitada, tópico removido - é tratada de forma diferente. Isso não é uma falha de impressão, então o consumidor tenta novamente com backoff exponencial começando em 5 s e limitado a 60 s, e o último erro do broker é mostrado na assinatura.

Keepalive ocioso

Se nenhuma mensagem chegar por 60 segundos, a plataforma envia um comando de ativação para a impressora de destino. Impressoras Link-OS entram em estado de baixo consumo; sem o keepalive, a primeira mensagem após um período silencioso paga a latência de ativação antes de imprimir. O keepalive toca a impressora, não o tópico - nenhum offset é consumido ou confirmado.

Criando a assinatura

Pressione Iniciar. A assinatura mostra então o status ao vivo - conectada, hora da última mensagem, último offset, contagem de mensagens - e um log com os valores recentes das mensagens e seu resultado de impressão.

Forma da mensagem

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

As chaves correspondem aos bindings por nome. Chaves que nenhum binding usa são ignoradas; bindings sem chave correspondente são renderizados vazios. Crie a etiqueta contra uma mensagem real antes de ir ao ar - Dados Teste no designer aceita JSON colado.

Comportamento na reinicialização

Assinaturas ativas reiniciam quando a plataforma reinicia, e assinaturas on-prem reiniciam quando o agente CLI reconecta. Uma janela de manutenção noturna ou uma conexão caída não exigem que alguém pressione Iniciar novamente - com a exceção acima: uma assinatura parada por falha de impressão permanece parada até você consertar a impressora e iniciá-la.

Planos

O streaming de dados é medido. Starter o inclui para testes, limitado a 100 etiquetas em streaming por mês. Pro inclui 2 endpoints de streaming (Kafka / Azure Service Bus); cada endpoint adicional custa € 10 por mês. Veja a página de preços.

Relacionados

• CLI zplCloud - agente, brokers, instalação de serviço
• Agente como contêiner Docker
• Cloud Integration / Connections