ZPL-Tools-API: ZPL zu PDF, PNG & Konverter

Überblick

POST https://api.zplcloud.com/v1/tools/{slug}

JSON-Body in camelCase. API-Key über X-API-Key oder Basic Auth; Authentifizierung, Fehler und Request-IDs beschreibt die API-Übersicht.
Gleiche Logik wie die Website-Tools unter /de/tools/{slug}, aber ohne Rate-Limits (einzige Ausnahme: pdf-to-native-zpl mit eigenem Seitenlimit je Tarif) und mit größeren Eingabegrenzen. Antworten und Fehlermeldungen sind immer Englisch.
Binäre Eingaben (PDF, PNG, andere Bilder) sind Base64-Strings; Data-URIs wie data:image/png;base64,… werden akzeptiert.
dpi ist bei allen Tools außer dem DPI-Rechner und den Druckersprachen-Tools (dort die Auflösungen ihrer Druckköpfe) 152, 203, 300 oder 600 (Standard 203).
Fehler: { "error": "…", "tool": "<slug>", "requestId": "…" }, meist 400; 413 bei zu großer Eingabe.
Webhook: Jedes Tool akzeptiert webhookId und webhookResult. Event api.tool.completed, summary.tool ist der Slug plus tool-spezifische Werte; mit webhookResult=true kommen Dateien als Base64, SVG als UTF-8-Text und JSON-Antworten als JSON mit (Payload).

Tool	Eingabe	Antwort	Renders
`zpl-to-pdf`	ZPL	application/pdf	1 je Etikett
`zpl-to-png`	ZPL	image/png	1
`zpl-to-jpg`	ZPL	image/jpeg	1
`zpl-to-svg`	ZPL	image/svg+xml	1
`zpl-linter`	ZPL	JSON-Befunde	1
`zpl-analyser`	ZPL	JSON-Analyse	1
`zpl-dpi-converter`	ZPL	JSON `zpl` + Engine-Prüfung	1
`zpl-formatter`	ZPL	JSON `zpl` + Pixelprüfung	1 je geprüftem Etikett
`zpl-diff`	2 × ZPL	JSON-Diff + Overlay-PNG oder image/png	2 je Etikett
`label-compliance-check`	ZPL + Regelpakete	JSON-Befunde oder SARIF	1 je Etikett
`barcode-scan-proof`	ZPL	JSON-Bericht je Barcode	2 je Etikett
`rfid-encode`	GS1-Schlüssel oder Elementfolge	JSON-EPC, Bitfelder, ZPL-Befehle + Etikett	1
`rfid-decode`	EPC als Hex oder EPC-URI	JSON-EPC-Felder	1
`rfid-check`	ZPL	JSON-RFID-Regeln + Tag-Simulation	1
`check-barcode`	Foto/Scan oder Daten	JSON-Befunde	1
`html-to-zpl`	PNG des HTML	JSON `zpl`	1
`pdf-to-zpl`	PDF	JSON `zpl`	1 je Seite
`pdf-to-native-zpl`	PDF oder SVG	JSON `zpl` + Treue	5 je Seite
`image-to-zpl`	PNG, JPG, GIF, BMP	JSON `zpl`, `grf`	1
`svg-to-zpl`	SVG-Markup	JSON `zpl`	1
`epl2-to-zpl`	EPL2-Code	JSON `zpl`	1
`dpl-to-zpl`	DPL-Code	JSON `zpl`	1
`tspl-to-zpl`	TSPL-Code	JSON `zpl`	1
`zpl-to-tspl`	ZPL	roher Druckauftrag	1 je Etikett
`zpl-to-epl2`	ZPL	roher Druckauftrag	1 je Etikett
`zpl-to-dpl`	ZPL	roher Druckauftrag	1 je Etikett
`zpl-to-sbpl`	ZPL	roher Druckauftrag	1 je Etikett
`zpl-to-cpcl`	ZPL	roher Druckauftrag	1 je Etikett
`zpl-to-escpos`	ZPL	roher Druckauftrag	1 je Etikett
`zpl-to-brother`	ZPL	roher Druckauftrag	1 je Etikett
`zpl-to-pcl`	ZPL	roher Druckauftrag	1 je Etikett
`zpl-to-easyplug`	ZPL	roher Druckauftrag	1 je Etikett
`zpl-to-tpcl`	ZPL	roher Druckauftrag	1 je Etikett
`zpl-to-jscript`	ZPL	roher Druckauftrag	1 je Etikett
`barcode-to-zpl`	Symbologie + Daten	JSON `zpl`	1
`qr-code-to-zpl`	QR-Typ + Felder	JSON `zpl`	1
`gs1-ai-128-to-zpl`	GS1-AIs	JSON `zpl`	1
`gs1-ai-datamatrix-to-zpl`	GS1-AIs	JSON `zpl`	1
`gs1-ai-qr-code-to-zpl`	GS1-AIs	JSON `zpl`	1
`gs1-ai-databar-to-zpl`	GS1-AIs	JSON `zpl`	1
`sunrise-2027-migration`	ZPL	JSON `migratedZpl` + Prüfung	1 je Etikett
`dpi-calculator`	Werte	JSON-Umrechnungen	1

Dateien senden - ZPL oder Code als JSON-String, Binärdateien als Base64:

# Textdatei (ZPL, SVG, EPL2 …) als JSON-String
jq -Rs '{zpl: ., dpi: 203}' label.zpl \
  | curl -X POST https://api.zplcloud.com/v1/tools/zpl-to-pdf \
      -H "X-API-Key: sk_zplcloud_…" -H "Content-Type: application/json" \
      --data-binary @- -o label.pdf

# Binärdatei als Base64 (GNU base64; unter macOS: base64 -i datei.pdf)
base64 -w0 label.pdf | jq -Rs '{pdfBase64: ., pages: "all"}' \
  | curl -X POST https://api.zplcloud.com/v1/tools/pdf-to-zpl \
      -H "X-API-Key: sk_zplcloud_…" -H "Content-Type: application/json" \
      --data-binary @- | jq -r .zpl > label.zpl

Render-Zählung

Die Tools werden vom monatlichen Label-Kontingent nie blockiert (kein 429), aber jeder erfolgreiche Aufruf zählt als Render in der Nutzung des Kontos und in der API-Statistik im Dashboard:

Tool	Renders
`zpl-to-pdf`	einer je Etikett (`^XA…^XZ`-Block)
`pdf-to-zpl`	einer je konvertierter Seite
`label-compliance-check`	1 je geprüftem Etikett
`barcode-scan-proof`	2 je geprüftem Etikett (jeder Barcode wird mit zwei Decodern gelesen)
`rfid-encode`, `rfid-decode`, `rfid-check`	1 je Aufruf (rfid-check: je Aufruf, nicht je Etikett)
`sunrise-2027-migration`	1 je Etikett
`pdf-to-native-zpl`	5 je umgewandelter Seite (vorläufiger Wert, wird anhand der im Betrieb gemessenen Rechenzeit kalibriert)
`zpl-to-tspl`, `zpl-to-epl2` … (Druckersprachen)	einer je Etikett
alle anderen Tools	einer je Aufruf
fehlgeschlagene Aufrufe (HTTP 400 und höher)	keiner

Die vier zplCore-Tools (label-compliance-check, barcode-scan-proof, sunrise-2027-migration, pdf-to-native-zpl) schreiben die gezählten Renders zusätzlich in den Header X-ZplCloud-Renders und in summary.renders des Webhooks. Die Gewichtung steht auch auf der Preisseite.

Tarife und Zählung: API-Übersicht → Kontingent.

Eingabegrenzen

Schutz vor Überlast, unabhängig vom Tarif:

Eingabe	Grenze
ZPL, EPL2-/DPL-/TSPL-Code, SVG	2.000.000 Zeichen (413)
Bilder (PNG, JPG, GIF, BMP)	20 MB (413) und 16 Megapixel
PDF	50 MB (413), 100 Seiten je Aufruf
Labelgröße	400 × 400 mm
ZPL zu Druckersprachen	1.000 Etiketten und 256 MB unkomprimierte Bilddaten je Aufruf
Request-Body	rund 4 MB bei Text-Tools; 72 MB bei html-to-zpl, pdf-to-zpl, image-to-zpl und check-barcode
Barcode-Daten	128 Zeichen (linear), 4.096 (QRCode, DataMatrix, Pdf417, AztecCode, MaxiCode); GS1-AI-String 4.096
pdf-to-native-zpl	PDF 20 MB (413), Seiten 1–100, Seiten je Aufruf nach Tarif (Limits), SVG 2.000.000 Zeichen; isolierter Worker-Prozess mit Zeit- und Speichergrenze je Seite, 503 mit `Retry-After`, wenn alle Worker belegt sind
label-compliance-check	50 Etiketten je Aufruf in jedem Tarif; mehr ist eine Batch-Prüfung (nur Pro, bis 1.000 Etiketten je Aufruf, sonst 403); annotierte Bilder für höchstens 10 Etiketten
barcode-scan-proof, sunrise-2027-migration	50 Etiketten je Aufruf, Scan-Proof höchstens 500 Barcode-Befehle, annotierte Bilder für höchstens 10 Etiketten
rfid-encode, rfid-decode, rfid-check	Einzelfelder 40 Zeichen, elementString 300, Lesen 400; rfid-check 50 Etiketten je Aufruf, bis zu 10 Versuche je Etikett (`^RS n`), annotierte Bilder für höchstens 10 Etiketten
QR-Feldwert / check-barcode-Daten	je 2.000 Zeichen

Aus ZPL

ZPL zu PDF

POST /v1/tools/zpl-to-pdf · Website-Tool. Rendert rohes ZPL als PDF: eine Seite je ^XA…^XZ-Etikett oder Etiketten in Originalgröße auf A4-/Letter-Bögen für Bürodrucker.

Feld	Typ	Standard	Hinweise
`zpl`	string	Pflicht	Ein oder mehrere Etiketten, max. 2.000.000 Zeichen.
`dpi`	int	203	152, 203, 300 oder 600.
`widthMm`	number	`^PW`, sonst 75	Labelbreite in mm, max. 400.
`heightMm`	number	`^LL`, sonst 50	Labelhöhe in mm, max. 400.
`layout`	string	`label`	`label`: eine Seite je Etikett in Etikettengröße. `a4` / `letter`: Etiketten in Originalgröße auf Bögen, max. 2.000 Etiketten.
`cutLines`	bool	true	Nur bei Bögen: feine gestrichelte Schnittlinien um jedes Etikett.
`fieldValues`	object	–	Optionale Werte für `^FN`-Felder, Schlüssel = Feldnummer: `{"1": "ACME"}`. Füllt normale Etiketten und `^DF`/`^XF`-Formate (hat Vorrang vor `^FD`-Vorgaben und dem `^XF`-Datenblock), alle Etiketten und `^PQ`-Kopien. Schlüssel ohne passendes `^FN` (INVALID_FIELD_VALUE_KEY) stehen im Header `X-ZplCloud-Invalid-Field-Keys`. Max. 500 Felder, 4.000 Zeichen je Wert. Gilt auch für zpl-to-png, zpl-to-jpg und zpl-to-svg.

curl -X POST https://api.zplcloud.com/v1/tools/zpl-to-pdf \
  -H "X-API-Key: sk_zplcloud_…" -H "Content-Type: application/json" \
  -d '{"zpl":"^XA^FO50,50^A0N,40,40^FDEtikett 1^FS^XZ^XA^FO50,50^A0N,40,40^FDEtikett 2^FS^XZ","widthMm":100,"heightMm":50}' \
  -o labels.pdf

