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.

Anonyme (schlüssellose) Anfragen werden pro IP-Adresse gezählt (IPv6: pro /64-Präfix) — alle hinter dieser Adresse teilen sich einen Topf: 5.000 Etiketten und 10.000 Anfragen pro Kalendermonat (UTC), eine Tagesobergrenze von 5.000 Etiketten, 3 Anfragen pro Sekunde, bis zu 50 Etiketten pro Anfrage. Ein kostenloses Konto (labelixa.com/panel) erhält einen API-Schlüssel mit eigenem, von der IP unabhängigem Monatskontingent und kann Etiketten speichern; kostenpflichtige Tarife heben die Limits an.

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. Die Zusage gilt für die auf dieser Seite dokumentierten Endpunkte. Unter /v1 können auch nicht dokumentierte Pfade antworten; sie dienen internen Abläufen, tragen keine Stabilitätszusage und können sich ohne Ankündigung ändern — bauen Sie Ihre Integration ausschließlich auf den dokumentierten Endpunkten auf.

Schnellstart

1. Senden Sie ein ZPL-Etikett an den anonymen Endpunkt — kein Schlüssel nötig, das kostenlose Kontingent reicht:
   bash

   curl -X POST "https://api.labelixa.com/v1/printers/8dpmm/labels/4x6/0" \
     -H "Content-Type: text/plain" \
     --data-binary '^XA^FO50,50^A0N,40,40^FDHello^FS^XZ' \
     -o label.png

2. Das zurückgegebene PNG ist das Etikett. Mit Accept: application/pdf erhalten Sie stattdessen ein PDF.
3. Mit Konto und X-API-Key-Header gelten Kontingent und Ratenlimit Ihres Plans; Details in den Abschnitten unten.

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.

Fehler und ihre Behebung

Jeder Fehler ist ein HTTP-Statuscode plus ein Body. Lesen Sie zuerst den Status, dann den Body: Render-Endpunkte antworten mit EINER ZEILE KLARTEXT, alle anderen mit JSON, dessen Meldung in hata steht (Englisch). Manche JSON-Bodies tragen zusätzlich einen stabilen maschinenlesbaren Namen — kod (snake_case) oder hata_tipi (PascalCase) — und diese Namen sind Wire-Werte: verzweigen Sie darauf, nie auf den Satz. Der Abschnitt Feldnamen in Antworten erklärt, warum die Schlüsselnamen türkisch sind. Die Tabelle unten listet die Fehler, auf die Integratoren tatsächlich treffen, wann jeder auftritt und was ihn behebt.

401 / 403 — Schlüssel, Herkunft, Tarif, Scope, Business Central

{"hata": "Invalid API key", "kod": "gecersiz_anahtar"}

{"hata": "X-API-Key required"}

{"hata": "Access denied", "kod": "origin_kapisi"}

{"hata": "This feature (webhook) is not available on the free plan. See the /v1/plans endpoints to upgrade."}

{"hata": "This key does not have the 'etiket_yaz' scope", "kod": "kapsam_yok", "gereken_kapsam": "etiket_yaz"}

{"hata": "The billing portal can only be opened with the account's primary key or a panel session", "kod": "birincil_gerekli"}

{"hata": "Role 'viewer' is not allowed to perform 'etiket_yaz'", "kod": "rol_yetkisiz", "gereken_eylem": "etiket_yaz"}

{"hata": "Saved labels require an account; a free account is enough (POST /v1/accounts).", "kod": "hesap_gerekli"}

{"hata": "Invalid Entra token: signature verification failed", "hata_tipi": "EntraJetonuGecersiz"}

{"hata": "This Entra tenant is not linked to a Labelixa account; run Connect Account with an API key first", "hata_tipi": "EntraEslemesiYok"}

{"hata": "This Entra tenant is linked to more than one Labelixa account; connect with an API key", "hata_tipi": "EntraBelirsiz"}

{"hata": "This tenant/environment/company is linked to another account", "hata_tipi": "KiraciBaskasinin"}

400 / 404 / 413 / 422 — Parameter, Größe, Validierung

