Integration

ZPL aus S3 oder Azure Blob drucken - und gedruckte Etiketten dort archivieren

Objektspeicher ist der Ort, an dem Druckdateien ohnehin schon liegen: Carrier-Labels vom Versanddienstleister, vorgerenderte Chargen aus dem ERP, Archive für…

Objektspeicher ist der Ort, an dem Druckdateien ohnehin schon liegen: Carrier-Labels vom Versanddienstleister, vorgerenderte Chargen aus dem ERP, Archive für die Aufbewahrungspflicht. Dieser Guide zeigt beide Richtungen - ZPL aus dem Bucket drucken und gedrucktes ZPL wieder dort ablegen.

Alles gilt für Amazon S3 und Azure Blob Storage. Weil der S3-Zugang standardisiert ist, funktionieren auch MinIO, Cloudflare R2, Wasabi, Backblaze B2 und Ceph.

Storage-Verbindung anlegen

Unter Streaming → Speicher → Neue Verbindung legst du die Verbindung einmal an. Der Name ist wichtig: mit ihm sprechen Nachrichten die Verbindung später an.

Feld	S3	Azure Blob
Bucket / Container	Bucket-Name	Container-Name
Region	z. B. `eu-central-1`	entfällt
Endpunkt	leer für AWS, sonst z. B. `https://minio.example.com`	entfällt
Path-Style	für MinIO und Ceph einschalten	entfällt
Präfix	optional, z. B. `zpl/`	optional
Zugangsdaten	`AccessKey=…;SecretKey=…`	Connection-String oder Container-SAS-URL

Die Zugangsdaten liegen AES-verschlüsselt in der Plattform-Datenbank. Sie kommen nie wieder an den Browser zurück - im Formular siehst du nur, dass welche hinterlegt sind. Bei S3 kannst du sie auch ganz weglassen: dann greift die normale AWS-Credential-Kette, also etwa die IAM-Rolle der Umgebung.

Mit Test prüfst du, ob Bucket und Rechte stimmen, bevor irgendetwas gedruckt wird.

Richtung 1: ZPL aus dem Bucket drucken

Eine Bus-Nachricht kann fertiges ZPL tragen. Bei großen Dateien ist das unpraktisch - viele Broker begrenzen die Nachrichtengröße, und ein Etikett mit eingebetteter Grafik wird schnell groß. Besser: die Nachricht verweist nur darauf.

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

storage ist der Name deiner Verbindung, key der Objekt-Schlüssel darin. Ein eingestelltes Präfix wird vorangestellt: mit Präfix zpl/ liest das Beispiel oben zpl/auftraege/4711.zpl.

Geholt wird die Datei erst beim Druck, nicht beim Empfang. Der Name wird nur im eigenen bzw. Firmen-Bereich aufgelöst - eine fremde Verbindung ist über eine Nachricht nicht erreichbar, selbst wenn jemand ihren Namen kennt.

Richtung 2: gedrucktes ZPL ablegen und melden

Die Gegenrichtung heißt Ausgabeziel. Es bündelt drei Schritte, die nach einem erfolgreichen Druck laufen, und jeder ist einzeln zuschaltbar:

1. Ablegen - das gedruckte ZPL wandert als Datei in eine Storage-Verbindung.

2. Melden - eine Nachricht geht an einen Bus, egal welchen der sieben.

3. Anstoßen - ein HTTP-POST an deine eigene URL, HMAC-SHA256-signiert.

Den Dateinamen bestimmst du über eine Vorlage. Alle Zeitangaben sind UTC:

Vorlage:  {yyyy}/{MM}/{dd}/{subscription}/{id}.zpl
Ergebnis: 2026/09/09/Warenausgang/8f3c1e2a9b7d4c0e.zpl

Verfügbar sind {yyyy} {MM} {dd} {HH} {mm} {ss}, {subscription}, {printer}, {key} (der Schlüssel der Bus-Nachricht) und {id} für eine eindeutige ID je Etikett.

Meldung und Webhook bekommen dieselbe Nutzlast:

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

Das ZPL selbst steckt nur dann drin, wenn du es ausdrücklich anforderst. Sonst steht dort null und die URL genügt - das hält die Nachricht klein.

Wofür das gut ist

Aufbewahrungspflicht. Versandetiketten sind Belege. Ein Archiv im eigenen Bucket, mit den Lebenszyklus-Regeln deines Anbieters, erfüllt das ohne Zusatzsystem.
Nachdruck ohne Neuberechnung. Was einmal gedruckt wurde, liegt byteweise vor. Ein Nachdruck ist dieselbe Datei, kein neuer Rendervorgang.
Übergabe an nachgelagerte Systeme. Der Webhook sagt dem ERP, dass Karton 12 etikettiert ist, und liefert den Link auf den Beleg gleich mit.

Ein Fehler in der Ablage stoppt nie den Druck

Ablegen, Melden und Webhook laufen nach dem Druck. Wenn der Bucket kurz nicht erreichbar ist, ist das Etikett trotzdem gedruckt; der Fehler landet als Text im Protokoll der Subscription. Ein Archiv soll den Betrieb nicht aufhalten.

Ausprobieren lässt sich ein Ausgabeziel jederzeit über Test: es legt ein Beispiel-ZPL ab und löst Meldung und Webhook aus, ohne irgendetwas zu drucken.