Antwort: application/pdf (label.pdf). Renders: einer je Etikett. Summary: { tool, widthMm, heightMm, dpi, labels, bytes }. Fehler: zpl is required., dpi must be 152, 203, 300 or 600., Label size must not exceed 400 × 400 mm., Rendering produced no PDF - check the ZPL., layout must be "label", "a4" or "letter"., A … mm label does not fit on an A4 sheet - use layout "label"., 413 zpl is too long … oder Too many labels for a sheet PDF (max 2,000).

ZPL zu PNG

POST /v1/tools/zpl-to-png · Website-Tool. Rendert ein Etikett als PNG - standardmäßig das erste. Felder, Größenregeln und Fehler wie bei zpl-to-pdf, dazu labelIndex (int, 0-basiert, Standard 0) für ein bestimmtes Etikett in mehrteiligem ZPL. Der Antwort-Header X-ZplCloud-Label-Count nennt die Zahl der Etiketten; ein Index außerhalb des Bereichs wird mit 400 beantwortet.

curl -X POST https://api.zplcloud.com/v1/tools/zpl-to-png \
  -H "X-API-Key: sk_zplcloud_…" -H "Content-Type: application/json" \
  -d '{"zpl":"^XA^FO50,50^A0N,40,40^FDEins^FS^XZ^XA^FO50,50^A0N,40,40^FDZwei^FS^XZ","dpi":203,"labelIndex":1}' -o label-2.png

Antwort: image/png. Renders: 1. Summary: { tool, widthMm, heightMm, dpi, labels: 1, bytes }.

Eine ^FN-Vorlage (siehe ZPL Template Filler) mit fieldValues füllen:

curl -X POST https://api.zplcloud.com/v1/tools/zpl-to-png \
  -H "X-API-Key: sk_zplcloud_…" -H "Content-Type: application/json" \
  -d '{"zpl":"^XA^DFR:SHIP.ZPL^FS^FO50,50^A0N,40,40^FN1\"Name\"^FS^XZ^XA^XFR:SHIP.ZPL^FS^XZ","fieldValues":{"1":"ACME GmbH"}}' -o filled.png

ZPL zu JPG

POST /v1/tools/zpl-to-jpg · Website-Tool. Rendert ein Etikett als JPEG. Felder und Fehler wie bei zpl-to-png, einschließlich labelIndex und X-ZplCloud-Label-Count.

curl -X POST https://api.zplcloud.com/v1/tools/zpl-to-jpg \
  -H "X-API-Key: sk_zplcloud_…" -H "Content-Type: application/json" \
  -d '{"zpl":"^XA^FO50,50^A0N,40,40^FDHallo^FS^XZ","widthMm":60,"heightMm":30}' -o label.jpg

Antwort: image/jpeg. Renders: 1.

ZPL zu SVG

POST /v1/tools/zpl-to-svg · Website-Tool. Rendert ZPL als Vektor-SVG. Nötig ist nur zpl; dpi, widthMm und heightMm werden wie bei zpl-to-pdf geprüft, ändern das SVG aber nicht.

curl -X POST https://api.zplcloud.com/v1/tools/zpl-to-svg \
  -H "X-API-Key: sk_zplcloud_…" -H "Content-Type: application/json" \
  -d '{"zpl":"^XA^FO50,50^GB300,120,4^FS^FO80,90^A0N,40,40^FDHallo^FS^XZ"}' -o label.svg

Antwort: image/svg+xml; charset=utf-8 (im Webhook-Ergebnis als utf-8-Text). Renders: 1. Fehler: wie zpl-to-pdf, dazu Rendering produced no SVG - check the ZPL.

Prüfen

ZPL-DPI-Konverter und Drehen

POST /v1/tools/zpl-dpi-converter · Website-Tool. Rechnet ZPL, das für eine Druckerauflösung geschrieben wurde, auf eine andere um und/oder dreht das ganze Etikett im Uhrzeigersinn. Positionen, Etikettengröße, Schriften, Barcodehöhen und Modulbreiten, Rahmen, Textblöcke und ^GFA-Grafiken werden neu berechnet; beim Drehen wird die gerenderte Größe jedes Felds gemessen, damit das gedrehte Feld genau an seiner Stelle landet. Danach vergleicht die Render-Engine jedes Element mit seiner erwarteten Position und Größe.

Feld	Typ	Standard	Hinweise
`zpl`	string	Pflicht	Ein oder mehrere Etiketten, max. 2.000.000 Zeichen.
`sourceDpi`	int	203	Auflösung, für die das ZPL geschrieben wurde: 152, 203, 300 oder 600.
`targetDpi`	int	`sourceDpi`	Auflösung des Zieldruckers: 152, 203, 300 oder 600.
`rotation`	int	0	Im Uhrzeigersinn: 0, 90, 180 oder 270. Bei 90 und 270 tauschen Breite und Höhe.
`widthMm`, `heightMm`	number	`^PW` / `^LL`, sonst 75 × 50	Etikettengröße in mm (bei `sourceDpi`). Für exaktes Drehen nötig, wenn das ZPL kein `^PW` / `^LL` enthält.

jq -Rs '{zpl: ., sourceDpi: 203, targetDpi: 300, rotation: 90}' label.zpl \
  | curl -X POST https://api.zplcloud.com/v1/tools/zpl-dpi-converter \
      -H "X-API-Key: sk_zplcloud_…" -H "Content-Type: application/json" -d @-

{
  "zpl": "^XA^PW751^LL1200...",
  "sourceDpi": 203, "targetDpi": 300, "rotation": 90,
  "sourceWidthMm": 101.6, "sourceHeightMm": 63.6,
  "targetWidthMm": 63.6, "targetHeightMm": 101.6,
  "notes": [
    { "code": "QR", "command": "BQ", "line": 8, "message": "QR codes have no orientation parameter in ZPL - ..." }
  ],
  "check": {
    "elements": 6, "compared": 6, "maxDeviationMm": 0.25, "toleranceMm": 0.3, "passed": true,
    "deviations": [
      { "element": "A", "content": "SHIP TO", "line": 6, "deltaX": 0, "deltaY": -1, "deltaWidth": -3, "deltaHeight": 0, "maxMm": 0.25 }
    ]
  }
}

check.passed ist true, wenn kein Element um mehr als toleranceMm (0,3 mm) abweicht. Abweichungen werden in Dots des Zieldruckers gemessen; typische Ursache sind Modulbreiten und Schriftgrößen, die nur ganze Dots sein können. notes[].code: SIZE, MODULE, QR_MAG, DM_MODULE, AZTEC_MAG, GRAPHIC_SCALE, GRAPHIC_ROTATE, STORED_SCALE, STORED_ROTATE, UNITS, MAXICODE, QR, UNVERIFIED. Meldungen sind immer Englisch. Renders: 1. Summary: { tool, sourceDpi, targetDpi, rotation, passed, maxDeviationMm }. Fehler: zpl is required., sourceDpi and targetDpi must be 152, 203, 300 or 600., rotation must be 0, 90, 180 or 270., Nothing to do: set a different targetDpi or a rotation., 413.

ZPL-Formatter (Pretty-Print / Minify)

POST /v1/tools/zpl-formatter · Website-Tool. Formatiert ZPL mit einem Befehl pro Zeile und eingerückten Feldblöcken (^FO/^FT … ^FS), optional mit einem ^FX-Kommentar je Feld, oder minifiziert es. Felddaten (^FD/^FV), ^FH-Escapes und ^GF/~DG-Nutzdaten werden Byte für Byte übernommen, in oder nach Felddaten wird nie ein Zeilenumbruch eingefügt - das Ergebnis ergibt dieselben Befehle. Mit check werden beide Fassungen gerendert und Pixel für Pixel verglichen.

Feld	Typ	Standard	Hinweise
`zpl`	string	Pflicht	Max. 2.000.000 Zeichen.
`mode`	string	`pretty`	`pretty` oder `minify` (kein Leerraum zwischen Befehlen, ein Etikett pro Zeile).
`indent`	int	2	Pretty: Leerzeichen je Ebene, 0–8.
`comments`	bool	false	Pretty: `^FX`-Kommentar je Feld (Text, Barcode, Box … mit Position).
`oneLine`	bool	false	Pretty: jeder Feldblock in einer Zeile.
`stripComments`	bool	true bei minify	Vorhandene `^FX`-Kommentare entfernen.
`check`	bool	true	Original und Ergebnis rendern (bis 10 Etiketten) und vergleichen.
`dpi`, `widthMm`, `heightMm`	int, number	203, `^PW` / `^LL`, sonst 75 × 50	Render-Einstellungen der Prüfung.

jq -Rs '{zpl: ., comments: true}' label.zpl \
  | curl -X POST https://api.zplcloud.com/v1/tools/zpl-formatter \
      -H "X-API-Key: sk_zplcloud_…" -H "Content-Type: application/json" -d @-

{
  "zpl": "^XA\n  ^PW812\n  ^FX Text \"SHIP TO\" at 60,60\n  ^FO60,60\n    ^A0N,44,44\n    ^FDSHIP TO^FS\n^XZ\n",
  "mode": "pretty", "inputChars": 412, "outputChars": 655, "inputLines": 1, "outputLines": 31, "commands": 38,
  "check": { "labels": 1, "totalLabels": 1, "pixelIdentical": true, "changedPixels": 0 }
}

Meldungen sind immer Englisch. Renders: 1 je geprüftem Etikett (1 ohne Prüfung). Summary: { tool, mode, outputChars, pixelIdentical }. Fehler: zpl is required., mode must be "pretty" or "minify"., indent must be 0 to 8., dpi must be 152, 203, 300 or 600., 413.

ZPL-Diff (zwei Fassungen vergleichen)

POST /v1/tools/zpl-diff · Website-Tool. Rendert zplA (vorher) und zplB (nachher) in derselben Auflösung und Größe und vergleicht sie: je Etikett die geänderten Pixel (removed = Tinte nur in A, added = Tinte nur in B), die Bounding-Boxen der geänderten Bereiche in Dots und ein Overlay-PNG (weißer Hintergrund, grau unverändert, rot entfernt, grün neu), dazu ein Zeilen-Diff beider Quellen nach dem Formatieren - reine Layout-Änderungen (Zeilenumbrüche, Einrückung) tauchen deshalb nicht auf. Verglichen werden bis zu 10 Etiketten.

Feld	Typ	Standard	Hinweise
`zplA`, `zplB`	string	Pflicht	Die beiden Fassungen, je max. 2.000.000 Zeichen.
`dpi`	int	203	152, 203, 300 oder 600.
`widthMm`, `heightMm`	number	größeres `^PW` / `^LL`, sonst 75 × 50	Beide Fassungen werden in dieser Größe gerendert.
`output`	string	`json`	`png`: nur das Overlay-PNG von `labelIndex`; Header `X-ZplCloud-Changed-Pixels`, `X-ZplCloud-Label-Count`.
`labelIndex`	int	0	Etikett für `output: png` (0-basiert).
`images`	bool	true	JSON: `overlayPng` (Base64) je Etikett mitliefern.
`outlineRegions`	bool	false	Einen Rahmen um jeden geänderten Bereich ins Overlay zeichnen.

jq -n --rawfile a v1.zpl --rawfile b v2.zpl '{zplA: $a, zplB: $b, images: false}' \
  | curl -X POST https://api.zplcloud.com/v1/tools/zpl-diff \
      -H "X-API-Key: sk_zplcloud_…" -H "Content-Type: application/json" -d @-

