ZPL-Etiketten-API: Authentifizierung & Webhooks

Basis-URL und Authentifizierung

Punkt	Detail
Basis-URL	`https://api.zplcloud.com` - Pfade beginnen mit `/v1`, ohne `/api`-Präfix.
Header	`X-API-Key: sk_zplcloud_…`
Basic Auth	API-Key als Benutzername, Passwort leer: `curl -u sk_zplcloud_…:`
Key-Präfixe	`sk_zplcloud_` für normale Keys, `sk_sandbox_` für Sandbox-Keys.
Keys anlegen	Plattform → API-Keys (`/platform/api`). Keys werden immer serverseitig erzeugt. Der vollständige Key wird nur einmal direkt nach dem Anlegen angezeigt - zplCloud speichert nur einen SHA-256-Hash. Ein verlorener Key lässt sich nicht wiederherstellen: neuen anlegen und den alten löschen. Ein Key gehört dem Benutzer, der ihn anlegt, und - wenn dieser einer Firma angehört - der Firma.
Sprache	Immer Englisch: Fehlermeldungen, Hinweise und Feldnamen.
Referenz	api.zplcloud.com/scalar - interaktive Referenz mit Request-Builder für jeden öffentlichen Endpunkt, nach Themen gegliedert (siehe Endpunkt-Übersicht unten).

# Header X-API-Key
curl https://api.zplcloud.com/v1/quota -H "X-API-Key: sk_zplcloud_YOUR_KEY"

# Basic Auth: Key als Benutzername, leeres Passwort (Doppelpunkt beachten)
curl https://api.zplcloud.com/v1/quota -u sk_zplcloud_YOUR_KEY:

Worauf ein Key zugreifen kann, richtet sich nach seinem Besitzer: Designs, Drucker, Agents, Webhooks und Batch-Jobs der Firma des Keys - bei Keys ohne Firma die der E-Mail des Besitzers. Alles außerhalb dieses Bereichs gilt als nicht vorhanden.

Sandbox-Keys

Sandbox-Keys (sk_sandbox_…) sind kostenlos und verbrauchen keine Renders, funktionieren aber ausschließlich für /v1/virtual-printers - deren Ausgabe ist ein PNG mit Wasserzeichen. Jeder andere /v1-Pfad antwortet mit 403 und einem Hinweis. Für alle Endpunkte dieser Seite wird ein normaler Key benötigt.

Konventionen

Requests: JSON-Bodys mit camelCase-Feldnamen und Content-Type: application/json. Unbekannte Felder werden ignoriert.
Binäre Eingaben: PDFs und Bilder als Base64-Strings im JSON-Body. Data-URIs wie data:application/pdf;base64,JVBERi0x… werden akzeptiert.
Antworten: Dateien (PDF, PNG, JPG, SVG, rohes ZPL) kommen als Response-Body mit passendem Content-Type, alles andere als JSON.
Request-ID: Jede Antwort eines /v1-Endpunkts trägt X-ZplCloud-Request-Id (GUID) - mitloggen und bei Support-Anfragen angeben. An den Endpunkten mit Webhook-Unterstützung steht dieselbe ID auch als requestId in Fehlerantworten und Webhook-Callbacks.
Zeitstempel sind UTC. Werte aus der Datenbank werden ohne abschließendes Z geschrieben (2026-09-11T08:12:44.193) - trotzdem als UTC behandeln.
Webhook-Callback: Die Query-Parameter webhookId und webhookResult funktionieren beim Rendern als PDF und PNG, an den ZPL-Tools, der Label-Anreicherung, den Batch-Jobs, den Drucker- und Agent-Listen, Kontingent und Webhooks - nicht an den weiteren Endpunkten. Siehe Webhook-Callback.

Fehler

Fehler sind JSON mit lesbarem error, meist einem hint und - an den Endpunkten mit Webhook-Unterstützung - der requestId. Manche Fehler liefern zusätzliche Felder: limit, used und requested bei 429, plan bei 403, wenn ein Endpunkt den Pro-Tarif verlangt, tool bei Tool-Fehlern, jobId bei fehlgeschlagenen Batch-Jobs.

HTTP/1.1 429 Too Many Requests
Content-Type: application/json; charset=utf-8
X-ZplCloud-Request-Id: 8b1d6c3e-2f4a-4e0b-9a7d-5c3e1f2a9b64