dpmm must be 6, 8, 12 or 24

Label size must be at most 15 inches

{"hata": "Not found"}

Request body exceeds the 1 MB limit

At most 20000 commands per label (23417 found). Split the ZPL stream into several labels or simplify it.

At most 50 labels per request (120 sent). Upgrade your plan for a higher limit.

{"detail": [{"type": "json_invalid", "loc": ["body", 1], "msg": "JSON decode error", "input": {}}]}

{"hata": "Quick batch accepts at most 20 rows; for more, use a Pro bulk job (/v1/bulk/jobs)", "kod": "satir_tavani", "tavan": 20, "satir_sayisi": 21}

{"hata": "An account with this email already exists", "kod": "eposta_kullanimda"}

402 / 429 — Ratenlimit vs. Tages- und Monatskontingent

Per-second request limit exceeded (3/s). Starter: 5/s, 9 USD/month -> https://labelixa.com/pricing?amac=kota

Daily quota insufficient: 3 operations left, this request needs 5 (daily 5000). Upgrade your plan to continue. Next plan: starter, 9 USD/month -> https://labelixa.com/pricing?amac=kota

Monthly label quota insufficient: 40 labels left, this request needs 50 (monthly 20000). The quota renews on 2026-11-17T00:00:00Z; upgrade your plan to continue.

{"hata": "Too many account creation attempts; try again later", "kod": "hiz_siniri"}

{"hata": "Saved label limit reached (5/5)"}

{"hata": "Free DirectPrint trial used up (25 labels). Upgrade to Starter or higher to continue.", "hata_tipi": "DenemeDoldu"}

{"hata": "This tenant's monthly BC print cap (500) is reached", "hata_tipi": "TavanDoldu"}

Zwei verschiedene Grenzen teilen sich den Status 429; die Header unterscheiden sie. Das Ratenlimit pro Sekunde antwortet mit Retry-After: 1 und OHNE X-Quota-Reason-Header: eine Sekunde warten und erneut senden. Das Tages- oder Monatskontingent antwortet mit Retry-After: 3600, X-Quota-Action und X-Quota-Reason (gunluk, aylik_etiket oder aylik_istek); X-Quota-Reset nennt den exakten UTC-Zeitpunkt der Erneuerung, und ein Versuch davor ist sinnlos — Tarif erhöhen (der nächste Tarif und seine Adresse stehen maschinenlesbar in X-Quota-Next-Plan und X-Quota-Upgrade-Url) oder auf die Erneuerung warten. Anonyme 200-Antworten ergänzen X-Quota-Hint, sobald 150 der 5.000 freien Etiketten verbraucht sind: Ein kostenloser Schlüssel gibt Ihnen ein eigenes Kontingent.

409 / 412 / 428 — Nebenläufigkeit und Wiederholungen

{"hata": "If-Match is required (prevents lost updates)", "guncel_surum": 7, "etag": "\"7\""}

{"hata": "The label changed in the meantime (version mismatch)", "guncel_surum": 8, "etag": "\"8\""}

{"hata": "Same Idempotency-Key but a different request"}

{"hata": "A previous request with the same Idempotency-Key is still being processed"}

5xx — Render-Budget und Dienst

Render time limit exceeded

Service temporarily unavailable

{"hata": "Unexpected server error"}

Fehlertypen von Druckaufträgen

Ein fehlgeschlagener Druckauftrag lässt die HTTP-Anfrage nicht fehlschlagen — POST /v1/print hat mit 202 geantwortet, das Ergebnis steht im Auftragsstatus. Das Feld hata_tipi eines fehlgeschlagenen Auftrags ist eine dieser Klassen; asama sagt, wie weit der Auftrag vor dem Fehler kam.

Feldnamen in Antworten

