FedEx-ZPL-Etiketten: anfordern, prüfen, fixen

Veröffentlicht: 2026-09-14

Druckerauflösung

Ergebnis

Fordern Sie bei der FedEx Ship API ein Thermoetikett an, kommt ZPL zurück — base64-kodiert im JSON der Sendungsantwort. Welches ZPL Sie bekommen — Etikettengröße, ob ein Doc-Tab dranhängt und vor allem für welche Druckdichte die Punkte geschrieben sind — entscheidet eine Handvoll Anfragefelder. Diese Seite listet die Felder, zeigt, wo das Etikett in der Antwort steckt, und geht die Prüfungen durch, die sich lohnen, bevor die Datei einen Drucker erreicht. Die Regeln, die für jedes Carrier-Etikett gelten (nicht bearbeiten, eigene Daten separat drucken), stehen in mit Carrier-ZPL-Etiketten arbeiten; diese Seite ist die FedEx-spezifische Schicht darüber. Das UPS-Gegenstück: UPS-ZPL-Etiketten.

Die Feldnamen und Werte unten wurden am 2026-09-14 aus der von FedEx veröffentlichten Ship-API-Referenz gelesen. Sie ändern sich zwischen API-Versionen; prüfen Sie sie gegen die aktuelle Referenz, bevor Sie sich darauf verlassen. Labelixa ist nicht mit FedEx verbunden — dies ist eine Workflow-Beschreibung, keine Integration.

Die Anfragefelder, die das ZPL formen

Alles Relevante steckt in labelSpecification innerhalb der angeforderten Sendung eines POST /ship/v1/shipments-Aufrufs:

imageType — ZPLII für einen Zebra-Datenstrom. Die anderen Werte sind EPL2, PDF und PNG; nur die ersten beiden sind Thermoformate.
labelFormatType — COMMON2D liefert ein vollständiges Etikett. LABEL_DATA_ONLY liefert Barcodedaten für ein selbst gezeichnetes Etikett und ist ein anderer Workflow.
labelStockType — STOCK_4X6 für einfaches 4×6-Zoll-Material. Die Doc-Tab-Varianten (STOCK_4X675_LEADING_DOC_TAB, STOCK_4X675_TRAILING_DOC_TAB, STOCK_4X9_LEADING_DOC_TAB, STOCK_4X9_TRAILING_DOC_TAB, STOCK_4X85_TRAILING_DOC_TAB, STOCK_4X105_TRAILING_DOC_TAB) und die langen einfachen Stocks (STOCK_4X8, STOCK_4X9) sind physisch länger als 6 Zoll — das zurückgegebene Etikett ist für diese Länge geschrieben.
resolution — 203 oder 300. Laut Referenz ist 203 der Standard, und 300 ist nur mit ZPLII erlaubt. Dieses eine Feld entscheidet, wie jede Koordinate in der Datei zu lesen ist.
Optional: labelRotation (NONE, LEFT, RIGHT, UPSIDE_DOWN) und labelPrintingOrientation (TOP_EDGE_OF_TEXT_FIRST, BOTTOM_EDGE_OF_TEXT_FIRST) gelten für Thermoausgabe auf Rollenmaterial; labelOrder setzt das Versandetikett an den Anfang oder das Ende, wenn mehrere Dokumente erzeugt werden.

"labelSpecification": {
  "labelFormatType": "COMMON2D",
  "imageType": "ZPLII",
  "labelStockType": "STOCK_4X6",
  "resolution": 203
}

Wo das Etikett in der Antwort steckt

Das Etikett liegt nicht auf oberster Ebene. Der Pfad ist output.transactionShipments[].pieceResponses[].packageDocuments[]: eine Piece-Response pro Paket, darin ein oder mehrere Package-Documents, jedes mit encodedLabel (der base64-Nutzlast) neben docType, contentType, trackingNumber und copiesToPrint. Ein url-Feld kann das Dokument begleiten; wer encodedLabel selbst dekodiert, behält das ZPL unter Kontrolle.

jq -r '.output.transactionShipments[0].pieceResponses[0].packageDocuments[0].encodedLabel'    response.json | base64 -d > label.zpl
grep -c '\^XA' label.zpl     # Anzahl der Etikettenformate im Puffer

Zählen Sie die Formate. Die Referenz merkt an, dass alle für eine Sendung nötigen Etiketten in einem einzigen Puffer erzeugt und zurückgegeben werden — ein dekodiertes Dokument kann also mehr als einen ^XA … ^XZ-Block enthalten, etwa ein Service-Etikett nach dem Versandetikett. Ein Drucker druckt alle; der Vorschau-Endpunkt liefert pro Index ein Format oder ohne Index alle als PDF.

In der angeforderten Dichte prüfen