{
  "error": "Render limit reached (9950/10000 labels this month, this request needs 500).",
  "hint": "GET /v1/quota shows your current label quota. Upgrade your plan or buy a render top-up under Billing in the platform. The ZPL tools under /v1/tools are not limited.",
  "limit": 10000,
  "used": 9950,
  "requested": 500,
  "requestId": "8b1d6c3e-2f4a-4e0b-9a7d-5c3e1f2a9b64"
}

Requests, die vor jeder Verarbeitung abgewiesen werden - fehlender oder ungültiger API-Key, unbekannte oder deaktivierte webhookId, Sandbox-Key - liefern nur error und hint, ohne requestId im Body. Das 403 für einen Sandbox-Key kommt, bevor der Endpunkt läuft, und hat auch keinen X-ZplCloud-Request-Id-Header.

Statuscodes

Code	Bedeutung
200	Erfolg. `POST /v1/batch/design/{designId}` mit `"async": true` antwortet mit `202 Accepted`.
400	Ungültiges JSON oder ungültige Feldwerte, ungültige `designId`, unbekannte oder deaktivierte `webhookId`, `webhookResult=true` ohne `webhookId`.
401	API-Key fehlt oder ist ungültig.
403	Sandbox-Key außerhalb von `/v1/virtual-printers` verwendet, oder der Key-Besitzer hat nicht den Pro-Tarif, den Batch-Jobs und Label-Anreicherung voraussetzen.
404	Design, Batch-Job oder Drucker im Bereich des Key-Besitzers nicht gefunden; Label-Anreicherung nicht freigeschaltet.
413	Body oder Eingabe zu groß: Body-Größe, Anzahl Datensätze, Zeichen, Dateigröße, Seiten.
429	Label-Kontingent aufgebraucht - nur Design-Renders (ZPL, PDF, PNG) und Batch-Jobs.
499	Der Client hat die Verbindung vor Abschluss geschlossen (erscheint in Logs und Statistik, nicht beim Client).
503	Vorübergehend nicht verfügbar (Datenbank), auch wenn der Tarif für einen Pro-Endpunkt nicht gelesen werden kann. Mit Backoff erneut versuchen.

Label-Kontingent und Render-Zählung

Labels werden je Konto - der E-Mail des API-Key-Besitzers - pro Kalendermonat in UTC gezählt. Es ist derselbe Zähler wie in der Plattform: Labels aus Designer, Print Views und API addieren sich. Am 1. jedes Monats um 00:00 UTC beginnt der Zähler wieder bei 0.

Tarif	Labels pro Monat	Batch-Jobs und Label-Anreicherung
Developer (kostenlos)	100	Nein - 403
Starter	10.000	Nein - 403
Pro	100.000	Ja
Render-Top-ups	Kommen zum Tarif-Limit hinzu (Kauf unter Billing in der Plattform).	-

Alles andere - Design-Rendering als ZPL, PDF und PNG, die ZPL-Tools, Drucker- und Agent-Listen, Kontingent und Webhooks - funktioniert in jedem Tarif. POST /v1/batch/design/{designId} und POST /v1/enrich/zpl prüfen zuerst den Tarif des Key-Besitzers (GET /v1/quota → plan) und antworten anderen Tarifen mit 403, oder mit 503, wenn der Tarif nicht lesbar ist. Status, Ausgabe und Pickliste eines Batch-Jobs (GET /v1/batch/jobs/…) werden nicht auf den Tarif geprüft.

Was begrenzt und was gezählt wird

Endpunkt	Kontingent-Prüfung	Gezählte Renders
`POST /v1/zpl/render/design/{designId}`	Ja - 429	1 je Datensatz (mindestens 1)
`POST /v1/pdf/render/design/{designId}`	Ja - 429	1 je Seite (= Datensatz, mindestens 1)
`POST /v1/png/render/design/{designId}`	Ja - 429	1
`POST /v1/batch/design/{designId}`	Ja - 429 (nur Pro-Tarif)	1 je Datensatz
`POST /v1/tools/zpl-to-pdf`	Nie blockiert	1 je Label im ZPL
`POST /v1/tools/pdf-to-zpl`	Nie blockiert	1 je konvertierter Seite
Alle anderen `/v1/tools/{slug}`	Nie blockiert	1 je Aufruf
`POST /v1/enrich/zpl`	Nie blockiert (nur Pro-Tarif)	1 je angereichertem Label
Batch-Job-Status, -Ausgabe und -Pickliste; Drucker, Agents, Kontingent, Webhooks	Nein	0