JSON-Antworten verwenden stabile Schlüsselnamen. Die meisten sind türkische Wörter (zum Beispiel ozet, mesaj, durum) und bleiben genau so: Ein umbenannter Schlüssel wäre eine inkompatible Änderung, die die oben beschriebene API-Stabilitätszusage innerhalb von /v1 ausschließt. Die offiziellen Integrationen — der MCP-Server und der n8n-Knoten — übersetzen die Schlüssel und zeigen englische Namen. Die folgende Tabelle wird aus derselben Zuordnung erzeugt, die sie verwenden; rohe Antworten und Integrationsausgabe lassen sich so nebeneinander lesen. Ein nicht aufgeführter Schlüssel behält auch in den Integrationen seinen JSON-Namen. Fehlerantworten tragen die lesbare Meldung auf Englisch in hata. Wann jeder Fehler auftritt und wie er behoben wird: Fehler und ihre Behebung.

Feste Werte

Manche Felder enthalten ein Wort aus einer festen Menge. Der JSON-Wert bleibt unverändert; die Integrationen zeigen das englische Wort. Pfade verwenden die englischen Feldnamen aus der Tabelle oben; [] steht für ein Array-Element, * für einen beliebigen Schlüssel.

Status von Massenaufträgen

Das Feld durum eines Massenauftrags ist einer von:

Kompatibilitätsstufen

Die Kompatibilitätsprüfung liefert in risk.seviye eine Risikostufe, nie eine Garantie:

onizleme_kapsami gruppiert die Befehle des Etiketts danach, was UNSERE Vorschau mit ihnen macht. Es beschreibt die Vorschau, nicht den Drucker:

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. Jedes Konto kann speichern: Free 5, Starter 50, Professional 500, Business 2.500 gespeicherte Etiketten; Enterprise unbegrenzt. Anonyme (schlüssellose) Anfragen können nicht speichern — ein kostenloses Konto genügt, keine Karte nötig. 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.

Drucken

Render-Endpunkte liefern Ihnen ein Bild; diese Endpunkte senden den Auftrag an einen registrierten Drucker. Ein kostenpflichtiger Tarif ist erforderlich (ab Starter); der kostenlose Tarif enthält eine einmalige Testphase mit 25 Etiketten auf 1 Drucker. Es wird nicht doppelt abgerechnet: Übergeben Sie die ID eines bereits gerenderten Auftrags als kaynak_is_id, ist der Druck kostenlos; senden Sie rohes ZPL, gilt das Etikett als hier erzeugt und wird hier abgerechnet.

Auftragsstatus — und warum es kein `printed` gibt

Einen Status „gedruckt“ gibt es bewusst nicht. Über rohes 9100 lässt sich nicht beweisen, dass ein Etikett gedruckt wurde: Dass der Socket Ihre Bytes annimmt, zeigt nur, dass sie im Puffer des Druckers angekommen sind; leeres Material, ein offener Druckkopf oder ein Stau passieren, nachdem die Bytes angenommen wurden — und der Socket sagt Ihnen das nie. Der weiteste Zustand ist dispatched = „übergeben“. Jede Antwort trägt zudem basim_onaylandi: false, damit das Ignorieren des Feldes nicht als „also wurde gedruckt“ gelesen werden kann.

Sie können also einen Workflow bauen, der das Drucken auslöst, aber bauen Sie keine Geschäftsregeln auf eine Druckbestätigung. Wo eine Bestätigung wirklich zählt (Pharma, Rückverfolgung), muss die Prüfung vom Etikett selbst zurückgelesen werden.

`failed` heißt nicht „nichts wurde gedruckt“

Ein Auftrag kann an fünf verschiedenen Stellen scheitern, und in vier davon erreicht kein einziges Byte den Drucker (Gerät nicht zugeordnet, kein Adapter, Identitätsprüfung fehlgeschlagen). Im fünften Fall — die Verbindung zum Drucker bricht ab — sind die Bytes hinausgegangen, und bei mehreren Kopien liegt ein Teil davon möglicherweise schon auf Papier. Die Statusantwort trägt diesen Unterschied in eigenen Feldern:

Ein Auftrag, dessen Bytes den Drucker erreicht haben, wird nie automatisch wiederholt — eine Wiederholung würde das Etikett ein zweites Mal drucken. Ein solcher Auftrag wird angehalten, und die Entscheidung zum Fortfahren liegt bei Ihnen. Fehler, die den Drucker nie erreicht haben, werden weiterhin wie bisher wiederholt.