ZPL hat keinen Auflösungs-Header: Die Punkte in der Datei werden mit der Dichte des Druckers gelesen. Eine mit resolution: 300 angeforderte Datei sieht bei 8 Punkten/mm etwa anderthalbmal zu groß aus und läuft über das Etikett hinaus; dieselbe Datei ist bei 12 Punkten/mm korrekt. Passen Sie die Vorschau der Anfrage an — 8dpmm für 203, 12dpmm für 300 — und geben Sie die angeforderte Stocklänge an (6, 6.75, 8, 9 …).

curl -X POST "https://api.labelixa.com/v1/printers/8dpmm/labels/4x6/0"      --data-binary @label.zpl --output label-0.png
curl -X POST "https://api.labelixa.com/v1/printers/8dpmm/labels/4x6/1"      --data-binary @label.zpl --output label-1.png   # zweites Format, falls vorhanden

Wenn Sie nicht mehr wissen, für welche Auflösung eine gespeicherte Datei erzeugt wurde, liest der Größen- und DPI-Analyzer die deklarierte Breite und Länge aus der Datei und meldet die Dichte, bei der daraus ein Standard-Etikettenmaß wird — oder sagt, dass er es nicht bestimmen kann.

Prüfungen, die sich vor dem Druck lohnen

Dichte passt zum Drucker. Die Referenz gibt dem FedEx-1D-Barcode eine X-Dimension von 3 Punkten bei 203 dpi und 4 Punkten bei 300 dpi. Schicken Sie eine 203-dpi-Datei an einen 300-dpi-Kopf, schrumpfen diese 3-Punkt-Balken auf zwei Drittel der vorgesehenen Breite — das Etikett sieht auf Armlänge gut aus und fällt am Scanner durch.
Stock passt zum Material. Ein Doc-Tab-Stock ist 6,75 Zoll oder länger; auf einfachem 6-Zoll-Material landet der Tab auf dem nächsten Etikett oder wird abgeschnitten. In der angeforderten Länge prüfen und mit dem tatsächlich eingelegten Material vergleichen.
Keine Befunde der Stufe „error“. Die Datei durch die Diagnose laufen lassen und nur ohne Fehler in die Warteschlange stellen; Warnungen sind es wert, protokolliert zu werden.
Nichts bearbeitet. Tracking-Barcode, Routing-Block und Service-Markierungen müssen den Drucker so erreichen, wie sie erzeugt wurden. Eigene Daten kommen auf ein separates Etikett, nicht durch Bearbeiten des FedEx-Formats.

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. Die Referenz nennt außerdem die Thermodrucker, die FedEx für die API empfiehlt — unter den ZPL-Modellen GK420, ZT410 und weitere Drucker der ZT4xx-Serie — ein nützlicher Plausibilitätscheck bei einer gemischten Lagerflotte.

Fehler, die nach FedEx aussehen, es aber nicht sind

Etikett druckt auf zwei Drittel der Größe mit breitem Rand. Die Datei wurde für 203 dpi erzeugt und auf einem 300-dpi-Kopf gedruckt (oder umgekehrt: sie läuft über und wird beschnitten). Korrigieren Sie resolution in der Anfrage oder den Drucker, nicht die Datei.
Ein zusätzliches, fast leeres Etikett nach jeder Sendung. Ein Doc-Tab- oder 8/9-Zoll-Stock wurde angefordert und das Material ist 6 Zoll; oder der Puffer enthielt ein zweites, nicht erwartetes Format. Die Formatzählung oben sagt, was von beidem.
Ausgabe ist gedreht. Papier mit Vorschau vergleichen. Ist auch die Vorschau gedreht, war es labelRotation oder die Orientierung in der Anfrage; ist nur das Papier gedreht, ist die Orientierungseinstellung des Druckers die Ursache — siehe Etikett druckt auf dem Kopf.
Nur das Versandetikett wurde gedruckt. Sendungen mit mehreren Paketen liefern pro Paket eine Piece-Response; über alle iterieren und über jedes Package-Document darin.

Häufig gestellte Fragen

Welches FedEx-Anfragefeld bestimmt die Dichte des ZPL?

labelSpecification.resolution — 203 oder 300. Die Referenz nennt 203 als Standard und erlaubt 300 nur mit imageType ZPLII. Vorschau bei 8 Punkten/mm für 203 und 12 Punkten/mm für 300.

Wo steckt das ZPL in der FedEx-Sendungsantwort?

In output.transactionShipments[].pieceResponses[].packageDocuments[].encodedLabel, base64-kodiert, eine Piece-Response pro Paket. Ein dekodiertes Dokument kann mehr als ein ^XA…^XZ-Format enthalten, weil alle Etiketten einer Sendung in einem Puffer zurückkommen.

Warum druckt das FedEx-Etikett auf zwei Drittel der Größe?

Die Datei wurde für 203 dpi erzeugt und auf einem 300-dpi-Kopf gedruckt (oder in der falschen Dichte geprüft). resolution in der Anfrage ändern oder einen passenden Drucker verwenden; die Datei nicht bearbeiten.