Imprimir ZPL do S3 ou do Azure Blob - e arquivar lá as etiquetas impressas

O object storage é onde os arquivos de impressão já estão: etiquetas de transportadora vindas do provedor de envio, lotes pré-renderizados do ERP, arquivamentos mantidos por regras de retenção. Este guia cobre as duas direções - imprimir ZPL a partir de um bucket e gravar o ZPL impresso de volta em um bucket.

Tudo se aplica ao Amazon S3 e ao Azure Blob Storage. Como a interface S3 é padronizada, MinIO, Cloudflare R2, Wasabi, Backblaze B2 e Ceph também funcionam.

Criando uma conexão de armazenamento

Em Streaming → Armazenamento → Nova conexão, você cria a conexão uma única vez. O nome é importante: é por ele que as mensagens se referem à conexão depois.

Campo	S3	Azure Blob
Bucket / contêiner	nome do bucket	nome do contêiner
Região	ex.: eu-central-1	não usado
Endpoint	vazio para AWS; caso contrário, ex.: https://minio.example.com	não usado
Path style	ativar para MinIO e Ceph	não usado
Prefixo	opcional, ex.: zpl/	opcional
Credenciais	AccessKey=…;SecretKey=…	string de conexão ou URL SAS do contêiner

As credenciais são armazenadas criptografadas com AES no banco de dados da plataforma. Elas nunca voltam para o navegador - o formulário mostra apenas que existem credenciais. No S3, você pode omiti-las por completo: nesse caso vale a cadeia normal de credenciais da AWS, por exemplo a IAM role do ambiente.

Teste verifica se o bucket e as permissões estão corretos antes que qualquer coisa seja impressa.

Direção 1: imprimir ZPL a partir do bucket

Uma mensagem de barramento pode carregar ZPL pronto. Para arquivos grandes, isso é inconveniente - muitos brokers limitam o tamanho da mensagem, e uma etiqueta com um gráfico embutido fica grande rapidamente. Melhor: a mensagem apenas aponta para o arquivo.

{
  "schemaVersion": 1,
  "printer": "rp:7",
  "zplRef": { "storage": "archive", "key": "orders/4711.zpl" }
}

storage é o nome da sua conexão, key é a chave do objeto dentro dela. Um prefixo configurado é adicionado na frente: com o prefixo zpl/, o exemplo acima vira zpl/orders/4711.zpl.

O arquivo é buscado no momento da impressão, não no recebimento. O nome é resolvido apenas dentro do seu próprio escopo ou do escopo da sua empresa - a conexão de outra pessoa não pode ser alcançada por uma mensagem, nem mesmo por quem conhece o nome dela.

Direção 2: armazenar o ZPL impresso e notificar

A direção inversa se chama destino de saída. Ele reúne três etapas que rodam após uma impressão bem-sucedida, e cada uma é ativada separadamente:

1. Armazenar - o ZPL impresso é gravado como arquivo em uma conexão de armazenamento.

2. Notificar - uma mensagem vai para um barramento, qualquer um dos sete.

3. Disparar - um HTTP POST para a sua própria URL, assinado com HMAC-SHA256.

O nome do arquivo vem de um modelo. Todos os horários estão em UTC:

Modelo:    {yyyy}/{MM}/{dd}/{subscription}/{id}.zpl
Resultado: 2026/09/09/Outbound/8f3c1e2a9b7d4c0e.zpl

Estão disponíveis {yyyy} {MM} {dd} {HH} {mm} {ss}, {subscription}, {printer}, {key} (a chave da mensagem do barramento) e {id} para um id único por etiqueta.

A notificação e o webhook recebem o mesmo payload:

{
  "schemaVersion": 1,
  "event": "label.printed",
  "utc": "2026-09-09T12:34:56.7890000Z",
  "subscription": "Outbound",
  "printer": "rp:7",
  "storageKey": "zpl/2026/09/09/Outbound/8f3c1e2a.zpl",
  "storageUrl": "https://archive.s3.eu-central-1.amazonaws.com/zpl/2026/09/09/...",
  "zplBytes": 812,
  "zpl": null
}

O ZPL em si só é incluído se você pedir explicitamente. Caso contrário, o campo é null e a URL basta - o que mantém a mensagem pequena.

Para que isso serve

• Regras de retenção. Etiquetas de envio são documentos que precisam ser guardados. Um arquivamento no seu próprio bucket, sob as regras de ciclo de vida do seu provedor, atende a isso sem um segundo sistema.
• Reimpressões sem nova renderização. O que foi impresso uma vez existe byte por byte. Uma reimpressão é o mesmo arquivo, não uma nova renderização.
• Entrega a sistemas posteriores. O webhook informa ao ERP que a caixa 12 foi etiquetada e, ao mesmo tempo, entrega o link para o registro.

Uma falha de armazenamento nunca interrompe a impressão

Armazenar, notificar e o webhook rodam depois da impressão. Se o bucket ficar inacessível por um momento, a etiqueta é impressa mesmo assim; o erro vai como texto para o log da assinatura. O arquivamento não deve travar a operação.

Um destino de saída pode ser testado a qualquer momento com Teste: ele armazena um ZPL de exemplo e dispara a notificação e o webhook sem imprimir nada.