Doppeldrucke vermeiden: Idempotency-Key

Eine Anfrage nach einem Netzwerk-Timeout erneut zu senden ist der richtige Reflex — aber das Etikett liegt möglicherweise schon auf Papier. Senden Sie einen Idempotency-Key-Header, und eine zweite Anfrage mit demselben Schlüssel erzeugt keinen neuen Auftrag: Sie gibt die erste Antwort erneut zurück (Idempotency-Replayed: true). Derselbe Schlüssel mit einem ANDEREN Rumpf ergibt 422 — einen Schlüssel wiederzuverwenden würde stillt das falsche Etikett drucken. Ein 429 (Warteschlange voll) verbraucht den Schlüssel NICHT; ein erneuter Versuch damit ist vorgesehen.

Aus einer gespeicherten Vorlage drucken

Statt yuk können Sie sablon_id und degiskenler senden; die Nutzlast wird aus der Vorlage erzeugt. Beides zusammen wird abgelehnt. Eine fehlende oder ungültige Variable ergibt 400 — ein Etikett mit fehlender Variable verschwendet Material, und nur die Person am Drucker würde es bemerken.

Ein gespeichertes Etikett drucken: etiket_id

Statt yuk können Sie die etiket_id eines in Ihrem Konto gespeicherten Etiketts (/v1/labels) zusammen mit degiskenler für seine Variablen senden; die Nutzlast wird aus dem Etikett erzeugt. Um mehrere Etiketten als EINEN Auftrag zu drucken, senden Sie satirlar: ein Objekt pro Etikett, 1-1000 Zeilen; die Werte einer Zeile überschreiben degiskenler, und etiket_sayisi wird zur Zeilenzahl. Eine leere satirlar-Liste wird abgelehnt; lassen Sie sie weg, um ein einzelnes Etikett zu drucken. etiket_id lässt sich nicht mit yuk, zpl oder sablon_id kombinieren (422). Eine fehlende oder ungültige Variable ergibt 422 und nennt die Zeile — der Auftrag wird nicht eingereiht, keine Zeile wird übersprungen. Das Etikett eines anderen Kontos erhält dasselbe 404 wie ein fehlendes, archivierte Etiketten werden nicht gedruckt. Idempotency-Key, kopya, device_id / printer_group und die Abrechnung funktionieren genau wie bei einer Roh-Nutzlast; die Antwort enthält etiket_id. Ist der Freigabe-Workflow aktiv, können nur veröffentlichte Etiketten gedruckt werden (sonst 422); reichen Sie das Etikett im Panel unter Gespeicherte Arbeit zur Freigabe ein und geben Sie es frei, oder nutzen Sie POST /v1/labels/{id}/publish und /approve.

Druckergruppen: printer_group

Vergeben Sie bei der Geräteregistrierung ein grup (DEPO, URETIM), dann darf eine Druckanfrage statt device_id ein printer_group tragen. Der Zweck: Gerätekennungen aus dem Geschäftssystem heraushalten — wird ein Drucker getauscht, wandert die Gruppe mit dem Geräteeintrag und der Code auf ERP-Seite bleibt unberührt. Die Auflösung ist bewusst DETERMINISTISCH: für ein "nimm den freien" fehlen uns die Daten, denn ein roher 9100-Socket meldet keine Auslastung. Ein Gerät in der Gruppe: dieses Gerät. Mehrere: das als Standard markierte. Kein Standard oder mehrere, dann wird der Auftrag NICHT gedruckt — der Fehler nennt die kollidierenden Geräte. device_id und printer_group zusammen zu senden wird abgelehnt. Gruppennamen werden in Großbuchstaben normalisiert und dürfen nur Buchstaben, Ziffern, - und _ enthalten. Für Integrationen ohne Gruppen ändert sich nichts: grup entsteht leer und device_id funktioniert wie bisher. In beiden Fällen liefert die Antwort die device_id zurück, auf der der Auftrag gelandet ist.

Webhook-Benachrichtigungen