Die Prüfung läuft, bevor gerendert wird: Übersteigt used + requested das Limit, antwortet der Request mit 429 und es wird nichts gezählt.
ZPL-Tools und Label-Anreicherung haben kein Rate-Limit und funktionieren auch bei aufgebrauchtem Kontingent weiter. Ihre Renders zählen trotzdem - sie können den Zähler über das Limit schieben, und der nächste Design-Render oder Batch-Job erhält dann 429.
Fehlgeschlagene Requests (Status ab 400) zählen nichts.
Gezählt wird gepuffert je Konto: Limit und Verbrauch werden 60 Sekunden zwischengespeichert, neue Renders zählen sofort im Speicher mit und werden alle 5 Sekunden in die Datenbank geschrieben. GET /v1/quota und die 429-Prüfung sehen neue API-Renders deshalb sofort und in der Plattform gerenderte Labels spätestens nach 60 Sekunden; das Dashboard der Plattform kann einige Sekunden hinterherhinken.
Die API-Nutzung erscheint zusätzlich in der API-Statistik im Dashboard.

Aktuelle Werte: GET /v1/quota.

Webhook-Callback

Die Endpunkte der Übersicht - alle außer den weiteren Endpunkten - akzeptieren zwei optionale Query-Parameter. Damit ruft zplCloud nach Abschluss des Requests einen hinterlegten Webhook auf - ohne Polling und bei asynchronen Batch-Jobs ohne offene Verbindung. Der Callback läuft über das reguläre Webhook-System: mit dem Webhook-Secret signiert, bei Fehlern wiederholt und im Zustell-Log der Plattform sichtbar.

Parameter

Parameter	Wert	Bedeutung
`webhookId`	Zahl	ID eines hinterlegten Webhooks (wo sie steht). Er muss aktiv sein und dem Key-Besitzer gehören: der Firma des Keys, bei Keys ohne Firma der E-Mail des Besitzers.
`webhookResult`	`true` / `false` (Standard `false`)	`true` legt das Ergebnis - PDF, PNG, ZPL, JSON - in den Callback. Setzt `webhookId` voraus.

curl -X POST "https://api.zplcloud.com/v1/tools/zpl-to-pdf?webhookId=12&webhookResult=true" \
  -H "X-API-Key: sk_zplcloud_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{"zpl":"^XA^FO50,50^A0N,40,40^FDHello^FS^XZ","dpi":203}' \
  -o label.pdf -D -

HTTP/1.1 200 OK
Content-Type: application/pdf
X-ZplCloud-Request-Id: 3f0c9a52-7d1e-4b8a-9c61-2e5f4d8b7a10
X-ZplCloud-Webhook: queued

Wann der Callback kommt

Nach Abschluss des Requests - bei Erfolg und bei Fehlern. Validierungsfehler (400), fehlender Pro-Tarif (403), nicht gefunden (404), zu groß (413) und Kontingent (429) werden mit status: "failed", HTTP-Status und Fehlermeldung gemeldet.
Erst nach Authentifizierung und Webhook-Prüfung. Ungültiger Key (401), Sandbox-Key (403), unbekannte oder deaktivierte webhookId oder webhookResult=true ohne webhookId (400) werden sofort beantwortet, bevor gearbeitet wird, und lösen keinen Callback aus. Ebenso wenig abgebrochene Requests (499) und ein 503 bei der Authentifizierung.
Unabhängig von den Event-Abos des Webhooks - webhookId adressiert den Webhook direkt.
Response-Header X-ZplCloud-Webhook: queued = Callback zur Zustellung gespeichert (meist innerhalb von Sekunden zugestellt), failed = konnte nicht eingereiht werden, z. B. weil der Webhook inzwischen deaktiviert wurde. Der Header wird nur gesetzt, wenn webhookId übergeben wurde.
Asynchrone Batch-Jobs ("async": true): Die 202-Antwort hat keinen X-ZplCloud-Webhook-Header, aber ein webhook-Objekt (id, includeResult, event). Der Callback api.batch.completed folgt, wenn der Job fertig ist; seine requestId ist die jobId.

