API-Referenz

Labelixa REST-API-Referenz: Render- und Barcode-Endpunkte, Anfrage-/Antwort-Header, Fehlercodes und Authentifizierung per API-Schlüssel.

Authentifizierung

Die kostenlose Stufe funktioniert ohne Schlüssel (IP-basiertes Limit); kein Tarif fügt der Ausgabe ein Wasserzeichen hinzu. Senden Sie den Schlüssel im Header X-API-Key; er erhöht die Limits. Der Query-Parameter ?key= funktioniert weiterhin, ist aber veraltet (Abschaltung 2027-01-31): Query-Strings gelangen in Browser-Verlauf, Referer-Header, Proxy-Logs und geteilte Links. Solche Anfragen erhalten Deprecation- und Sunset-Antwortheader.

API-Stabilität

Innerhalb von /v1 kommt nur Neues hinzu: neue Antwortfelder, neue optionale Parameter und neue Endpunkte können jederzeit auftauchen — ignorieren Sie Felder, die Sie nicht kennen. Ein Breaking Change — ein entferntes oder umbenanntes Feld, ein geänderter Typ oder eine geänderte Bedeutung, ein neu definierter Fehlercode — erscheint als neue Hauptversion neben dieser. Entfällt ein Endpunkt oder ein Auth-Verfahren, erhalten Sie mindestens sechs Monate Vorlauf, Deprecation- und Sunset-Header mit dem Entfernungsdatum und danach 410 Gone samt Verweis auf den Nachfolger — nie ein stilles 404. Das ist eine vertragliche Zusage, keine Gewohnheit: AGB §24.4.1.

Endpunkte

Anfrage-Header

Antwort-Header

Fehlercodes

In der Barcode-API werden ungültige Daten zusammen mit HTTP 200 als Bild zurückgegeben (Kompatibilität mit No-Code-Tools), und das Detail steht im Header X-Warnings.

Datenextraktion (JSON)

Wenn Sie Accept: application/json an den Render-Endpunkt senden, werden die sichtbaren Text- und Barcode-Felder des Etiketts zusammen mit ihren Koordinaten als JSON zurückgegeben (Barcodes werden mit tur: barkod gekennzeichnet):

curl -X POST "https://api.labelixa.com/v1/printers/8dpmm/labels/4x6/0" \
     --data "^XA^FO50,60^FDHello^FS^XZ" -H "Accept: application/json"

ZPL-Umwandlung (application/zpl)

Mit Accept: application/zpl wird Ihr ZPL neu formatiert (jeder Befehl in einer eigenen Zeile; mit X-Formatter: Off deaktiviert), und wenn X-Target-Dpmm angegeben ist, werden die Koordinaten-/Größenparameter von der Quell- zur Zielauflösung skaliert. Datenfelder (^FD) ändern sich nicht.

curl -X POST "https://api.labelixa.com/v1/printers/8dpmm/labels/4x6/0" \
     --data-binary @label.zpl -H "Accept: application/zpl" \
     -H "X-Target-Dpmm: 12" > label-12dpmm.zpl

EPL2-Ausgabe (application/epl)

Mit Accept: application/epl wird Ihr Etikett in EPL2 umgewandelt — die Sprache älterer Zebra-Drucker. Text-, Barcode-, Kasten- und Linienfelder werden zu EPL2-Befehlen; Größen werden aus der Punktdichte des Druckers berechnet (8dpmm = 203 dpi, 12dpmm = 300 dpi — die EPL2-Schriftmaße UNTERSCHEIDEN sich zwischen beiden, die richtige Tabelle wird automatisch gewählt). Unterstützte Barcodes: ^BC Code 128, ^B3 Code 39, ^BE EAN-13, ^B8 EAN-8, ^BU UPC-A, ^B2 Interleaved 2/5, ^BK Codabar.

EPL2 hat einen kleineren Befehlssatz als ZPL, daher lässt sich nicht jedes Etikett eins zu eins umwandeln. Nichts entfällt stillschweigend: was nicht übersetzt werden konnte, wird im X-Warnings-Header benannt. Derzeit nicht umgewandelt: QR (^BQ), DataMatrix (^BX), eingebettete Grafiken (^GF) und Textblöcke (^FB). Zudem ist die EPL2-Textgröße nicht stufenlos — feste Schrift x ganzzahliger Multiplikator — und die schmale Balkenbreite ist je Symbologie begrenzt (1-10 bei Code 128, 2-4 bei EAN/UPC); ein Wert außerhalb wird gekappt und ebenfalls gemeldet.

curl -X POST "https://api.labelixa.com/v1/printers/8dpmm/labels/4x6/" \
     --data-binary @label.zpl -H "Accept: application/epl" \
     -D headers.txt > label.epl