Sie müssen den Status nicht abfragen: Abonnieren Sie baski.teslim und baski.basarisiz. Ein Ereignis baski.basildi gibt es nicht — aus demselben Grund, aus dem es keinen Status printed gibt. Der Rumpf enthält keinen rohen Etiketteninhalt: nur Auftrags-ID, Stufe und Zähler. Das Fehlerereignis wird erst ausgelöst, wenn ein Auftrag dauerhaft fehlgeschlagen ist; eine Benachrichtigung bei jedem Versuch würde den echten Fehler im Rauschen begraben. Ein Auftrag, der ungewiss wird, löst baski.belirsiz aus — ein eigenes Ereignis, damit eine Automatisierung, die bei baski.basarisiz neu druckt, ihn nicht doppelt druckt; bestehende Abonnements erhalten es erst, wenn Sie es hinzufügen. Jeder baski.*-Rumpf enthält veri.sira (1, 2, … je Auftrag) und veri.status (der Status bei diesem Ereignis). Zustellungen werden wiederholt, daher kann ein älteres Ereignis nach einem neueren eintreffen: Vergleichen Sie sira und ignorieren Sie ein Ereignis, dessen sira kleiner ist als das zuletzt verarbeitete desselben Auftrags.

Der DirectPrint-Agent, der diese Aufträge abholt und an den Drucker liefert, wird hier heruntergeladen: /de/download

Agent einrichten (Einrichtungsassistent)

Führen Sie auf dem Computer, an dem die Drucker hängen, labelixa-agent setup aus (der Einzeiler-Installer auf der Download-Seite installiert den Agent und startet ihn). Der Agent öffnet die Labelixa-Seite im Browser; prüfen Sie, dass dort derselbe kurze Code steht wie im Agent-Fenster, und klicken Sie auf Verbinden. Ohne Browser erstellen Sie auf der Seite Drucker im Panel einen Kopplungscode und führen labelixa-agent setup CODE aus. Der kostenlose Plan enthält eine Testphase mit 1 Computer, 1 Drucker und insgesamt 25 Etiketten (Testetiketten zählen nicht); darüber hinaus ist ein bezahlter Plan nötig. Das Herunterladen ist kostenlos.

Der Assistent liest die Druckwarteschlangen des Computers: ein einzelner Etikettendrucker wird ohne Rückfrage verwendet, mehrere werden als Liste angeboten, ein Bürodrucker nur nach Ihrer Bestätigung. Jeder gewählte Drucker wird Ihrem Konto hinzugefügt und auf diesem Computer zugeordnet; am Ende kann ein Testetikett gedruckt werden. Während der Einrichtung wird nichts an einen Drucker gesendet und das Netzwerk nicht durchsucht.

• labelixa-agent discover -mdns listet die Netzwerkdrucker, die sich selbst ankündigen (Bonjour/mDNS), ohne ihnen etwas zu senden.
• labelixa-agent import DATEI fügt viele Netzwerkdrucker auf einmal aus einer CSV-Datei hinzu, eine Zeile name,adresse[,gruppe] pro Drucker (-dry-run prüft die Datei vorher). Jede Zeile wird gemeldet; eine fehlerhafte Zeile stoppt die Datei nicht.
• Ein erneutes setup auf einem verbundenen Computer behält die Verbindung und die bereits eingerichteten Drucker.

Der Agent fragt die Cloud nach Arbeit, und die Cloud hält die Anfrage offen, bis ein Auftrag eintrifft (Long Polling) — ein Etikett wird übergeben, sobald es gesendet ist. Der Agent öffnet keinen Port: jede Verbindung geht vom Computer zu Labelixa.

Windows: stille Installation für IT-Teams