Payload

zplCloud sendet einen POST mit JSON-Body. Beispiel: Design als PDF gerendert, mit webhookResult=true:

{
  "event": "api.design.pdf",
  "timestamp": "2026-09-11T10:15:02Z",
  "requestId": "3f0c9a52-7d1e-4b8a-9c61-2e5f4d8b7a10",
  "operation": "POST /v1/pdf/render/design/{designId}",
  "status": "succeeded",
  "httpStatus": 200,
  "durationMs": 184,
  "renders": 2,
  "summary": {
    "design": "shipping-label.42",
    "format": "pdf",
    "pages": 2,
    "bytes": 48211,
    "widthMm": 100,
    "heightMm": 150,
    "dpi": 203
  },
  "error": null,
  "resultIncluded": true,
  "result": {
    "contentType": "application/pdf",
    "encoding": "base64",
    "size": 48211,
    "data": "JVBERi0xLjcKJeLjz9MKMSAwIG9iago8PC9UeXBlL0NhdGFsb2cv..."
  }
}

Ohne webhookResult=true und bei jedem Fehler gibt es kein result, resultIncluded ist false. Beispiel: Batch-Job wegen aufgebrauchten Kontingents abgewiesen:

{
  "event": "api.batch.completed",
  "timestamp": "2026-09-11T10:17:40Z",
  "requestId": "8b1d6c3e-2f4a-4e0b-9a7d-5c3e1f2a9b64",
  "operation": "POST /v1/batch/design/{designId}",
  "status": "failed",
  "httpStatus": 429,
  "durationMs": 36,
  "renders": 0,
  "summary": {
    "hint": "GET /v1/quota shows your current label quota. ...",
    "limit": 10000,
    "used": 9950,
    "requested": 500
  },
  "error": "Render limit reached (9950/10000 labels this month, this request needs 500).",
  "resultIncluded": false
}

Feld	Bedeutung
`event`	Event-Name (Tabelle unten), zusätzlich als Header `X-ZplCloud-Event`.
`timestamp`	UTC-Zeitpunkt, zu dem der Request fertig war (ISO 8601, Sekunden).
`requestId`	Dieselbe GUID wie im Response-Header `X-ZplCloud-Request-Id` (asynchrone Batch-Jobs: die `jobId`). Damit Callbacks den Aufrufen zuordnen und Duplikate verwerfen.
`operation`	HTTP-Methode und Routen-Template, z. B. `POST /v1/tools/zpl-to-pdf` oder `GET /v1/batch/jobs/{jobId}`.
`status`	`succeeded` (HTTP-Status unter 400) oder `failed`.
`httpStatus`	Statuscode der API-Antwort. Asynchrone Batch-Jobs: der Status, mit dem der Job endete (`500` bei Abbruch).
`durationMs`	Verarbeitungszeit in Millisekunden.
`renders`	Für diesen Aufruf gezählte Labels; bei Fehlern immer `0`.
`summary`	Kurze, endpunktspezifische Eckdaten (siehe Event-Tabelle). Bei Fehlern: die zusätzlichen Fehlerfelder, z. B. `{ tool }` oder `{ hint, limit, used, requested }`, oder `null`.
`error`	Fehlermeldung bei Fehlern, sonst `null`.
`resultIncluded`	`true`, wenn `result` enthalten ist.
`result`	Nur mit `webhookResult=true` und bei Erfolg: `{ contentType, encoding, size, data }`.
`resultOmitted`	Nur mit `webhookResult=true`, wenn das Ergebnis zu groß ist: erklärt, warum `result` fehlt.

Ergebnis-Kodierung

encoding	Verwendet für	data / size
`base64`	Datei-Antworten: PDF, PNG, JPG sowie die Dateien von `/v1/batch/jobs/{jobId}/output` und `/picklist` (auch wenn die Ausgabe ZPL ist).	Base64-String der Datei; `size` = Dateigröße in Bytes.
`utf-8`	Text-Antworten: SVG von `zpl-to-svg`, rohes ZPL von `/v1/enrich/zpl?format=zpl`.	Der Text selbst; `size` = UTF-8-Bytes.
`json`	JSON-Antworten: Konverter, Linter, Analyser, Listen, Kontingent, Batch-Jobs.	Das vollständige Antwortobjekt wie in der HTTP-Antwort; `size` = serialisierte Bytes.