{
  "pixelIdentical": false, "textIdentical": false, "changedPixels": 5512,
  "labelCountA": 1, "labelCountB": 1, "linesAdded": 6, "linesRemoved": 3,
  "widthMm": 101.6, "heightMm": 76.2, "dpi": 203,
  "labels": [ {
    "index": 0, "width": 812, "height": 609, "identical": false,
    "changedPixels": 5512, "addedPixels": 3120, "removedPixels": 2392, "unchangedPixels": 61873,
    "missingInA": false, "missingInB": false,
    "regions": [ { "x": 60, "y": 160, "width": 512, "height": 26, "changedPixels": 2310 } ],
    "overlayPng": null
  } ],
  "textDiff": [ { "kind": "removed", "text": "    ^FDWeight: 2.4 kg^FS", "lineA": 18, "lineB": null } ]
}

# nur das Overlay:
jq -n --rawfile a v1.zpl --rawfile b v2.zpl '{zplA: $a, zplB: $b, output: "png", outlineRegions: true}' \
  | curl -X POST https://api.zplcloud.com/v1/tools/zpl-diff -H "X-API-Key: sk_zplcloud_…" \
      -H "Content-Type: application/json" -d @- -o diff.png

textDiff[].kind: unchanged, removed, added; lineA/lineB sind 1-basierte Zeilennummern der formatierten Fassungen. Meldungen sind immer Englisch. Renders: 2 je verglichenem Etikett. Summary: { tool, pixelIdentical, changedPixels, labels }. Fehler: zplA and zplB are required., dpi must be 152, 203, 300 or 600., output must be "json" or "png"., labelIndex must be 0 to n., 413.

ZPL-Linter

POST /v1/tools/zpl-linter · Website-Tool. Prüft ZPL auf Syntaxfehler, Felder außerhalb des Labels, Schriften, Barcodes und Druckerfallen.

Feld	Typ	Standard	Hinweise
`zpl`	string	Pflicht	Max. 2.000.000 Zeichen.
`dpi`	int	-	Optional: 152, 203, 300 oder 600 für auflösungsabhängige Prüfungen.
`widthMm`, `heightMm`	number	-	Optionale Labelgröße für die Randprüfungen.
`profile`	string	-	Optionaler Regelsatz: `amazon-fba` ergänzt Prüfungen für Amazon-FBA-Etiketten (z. B. FNSKU-Format).

curl -X POST https://api.zplcloud.com/v1/tools/zpl-linter \
  -H "X-API-Key: sk_zplcloud_…" -H "Content-Type: application/json" \
  -d '{"zpl":"^XA^PR20^FO50,50^A0N,40,40^FDHallo^FS^XZ","dpi":203}'

{
  "clean": false,
  "profile": null,
  "errorCount": 0,
  "warningCount": 1,
  "infoCount": 0,
  "issues": [
    {
      "severity": "warning",
      "code": "ZPL-060",
      "category": "Hardware",
      "message": "^PR 20 ips exceeds the maximum of most printers (14 ips).",
      "line": 1,
      "column": 4,
      "fix": "Lower the print speed (e.g. ^PR6)."
    }
  ]
}

clean ist true, wenn es weder Fehler noch Warnungen gibt (Infos sind erlaubt). severity: error, warning oder info. Renders: 1. Summary: { tool, clean, errorCount, warningCount, infoCount }. Fehler: zpl is required., dpi must be 152, 203, 300 or 600., Unknown profile. Known profiles: amazon-fba., 413.

ZPL-Analyse

POST /v1/tools/zpl-analyser · Website-Tool. Erklärt jedes Kommando, vermisst das Label und schätzt Druck-, Netzwerk- und Renderzeiten.

Feld	Typ	Standard	Hinweise
`zpl`	string	Pflicht	Max. 2.000.000 Zeichen.
`dpi`	int	-	Optional: 152, 203, 300 oder 600.
`widthMm`, `heightMm`	number	-	Ersatzgröße, wenn das ZPL kein `^PW` / `^LL` enthält.
`networkMbit`	int	10	Leitungsgeschwindigkeit für die Transferprognose, 1 bis 100.000 Mbit/s.

curl -X POST https://api.zplcloud.com/v1/tools/zpl-analyser \
  -H "X-API-Key: sk_zplcloud_…" -H "Content-Type: application/json" \
  -d '{"zpl":"^XA^PW812^LL1218^MD20^PR8^FO50,50^A0N,40,40^FDHallo^FS^XZ","networkMbit":100}'

Antwortfeld	Inhalt
`commands[]`	`{ code, params, description, count }` je Kommando
`logs[]`	Schritt-für-Schritt-Ablauf `{ time, code, params, details }`
`labelWidthMm`, `labelHeightMm`, `dpi`	Erkannte Labelgröße und Auflösung
`zplBytes`, `zplChars`, `commandCount`	Größenkennzahlen
`printSpeedIps`, `darkness`	Aus `^PR` / `^MD`, sonst die Zebra-Werkseinstellungen 5 ips und 15
`timePerLabel`	Geschätzte Druckzeit je Etikett (Text)
`predictions[]`	`{ count, print, network, render, networkMb, cloud }` für 10, 1.000 und 10.000 Etiketten
`assumed`	Annahmen der Prognose: `printSpeedIps`, `speedFromZpl`, `labelLengthInch`, `lengthFromZpl`, `feedSeconds`, `networkMbit`, `renderBaseMs`, `renderKbPerSec`

Renders: 1. Summary: { tool, labelWidthMm, labelHeightMm, dpi, commandCount, timePerLabel }. Fehler: zpl is required., dpi must be 152, 203, 300 or 600., networkMbit must be between 1 and 100000., 413.

Barcode prüfen

POST /v1/tools/check-barcode · Website-Tool. Liest alle Barcodes aus einem Foto oder Scan - oder nimmt den Inhalt direkt - und prüft GS1-Struktur, Prüfziffern, Datumsangaben und Längen.

Feld	Typ	Standard	Hinweise
`imageBase64`	string	-	Foto oder Scan (PNG, JPG, GIF, BMP, WebP), max. 20 MB und 16 Megapixel. Hat Vorrang vor `data`.
`data`	string	-	Alternativ der Barcode-Inhalt, max. 2.000 Zeichen, z. B. in Klammer-Notation.

curl -X POST https://api.zplcloud.com/v1/tools/check-barcode \
  -H "X-API-Key: sk_zplcloud_…" -H "Content-Type: application/json" \
  -d '{"data":"(01)04006381333931(17)271231(10)L-2026-0417"}'

{
  "count": 1,
  "valid": true,
  "codes": [
    {
      "symbology": null,
      "source": "text",
      "raw": "(01)04006381333931(17)271231(10)L-2026-0417",
      "kind": "gs1",
      "valid": true,
      "number": "04006381333931",
      "numberType": "GTIN-14 / ITF-14",
      "bracketed": "(01)04006381333931(17)271231(10)L-2026-0417",
      "parts": [ { "ai": "01", "title": "GTIN", "value": "04006381333931", "ok": true, "note": null }, … ],
      "findings": [ { "ok": true, "code": "checkDigitOk", "ai": "01", "message": "Check digit matches." }, … ]
    }
  ]
}

source: image oder text; symbology ist bei Bildern das erkannte Format (z. B. Code 128 / GS1-128), bei data null.
kind: gs1, digitallink, number oder plain. Steuerzeichen erscheinen in raw als <GS>, <RS>, <EOT>.
valid je Code ist bei reinem Text null; das oberste valid wird false, sobald ein Code ungültig ist. Befund-Codes wie bei den GS1-Tools.

Renders: 1 je Aufruf. Summary: { tool, count, valid }. Fehler: 400 Send imageBase64 (photo or scan) or data (the barcode content)., imageBase64 is not valid base64., kein Bild, zu viele Pixel; 413 Bild zu groß; 422 No barcode found in the image.

Label-Compliance-Check (Vorabprüfung)

POST /v1/tools/label-compliance-check · Website-Tool. Rendert das ZPL, vermisst jedes Feld bei dpi und prüft es gegen Regelpakete: gs1-logistic (GS1-Logistiketikett, SSCC), sunrise (Sunrise 2027), amazon-fba, ups, udi, fedex, dhl-paket. Jeder Befund trägt Regel-ID, Schwere, Meldung, Quelle in der Spezifikation, Korrekturvorschlag und die Fläche auf dem Etikett. Eine Vorabprüfung gegen öffentliche Spezifikationen, keine Zertifizierung.

Feld	Typ	Standard	Hinweise
`zpl`	string	Pflicht	Max. 2.000.000 Zeichen, bis zu 50 Etiketten in jedem Tarif; Pro: Batch-Prüfung bis 1.000 Etiketten.
`packs`	string[]	["gs1-logistic"]	`gs1-logistic`, `sunrise`, `amazon-fba`, `ups`, `udi`, `fedex`, `dhl-paket`.
`dpi`	int	203	152, 203, 300 oder 600 - alle mm-Werte werden damit berechnet.
`defaultWidthMm`, `defaultHeightMm`	number	101,6 × 152,4	Größe für Etiketten ohne `^PW`/`^LL`.
`format`	string	`json`	`sarif`: SARIF-2.1.0-Log (`application/sarif+json`) für CI und GitHub Code Scanning.
`images`	bool	false	JSON: `annotatedPngs` (Base64) mit eingezeichneten Befunden, bis zu 10 Etiketten.

jq -Rs '{zpl: ., packs: ["gs1-logistic", "sunrise"], dpi: 203}' sscc.zpl \
  | curl -X POST https://api.zplcloud.com/v1/tools/label-compliance-check \
      -H "X-API-Key: sk_zplcloud_…" -H "Content-Type: application/json" --data-binary @-

{
  "disclaimer": "Pre-check against public specifications; it does not certify the label …",
  "labelCount": 1, "dpi": 203,
  "packs": [ { "id": "gs1-logistic", "name": "GS1 logistic label", "version": "…" }, … ],
  "errorCount": 6, "warningCount": 0, "infoCount": 2,
  "findings": [ {
    "ruleId": "ZPL3104", "packId": "gs1-logistic", "severity": "error",
    "message": "X-dimension 0.25 mm (2 dot(s) at 203 dpi) is below the minimum 0.495 mm for logistic units …",
    "labelIndex": 0, "command": "^BC", "line": 13, "column": 1,
    "bounds": { "x": 20, "y": 420, "width": 312, "height": 120 },
    "advisory": false,
    "source": "GS1 General Specifications 26.0 §5.12.3.5 Table 5-51",
    "suggestion": "Use ^BY4 or wider at 203 dpi."
  }, … ],
  "annotatedPngs": []
}

Batch-Compliance (nur Pro): Mehr als 50 Etiketten (^XA … ^XZ) in einem Aufruf sind eine Batch-Prüfung - wie die Batch-API nur im Pro-Tarif, bis 1.000 Etiketten je Aufruf, als JSON oder SARIF (für CI-Pipelines). In Developer und Starter antwortet der Endpunkt mit 403 Batch compliance checks (more than 50 labels per call) require the Pro plan. und dem Hinweis, das ZPL in Aufrufe mit höchstens 50 Etiketten aufzuteilen - das geht in jedem Tarif. Über 1.000 Etiketten: 413.

Renders: 1 je geprüftem Etikett (Header X-ZplCloud-Renders). Summary: { tool, labelCount, errorCount, warningCount, infoCount, renders }. Fehler: 400 zpl is required., Unknown pack(s): …, dpi must be 152, 203, 300 or 600., format must be "json" or "sarif".; 413 ZPL zu lang. Die Meldungen der Befunde sind englisch; ruleId ist stabil, der Text kann sich zwischen Versionen ändern.

Barcode-Scan-Proof (digitale Vorabprüfung)

POST /v1/tools/barcode-scan-proof · Website-Tool. Rendert das ZPL in Druckerauflösung und liest jeden Barcode mit zwei Decodern zurück (zxing-cpp und ZXing.Net): gelesene gegen erwartete Daten, Ruhezonen, X-Dimension, Balkenhöhe, Abschneiden, Überdeckung, Klarschriftzeile und eine digitale Vorab-Note A–F nach dem Modell von ISO/IEC 15415/15416. Keine ISO-konforme Verifizierung und kein Ersatz für ein kalibriertes Prüfgerät am gedruckten Etikett.