Für Intune-, Gruppenrichtlinien- oder SCCM-Rollouts gibt es den Windows-Agent auch als MSI-Paket. Eine Zeile richtet ihn als Windows-Dienst LabelixaAgent ein, koppelt ihn mit einem Einmalcode von der Seite Drucker im Dashboard und importiert die Druckerliste: msiexec /i labelixa-agent_0.6.1_windows_amd64.msi /qn PAIRCODE=CODE PRINTERSFILE=C:\pfad\drucker.csv. PRINTERSFILE ist optional (eine Zeile name,adresse[,gruppe] je Drucker); schlägt Kopplung oder Import fehl, wird die Installation zurückgerollt, und der Code landet nicht im Installationsprotokoll. Paket und Prüfsumme liegen auf der Release-Seite.

USB-Drucker: die Druckwarteschlange des Betriebssystems

Ein Desktop-Drucker am USB-Anschluss öffnet keinen Port 9100; er erscheint im Betriebssystem als Druckwarteschlange (Windows-Spooler, CUPS unter macOS und Linux). Ab Agent 0.2.0 werden die Bytes als RAW-Daten an diese Warteschlange übergeben: Der Treiber rendert nichts, die Etikettensprache erreicht den Drucker genau so, wie Sie sie gesendet haben.

1. Registrieren Sie das Gerät mit adaptor: "os_driver" (POST /v1/devices).
2. Ermitteln Sie auf dem Agent-Rechner den Namen der Warteschlange: labelixa-agent discover -queues.
3. Ordnen Sie das Gerät der Warteschlange zu: labelixa-agent map-printer -device GERAETE_ID -queue "WARTESCHLANGE".
4. Optional läuft der Agent ab jeder Anmeldung im Hintergrund: labelixa-agent install (LaunchAgent unter macOS, systemd-Benutzereinheit unter Linux; unter Windows gibt er die Dienstbefehle für eine Administrator-Eingabeaufforderung aus).

Auf diesem Weg ist die weiteste Stufe submitted_to_os: Der Spooler hat den Auftrag angenommen. Das ist ein Schritt vor submitted_to_printer — ein ausgeschalteter Drucker oder fehlendes Material zeigt sich in der Warteschlange des Betriebssystems, nicht hier, und die Warteschlange meldet keinen Druckerstatus (yazici_durumu: null). Ein Auftrag, der bei ausgeschaltetem Drucker gesendet wird, wartet dort und wird gedruckt, sobald der Drucker wieder an ist. Ein teilweise übergebener Mehrfachauftrag wird nicht automatisch wiederholt.

Cloud-Eintrag und Agent-Zuordnung müssen übereinstimmen: Ein os_driver-Gerät mit Netzwerkadresse oder ein raw_tcp-Gerät mit Warteschlange wird nicht gedruckt und schlägt mit AdaptorYok fehl — Anhalten ist besser als ein Druck auf dem falschen Drucker.

ZPL aus der Cloud auf einem USB-Zebra-Drucker drucken

PrintOps — Kennzahlen, Warnungen, Druckprüfung

Die Betriebsseite der Druck-Endpunkte: Was wurde gedruckt, was hängt, wer hat gedruckt. Nur lesend — fasst die vorhandenen Druckaufträge des Kontos zusammen und schreibt nichts. Dieselben Daten stehen im Panel im Reiter PrintOps (gleiche Plan-Schranke wie Drucker). Es gibt bewusst keine Zahl „gedruckt“: Zugestellt heißt, die Bytes haben den Agenten erreicht, nicht das Papier.

Business Central

Die Business-Central-Erweiterung von Labelixa (Labelixa Core + DirectPrint) nutzt diese Endpunkte; Ihre eigene Integration kann sie ebenfalls nutzen. Die Authentifizierung erfolgt per API-Schlüssel; eine anonyme Anfrage kann keine Zuordnung anlegen (403). Die Plan-Schranke ist dieselbe wie bei den Druck-Endpunkten.

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.

Regeldateien für Coding-Assistenten

Eine Regeldatei bringt Claude Code, Cursor, GitHub Copilot oder Windsurf bei, Etikettencode mit Labelixa zu prüfen und zu rendern, statt aus dem Text zu raten. Kopieren Sie die Datei für Ihren Assistenten aus dem Repository Labelixa/agent-skills in Ihr Projekt: .claude/skills/labelixa/SKILL.md, .cursor/rules/labelixa.mdc, .github/instructions/labelixa.instructions.md, .windsurf/rules/labelixa.md. Die Regeln rufen den MCP-Server oder die CLI auf; ein API-Schlüssel kommt, falls vorhanden, nur aus der Umgebung.

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.