Ausgehende Webhooks

Statt den Status eines Massenauftrags abzufragen, können wir Sie benachrichtigen. Registrieren Sie einen Endpunkt mit POST /v1/webhooks; die Ereignisse sind toplu.tamamlandi und toplu.basarisiz.

curl -X POST "https://api.labelixa.com/v1/webhooks" \
     -H "X-API-Key: $LABELIXA_KEY" -H "Content-Type: application/json" \
     -d '{"url": "https://erp.example.com/labelixa"}'

Das Signaturgeheimnis wird NUR in dieser Antwort zurückgegeben und in Auflistungen nie wieder gezeigt; geht es verloren, löschen Sie den Endpunkt und legen ihn neu an. Das Geheimnis ist vom API-Schlüssel des Kontos getrennt: Ein Schlüsselwechsel bricht die Webhook-Prüfung nicht.

Jede Anfrage trägt Labelixa-Signature: t=<unix>,v1=<hmac>. Der HMAC-SHA256 wird über "<t>.<body>" berechnet — der Zeitstempel steckt IN der Signatur, sodass Sie Replays über seine Aktualität ausschließen können. Das Format entspricht dem von Stripe; Code, der Stripe-Webhooks prüft, lässt sich übernehmen.

import hmac, hashlib, time

def verify(secret, body, header, tolerance=300):
    p = dict(x.split("=", 1) for x in header.split(","))
    t = int(p["t"])
    if abs(time.time() - t) > tolerance:
        return False
    expected = hmac.new(secret.encode(), f"{t}.".encode() + body,
                        hashlib.sha256).hexdigest()
    return hmac.compare_digest(p["v1"], expected)

Jede Anfrage trägt zudem Labelixa-Delivery-Id, und diese Kennung ändert sich bei Wiederholungen NICHT. Sehen Sie dieselbe Kennung ein zweites Mal, führen Sie die Verarbeitung nicht erneut aus — die Zustellung erfolgt mindestens einmal.

Geheimnisrotation

POST /v1/webhooks/{id}/rotate erzeugt ein neues Geheimnis. Das alte bleibt während eines Übergangsfensters gültig (standardmäßig 24 Stunden); in dieser Zeit trägt jede Anfrage ZWEI Signaturen (v1=… ,v1=…). Es passt diejenige, die Ihre Prüfung kennt — Sie können also unterbrechungsfrei rotieren. Die Restzeit steht im Feld rotasyon_bitis der Antwort von GET /v1/webhooks.

Ihr Prüfcode muss MEHRERE v1-Werte unterstützen — wer den Header in ein Wörterbuch umwandelt und einen einzelnen Wert liest, sieht nur den letzten und lehnt in der ersten Hälfte einer Rotation gültige Signaturen ab.

Jede Antwort außer 2xx gilt als Fehlschlag und wird wiederholt; Weiterleitungen (3xx) werden NICHT verfolgt. Ein dauerhaft fehlschlagender Endpunkt wird automatisch deaktiviert — die Auflistung zeigt dann aktif: false und den letzten Statuscode. Der Rumpf enthält KEINE Zeilendaten: nur Auftragskennung und Zähler; das Ergebnis holen Sie über die Auftragskennung.

Gespeicherte Etiketten

Render-Endpunkte sind zustandslos und speichern nichts; das Speichern geschieht nur über diese Endpunkte, auf ausdrückliche Anfrage. Ein Bezahlplan ist erforderlich (Starter 50, Professional 500 gespeicherte Etiketten; Enterprise unbegrenzt). Dieses Limit ist unabhängig vom täglichen Kontingent: das eine zählt, wie viele Etiketten Sie drucken, das andere, wie viele Designs Sie aufbewahren.

Gleichzeitigkeit (If-Match)

Jede Leseantwort enthält ein ETag, und jede Schreibanfrage erfordert den Header If-Match: ohne ihn kommt 428 zurück, mit veralteter Version 412 (der Rumpf enthält die aktuelle Version). So kann ein zweiter Browser-Tab die Änderungen des ersten nicht stillschweigend überschreiben. Zum bewussten Überschreiben senden Sie If-Match: *.

Versionen und Papierkorb

Jede Aktualisierung sichert den vorherigen Stand (die letzten 50 Versionen pro Etikett bleiben erhalten). Das Wiederherstellen einer alten Version wird als neue Version geschrieben — auch das Wiederherstellen ist also umkehrbar. Ein gelöschtes Etikett bleibt 30 Tage im Papierkorb; aktive Etiketten werden unbegrenzt aufbewahrt. Idempotency-Key gilt auch für POST /v1/labels: eine Wiederholung mit demselben Schlüssel nach einem Netzwerk-Timeout erzeugt kein zweites Etikett.

