Ratgeber › Mit Carrier-ZPL-Etiketten arbeiten

Mit Carrier-ZPL-Etiketten arbeiten

Veröffentlicht: 2026-08-27

Wenn Sie bei FedEx oder UPS ein Thermoetikett anfordern, kommt kein Bild zurück, sondern ZPL — meist base64-kodiert in einer JSON-Antwort. Das ist eine gute Nachricht: Text lässt sich prüfen, rendern und diagnostizieren, bevor ein einziges Etikett verbrannt wird. Und es heißt, dass eine ganze Klasse von "das Etikett druckt falsch"- Tickets auf der Integrationsebene lösbar ist statt am Drucker.

Zuerst dekodieren, nicht drucken

Das Etikettenfeld einer Carrier-Antwort ist typischerweise base64. Dekodiert erhalten Sie reines ZPL, das mit ^XA beginnt. Schreiben Sie es in eine Datei, bevor Sie es weiterschicken — die Datei ist Ihr Beweismittel, wenn etwas schiefgeht, und kostet nichts.

base64 -d label.b64 > label.zpl
head -c 200 label.zpl        # muss mit ^XA beginnen

Beginnt der dekodierte Text nicht mit ^XA, haben Sie ein anderes Format angefordert (PNG, PDF, EPL) oder das gelesene Feld ist nicht die Etikettennutzlast. Prüfen Sie die genauen Feldnamen in der AKTUELLEN API-Referenz des Carriers — sie unterscheiden sich zwischen FedEx und UPS und ändern sich über API-Versionen; ein aus einem Blog kopierter Wert ist eine häufige Quelle verlorener Stunden.

Was Sie nicht ändern dürfen

Ein Carrier-Etikett ist ein Compliance-Dokument. Barcodeinhalt, Routing-Block und Servicekennzeichen erzeugt der Carrier, und sie müssen UNVERÄNDERT beim Drucker ankommen: Wer den Tracking-Barcode oder den Routing-Code anfasst, kann das Paket im Netz des Carriers unlesbar machen — und dieser Fehler zeigt sich Tage später im Verteilzentrum, nicht in Ihren Tests.

Eigene Informationen hinzuzufügen ist etwas anderes. Drucken Sie sie als separates Etikett — interne SSCC, Kommissioniercode, Lagerplatz — statt das Carrier-Format zu bearbeiten. Zwei Etiketten, die jeweils gültig bleiben, sind besser als eines, für das niemand Verantwortung übernimmt.

Die Auflösungsfalle

Carrier-Etiketten sind fast immer 4×6 Zoll, und das ZPL ist in Punkten für eine bestimmte Dichte geschrieben. Ein für 203 dpi erzeugtes Etikett druckt auf 300 dpi bei etwa zwei Dritteln mit breitem Rand; umgekehrt läuft es über und wird beschnitten. Nichts an der Datei ist "falsch" — die Punkte bedeuten auf beiden Köpfen einfach unterschiedliche physische Abstände.

Klären Sie die angenommene Dichte, bevor Sie dem Drucker die Schuld geben: Der Größen- und DPI-Analyzer liest die deklarierten Maße aus der Datei und nennt die Dichte, die daraus eine Standardgröße macht — oder sagt klar, dass er es nicht bestimmen kann.

Ein Prüftor, das sich bezahlt macht

Weil das Etikett Text ist, können Sie es in demselben Codepfad prüfen, der es empfängt. Ein minimales Tor sieht so aus: Etikett anfordern, dekodieren, Diagnose laufen lassen und erst bei null Fehlern zum Druck einreihen. Befunde der Stufe "error" bedeuten, dass das Etikett nicht wie beabsichtigt rendert; Warnungen lohnt es zu protokollieren, auch wenn Sie weitermachen.

curl -X POST "https://api.labelixa.com/v1/diagnostics?dpmm=8&w=4&h=6"      --data-binary @label.zpl

Dieselbe Prüfung gibt es als Kommandozeilenschritt für CI oder einen Versand-Worker (npx labelixa validate label.zpl endet mit Exit-Code ungleich null, wenn das Etikett Fehler trägt) und als Browser-Einfügen im ZPL-Viewer, wenn Sie ein einzelnes Paket untersuchen.

Fehler, die nach Carrier aussehen, aber keine sind

Ein leeres Etikett nach jeder Sendung. Meist passt die Etikettenlänge nicht zum Material, oder eine Kopienzahl hat sich eingeschlichen — der Mechanismus steht in zusätzliches leeres Etikett.
Der untere Teil fehlt. Material schmaler oder kürzer als deklariert; siehe Etikett abgeschnitten.
Alles druckt gedreht. Die Druckausrichtung wirkt im Drucker, deshalb sieht die Vorschau aufrecht aus und das Papier nicht — druckt auf dem Kopf erklärt die drei Schalter.

Nichts davon braucht den Carrier-Support. Alle drei sind in der Datei sichtbar — genau deshalb lohnen sich die zwei zusätzlichen Codezeilen zum Dekodieren vor dem Druck.