Grenze 10 MB. Größere Ergebnisse werden weggelassen: resultIncluded ist false, resultOmitted nennt den Grund - das Ergebnis dann aus der API-Antwort nehmen (Batch-Jobs: GET /v1/batch/jobs/{jobId}/output innerhalb einer Stunde). Bei Dateien gilt die Grenze für die Base64-Größe, Dateien bis etwa 7,5 MB passen also hinein.

Event-Namen

Event	Endpunkt	summary
`api.design.pdf`	`POST /v1/pdf/render/design/{designId}`	`design`, `format`, `pages`, `bytes`, `widthMm`, `heightMm`, `dpi`
`api.design.png`	`POST /v1/png/render/design/{designId}`	`design`, `format`, `record`, `bytes`, `widthMm`, `heightMm`, `dpi`
`api.tool.completed`	`POST /v1/tools/{slug}`	`tool` (der Slug) plus toolspezifische Werte, z. B. `labels`, `bytes`, `zplBytes`, `errorCount`
`api.enrich.completed`	`POST /v1/enrich/zpl`	`labels`, `fields`, `records`, `dpi`, `zplBytes`
`api.batch.completed`	`POST /v1/batch/design/{designId}` (synchron und asynchron)	`jobId`, `jobStatus`, `design`, `labels`, `output`, `outputBytes`, `printer`, `printedLabels`, `printError`, `error`
`api.batch.status`	`GET /v1/batch/jobs/{jobId}`	wie `api.batch.completed`
`api.batch.output`	`GET /v1/batch/jobs/{jobId}/output`	wie `api.batch.completed`
`api.batch.picklist`	`GET /v1/batch/jobs/{jobId}/picklist`	wie `api.batch.completed`
`api.printers.listed`	`GET /v1/printers`	`scope`, `count`, `weblink`, `remote`
`api.company.printers.listed`	`GET /v1/company/printers`	`scope`, `count`, `weblink`, `remote`, `virtual`
`api.agents.listed`	`GET /v1/agents`	`scope`, `count`, `online`
`api.company.agents.listed`	`GET /v1/company/agents`	`scope`, `count`, `online`
`api.quota.checked`	`GET /v1/quota`	`plan`, `limit`, `used`, `remaining`
`api.webhooks.listed`	`GET /v1/webhooks`	`count`

Zustellung und Wiederholungen

Header	Wert
`Content-Type`	`application/json`
`User-Agent`	`zplcloud-webhooks/1.0`
`X-ZplCloud-Event`	Event-Name, z. B. `api.design.pdf`.
`X-ZplCloud-Delivery`	Numerische ID der Zustellung; bleibt bei Wiederholungen gleich.
`X-ZplCloud-Timestamp`	Zeitpunkt dieses Versuchs, ISO 8601 UTC, z. B. `2026-09-11T10:15:02.4817731Z`.
`X-ZplCloud-Signature`	HMAC-SHA256 des rohen Bodys mit dem Webhook-Secret als Schlüssel, hex in Kleinbuchstaben. Ohne `sha256=`-Präfix.

Der Empfänger muss innerhalb von 10 Sekunden mit einem beliebigen 2xx antworten. Andere Statuscodes, Timeouts und Verbindungsfehler gelten als fehlgeschlagen.
Wiederholungen nach 1 Minute, 5 Minuten und 30 Minuten; nach dem vierten fehlgeschlagenen Versuch gilt die Zustellung als fehlgeschlagen. Der Body ist bei jedem Versuch identisch.
Zugestellt wird nur an aktive Webhooks; das Deaktivieren eines Webhooks pausiert die Zustellung.
Jeder Versuch steht im Zustell-Log des Webhooks in der Plattform (Webhooks → Log); fehlgeschlagene Zustellungen lassen sich dort manuell wiederholen.
Ein Callback kann mehrfach ankommen, z. B. wenn das 2xx erst nach dem Timeout eintrifft. Duplikate anhand der requestId erkennen.

Erst antworten, dann verarbeiten

Signatur prüfen, Payload speichern und sofort mit 2xx antworten. Längere Arbeit innerhalb des Requests - Drucken, Ergebnis hochladen, ERP aufrufen - riskiert das 10-Sekunden-Timeout und löst Wiederholungen eines bereits verarbeiteten Callbacks aus.