Feld	Typ	Standard	Hinweise
`zpl`	string	Pflicht	Max. 2.000.000 Zeichen, bis zu 50 Etiketten und 500 Barcode-Befehle.
`dpi`	int	203	152, 203, 300 oder 600.
`widthMm`, `heightMm`	number	4 × 6 Zoll	Größe, wenn das ZPL kein `^PW`/`^LL` hat.
`images`	bool	false	`annotatedPngs` (Base64): Etikett mit Rahmen je Symbol, geforderter Ruhezone und Note.

jq -Rs '{zpl: ., dpi: 203}' regal.zpl \
  | curl -X POST https://api.zplcloud.com/v1/tools/barcode-scan-proof \
      -H "X-API-Key: sk_zplcloud_…" -H "Content-Type: application/json" --data-binary @-

{
  "disclaimer": "Digital pre-check modelled on ISO/IEC 15415/15416 … not an ISO-conformant verification …",
  "dpi": 203, "labelCount": 1, "lowestGrade": "F",
  "symbols": [ {
    "command": "^BE", "symbology": "EAN-13", "status": "Match", "grade": "F",
    "expectedData": "4006381333931", "decodedData": "4006381333931",
    "xDimensionMm": 0.375, "quietZones": { "requiredLeft": 11, "left": 2.7, … },
    "findings": [ { "code": "SP1101", "severity": "Error", "message": "Quiet zone left: 2.7X, 11X required (ISO/IEC 15420 / GS1); limited by the label edge." } ],
    "parameters": [ … ]
  }, … ],
  "decoders": [ { "name": "zxing-cpp", "available": true, … }, { "name": "ZXing.Net", … } ],
  "annotatedPngs": []
}

status: Match, DataAltered (von der Symbologie angepasst, z. B. Prüfziffer), Mismatch, NotDecoded, NotDecodable (kein Decoder für die Symbologie, nur Strukturprüfung), NotRendered, Unverified. Renders: 2 je geprüftem Etikett (Header X-ZplCloud-Renders). Summary: { tool, renders, labelCount, symbols, lowestGrade, dataProblems }. Fehler: 400 zpl is required., dpi-/Größenfehler; 413 ZPL zu lang oder zu viele Barcodes.

RFID Studio: EPC erzeugen, lesen und vorab prüfen

Drei Endpunkte, einer je Reiter des Website-Tools: EPCs nach dem GS1 EPC Tag Data Standard (TDS) 2.3 in allen 15 Schemata (sgtin-96, sgtin-198, sgtin+, dsgtin+, sscc-96, sscc+, sgln-96, sgln-195, sgln+, grai-96, grai-170, grai+, giai-96, giai-202, giai+), die ZPL-RFID-Befehle eines Etiketts und eine Vorabprüfung mit simuliertem RFID-Drucker. Engine: zplCore RFID. Vorabprüfung, keine Zertifizierung; GS1 und EPC sind Marken der GS1 AISBL und beschreiben hier den Standard. Renders: 1 je Aufruf bei allen drei Endpunkten (Header X-ZplCloud-Renders).

RFID: EPC erzeugen

POST /v1/tools/rfid-encode. Kodiert einen GS1-Schlüssel als EPC und erzeugt die RFID-Befehle (^RS, ^RF, ^HV) sowie ein Etikett 100 × 50 mm, dessen Barcode denselben GS1-Schlüssel trägt (GS1-128 oder GS1 DataMatrix).

Feld	Typ	Standard	Hinweise
`scheme`	string	`sgtin-96`	Eines der 15 Schemata oben.
`elementString`	string	–	GS1-Elementfolge, z. B. `(01)09506000134352(21)6789` - statt der Einzelfelder.
`gtin`, `serial`	string	–	SGTIN-Schemata; `dateAi` (11, 13, 15, 16, 17, 7006, 7007; Standard 17) und `date` (JJMMTT) für `dsgtin+`.
`sscc` · `gln`, `extension` · `grai`, `graiSerial` · `giai`	string	–	Schlüssel der übrigen Schemata (GRAI: 14 Stellen ohne Seriennummer).
`filter`	int	0	Filterwert 0–7 (reservierte Werte ergeben eine Warnung).
`companyPrefixLength`	int	–	6–12; Pflicht für die Festlängen-Schemata (sie steht nicht im GS1-Schlüssel), optional für die „+“-Schemata; eine GTIN-8 hat immer 8.
`pcMode`	string	`auto`	`auto` (`^RFW,H,,,A`, Drucker setzt die PC-Länge), `keep` (`^RFW,H`, nur EPCs mit 6 Wörtern), `explicit` (PC-Wort ab Wort 1 mitgeschrieben).
`hostVerification`	bool	true	`^FN1` am EPC-Feld + `^HV1`.
`epcFormat`	bool	false	`^RB`-Layout + `^RFW,E` mit Dezimalfeldern (96-Bit-Schemata).
`dpi`	int	203	Auflösung des Etiketts: 152, 203, 300 oder 600.
`images`	bool	false	`labelPng` (Base64) und `readBack`: der vom gerenderten Etikett mit zxing-cpp und ZXing.Net zurückgelesene Barcode, verglichen mit dem EPC.

curl -X POST https://api.zplcloud.com/v1/tools/rfid-encode \
  -H "X-API-Key: sk_zplcloud_…" -H "Content-Type: application/json" \
  -d '{"scheme": "sgtin-96", "gtin": "09506000134352", "serial": "6789", "filter": 1, "companyPrefixLength": 7}'

{
  "scheme": "sgtin-96", "header": "30", "bitLength": 96, "words": 6,
  "hex": "30364433400D1EC000001A85", "pcWord": "3000",
  "filter": 1, "filterName": "Point of Sale (POS) Trade Item", "companyPrefix": "9506000",
  "elementString": "(01)09506000134352(21)6789",
  "pureIdentityUri": "urn:epc:id:sgtin:9506000.013435.6789",
  "tagUri": "urn:epc:tag:sgtin-96:1.9506000.013435.6789",
  "digitalLinkUri": "https://id.gs1.org/01/09506000134352/21/6789",
  "fields": [ { "field": "header", "start": 0, "bits": 8, "binary": "00110000", "value": "30h · SGTIN-96" }, … ],
  "commands": "^RS8\n^FN1^RFW,H,,,A^FD30364433400D1EC000001A85^FS\n^FH_^HV1,24,EPC:,_0D_0A,L^FS\n",
  "labelZpl": "^XA … ^XZ", "labelSymbol": "datamatrix",
  "consistency": { "pack": "rfid", "errorCount": 0, "findings": [] },
  "warnings": [], "labelPng": null, "readBack": null
}

Fehler: 400 mit englischer Meldung und code (InvalidElementString, MissingElement, InvalidCompanyPrefixLength, GtinNotAllowed, ValueOutOfRange, InvalidCharacter, InvalidDate, InvalidInput …), z. B. eine Seriennummer mit führender Null bei SGTIN-96. Summary: { tool, renders, scheme }.

RFID: EPC lesen

POST /v1/tools/rfid-decode. Dekodiert Hex (EPC-Bank ab Bit 20h), PC-Wort + EPC, einen EPC-Tag-URI oder einen Pure-Identity-URI.

Feld	Typ	Standard	Hinweise
`hex`	string	–	EPC als Hex (Leerzeichen und `0x` erlaubt), max. 400 Zeichen.
`uri`	string	–	`urn:epc:tag:…` oder `urn:epc:id:…` (statt `hex`).
`pcWord`	bool	false	Die Hex-Daten beginnen mit dem PC-Wort; seine Längenbits bestimmen die EPC-Wörter.
`scheme`, `filter`	string, int	auto, 0	Nur für einen Pure-Identity-URI, der das Objekt benennt, aber nicht seine Kodierung.

Antwort: die Felder von rfid-encode plus valid, input (hex, pc-hex, tag-uri, pure-uri), pc und die Schlüsselfelder (gtin, serial, sscc, gln, extension, grai, giai, dateAi, date). Daten, die kein gültiger EPC sind, sind ein Ergebnis und kein Fehler: { ""valid"": false, ""errorCode"": ""UnknownHeader"", ""error"": ""…"" } (ebenso Truncated, InvalidBinary, InvalidHex, InvalidUri). Fehler: 400 ohne Eingabe oder mit hex und uri zugleich, 413 bei mehr als 400 Zeichen.

RFID: ZPL vorab prüfen und simulieren

POST /v1/tools/rfid-check. Führt das Regelpaket rfid aus (ZPL3901–ZPL3912: ^RF-Felddaten, EPC-Länge und PC-Bits, gültiger EPC, EPC gegen die gedruckten GS1-Barcodes und die Klarschrift, gedruckter EPC-Text, reservierte Filterwerte, ^RB-Layout, gleicher EPC auf ^PQ-Kopien, ^RS-Einrichtung, Sperren ohne Zugriffspasswort, ^HV-Feld) samt den allgemeinen ZPL-Regeln und simuliert danach je Etikett einen Zebra-RFID-Drucker: Schreiben mit Rücklesen, PC-Wort und StoredCRC, ^RR-Wiederholungen, VOID und nächstes Etikett nach ^RS n/e, ^HV-Antworten und das ~RV-Ergebnis.

Feld	Typ	Standard	Hinweise
`zpl`	string	Pflicht	Max. 2.000.000 Zeichen, bis zu 50 Etiketten.
`failure`	string	`none`	Tags der simulierten Rolle: `none`, `weak-tag` (die ersten zwei Schreibvorgänge scheitern), `void-first` (der erste Tag lässt sich nicht beschreiben), `no-tag`, `locked` (EPC-Bank mit unbekanntem Passwort gesperrt), `small-tag` (96 Bit EPC-Speicher).
`simulate`	bool	true	`false` lässt die Simulation weg.
`dpi`	int	203	152, 203, 300 oder 600.
`images`	bool	false	`annotatedPngs` (Base64) mit den Befunden auf dem Etikett.

{
  "labelCount": 1, "rfidLabels": 1, "errorCount": 1, "warningCount": 0, "infoCount": 0,
  "rules": [ { "id": "ZPL3904", "title": "EPC does not match the printed barcode", "severity": "error", "status": "failed", "findings": 1 }, … ],
  "findings": [ { "ruleId": "ZPL3904", "message": "The SSCC-96 EPC encodes SSCC (00) 376104250021234576, but ^BC prints 376104250021234569.", … } ],
  "simulation": { "failure": "void-first", "labels": [ {
    "success": true, "voidedLabels": 1, "labelsToTry": 3, "retries": 3, "resultReport": "_+,1_",
    "attempts": [ { "attempt": 1, "success": false, "operations": [ { "command": "^RFW,H,,,A", "status": "WriteFailed", … } ] }, … ],
    "tag": { "pcWord": "3000", "storedCrc": "F8BF", "crcValid": true, "epcHex": "31D5D080E4B2F0C4C1000000", … },
    "hostResponses": [ { "fieldNumber": 1, "text": "EPC:31D5D080E4B2F0C4C1000000\r\n" } ] } ] }
}

rules[].status: passed, failed oder advisory. resultReport ist das, was der Drucker mit ~RVE sendet (null nach ~RVD). Meldungen sind englisch. Fehler: 400 zpl is required., unbekanntes failure, dpi; 413 ZPL zu lang. Summary: { tool, renders, result }.

Nach ZPL

HTML zu ZPL