Druckersprachen-Umwandlung (SBPL / DPL / IPL → ZPL)

Drei Endpunkte wandeln SATO-SBPL-, Honeywell-(Datamax-)DPL- und Honeywell-(Intermec-)IPL-Datenströme in ZPL um, damit das Etikett mit den ZPL-Werkzeugen angezeigt, geprüft und gedruckt werden kann. Der Body ist der Rohdatenstrom — echte Steuerzeichen und die lesbare Schreibweise der Handbücher (<STX>, <ESC>) ergeben dasselbe Ergebnis. Die Quellsprache wählen Sie: Die automatische Spracherkennung kennt diese drei Sprachen nicht.

Parameter

Antwort

Gibt es Warnungen, ist die Umwandlung nicht 1:1. Befehle außerhalb der unterstützten Teilmenge — Druckereinstellungen (Geschwindigkeit, Schwärzung, Sensor), RFID, Auftragsverwaltung und einige 2D-Symbologien — werden MIT Warnung übersprungen, nie stillschweigend. Zeigen Sie die Warnungen der Person, die das Etikett druckt.

curl -X POST "https://api.labelixa.com/v1/convert/sbpl-to-zpl?dpmm=8" \
     --data-binary "<A><CS>6<V>100<H>200<L>0202<XM>ABCD<Q>1<Z>"

{"zpl": "^XA\n^FO199,99^A0N,48,48^FDABCD^FS\n^PQ1\n^XZ",
 "uyarilar": ["<CS> Print Speed not carried over to ZPL (manual p. 326; printer setting or outside the supported subset)"],
 "kaynak_dil": "sbpl", "birebir": false}

curl -X POST "https://api.labelixa.com/v1/convert/dpl-to-zpl?dpmm=8&etiket_boyu_mm=101.6" \
     --data-binary @label.dpl

Nicht auf einem physischen Drucker geprüft. Es wurde kein SATO-, Datamax- oder Intermec-Drucker verwendet: Die Ausgabe ist das ZPL-Äquivalent laut Befehlsreferenz des jeweiligen Herstellers. Positionen gedrehter Felder sind angenähert und andere Schriftfamilien werden auf ^A0 abgebildet; beides wird als Warnung gemeldet. Prüfen Sie vor der Produktion die Vorschau und einen Testdruck.

Die Umwandlung zählt nicht gegen das Anfragekontingent; es gilt nur das Limit pro Sekunde. Body bis 512 KB (darüber 413), leerer Body 400. Die Endpunkte sind zustandslos: Der Code wird weder gespeichert noch protokolliert.

Dasselbe im Browser: Druckersprachen-Konverter.

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.

Postman-Sammlung

Jeder Endpunkt dieser Referenz liegt als fertige Anfrage im öffentlichen Postman-Workspace: postman.com/labelixa-3901521. Die Sammlung wird aus dem OpenAPI-Schema (/openapi.json) erzeugt, nicht von Hand gepflegt. Der Schlüssel reist in der Variablen apiKey und ist NICHT in der Sammlung eingebettet — forken Sie den Workspace und setzen Sie ihn in Ihrer eigenen Umgebung; bleibt er leer, laufen die Anfragen über das anonyme Kontingent.

Ein Badge für Ihre README

Werden die ZPL-Dateien Ihres Repositorys in der CI geprüft (POST /v1/diagnostics beendet sich bei Fehlern mit Exit-Code ≠ 0), können Sie das mit einem statischen Badge sagen — kein Zähler, kein Tracking, einen Tag gecacht:

[![ZPL validated with Labelixa](https://labelixa.com/static/badge-zpl-validated.svg)](https://labelixa.com/tools/zpl-preview)

Nur verwenden, wenn die Aussage für Ihr Repository stimmt. Den Viewer in die eigene Seite einbetten, mit Quellenzeile darunter: Einbettungsanleitung.