Signatur prüfen

HMAC-SHA256 über die rohen Bytes des Request-Bodys berechnen - vor jedem JSON-Parsing - mit dem Webhook-Secret als Schlüssel (in der Plattform unter Webhooks einsehbar), hex in Kleinbuchstaben kodieren und in konstanter Zeit mit X-ZplCloud-Signature vergleichen.

Node.js (Express):

import crypto from "node:crypto";
import express from "express";

const app = express();
const secret = process.env.ZPLCLOUD_WEBHOOK_SECRET;

// express.raw: die Signatur gilt für die exakten Bytes, also nicht vorher JSON parsen
app.post("/hooks/zplcloud", express.raw({ type: "application/json", limit: "16mb" }), (req, res) => {
  const expected = crypto.createHmac("sha256", secret).update(req.body).digest("hex");
  const received = req.get("X-ZplCloud-Signature") ?? "";
  const valid = received.length === expected.length &&
    crypto.timingSafeEqual(Buffer.from(received), Buffer.from(expected));
  if (!valid) return res.sendStatus(401);

  const payload = JSON.parse(req.body.toString("utf8"));
  res.sendStatus(204);        // innerhalb von 10 s antworten
  handleCallback(payload);    // eigener Code: Duplikate per payload.requestId, payload.result speichern
});

app.listen(3000);

C# (ASP.NET Core Minimal API):

using System.Security.Cryptography;
using System.Text;
using System.Text.Json;

app.MapPost("/hooks/zplcloud", async (HttpRequest request) =>
{
    using var buffer = new MemoryStream();
    await request.Body.CopyToAsync(buffer);   // rohe Bytes, vor jedem JSON-Parsing
    var body = buffer.ToArray();

    var secret = Environment.GetEnvironmentVariable("ZPLCLOUD_WEBHOOK_SECRET")!;
    var expected = Convert.ToHexString(
        HMACSHA256.HashData(Encoding.UTF8.GetBytes(secret), body)).ToLowerInvariant();
    var received = request.Headers["X-ZplCloud-Signature"].ToString();
    if (!CryptographicOperations.FixedTimeEquals(
            Encoding.ASCII.GetBytes(expected), Encoding.ASCII.GetBytes(received)))
        return Results.Unauthorized();

    using var payload = JsonDocument.Parse(body);
    var requestId = payload.RootElement.GetProperty("requestId").GetString();
    // Payload speichern, im Hintergrund verarbeiten, Duplikate per requestId erkennen
    return Results.NoContent();
});

Webhook-IDs finden

Plattform → Webhooks (/platform/webhooks): Webhook mit der Empfänger-URL anlegen; jeder Webhook zeigt seine ID als Badge, z. B. ID 12. Dort steht auch das Secret für die Signatur.
GET /v1/webhooks listet ID, URL, Status und letzte Zustellung aller hinterlegten Webhooks - siehe Drucker, Agents & Kontingent.
Welche Events ein Webhook abonniert hat, spielt für den Callback keine Rolle.

Endpunkt-Übersicht

Die interaktive Referenz enthält die gesamte öffentliche API und gliedert sie mit englischen Namen: Rendering (Design rendering, Batch jobs, Label enrichment, Fonts), ZPL tools (Render ZPL, Convert to ZPL, Barcodes & GS1, Validate & analyse), Printing (Printers, Agents & watch folders, Remote printers, Virtual printers, Printer profiles & cookbook, Weblink certificates), Account (Quota & webhooks) und Integrations (DHL). Diese Übersicht ist nach Webhook-Unterstützung sortiert: alle folgenden Endpunkte akzeptieren webhookId und webhookResult, außer den weiteren Endpunkten. designId ist <name>.<id>, z. B. shipping-label.42.

Rendering

Endpunkt	Body	Ergebnis	Event
`POST /v1/pdf/render/design/{designId}`	JSON-Array mit Datensätzen (optional, max. 2.000, 5 MB)	PDF, eine Seite je Datensatz	`api.design.pdf`
`POST /v1/png/render/design/{designId}?record=0`	JSON-Array mit Datensätzen (optional)	PNG eines Labels	`api.design.png`

Batch-Jobs

