Stampare ZPL da S3 o Azure Blob - e archiviarvi le etichette stampate

Lo storage a oggetti è il posto in cui i file di stampa si trovano già: etichette del corriere fornite dal servizio di spedizione, batch pre-renderizzati dall'ERP, archivi conservati per obblighi di conservazione. Questa guida copre entrambe le direzioni - stampare ZPL da un bucket e riscrivere lo ZPL stampato in un bucket.

Tutto vale per Amazon S3 e Azure Blob Storage. Poiché l'interfaccia S3 è standardizzata, funzionano anche MinIO, Cloudflare R2, Wasabi, Backblaze B2 e Ceph.

Creare una connessione di storage

In Streaming di dati → Archiviazione → Nuova connessione crei la connessione una volta sola. Il nome è importante: è con questo che i messaggi faranno poi riferimento alla connessione.

Campo	S3	Azure Blob
Bucket / contenitore	nome del bucket	nome del contenitore
Regione	p. es. eu-central-1	non usato
Endpoint	vuoto per AWS, altrimenti p. es. https://minio.example.com	non usato
URL path-style	da attivare per MinIO e Ceph	non usato
Prefisso	facoltativo, p. es. zpl/	facoltativo
Credenziali	AccessKey=…;SecretKey=…	stringa di connessione o URL SAS del contenitore

Le credenziali vengono salvate cifrate AES nel database della piattaforma. Non tornano mai al browser - il modulo mostra solo che esistono delle credenziali. Con S3 puoi anche ometterle del tutto: si applica allora la normale catena di credenziali AWS, per esempio il ruolo IAM dell'ambiente.

Test verifica che bucket e permessi siano corretti prima che venga stampato qualcosa.

Direzione 1: stampare ZPL dal bucket

Un messaggio sul bus può contenere ZPL finito. Per file grandi è scomodo - molti broker limitano la dimensione dei messaggi, e un'etichetta con una grafica incorporata diventa grande in fretta. Meglio: il messaggio si limita a puntare al file.

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

storage è il nome della tua connessione, key la chiave dell'oggetto al suo interno. Un prefisso configurato viene anteposto: con il prefisso zpl/ l'esempio sopra diventa zpl/orders/4711.zpl.

Il file viene recuperato al momento della stampa, non alla ricezione. Il nome viene risolto solo nel tuo ambito o in quello della tua azienda - la connessione di qualcun altro non è raggiungibile tramite un messaggio, nemmeno da chi ne conosce il nome.

Direzione 2: archiviare lo ZPL stampato e segnalarlo

La direzione inversa si chiama destinazione di uscita. Raggruppa tre passi che vengono eseguiti dopo una stampa riuscita, e ognuno si attiva separatamente:

1. Archiviare - lo ZPL stampato viene scritto come file in una connessione di storage.

2. Notificare - un messaggio va a un bus, uno qualsiasi dei sette.

3. Attivare - una HTTP POST verso il tuo URL, firmata HMAC-SHA256.

Il nome del file deriva da un modello. Tutti gli orari sono in UTC:

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

Sono disponibili {yyyy} {MM} {dd} {HH} {mm} {ss}, {subscription}, {printer}, {key} (la chiave del messaggio sul bus) e {id} per un id univoco per etichetta.

La notifica e il webhook ricevono lo stesso 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
}

Lo ZPL stesso viene incluso solo se lo richiedi esplicitamente. Altrimenti il campo è null e basta l'URL - così il messaggio resta piccolo.

A cosa serve

• Obblighi di conservazione. Le etichette di spedizione sono documenti da conservare. Un archivio nel tuo bucket, soggetto alle regole di ciclo di vita del tuo provider, soddisfa questo requisito senza un secondo sistema.
• Ristampe senza nuovo rendering. Ciò che è stato stampato una volta esiste byte per byte. Una ristampa è lo stesso file, non un nuovo render.
• Passaggio ai sistemi a valle. Il webhook comunica all'ERP che il cartone 12 è stato etichettato e allo stesso tempo consegna il link al documento.

Un errore di storage non ferma mai la stampa

Archiviazione, notifica e webhook vengono eseguiti tutti dopo la stampa. Se il bucket è brevemente irraggiungibile, l'etichetta viene stampata comunque; l'errore finisce come testo nel log della sottoscrizione. Un archivio non deve bloccare l'operatività.

Una destinazione di uscita può essere provata in qualsiasi momento con Test: archivia uno ZPL di esempio e attiva la notifica e il webhook senza stampare nulla.