Imprimir ZPL desde S3 o Azure Blob - y archivar allí las etiquetas impresas

El almacenamiento de objetos es donde ya están los archivos de impresión: etiquetas de transportista del proveedor de envíos, lotes prerrenderizados del ERP, archivos históricos que se conservan por normas de retención. Esta guía cubre ambas direcciones: imprimir ZPL desde un bucket y volver a escribir en uno el ZPL impreso.

Todo se aplica a Amazon S3 y Azure Blob Storage. Como la interfaz S3 está estandarizada, también funcionan MinIO, Cloudflare R2, Wasabi, Backblaze B2 y Ceph.

Crear una conexión de almacenamiento

En Streaming → Almacenamiento → Nueva conexión creas la conexión una sola vez. El nombre importa: es la forma en que los mensajes se refieren después a la conexión.

Campo	S3	Azure Blob
Bucket / contenedor	nombre del bucket	nombre del contenedor
Región	p. ej. eu-central-1	no se usa
Endpoint	vacío para AWS; si no, p. ej. https://minio.example.com	no se usa
URLs path-style	actívalo para MinIO y Ceph	no se usa
Prefijo	opcional, p. ej. zpl/	opcional
Credenciales	AccessKey=…;SecretKey=…	cadena de conexión o URL SAS del contenedor

Las credenciales se almacenan cifradas con AES en la base de datos de la plataforma. Nunca vuelven al navegador: el formulario solo muestra que existen credenciales. Con S3 puedes omitirlas por completo; entonces se aplica la cadena de credenciales normal de AWS, por ejemplo el rol IAM del entorno.

Probar verifica que el bucket y los permisos son correctos antes de imprimir nada.

Dirección 1: imprimir ZPL desde el bucket

Un mensaje del bus puede transportar ZPL terminado. Con archivos grandes eso resulta incómodo: muchos brokers limitan el tamaño de los mensajes, y una etiqueta con un gráfico incrustado crece rápidamente. Mejor: el mensaje solo apunta al archivo.

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

storage es el nombre de tu conexión y key la clave del objeto dentro de ella. Se antepone el prefijo configurado: con el prefijo zpl/, el ejemplo anterior queda como zpl/orders/4711.zpl.

El archivo se obtiene en el momento de imprimir, no al recibir el mensaje. El nombre solo se resuelve dentro de tu propio ámbito o del de tu empresa: la conexión de otra persona no puede alcanzarse a través de un mensaje, ni siquiera por alguien que conozca su nombre.

Dirección 2: guardar el ZPL impreso y notificarlo

La dirección inversa se llama destino de salida. Agrupa tres pasos que se ejecutan tras una impresión con éxito, y cada uno se activa por separado:

1. Guardar - el ZPL impreso se escribe como archivo en una conexión de almacenamiento.

2. Notificar - se envía un mensaje a un bus, cualquiera de los siete.

3. Disparar - un HTTP POST a tu propia URL, firmado con HMAC-SHA256.

El nombre del archivo sale de una plantilla. Todas las horas están en UTC:

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

Están disponibles {yyyy} {MM} {dd} {HH} {mm} {ss}, {subscription}, {printer}, {key} (la clave del mensaje del bus) e {id} para un id único por etiqueta.

La notificación y el webhook reciben el mismo 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
}

El ZPL en sí solo se incluye si lo pides explícitamente. En caso contrario el campo es null y basta con la URL - así el mensaje sigue siendo pequeño.

Para qué sirve

• Normas de retención. Las etiquetas de envío son documentos que hay que conservar. Un archivo en tu propio bucket, bajo las reglas de ciclo de vida de tu proveedor, cumple con ello sin un segundo sistema.
• Reimpresiones sin volver a renderizar. Lo que se imprimió una vez existe byte a byte. Una reimpresión es el mismo archivo, no un nuevo renderizado.
• Entrega a sistemas posteriores. El webhook avisa al ERP de que la caja 12 ya está etiquetada y, al mismo tiempo, le entrega el enlace al documento.

Un fallo de almacenamiento nunca detiene la impresión

El almacenamiento, la notificación y el webhook se ejecutan después de la impresión. Si el bucket no está accesible durante un momento, la etiqueta se imprime igualmente; el error queda como texto en el registro de la suscripción. Un archivo no debe frenar la operativa.

Un destino de salida puede probarse en cualquier momento con Probar: guarda un ZPL de ejemplo y lanza la notificación y el webhook sin imprimir nada.