POST /v1/tools/html-to-zpl · Website-Tool. Macht aus einem HTML-Label monochrome ZPL-Grafik. Die API rendert kein HTML selbst: Die Seite zuerst als PNG rendern (z. B. Screenshot per Headless-Browser) und das PNG senden. Es wird Pixel für Pixel ohne Beschnitt umgesetzt, also in Druckerauflösung rendern - widthMm / 25,4 × dpi Pixel breit (100 × 50 mm bei 203 dpi = 799 × 400 px).

Feld	Typ	Standard	Hinweise
`pngBase64`	string	Pflicht	Das gerenderte HTML-Label als PNG, max. 20 MB.
`widthMm`, `heightMm`	number	Pflicht	Labelgröße in mm, max. 400.
`dpi`	int	203	152, 203, 300 oder 600.
`thresholdLow`	int	60	Schwarz-Schwelle; zusammen mit `thresholdHigh` bestimmt sie das Dither-Band.
`thresholdHigh`	int	40	Gleiche Werte ergeben einen harten Schwarz-Weiß-Schnitt ohne Dithering.
`compress`	bool	true	Hex-Daten von `^GFA` komprimieren.

base64 -w0 label.png \
  | jq -Rs '{pngBase64: ., dpi: 203, widthMm: 100, heightMm: 50}' \
  | curl -X POST https://api.zplcloud.com/v1/tools/html-to-zpl \
      -H "X-API-Key: sk_zplcloud_…" -H "Content-Type: application/json" \
      --data-binary @- | jq -r .zpl > label.zpl

Antwort: { zpl, widthPx, heightPx, dpi, widthMm, heightMm, zplBytes }. Renders: 1. Fehler: pngBase64 is required …, widthMm and heightMm are required., dpi must be 152, 203, 300 or 600., Größe über 400 mm; 413 PNG zu groß.

PDF zu ZPL

POST /v1/tools/pdf-to-zpl · Website-Tool. Wandelt PDF-Seiten (Versandlabels, Lieferscheine) in ^GFA-Grafik-ZPL um, ein Etikett je Seite.

Feld	Typ	Standard	Hinweise
`pdfBase64`	string	Pflicht	PDF-Dokument, max. 50 MB.
`pages`	string	"1"	`1`, `1-3,5` oder `all`; max. 100 Seiten je Aufruf.
`widthMm`, `heightMm`	number	PDF-Seitengröße	Labelgröße in mm (max. 400). Ohne Angabe gilt die Größe der ersten PDF-Seite.
`usePdfSize`	bool	false	`true` ignoriert `widthMm`/`heightMm` und nimmt die PDF-Seitengröße.
`rotate`	int	0	0, 90, 180 oder 270.
`scale`	string	contain	`contain`, `cover`, `fill`, `fitToWidth` oder `fitToHeight`.
`darkness`	int	15	0 bis 30, geschrieben als `^MD`.
`speed`	int	2	2 bis 12, geschrieben als `^PR`.
`dpi`	int	203	152, 203, 300 oder 600.
`offsetXmm`, `offsetYmm`	number	-	Versatz in mm (0 oder mehr).
`zplOffset`	bool	true	Versatz als `^FO` im ZPL statt durch Verschieben der Bitmap.

base64 -w0 versandlabels.pdf \
  | jq -Rs '{pdfBase64: ., pages: "all", widthMm: 101.6, heightMm: 152.4, dpi: 203, darkness: 20}' \
  | curl -X POST https://api.zplcloud.com/v1/tools/pdf-to-zpl \
      -H "X-API-Key: sk_zplcloud_…" -H "Content-Type: application/json" \
      --data-binary @- | jq -r .zpl > versandlabels.zpl

Antwort: { zpl, pageCount, widthMm, heightMm, widthPx, heightPx, dpi, zplBytes }. Renders: einer je Seite (pageCount). Fehler: pdfBase64 is required., pdfBase64 is not a PDF document., pages must look like "1", "1-3,5" or "all"., Too many pages (max 100 per call)., Bereichsfehler bei rotate, scale, darkness, speed; 413 PDF zu groß.

PDF zu nativem ZPL (Vector-Lift)

POST /v1/tools/pdf-to-native-zpl · Website-Tool. Wandelt eine Seite eines PDFs oder ein SVG in natives ZPL um: Text als ^A0-Felder, Barcodes dekodiert und als native ^B-Befehle neu erzeugt (und geprüft), Linien, Rahmen, Kreise und Ellipsen als ^GB/^GC/^GE/^GD; nur was kein natives Gegenstück hat, bleibt ^GF. Das Ergebnis wird Pixel für Pixel mit dem Original verglichen. Für ein reines Raster aller Seiten: pdf-to-zpl.

Feld	Typ	Standard	Hinweise
`pdfBase64`	string	-	PDF, max. 20 MB. Verschlüsselte PDFs, PDFs mit JavaScript oder XFA-Formularen werden abgelehnt.
`svg`	string	-	Alternativ ein SVG als Text (ohne DOCTYPE/Entities), max. 2.000.000 Zeichen.
`page`	int	1	Eine Seite (1-basiert, max. 100).
`pages`	string	-	Statt `page`: mehrere Seiten in einem Aufruf, z. B. `"1-3,5"`. Seiten je Aufruf nach Tarif (Limits); Antwort dann `{ pageCount, pagesConverted, zpl, pages[] }` mit einem Ergebnis je Seite.
`async`	bool	false	`true`: Umwandlung als Job (202 mit `jobId`, Status `GET /v1/batch/jobs/{jobId}`, Ergebnis-JSON `GET /v1/batch/jobs/{jobId}/output`, mit `webhookId` Webhook `api.tool.completed`). Pflicht über 20 Seiten je Aufruf.
`dpi`	int	erkannt, sonst 203	152, 203, 300 oder 600; ohne Angabe aus eingebetteten 203/300/600-dpi-Bildern.
`widthMm`, `heightMm`	number	Seitengröße	Beide zusammen (5–400 mm); der Inhalt wird eingepasst.
`crop`	bool	false	Vorher auf den gezeichneten Inhalt zuschneiden (Etikett auf einer A4-Seite).
`images`	bool	false	`originalPng`, `renderedPng`, `diffPng` (Base64) mitliefern; mit `pages` höchstens 10 Seiten je Aufruf.

base64 -w0 versandlabel.pdf | jq -Rs '{pdfBase64: ., dpi: 203}' \
  | curl -X POST https://api.zplcloud.com/v1/tools/pdf-to-native-zpl \
      -H "X-API-Key: sk_zplcloud_…" -H "Content-Type: application/json" --data-binary @-

{
  "zpl": "^XA\n^CI28\n^PW812\n^LL1218\n…",
  "dpi": 203, "dpiSource": "option", "widthDots": 812, "heightDots": 1218, "page": 1, "pageCount": 1,
  "fidelity": 0.9822, "fidelityExact": 0.9406, "nativeInkShare": 0.9922,
  "zplBytes": 1008, "rasterZplBytes": 8727, "barcodesMatch": true,
  "outcomes": { "native": 10, "approximated": 14, "raster": 0, "dropped": 1 },
  "elements": [ { "kind": "barcode", "outcome": "native", "x": 68, "y": 603, "width": 336, "height": 158, "text": "10115012001", "detail": "CODE_128", "score": 1, "dataMatch": true }, … ],
  "warnings": []
}

fidelity: Übereinstimmung der Druckfläche mit dem Original (±1 Punkt), fidelityExact ohne Toleranz. Text in Font 0 statt der PDF-Schrift behält Länge und Grundlinie, die Buchstabenformen weichen ab.
rasterZplBytes: dasselbe Etikett als ein einziges ^GF mit derselben Kompression - zum Vergleich mit zplBytes.
outcome je Element: native, approximated (z. B. Font 0 statt Helvetica), raster (Teil einer ^GF-Grafik) oder dropped (z. B. weiße Fläche auf leerem Papier).
Die Umwandlung läuft in einem isolierten Worker-Prozess mit Zeit- und Speichergrenze; sind alle Worker belegt, antwortet der Endpunkt mit 503 und Retry-After.

Limits je Tarif

Als einziges /v1/tools-Tool hat pdf-to-native-zpl ein eigenes Limit je Konto (alle API-Keys eines Kontos zusammen). Die übrigen Tools bleiben ohne Rate-Limit; das allgemeine Anfragelimit der API gilt für /v1/tools nicht.

	Developer	Starter	Pro	Enterprise
Seiten pro Minute	10	60	240	individuell
gleichzeitige Jobs	1	2	4	individuell
Seiten je Aufruf (direkt / als Job)	3	20	20 / 100 als Job	individuell
Seiten pro Monat	100 (500 Render)	keine Grenze	keine Grenze	individuell

429 + Retry-After, wenn das Seitenkontingent der laufenden Minute nicht mehr reicht ("limit": "pagesPerMinute") oder schon so viele Jobs des Kontos laufen ("limit": "concurrentJobs"). Gezählt werden nur Seiten, die tatsächlich einen Worker gebraucht haben.
403, wenn ein Aufruf mehr Seiten verlangt, als der Tarif je Aufruf erlaubt (pagesPerCall, requestedPages), und im Developer-Tarif, wenn die Monatsgrenze erreicht ist ("limit": "pagesPerMonth", usedThisMonth, resetsUtc, Upgrade-Hinweis). Starter und Pro haben keine Monatsgrenze; ihre Seiten zählen als Render gegen das Kontingent.
413, wenn ein Aufruf ohne async: true mehr als 20 Seiten verlangt. Gemessen auf test.zplcloud.com: rund 3,5 s je Seite; 20 Seiten bleiben mit Reserve unter dem verbreiteten 100-s-Client-Timeout. Größere Aufrufe laufen als Job: 202 mit jobId, statusUrl und outputUrl; Status, Ergebnis und Aufbewahrung (1 Stunde, auf dem Server, der den Job angenommen hat) wie bei der Batch-API.
503 + Retry-After: 5, wenn alle Konverter-Worker belegt sind (höchstens 2 gleichzeitig für Website und API zusammen) - unabhängig vom Tarif.

HTTP/1.1 429 Too Many Requests
Retry-After: 37

{
  "error": "PDF to native ZPL rate limit reached (10 pages per minute on the Developer plan, this call needs 3).",
  "tool": "pdf-to-native-zpl", "plan": "free", "limit": "pagesPerMinute",
  "pagesPerMinute": 10, "concurrentJobs": 1, "pagesPerCall": 3, "retryAfterSeconds": 37,
  "hint": "Retry after the number of seconds in the Retry-After header, or upgrade your plan …",
  "requestId": "…"
}

Renders: 5 je umgewandelter Seite (Header X-ZplCloud-Renders; vorläufiger Wert, wird anhand der im Betrieb gemessenen Rechenzeit je Seite kalibriert). Scheitert eine Seite eines Aufrufs mit pages, wird der ganze Aufruf nicht gezählt. Summary: { tool, kind, renders, pages, page, fidelity, zplBytes, rasterZplBytes, barcodesMatch }. Fehler: 400 pdfBase64 (or svg) is required., Encrypted or password-protected PDFs are not accepted., PDFs with JavaScript are not accepted., The page does not exist (the PDF has n page(s))., The label would be too large …; 413 Datei zu groß; 422 Zeit- oder Speichergrenze überschritten; 503 ausgelastet.

Bild zu ZPL

POST /v1/tools/image-to-zpl · Website-Tool. Wandelt ein Logo oder Bild in ZPL um: inline als ^GFA und als ~DG-Download-Kommando, das die Grafik im Drucker speichert. Transparenz wird weiß, der weiße Rand wird abgeschnitten.

