Die UPS Shipping API liefert ein Thermoetikett als
base64-ZPL, eines pro Paket, wenn die Anfrage danach verlangt. Verglichen
mit FedEx ist die Anfrage kleiner — ein Bildformat-Code und eine
Stockgröße — und es gibt überhaupt kein Auflösungsfeld, was eine wichtige
Frage (für welche Dichte sind die Punkte geschrieben?) von der Anfrage in
die Datei verschiebt. Diese Seite listet die Felder, den Pfad zum Etikett
in der Antwort und die Prüfungen vor dem Druck. Die Regeln für jedes
Carrier-Etikett stehen in
mit
Carrier-ZPL-Etiketten arbeiten; das FedEx-Gegenstück ist
FedEx-ZPL-Etiketten.
Die Feldnamen und Werte unten wurden am 2026-09-14 aus der
OpenAPI-Spezifikation der UPS Shipping API gelesen, die UPS auf GitHub
veröffentlicht. Sie ändern sich zwischen API-Versionen; prüfen Sie sie
gegen die aktuelle Spezifikation, bevor Sie sich darauf verlassen.
Labelixa ist nicht mit UPS verbunden — dies ist eine
Workflow-Beschreibung, keine Integration.
Die Anfragefelder, die das ZPL formen
Der Aufruf ist POST /shipments/{version}/ship — gegen
wwwcie.ups.com für das Customer Integration Environment und
onlinetools.ups.com für die Produktion. Das Etikett steuert
ShipmentRequest.Shipment.LabelSpecification:
LabelImageFormat.Code — ZPL. Die
Spezifikation nennt GIF, ZPL, EPL
(für EPL2) und SPL; sie merkt an, dass Sendungen mit
Print-Return-Label-Service dieselben vier akzeptieren und dass UPS
Premier Silver-Sendungen nur ZPL unterstützen.
LabelStockSize.Height und Width — ganze
Zoll, für Thermoformate erforderlich. Breite ist 4; Höhe ist
6 oder 8. Die Spezifikation ergänzt einen
Hinweis, der zweimal gelesen werden sollte: Das Etikettenbild skaliert
nur bis 4×6, auch wenn 4×8 angefordert wird.
CharacterSet — der auf dem Etikett erwartete
Sprachzeichensatz als Drei-Buchstaben-Code: eng (Latin-1,
Standard), deu und fra (Latin-1),
tur (Latin-5), pol (Latin-2), rus
(Kyrillisch) und weitere. Er verändert die zurückgegebenen Bytes, was
unten wichtig wird.
HTTPUserAgent — nur für GIF-Ausgabe relevant; für ZPL
ignorieren.
Es gibt kein Auflösungsfeld. Die Spezifikation sagt nicht, für welche
Dichte das ZPL geschrieben ist — also keine annehmen, sondern aus der
Datei lesen (unten).
Wo das Etikett in der Antwort steckt
Der Pfad ist
ShipmentResponse.ShipmentResults.PackageResults[] — ein
Eintrag pro Paket, jeder mit seiner TrackingNumber und einem
ShippingLabel-Objekt, dessen GraphicImage das
base64-Etikett ist und dessen ImageFormat.Code das
tatsächlich gelieferte Format bestätigt. Die Spezifikation merkt an, dass
Package-Results ab Version v2403 immer ein Array sind,
während ältere Versionen bei einem einzelnen Paket ein nacktes Objekt
liefern — ein klassischer Grund für „geht mit einem Paket, bricht mit
zwei“.
Zwei weitere Felder zählen für Thermoausgabe.
InternationalSignatureGraphicImage wird für Sendungen
außerhalb der USA in EPL2, ZPL und SPL geliefert — ein Bild pro Sendung,
im ersten Package-Result — und ist ein zweites zu druckendes Etikett,
kein Anhang zum Ignorieren. HTMLImage kommt nur bei GIF und
PNG; sein Fehlen bei ZPL ist normal. Die Spezifikation merkt außerdem an,
dass bei mehrteiligen COD-Sendungen das Etikett des ersten Pakets immer
GIF ist, egal welches Format angefordert wurde — pro Paket
ImageFormat.Code lesen statt annehmen.
Dichte finden, dann prüfen
Weil die Anfrage keine Auflösung trägt, ist die einzige verlässliche
Quelle die Datei. Der Größen- und
DPI-Analyzer liest die deklarierte Breite und Länge aus dem ZPL und
meldet die Dichte, bei der daraus ein 4×6- (oder 4×8-)Etikett wird;
deklariert die Datei sie nicht, sagt er das, statt zu raten. Dann in
dieser Dichte und mit diesem Stock prüfen:
curl -X POST "https://api.labelixa.com/v1/printers/8dpmm/labels/4x6/0" --data-binary @label.zpl --output label.png
Lassen Sie die dekodierten Bytes exakt so, wie sie sind. Haben Sie
einen anderen Zeichensatz als den Standard angefordert, folgen die
Etikettenbytes dieser Kodierung; die Datei als UTF-8 zu dekodieren und
neu zu kodieren kann jedes Umlaut- oder türkische Zeichen ersetzen oder
verwerfen, und die Vorschau zeigt genau diesen Schaden. Geben Sie die
rohen Bytes an die Vorschau und unverändert an den Drucker.
Prüfungen, die sich vor dem Druck lohnen
Ein Etikett pro Paket, alle davon. Über jedes
Package-Result iterieren; ein Test mit einem Paket prüft die Schleife
nicht.
Format ist das angeforderte.ImageFormat.Code lesen; ein GIF, das in eine ZPL-Warteschlange
rutscht, lässt einen Drucker Müll oder nichts drucken.
Internationales Signaturbild ebenfalls gedruckt,
falls vorhanden.
Keine Befunde der Stufe „error“. Diagnose für jede
dekodierte Datei; nur sauber in die Warteschlange.
Nichts bearbeitet. Tracking-Barcode, Routing-Block
und Service-Markierungen bleiben wie erzeugt; eigene Daten kommen auf ein
separates Etikett.
curl -X POST "https://api.labelixa.com/v1/diagnostics?dpmm=8&w=4&h=6" --data-binary @label.zpl
Dasselbe Gate läuft aus Shell oder CI als
npx labelixa validate label.zpl und beendet sich bei
Befunden der Stufe „error“ mit einem Code ungleich null.
Fehler, die nach UPS aussehen, es aber nicht sind
4×8 angefordert, das Layout ist 4×6. Erwartet: Die
Spezifikation sagt, das Bild skaliert nur bis 4×6. Die Datei in der
tatsächlich eingelegten Länge prüfen.
Etikett druckt zu klein oder läuft über.
Dichte-Mismatch zwischen Datei und Drucker; der Analyzer nennt die Dichte
der Datei, und korrigiert wird der Drucker, nicht die Datei.
Umlaute oder türkische Buchstaben drucken als
Fragezeichen. Die Bytes wurden unterwegs neu kodiert, oder das
Etikett wurde mit dem Standard-Zeichensatz angefordert.
CharacterSet in der Anfrage prüfen und die Nutzlast binär
halten.
Geht mit einem Paket, bricht mit zwei. Die
Package-Results wurden zum Array. Beide Formen behandeln oder auf eine
Version ab v2403 wechseln.
Nur das Etikett des ersten Pakets sieht anders aus.
Mehrteiliges COD: Das erste Etikett ist per Design GIF. Es auf einen
Bildpfad statt in die Thermo-Warteschlange leiten.
Häufig gestellte Fragen
Wie fordere ich ein ZPL-Etikett bei der UPS Shipping API an?
LabelSpecification.LabelImageFormat.Code auf ZPL setzen und LabelStockSize mit Width 4 und Height 6 (oder 8) in ganzen Zoll angeben. Die Spezifikation merkt an, dass das Bild nur bis 4×6 skaliert, auch wenn 4×8 angefordert wird.
Wo steckt das ZPL in der UPS-Antwort?
ShipmentResponse.ShipmentResults.PackageResults[].ShippingLabel.GraphicImage, base64-kodiert, ein Eintrag pro Paket; ImageFormat.Code bestätigt das Format. Ab v2403 sind die Package-Results immer ein Array.
Sagt die UPS-Anfrage, für welche dpi das ZPL geschrieben ist?
Nein — die Spezifikation hat kein Auflösungsfeld. Die Dichte mit dem Größen- und DPI-Analyzer aus der Datei lesen, dann in dieser Dichte prüfen und drucken.