MCP-Server für KI-Assistenten

Claude, ChatGPT und andere MCP-fähige KI-Clients können Labelixa direkt als Werkzeug verwenden: Der entfernte MCP-Server läuft unter https://api.labelixa.com/mcp (streamable HTTP, JSON-RPC; keine Installation — eine URL in den Client einfügen genügt). Ein Schlüssel ist nicht erforderlich — anonyme Nutzung unterliegt den Limits der kostenlosen Stufe; mit Authorization: Bearer lbx_... verbrauchen Sie Ihr eigenes Kontokontingent.

MCP-Aufrufe zählen gegen dieselben Kontingente und Ratenlimits wie REST — MCP ist keine separate Stufe, sondern dieselbe API mit Werkzeug-Gesicht. Die Tabelle zeigt eine Auswahl; die vollständige, stets aktuelle Liste liefert der Live-Server (tools/list) und die Seite /mcp.

Ein gedrucktes Etikett zurücklesen

POST /v1/verify liest die Barcodes in einem Foto oder Scan, den Sie hochladen — die Antwort auf "gedruckt, aber liest das Handgerät es auch?". Der Rumpf wird als multipart/form-data gesendet, das Bild im Feld file; akzeptiert werden PNG, JPEG, BMP und GIF, bis 5 MB und 6000×6000 Pixel. Die Antwort enthält olculdu (lief der Decoder), eine Liste okunan (je format und veri) und ein Feld not.

Nicht zu verwechseln mit POST /v1/barcode-check: dort ist die Eingabe ZPL — wir rendern das Etikett und lesen zurück, was wir selbst gezeichnet haben. Hier ist die Eingabe ein Bild aus der realen Welt.

Die Grenzen des Ergebnisses stehen in der Antwort und sind ernst zu nehmen: "gelesen" GARANTIERT nicht, dass jedes Handgerät es liest, und "nicht gelesen" BEWEIST nicht, dass das Etikett schlecht ist — Winkel, Fokus oder Beleuchtung des Fotos können schlicht nicht ausreichen. Dieser Endpunkt ist KEINE ISO/IEC-15416-Druckqualitätsnote (A–F); dafür braucht es ein Prüfgerät.

curl -X POST "https://api.labelixa.com/v1/verify" \
     -F "file=@label-photo.jpg"

Dasselbe im Browser: Barcode-Prüfer.

Druckersprachen über ZPL hinaus

Labelixa rendert und validiert vier Druckersprachen. Die folgenden Endpunkte entsprechen den ZPL-Pendants: render liefert ein PNG des Etiketts, diagnostics liefert Diagnosen mit Zeilennummern. Der Umfang ist je Sprache bewusst eine MVP-Teilmenge, und jede Antwort nennt ihre eigenen Grenzen — ein Befehl, den wir nicht zeichnen, wird gemeldet und nie stillschweigend übergangen.

POST /v1/language-detect beantwortet eine andere Frage: Um welche Sprache handelt es sich bei fremdem Code? Die Antwort ist heuristisch und deterministisch (kein LLM); die Sicherheit wird als High/Medium/Low angegeben statt als erfundener Prozentwert.

POST /v1/compatibility nimmt ZPL plus ein Druckermodell entgegen und liefert eine Risikoanalyse zur Kompatibilität — Sprachlage, Befunde zu Größenregeln und Vorschau-Umfang. Es ist KEIN Emulator und gibt nie eine Kompatibilitätsgarantie: Wir haben nur eines von vierzig Modellen physisch getestet, und ein dokumentierter Emulationsmodus ist keine native Unterstützung.

Die Vorschau in die eigene Seite einbetten

/embed/viewer ist eine minimale Vorschaukomponente ohne Seitenrahmen; Sie binden sie per <iframe> in Ihre eigene Anwendung ein. Das ZPL reist im URL-Fragment (#), nicht im Query-String — das Fragment wird nie an den Server gesendet, Ihr Etiketteninhalt landet also weder in unseren noch in den Logs zwischengeschalteter Proxys. Das Format ist IDENTISCH mit der Ausgabe von "Link kopieren" im Vorschauwerkzeug (base64-JSON) — Sie können diesen Link direkt einfügen.

<iframe src="https://labelixa.com/embed/viewer#eyJ6IjoiXlhBLi4uIiwiZCI6IjgiLCJ3IjoiNCIsImgiOiI2In0"
        width="420" height="620" style="border:0"></iframe>

Die Höhe geben Sie vor; die Komponente passt das Bild in den Rahmen ein. Die Seite ist noindex und nicht in der Sitemap — sie ist eine Komponente, keine Inhaltsseite.