Feld	Typ	Standard	Hinweise
`imageBase64`	string	Pflicht	PNG, JPG, GIF oder BMP, max. 20 MB und 16 Megapixel.
`blackness`	int	50	Schwarz-Schwelle in Prozent, 0 bis 100.
`rotate`	int	0	0, 90 (gegen den Uhrzeigersinn), 180 oder 270 (im Uhrzeigersinn).
`flipH`, `flipV`	bool	false	Horizontal / vertikal spiegeln (vor dem Drehen).
`compress`	bool	true	Hex-Daten komprimieren.
`dpi`	int	203	Nur für die mm-Angaben in der Antwort.
`fileName`	string	LOGO	GRF-Name, bis zu 40 Buchstaben, Ziffern, `_` oder `-`; `.GRF` wird angehängt.

base64 -w0 logo.png \
  | jq -Rs '{imageBase64: ., blackness: 45, fileName: "LOGO"}' \
  | curl -X POST https://api.zplcloud.com/v1/tools/image-to-zpl \
      -H "X-API-Key: sk_zplcloud_…" -H "Content-Type: application/json" \
      --data-binary @- > logo.json
jq -r .grf logo.json > logo-download.zpl   # einmal als LOGO.GRF speichern
jq -r .zpl logo.json > logo-inline.zpl     # oder direkt einbetten

Antwort: { zpl, grf, grfName, widthPx, heightPx, widthMm, heightMm, dpi, zplBytes }. Renders: 1. Fehler: imageBase64 is required (PNG, JPG, GIF or BMP)., kein Bild, zu viele Pixel, rotate must be 0, 90, 180 or 270., fileName may contain up to 40 letters, digits, _ or -.; 413 Bild zu groß.

SVG zu ZPL

POST /v1/tools/svg-to-zpl · Website-Tool. Rastert SVG-Markup in Druckerauflösung und liefert ein komplettes Label mit der Grafik bei 0,0.

Feld	Typ	Standard	Hinweise
`svg`	string	Pflicht	SVG-Markup, max. 2.000.000 Zeichen.
`sizeMm`	number	Pflicht	Länge der längeren Seite in mm, max. 400.
`dpi`	int	203	152, 203, 300 oder 600.

jq -Rs '{svg: ., sizeMm: 40, dpi: 203}' logo.svg \
  | curl -X POST https://api.zplcloud.com/v1/tools/svg-to-zpl \
      -H "X-API-Key: sk_zplcloud_…" -H "Content-Type: application/json" \
      --data-binary @- | jq -r .zpl > logo.zpl

Antwort: { zpl, widthPx, heightPx, dpi, zplBytes }, zpl = ^XA^FO0,0^GFA…^FS^XZ. Renders: 1. Fehler: svg is required., sizeMm is required (size of the longer side in mm)., The SVG could not be converted.; 413.

EPL2 zu ZPL

POST /v1/tools/epl2-to-zpl · Website-Tool. Konvertiert Zebra-EPL2-Druckercode nach ZPL II.

Feld	Typ	Standard	Hinweise
`code`	string	Pflicht	Druckercode, max. 2.000.000 Zeichen.

jq -Rs '{code: .}' label.epl \
  | curl -X POST https://api.zplcloud.com/v1/tools/epl2-to-zpl \
      -H "X-API-Key: sk_zplcloud_…" -H "Content-Type: application/json" \
      --data-binary @- | jq -r .zpl > label.zpl

Antwort: { zpl, labels, zplBytes }. Renders: 1 je Aufruf, unabhängig von labels. Fehler: code is required., The code could not be converted.; 413.

DPL zu ZPL

POST /v1/tools/dpl-to-zpl · Website-Tool. Konvertiert Datamax-/Honeywell-DPL-Code nach ZPL II. Feld code, Antwort und Fehler wie bei epl2-to-zpl.

jq -Rs '{code: .}' label.dpl \
  | curl -X POST https://api.zplcloud.com/v1/tools/dpl-to-zpl \
      -H "X-API-Key: sk_zplcloud_…" -H "Content-Type: application/json" \
      --data-binary @- | jq -r .zpl > label.zpl

TSPL zu ZPL

POST /v1/tools/tspl-to-zpl · Website-Tool. Konvertiert TSC-TSPL-/TSPL2-Code nach ZPL II. Feld code, Antwort und Fehler wie bei epl2-to-zpl.

jq -Rs '{code: .}' label.tspl \
  | curl -X POST https://api.zplcloud.com/v1/tools/tspl-to-zpl \
      -H "X-API-Key: sk_zplcloud_…" -H "Content-Type: application/json" \
      --data-binary @- | jq -r .zpl > label.zpl

ZPL zu anderen Druckersprachen

ZPL auf Druckern drucken, die kein ZPL sprechen. Jedes ^XA…^XZ-Etikett wird Punkt für Punkt in der Druckerauflösung gerendert - ohne Kantenglättung, wie ein Thermodruckkopf - und als Schwarz-Weiß-Bild in die Zielsprache geschrieben. Schriften, Barcodes und Emulationsunterschiede spielen keine Rolle mehr: der Drucker druckt nur noch Punkte. Die Antwort ist der rohe Druckauftrag; ihn unverändert an TCP-Port 9100 senden.

Feld	Typ	Standard	Hinweise
`zpl`	string	Pflicht	Ein oder mehrere Etiketten, max. 2.000.000 Zeichen. Jedes Etikett (inklusive `^PQ`-Kopien) wird ein Etikett im Auftrag.
`dpi`	int	je Sprache	Auflösung des Zieldruckkopfs, erlaubte Werte je Sprache unten. Brother: über `model`.
`widthMm`	number	`^PW`, sonst 75	Etikettenbreite in mm, max. 400.
`heightMm`	number	`^LL`, sonst 50	Etikettenhöhe in mm, max. 400.
`compress`	bool	false	Komprimiertes Bildformat der Sprache verwenden (400, wenn sie keins hat).
`hex`	bool	false	SBPL und CPCL: Bilddaten als Hex-Text statt binär.
`cut`	bool	true	ESC/POS und Brother: nach jedem Etikett schneiden.
`paper`	string	`a4`	PCL: `a4` oder `letter`.
`model`	string	`ql-820`	Brother: Modellfamilie, siehe zpl-to-brother.
`media`	string	`continuous`	Brother QL und TD-4: `continuous` oder `diecut`.

Antwort application/octet-stream mit Content-Disposition: attachment; filename=label.<ext> und dem Header X-ZplCloud-Label-Count. Jedes Etikett zählt als Render. Grenzen: 1.000 Etiketten und 256 MB unkomprimierte Bilddaten je Aufruf (413). Fehler wie bei den anderen Tools, z. B. dpi must be 203, 300, 600 for TSPL.

jq -Rs '{zpl: ., dpi: 203, compress: true}' label.zpl \
  | curl -X POST https://api.zplcloud.com/v1/tools/zpl-to-tspl \
      -H "X-API-Key: sk_zplcloud_…" -H "Content-Type: application/json" \
      --data-binary @- -o label.tspl

# Auftrag an den Drucker senden
nc -q 1 192.168.1.50 9100 < label.tspl

Tool	Drucker	dpi	Bildbefehl	compress
`zpl-to-tspl`	TSC, Printronix T-Serie	203, 300, 600	`BITMAP`	PCX über `DOWNLOAD` + `PUTPCX`
`zpl-to-epl2`	Zebra EPL (LP/TLP 2844 …)	203, 300	`GW`	-
`zpl-to-dpl`	Honeywell, Datamax-O'Neil	203, 300, 600	`<STX>I` PCX + Feld `Y`	immer PCX
`zpl-to-sbpl`	SATO	203, 300, 600	`ESC GB` / `ESC GH`	PCX über `ESC GP`
`zpl-to-cpcl`	Zebra- und Honeywell-Mobildrucker	203	`CG` / `EG`	PCX über `PCX`
`zpl-to-escpos`	Epson TM, Star, Bixolon, Citizen	180, 203	`GS v 0`	-
`zpl-to-brother`	Brother QL, TD-4, PT	je Modell	Rasterzeilen `g` / `G`	TIFF PackBits
`zpl-to-pcl`	HP LaserJet, PCL-5-Laser	300, 600	`ESC*b#W`	TIFF PackBits (Mode 2)
`zpl-to-easyplug`	Avery Dennison, Novexx	203, 300, 600	`#YIB`	RLE über `#YIR`
`zpl-to-tpcl`	Toshiba Tec	203, 300, 600	`{SG;…,1,…\|}`	TOPIX (`{SG;…,3,…\|}`)
`zpl-to-jscript`	cab	203, 300, 600	`d BMP` + Feld `I`	PCX über `d PCX`

Den Auftrag drucken

Der Auftrag enthält binäre Bilddaten: er muss Byte für Byte beim Drucker ankommen - ohne Text-Encoding, ohne angehängten Zeilenumbruch. Vier Wege:

Weg	So geht's	Hinweise
Direkt an TCP 9100	`nc -q 1 192.168.1.50 9100 < label.tspl`	Jeder Socket-Client, der Bytes unverändert sendet.
zplCloud CLI	`zplcloud send --target 192.168.1.50 --file label.tspl` `zplcloud send --usb --file label.bin` `zplcloud send --target 192.168.1.50 --file label.zpl --language tspl`	TCP oder USB. Die Auftrags-Endungen gehen automatisch byte-genau raus; `--language` wandelt vorher über diese API um. Ab CLI v1.2.26 - siehe CLI-Doku.
`POST /v1/remote-printers/{id}/raw`	`{ "base64": "…", "fileName": "label.tspl" }` oder `{ "zpl": "^XA…", "language": "tspl", "dpi": 203 }`	Über den zplCloud-CLI-Agenten im Netz des Druckers - ohne eingehende Ports. Mit `zpl` + `language` wandelt die Cloud vorher um (Felder wie oben, Renders je Etikett). Agent ab v1.2.22 für TCP-Drucker, ab v1.2.26 für USB-Drucker.
`POST /v1/print/folder`	`{ "agent", "folder", "zpl", "language": "tspl" }` oder `{ "agent", "folder", "base64", "fileName": "label.tspl" }`	Legt den Auftrag mit seiner Endung in einen Watch-Ordner des Agenten; der Agent druckt älteste-zuerst. Das `pattern` des Ordners muss die Endung enthalten. Agent ab v1.2.26.

jq -Rs '{zpl: ., language: "tspl", dpi: 300, compress: true}' label.zpl \
  | curl -X POST https://api.zplcloud.com/v1/remote-printers/4/raw \
      -H "X-API-Key: sk_zplcloud_…" -H "Content-Type: application/json" --data-binary @-

{ "ok": true, "error": null, "bytes": 9842, "language": "TSPL", "labels": 1 }

ok ist false mit error, wenn der Agent den Auftrag nicht zustellen konnte (Drucker nicht erreichbar, veralteter Agent); 409, wenn kein Agent online ist. Ein Watch-Ordner kann auch selbst umwandeln: "convert": { "language": "tspl" } in der Agent-Config macht aus jeder ZPL-Datei vor dem Druck TSPL - siehe Watch-Ordner.

Die Aufträge folgen den Programmierhandbüchern der Hersteller und werden geprüft, indem sie wieder zum Bild zurückgelesen werden. Firmware unterscheidet sich je Modell - vor dem Rollout einer Sprache ein Testetikett drucken.

ZPL zu TSPL

POST /v1/tools/zpl-to-tspl · Website-Tool. SIZE in mm (mit TSCs 8/12/24 Punkten je mm, so bekommt auch ältere Firmware ohne SIZE … dot genau die Punktzahl), CLS, BITMAP 0,0,<Bytes>,<Höhe>,0,<Daten> mit 0 = schwarz, PRINT 1,1. GAP, BLINE und DIRECTION werden nicht gesendet - der Drucker behält seine Kalibrierung. Mit compress geht das Etikett als 1-Bit-PCX in den RAM (DOWNLOAD), wird mit PUTPCX gedruckt und mit KILL gelöscht.