Endpunkt	Zweck	Event
`POST /v1/batch/design/{designId}`	Datensätze → ZPL oder PDF, optional Pickliste, optional Druck in Blöcken zu 100 Labels; synchron `200` oder `"async": true` → `202`	`api.batch.completed`
`GET /v1/batch/jobs/{jobId}`	Job-Status, Zeiten, Druckfortschritt	`api.batch.status`
`GET /v1/batch/jobs/{jobId}/output`	Erzeugtes ZPL oder PDF (bis 20 MB, 1 Stunde abrufbar)	`api.batch.output`
`GET /v1/batch/jobs/{jobId}/picklist`	Pickliste als PDF	`api.batch.picklist`

Einen Job starten setzt den Pro-Tarif voraus (sonst 403); Status, Ausgabe und Pickliste eines bestehenden Jobs werden nicht auf den Tarif geprüft.

Label-Anreicherung

Endpunkt	Body	Ergebnis	Event
`POST /v1/enrich/zpl`	Carrier- oder Amazon-`zpl`, `fields`, `records`, `dpi`	JSON `{ zpl, labels }` oder rohes ZPL mit `?format=zpl`	`api.enrich.completed`

Ergänzt jedes Label um eigene Felder (SKU, Lagerplatz, PO), ohne die Original-Kommandos anzufassen. Nur verfügbar, wenn die Label-Anreicherung freigeschaltet ist (sonst 404), und im Pro-Tarif (sonst 403).

ZPL-Tools

Alle Tools sind POST /v1/tools/{slug} mit JSON-Body; Event api.tool.completed. Nie durch das Kontingent blockiert.

Tool	Wichtigste Eingaben	Ergebnis
`zpl-to-pdf`	`zpl`, `dpi`, `widthMm`, `heightMm`	PDF mit allen Labels
`zpl-to-png` `zpl-to-jpg` `zpl-to-svg`	`zpl`, `dpi`, `widthMm`, `heightMm`	PNG, JPG oder SVG des ersten Labels
`zpl-linter`	`zpl`, `profile` (`amazon-fba`)	JSON: Fehler, Warnungen und Hinweise
`zpl-analyser`	`zpl`, `networkMbit`	JSON: Kommandos, Labelgröße, Geschwindigkeit, Schwärzung, Zeit je Label
`html-to-zpl`	`pngBase64` (HTML als PNG gerendert), `dpi`, `widthMm`, `heightMm`	JSON mit ZPL
`pdf-to-zpl`	`pdfBase64`, `pages`, `scale`, `rotate`, `darkness`	JSON mit ZPL (max. 100 Seiten)
`image-to-zpl`	`imageBase64` (PNG, JPG, GIF, BMP)	JSON mit ZPL und GRF
`svg-to-zpl`	`svg`, `dpi`, `sizeMm`	JSON mit ZPL
`epl2-to-zpl` `dpl-to-zpl` `tspl-to-zpl`	`code`	JSON mit ZPL
`zpl-to-tspl` `zpl-to-epl2` `zpl-to-dpl` `zpl-to-sbpl` `zpl-to-cpcl` `zpl-to-escpos` `zpl-to-brother` `zpl-to-pcl` `zpl-to-easyplug` `zpl-to-tpcl` `zpl-to-jscript`	`zpl`, `dpi`, `compress` (dazu `hex`, `cut`, `paper`, `model` je Sprache)	Roher Druckauftrag für TCP 9100
`barcode-to-zpl`	`symbology`, `data`	JSON mit ZPL
`qr-code-to-zpl`	`type` (url, wifi, vcard …), `fields`	JSON mit ZPL
`gs1-ai-128-to-zpl` `gs1-ai-datamatrix-to-zpl` `gs1-ai-qr-code-to-zpl` `gs1-ai-databar-to-zpl`	`ai` in Klammer-Notation, z. B. `(01)04006381333931(10)L-2026-0417`	JSON mit ZPL und zerlegten AI-Elementen
`check-barcode`	`imageBase64` (Foto oder Scan) oder `data`	JSON: erkannte und geprüfte Codes
`dpi-calculator`	`dpi`, `lengthMm`, `dots`, `fontPt` …	JSON: Umrechnungen und Referenztabelle

Drucker & Agents

