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.
Carrier-spezifische Anfragefelder und Antwortpfade — welcher Wert ZPL
anfordert, wo die base64-Nutzlast steckt, was die Dichte bestimmt — stehen
auf den Seiten FedEx
und UPS.
Häufig gestellte Fragen
Warum kommt das FedEx- oder UPS-Etikett als Text statt als Bild zurück?
Weil Sie ein Thermoformat angefordert haben: Die Antwort enthält ZPL, meist base64-kodiert. Dekodiert beginnt es mit ^XA. Das ist ein Vorteil — Text lässt sich rendern und prüfen, bevor ein einziges Etikett gedruckt wird.
Darf ich das ZPL des Carriers bearbeiten, um eigene Angaben zu ergänzen?
Verändern Sie das Format des Carriers nicht: Tracking-Barcode, Routing-Block und Service-Markierungen sind Compliance-Inhalt und müssen unverändert am Drucker ankommen. Eigene Daten — SSCC, Lagerplatz — drucken Sie als separates Etikett.
Das Etikett druckt zu klein mit breitem Rand. Ist die Datei defekt?
Meist nicht. Carrier-ZPL ist in Punkten für eine Dichte geschrieben; ein für 203 dpi erzeugtes Etikett druckt auf einem 300-dpi-Kopf etwa in Zweidrittelgröße. Prüfen Sie die angenommene Dichte mit dem Größen- und DPI-Analyzer und drucken Sie auf einem passenden Kopf oder konvertieren Sie die Datei.
Wie prüfe ich ein Carrier-Etikett vor dem Druck?
Dekodieren, durch die Diagnose laufen lassen (API-Endpunkt oder `npx labelixa validate`) und nur ohne Befunde der Stufe error in die Warteschlange stellen. Warnungen auch dann protokollieren — sie erklären spätere Scan-Probleme.