ZPL zu EPL2

POST /v1/tools/zpl-to-epl2 · Website-Tool. Je Etikett N, q<Breite>, GW0,0,<Bytes>,<Höhe>,<Daten> (0 = schwarz) und P1, Zeilenende LF. Keine Kompression: EPL2 legt PCX-Grafiken nur im Flash ab (GM) und würde ihn Etikett für Etikett abnutzen.

ZPL zu DPL

POST /v1/tools/zpl-to-dpl · Website-Tool. <SOH>D (schaltet bei älteren Datamax-Druckern die Sofortbefehle ab), dann je Etikett <STX>IDPZPLCLOUD mit dem Etikett als 1-Bit-PCX in den RAM (Modul D), ein Format <STX>L, D11, 1Y1100000000000ZPLCLOUD, Q0001, E und <STX>xDGZPLCLOUD zum Löschen. DPL nutzt immer den komprimierten PCX-Weg.

ZPL zu SBPL

POST /v1/tools/zpl-to-sbpl · Website-Tool. <ESC>A<ESC>A1 mit der Etikettengröße, dann je Etikett <ESC>A, <ESC>V0001<ESC>H0001, <ESC>GB (binär) oder <ESC>GH (hex) mit Bytes je Zeile und 8-Punkt-Blöcken - das Bild wird auf Vielfache von 8 Punkten aufgefüllt, 1 = schwarz -, <ESC>Q1<ESC>Z. Mit compress: <ESC>GP mit einem PCX, solange es ins 5-stellige Größenfeld passt (99.999 Bytes); größere Etiketten gehen als GB.

ZPL zu CPCL

POST /v1/tools/zpl-to-cpcl · Website-Tool. Je Etikett ! 0 200 200 <Höhe> 1, PAGE-WIDTH, dann Bänder aus bis zu 128 nicht leeren Zeilen als CG (binär) oder EG (hex), 1 = schwarz - leere Zeilen kosten nichts -, FORM und PRINT. Mit compress: PCX 0 0 gefolgt vom Etikett als 1-Bit-PCX. Für Endlos-Bonpapier FORM entfernen.

ZPL zu ESC/POS

POST /v1/tools/zpl-to-escpos · Website-Tool. ESC @, ESC a 0, das Etikett als GS v 0-Rasterbänder zu 256 Zeilen (kleine Bänder halten den Empfangspuffer mobiler Modelle frei), dann GS V 66 0 (vorschieben und schneiden), wenn cut gesetzt ist. 203 dpi für die meisten 80-mm-Drucker (576 Punkte Druckbreite), 180 dpi für die Epson-TM-T88-Serie (512 Punkte).

ZPL zu Brother-Raster

POST /v1/tools/zpl-to-brother · Website-Tool. Brother-Rastermodus: Nullbytes zum Zurücksetzen, ESC @, je Etikett ESC i a 01, ESC i z, ESC i M/A/K (Schnitt), ESC i d (Vorschub), M 02 bei compress, eine Rasterzeile je Punktzeile über die ganze Kopfbreite - gespiegelt, wie der Drucker sie erwartet - und 0x0C zwischen den Etiketten, 0x1A am Ende. Das Etikett wird auf der schmalsten passenden Medienbreite des Modells zentriert, mit den Rändern aus Brothers Command Reference. Das Modell legt die Auflösung fest:

model	Drucker	dpi	Kopf	TIFF
`ql-820`	QL-580N, QL-710W, QL-720NW, QL-810W, QL-820NWB	300	720 Punkte	ja
`ql-800`	QL-570, QL-700, QL-800	300	720 Punkte	nein
`ql-1100`	QL-1050, QL-1060N, QL-1100, QL-1110NWB, QL-1115NWB	300	1296 Punkte	ja
`td-4-203`	TD-4210D, TD-4410D, TD-4420DN	203	832 Punkte	ja
`td-4-300`	TD-4510D, TD-4520DN, TD-4550DNWB	300	1280 Punkte	ja
`pt-p750w`	PT-E550W, PT-P750W, PT-P710BT (Band bis 24 mm)	180	128 Punkte	ja
`pt-p900`	PT-P900, PT-P900W, PT-P950NW, PT-P910BT (Band bis 36 mm)	360	560 Punkte	ja

media: continuous (die Etikettenlänge kommt aus dem Auftrag) oder diecut (die Etikettengröße muss zu den eingelegten Etiketten passen). P-touch-Bänder sind immer endlos und werden quer bedruckt: die Etikettenbreite ist die bedruckbare Bandbreite.

ZPL zu PCL

POST /v1/tools/zpl-to-pcl · Website-Tool. PJL ENTER LANGUAGE = PCL, ESC E, Papierformat (paper), Hochformat, oberer Rand 0, Einheit und Rasterauflösung = dpi; je Etikett eine Seite mit dem Etikett in Originalgröße 10 mm von der oberen linken Ecke, Zeilen als ESC*b#W (Null-Bytes am Zeilenende entfallen, compress = Mode 2 TIFF PackBits), leere Zeilen als ESC*b#Y, ESC*rB und Seitenvorschub. 400, wenn das Etikett mit 10 mm Rand nicht aufs Papier passt.

ZPL zu Easy Plug

POST /v1/tools/zpl-to-easyplug · Website-Tool. Je Etikett #!A1, #IMSR<Breite>/<Länge> in mm, #ERN, #T0#J0, das Bild mit #YIB<Zeilen>/<Bytes je Zeile>/<Daten> (1 = schwarz, unterste Zeile zuerst) und #Q1/. Mit compress: #YIR-Lauflängen (Paare aus weißen und schwarzen Lauflängen, gleiche Zeilen mit FF nn) - typische Etiketten schrumpfen um rund 90 %. Drucker mit 12 Punkten/mm haben 305 dpi - mit 300 rendern.

ZPL zu TPCL

POST /v1/tools/zpl-to-tpcl · Website-Tool. {D<Teilung>,<Breite>,<Länge>|} in 0,1 mm (Teilung = Länge + 3 mm Lücke), dann je Etikett {C|}, {SG;0000,0000,<Breite>,<Höhe>,1,<Daten>|} (1 = schwarz) und {XS;I,0001,0002C3000|} (Durchlichtsensor, Stapelbetrieb, ohne Farbband - für Thermotransfer …C3020). Mit compress: Grafiktyp 3, Toshibas TOPIX-Kompression, in Blöcken unter 64 KB mit der Startzeile in Punkten.

ZPL zu JScript

POST /v1/tools/zpl-to-jscript · Website-Tool. Je Etikett lädt d BMP;ZPLCLOUD das Etikett als 1-Bit-BMP in den RAM (Übertragung zwischen ESC . und ESC ., jedes ESC in den Daten verdoppelt), dann m m, J, S l1;0,0,<Höhe>,<Höhe + 3>,<Breite> (Etiketten mit Lücke), I 0,0,0;ZPLCLOUD und A 1. Mit compress ist das Bild ein PCX (d PCX).

Barcodes & GS1

Barcode zu ZPL

POST /v1/tools/barcode-to-zpl · Website-Tool. Erzeugt ein Label mit einem Barcode, platziert mit 5 mm Rand.

Feld	Typ	Standard	Hinweise
`symbology`	string	Code128	Name aus der Tabelle unten (Groß-/Kleinschreibung egal).
`data`	string	Pflicht	Inhalt; max. 128 Zeichen bei linearen Codes, 4.096 bei QRCode, DataMatrix, Pdf417, AztecCode und MaxiCode.
`dpi`	int	203	152, 203, 300 oder 600.
`widthMm`, `heightMm`	number	Vorgabe	Labelgröße in mm (max. 400); Standard ist die Vorgabe der Symbologie.
`invert`	bool	false	Weißer Code auf schwarzem Label (`^LRY`).

Symbologie	Vorgabe (mm)	Datenregel
`Code128`	56 × 28	-
`Code39`	56 × 28	-
`Code93`	46 × 28	-
`Code11`	56 × 28	nur Ziffern
`Codabar`	46 × 28	Ziffern und A-D
`Msi`	40 × 28	nur Ziffern
`Plessey`	38 × 28	nur Ziffern
`Industrial2of5`	53 × 28	nur Ziffern
`Interleaved2of5`	54 × 28	nur Ziffern, gerade Anzahl
`Telepen`	40 × 28	-
`Pzn`	34 × 28	6 bis 8 Ziffern
`Ean13`	44 × 30	12 oder 13 Ziffern
`Ean8`	42 × 30	7 oder 8 Ziffern
`UpcA`	44 × 30	11 oder 12 Ziffern
`UpcE`	48 × 30	6 bis 8 Ziffern
`Isbn`	53 × 30	10 oder 13 Ziffern
`EanUpcAddOn2`, `EanUpcAddOn5`	50 × 24	-
`Ean128` (GS1-128)	66 × 28	-
`UccEan128`	50 × 24	-
`GS1DataBarExpanded`	46 × 28	-
`GS1DataBarExpandedStacked`	50 × 24	-
`Postnet`	52 × 22	nur Ziffern
`Planet`	60 × 22	nur Ziffern
`QRCode`	36 × 36	-
`DataMatrix`	29 × 29	-
`AztecCode`	28 × 28	-
`MaxiCode`	38 × 38	-
`Pdf417`	50 × 34	-
`MicroPdf417`	30 × 34	-
`CompactPdf417`	38 × 30	-
`CodablockF`	116 × 34	nur Ziffern
`Code16k`	69 × 30	-
`Code49`	74 × 30	nur Ziffern

curl -X POST https://api.zplcloud.com/v1/tools/barcode-to-zpl \
  -H "X-API-Key: sk_zplcloud_…" -H "Content-Type: application/json" \
  -d '{"symbology":"Ean13","data":"400638133393","dpi":203}'

{ "zpl": "^XA…^XZ", "symbology": "Ean13", "widthMm": 44, "heightMm": 30, "dpi": 203, "zplBytes": 187 }

Renders: 1. Summary: { tool, symbology, widthMm, heightMm, dpi, zplBytes }. Fehler: Unknown symbology. Known: …, data is required., Verstöße gegen die Datenregel, zu lange Daten, Label size must not exceed 400 × 400 mm.

QR-Code zu ZPL

POST /v1/tools/qr-code-to-zpl · Website-Tool. Baut den QR-Inhalt eines Typs aus seinen Feldern und liefert ein quadratisches Label.

Feld	Typ	Standard	Hinweise
`type`	string	url	QR-Typ aus der Tabelle unten.
`fields`	object	-	Feldwerte als Strings (Schlüssel ohne Beachtung der Groß-/Kleinschreibung), je max. 2.000 Zeichen.
`sizeMm`	number	25	Kantenlänge des quadratischen Labels, 1 bis 400 mm.
`dpi`	int	203	152, 203, 300 oder 600.
`mode`	string	native	`native` (Kommando `^BQ`) oder `image` (`^GFA`-Bitmap).
`errorCorrection`	string	-	`L`, `M`, `Q` oder `H` (Modus native).
`magnification`	int	-	1 bis 10 (Modus native).