Endpunkt	Zweck	Event
`GET /v1/printers`	Drucker, die an den API-Key gebunden sind	`api.printers.listed`
`GET /v1/company/printers`	Alle Drucker der Firma: Weblink, Remote, virtuell - mit `target` für Batch-Jobs	`api.company.printers.listed`
`GET /v1/agents`	zplCloud-CLI-Agents, die sich mit dem API-Key verbinden	`api.agents.listed`
`GET /v1/company/agents`	Alle Agents der Firma über alle Keys	`api.company.agents.listed`

Konto & Kontingent

Endpunkt	Zweck	Event
`GET /v1/quota`	Tarif, monatliches Label-Limit, verbrauchte und verbleibende Labels, Zeitraum	`api.quota.checked`
`GET /v1/webhooks`	Hinterlegte Webhooks mit ihren IDs (ohne Secrets)	`api.webhooks.listed`

Weitere Endpunkte

Diese Endpunkte kennen die Webhook-Parameter nicht. Sie stehen ebenfalls in der interaktiven Referenz.

Endpunkt	Zweck
`POST /v1/zpl/render/design/{designId}`	Gespeichertes Design als ZPL rendern (max. 500 Datensätze) - zählt einen Render je Datensatz gegen das Label-Kontingent, `429`, wenn es aufgebraucht ist.
`GET /v1/fonts` `GET /v1/fonts/platform/{name}`	Systemschriften; Plattform-Druckerschrift wie `ZPLCLOUD.TTF` herunterladen.
`GET /v1/printer-profiles`, `/{id}`	Druckerprofile mit ihren Kommandos in Reihenfolge (genutzt von `zplcloud profiles apply`).
`GET /v1/zpl-cookbook`, `/{id}`	Kommandos aus dem ZPL-Cookbook.
`GET /v1/remote-printers` `POST /v1/remote-printers/{id}/send`, `/file`, `/raw`	Remote-Drucker hinter einem zplCloud-CLI-Agent: auflisten, ZPL/SGD senden, `~DY`-Datei hochladen, Auftrag in einer anderen Druckersprache byte-genau drucken (fertig oder aus ZPL umgewandelt - siehe Den Auftrag drucken).
`GET /v1/virtual-printers` `POST /v1/virtual-printers/{id}/print` `GET /v1/virtual-printers/prints/{id}`, `.png`	Virtuelle Testdrucker - die einzigen Endpunkte für Sandbox-Keys.
`POST /v1/weblink/certificates/generate` `GET /v1/weblink/certificates/domains/…`	Weblink-Zertifikate (genutzt von `zplcloud weblink setup`).
`POST /v1/integrations/dhl/stamp` `GET /v1/integrations/dhl/stamps`, `/status`	DHL Internetmarke - siehe Integrationen.
`POST /v1/print/folder` `GET /v1/agents/folders`	Watch-Ordner-Druck über einen Agent: ZPL oder Aufträge anderer Druckersprachen mit `language` bzw. `base64` - siehe zplCloud CLI.

Schnellstart

1. Kontingent abfragen - zugleich ein schneller Test des Keys:

curl https://api.zplcloud.com/v1/quota -H "X-API-Key: sk_zplcloud_YOUR_KEY"

2. ZPL als PNG rendern - ein ZPL-Tool, zählt einen Render und wird nie blockiert:

curl -X POST https://api.zplcloud.com/v1/tools/zpl-to-png \
  -H "X-API-Key: sk_zplcloud_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{"zpl":"^XA^FO50,50^A0N,40,40^FDHello zplCloud^FS^XZ","dpi":203,"widthMm":75,"heightMm":50}' \
  -o label.png

3. Design als PDF rendern und zurückrufen lassen - zwei Datensätze, zwei Seiten, zwei Renders; Webhook 12 erhält api.design.pdf:

curl -X POST "https://api.zplcloud.com/v1/pdf/render/design/shipping-label.42?webhookId=12" \
  -u sk_zplcloud_YOUR_KEY: \
  -H "Content-Type: application/json" \
  -d '[{"sku":"A-1001","qty":"2"},{"sku":"A-1002","qty":"5"}]' \
  -o labels.pdf

Mit &webhookResult=true kommt das PDF zusätzlich als Base64 im Callback. Weiter mit: Rendering, ZPL-Tools, Drucker, Agents & Kontingent.