type	fields	Kodierter Inhalt
`url`	`url`	die URL
`text`	`text`	der Text
`wifi`	`ssid` (Pflicht), `password`, `security` (`WPA` Standard, `WEP`, `nopass`), `hidden` (`true`/`1`/`on`)	`WIFI:T:WPA;S:…;P:…;;`
`email`	`to`, `subject`, `body`	`mailto:…?subject=…&body=…`
`phone`	`phone`	`tel:…`
`whatsapp`	`phone`, `message`	`https://wa.me/<Ziffern>?text=…`
`signal`	`phone`	`https://signal.me/#p/<phone>`
`telegram`	`username`, `message`	`https://t.me/<username>?text=…`
`location`	`lat`, `lng`	`geo:lat,lng`
`vcard`	`name`, `phone`, `email`, `org`	vCard 3.0
`instagram`	`username`	`https://instagram.com/<username>`
`tiktok`	`username`	`https://www.tiktok.com/@<username>`
`snapchat`	`username`	`https://snapchat.com/add/<username>`
`facebook`	`url` (Seitenpfad)	`https://facebook.com/<url>`

curl -X POST https://api.zplcloud.com/v1/tools/qr-code-to-zpl \
  -H "X-API-Key: sk_zplcloud_…" -H "Content-Type: application/json" \
  -d '{"type":"wifi","fields":{"ssid":"Lager","password":"Palette-2026"},"sizeMm":30,"errorCorrection":"M"}'

{ "zpl": "^XA…^BQN,2,…^XZ", "data": "WIFI:T:WPA;S:Lager;P:Palette-2026;;", "type": "wifi", "mode": "native", "sizeMm": 30, "dpi": 203, "zplBytes": 92 }

Renders: 1. Summary: { tool, type, mode, sizeMm, dpi, zplBytes }. Fehler: Unknown type. Known: …, The fields for this QR type are empty. Required fields: …, sizeMm must be between 1 and 400., mode must be native or image., errorCorrection must be L, M, Q or H., magnification must be between 1 and 10., Feld oder Inhalt zu lang.

GS1-128 aus Application Identifiers

POST /v1/tools/gs1-ai-128-to-zpl · Website-Tool. Prüft GS1 Application Identifiers in Klammer-Notation und erzeugt einen GS1-128-Barcode. Die vier GS1-Tools teilen Felder, Prüfung und Fehler:

Feld	Typ	Standard	Hinweise
`ai`	string	Pflicht	AIs in Klammer-Notation, z. B. `(01)04006381333931(17)271231(10)L-2026-0417`; max. 4.096 Zeichen.
`dpi`	int	203	152, 203, 300 oder 600.
`widthMm`	number	automatisch / Vorgabe	GS1-128 und DataBar: breit genug für den Inhalt, mindestens die Vorgabe (66 mm / 34 mm). 2D: Vorgabe.
`heightMm`	number	Vorgabe	Gestapelter DataBar: aus Zeilen und Klartextzeilen berechnet.
`domain`	string	id.gs1.org	Nur gs1-ai-qr-code-to-zpl: Digital-Link-Domain.
`variant`	string	single	Nur gs1-ai-databar-to-zpl: `stacked` für die zweizeilige Form.

curl -X POST https://api.zplcloud.com/v1/tools/gs1-ai-128-to-zpl \
  -H "X-API-Key: sk_zplcloud_…" -H "Content-Type: application/json" \
  -d '{"ai":"(01)04006381333931(10)L-2026-0417"}'

{
  "zpl": "^XA…^XZ",
  "symbology": "Ean128",
  "widthMm": 66,
  "heightMm": 28,
  "dpi": 203,
  "zplBytes": 214,
  "content": "(01)04006381333931(10)L-2026-0417",
  "brackets": "(01)04006381333931(10)L-2026-0417",
  "elements": [
    { "ai": "01", "value": "04006381333931", "title": "GTIN" },
    { "ai": "10", "value": "L-2026-0417", "title": "BATCH/LOT" }
  ]
}

Jeder AI wird gegen den GS1-Katalog geprüft: unbekannte AIs, Dubletten, nur Ziffern und Zeichensatz 82, feste und maximale Längen, Monat und Tag von Datumsangaben, Prüfziffern. Bei einem Befund wird nichts erzeugt, die Antwort ist 400 (der error-Text verbindet die ersten vier Meldungen):

HTTP/1.1 400 Bad Request

{
  "error": "Check digit does not match: expected 1, found 2.",
  "tool": "gs1-ai-128-to-zpl",
  "issues": [
    { "code": "checkDigit", "ai": "01", "title": "GTIN", "message": "Check digit does not match: expected 1, found 2." }
  ],
  "requestId": "3f0c9a7e-5b1d-4c2e-9a41-7d0e6b2f8c13"
}

Befund-Codes: unknownAi, duplicate, empty, numeric, charset82, fixedLength, maxLength, month, day, checkDigit. Weitere Fehler: ai is required …, kein AI im String gefunden, dpi must be 152, 203, 300 or 600. Renders: 1. Summary: { tool, symbology, widthMm, heightMm, dpi, zplBytes }.

GS1 DataMatrix aus Application Identifiers

POST /v1/tools/gs1-ai-datamatrix-to-zpl · Website-Tool. Felder und Prüfung wie bei gs1-ai-128-to-zpl; erzeugt einen GS1 DataMatrix mit FNC1- und GS-Trennzeichen. symbology ist DataMatrix, Vorgabe 29 × 29 mm; content zeigt den kodierten String mit <GS> als Trennzeichen.

curl -X POST https://api.zplcloud.com/v1/tools/gs1-ai-datamatrix-to-zpl \
  -H "X-API-Key: sk_zplcloud_…" -H "Content-Type: application/json" \
  -d '{"ai":"(01)04006381333931(10)L-2026-0417(17)271231","dpi":300}' | jq -r .zpl

GS1-QR-Code (Digital Link) aus Application Identifiers

POST /v1/tools/gs1-ai-qr-code-to-zpl · Website-Tool. Felder und Prüfung wie bei gs1-ai-128-to-zpl; kodiert eine GS1-Digital-Link-URL in einem QR-Code. Optional domain (Standard id.gs1.org). Die AIs brauchen einen Primärschlüssel wie (01) GTIN, sonst 400. symbology ist QRCode, Vorgabe 36 × 36 mm; content ist die URL.

curl -X POST https://api.zplcloud.com/v1/tools/gs1-ai-qr-code-to-zpl \
  -H "X-API-Key: sk_zplcloud_…" -H "Content-Type: application/json" \
  -d '{"ai":"(01)04006381333931(10)L-2026-0417","domain":"example.com"}' | jq -r .content

GS1 DataBar aus Application Identifiers

POST /v1/tools/gs1-ai-databar-to-zpl · Website-Tool. Felder und Prüfung wie bei gs1-ai-128-to-zpl; erzeugt GS1 DataBar Expanded. "variant": "stacked" (kleingeschrieben) liefert die zweizeilige Form für schmale Labels mit darunter gesetzten Klartextzeilen; jeder andere Wert die einzeilige Form. symbology ist GS1DataBarExpanded oder GS1DataBarExpandedStacked.

curl -X POST https://api.zplcloud.com/v1/tools/gs1-ai-databar-to-zpl \
  -H "X-API-Key: sk_zplcloud_…" -H "Content-Type: application/json" \
  -d '{"ai":"(01)04006381333931(3103)001250(15)261231","variant":"stacked"}' | jq -r .zpl

Sunrise-2027-Migration (GS1 2D)

POST /v1/tools/sunrise-2027-migration · Website-Tool. Setzt neben den GTIN-Barcode jedes Etiketts (EAN/UPC, GS1-128 mit (01), ITF-14, GS1 DataBar) einen GS1-2D-Code: carrier: "qr" = QR-Code mit GS1-Digital-Link-URI, "datamatrix" = GS1 DataMatrix mit Element-Strings. Charge, Verfallsdatum, Seriennummer und weitere AIs des Etiketts werden übernommen, das Symbol kommt mit Ruhezone in eine freie Fläche, und das migrierte ZPL wird mit dem Sunrise-Regelpaket geprüft. Assistent und Vorabprüfung, keine Zertifizierung.

Feld	Typ	Standard	Hinweise
`zpl`	string	Pflicht	Max. 2.000.000 Zeichen.
`carrier`	string	`qr`	`qr` oder `datamatrix`.
`digitalLinkStem`	string	https://id.gs1.org	Domain der Digital-Link-URI (nur QR), http(s) ohne Query.
`dpi`	int	203	152, 203, 300 oder 600.
`extendLabel`	bool	false	Etikett verlängern (`^LL`), wenn keine freie Fläche da ist.
`images`	bool	false	`beforePng`/`afterPng` des ersten Etiketts (Base64).

jq -Rs '{zpl: ., carrier: "qr"}' kaese.zpl \
  | curl -X POST https://api.zplcloud.com/v1/tools/sunrise-2027-migration \
      -H "X-API-Key: sk_zplcloud_…" -H "Content-Type: application/json" --data-binary @-

{
  "success": true, "changed": true,
  "migratedZpl": "^XA … ^FX zplCore GS1 2D migration\n^BY2,3,10^FO280,132^BQN,2,4^FDMA,https://id.gs1.org/01/09506000134352/10/L2604?15=270331^FS …",
  "labels": [ {
    "labelIndex": 0, "status": "migrated",
    "source": { "command": "^BE", "name": "EAN-13", "gtin": "09506000134352", "line": 9 },
    "carrier": "qr", "digitalLinkUri": "https://id.gs1.org/01/09506000134352/10/L2604?15=270331",
    "elementString": "(01)09506000134352(15)270331(10)L2604", "moduleMm": 0.5, …
  } ],
  "sunriseCheck": { "errorCount": 0, "warningCount": 0, "infoCount": 0, "countingErrors": 0, "findings": [] }
}

status: migrated, already migrated, no GTIN carrier, no space (mit Vorschlägen in suggestions), conflict, unsupported. Renders: 1 je Etikett (Header X-ZplCloud-Renders). Summary: { tool, renders, success, labels, migrated }.

Helfer

DPI-Rechner

POST /v1/tools/dpi-calculator · Website-Tool. Rechnet bei einer Druckerauflösung zwischen Millimetern, Zoll, Dots und Punkt um. Alle Felder sind optional; die Antwort enthält nur die angefragten Blöcke plus eine Referenztabelle.

Feld	Typ	Standard	Antwortblock
`dpi`	int	203	72 bis 2400; `dpi`, `dotsPerMm`, `dotsPerInch`
`lengthMm` oder `lengthIn`	number	-	`length { mm, inch, dots }` (`lengthMm` hat Vorrang)
`dots`	number	-	`dots { dots, mm, inch }`
`labelWidthMm`, `labelHeightMm`	number	-	`label { widthMm, heightMm, widthDots, heightDots }`
`fontPt`	number	-	`fontPt { pt, dots }`
`fontDots`	number	-	`fontDots { dots, pt }`
`moduleMm`	number	-	`moduleMm { mm, dots }` (Barcode-Modul, mindestens 1 Dot)
`moduleDots`	number	-	`moduleDots { dots, mm }`

curl -X POST https://api.zplcloud.com/v1/tools/dpi-calculator \
  -H "X-API-Key: sk_zplcloud_…" -H "Content-Type: application/json" \
  -d '{"dpi":300,"lengthMm":100,"fontPt":12,"moduleMm":0.33}'

{
  "dpi": 300,
  "dotsPerMm": 11.811,
  "dotsPerInch": 300,
  "length": { "mm": 100, "inch": 3.937, "dots": 1181 },
  "fontPt": { "pt": 12, "dots": 50 },
  "moduleMm": { "mm": 0.33, "dots": 4 },
  "reference": [
    { "dpi": 203, "dotsPerMm": 7.99, "label100x60mmDots": "799 × 480" },
    { "dpi": 300, "dotsPerMm": 11.81, "label100x60mmDots": "1181 × 709" },
    { "dpi": 600, "dotsPerMm": 23.62, "label100x60mmDots": "2362 × 1417" }
  ]
}

Renders: 1. Summary: { tool, dpi }. Fehler: dpi must be between 72 and 2400.