So drucken Sie Etiketten über eine Web-Service-API: Ein Entwickler-Walkthrough

2026-10-03 pdf labels barcodes label merge browser based graphical layout editor google sheets addin microsoft excel addon electronic shelf labels esl barcode3 labels label editor

Etiketten über eine Web-Service-API drucken: Ein Entwickler-Walkthrough

Ihre Anwendung weiß bereits, was auf dem Etikett stehen soll – die Bestellnummer, die SKU, der Barcode-Wert, die Packliste. Der lästige Teil war nie die Daten. Es ist die Ausgabe: Treiber, Druckersprachen, Spooler und ein Lagerdrucker, der darauf besteht, Ihre Schrift zwei Punkt zu groß zu rendern.

Dieser Walkthrough überspringt diesen Stack komplett. Sie lernen, wie Sie Etiketten über eine Web-Service-API drucken: Registrieren Sie Ihr externes System einmal, gestalten Sie das Etikett einmal im Browser und übermitteln Sie dann Druckaufträge – oder rufen Sie gerenderte PDFs und PNGs ab – aus Ihrem eigenen Code. Kein Druckertreiber, kein SDK, keine rohen Druckerbefehle.

Was Sie bauen werden: Etiketten über eine Web-Service-API drucken

Es gibt zwei Ergebnisse, die Sie typischerweise wollen, und die gute Nachricht ist, dass sie dieselbe Request-Form teilen:

Einen Druckauftrag übermitteln. Ihre App sendet eine Etikettenreferenz plus eine Datennutzlast. Der Auftrag gelangt in eine Warteschlange und wird an den konfigurierten Drucker gesendet.
Ein einzelnes Etikett rendern. Dasselbe Etikett und dieselben Daten kommen als PDF oder PNG zurück – für Vorschauen in Ihrer UI, E-Mail-Anhänge, Freigaben oder ein Audit-Archiv.

Next Generation Label Printing System (LPSNG) stellt genau das als verwaltete Web-Service-API bereit. Sie rufen einen Endpunkt auf; der Dienst besitzt den Druck-Stack. Dieselbe API-Oberfläche deckt auch den Direktdruck (direkt an ein Gerät, an der Warteschlange vorbei) und Aktualisierungen elektronischer Regaletiketten ab, sodass die Integration, die Sie heute bauen, weiter funktioniert, wenn Ihre Anforderungen wachsen.

Hier ist der Weg, den wir nehmen:

Das externe System mit OAuth2 registrieren.
Das Etikett einmal im Label-Studio gestalten.
Einen Druckauftrag aus Ihrer App übermitteln.
Ein einzelnes Etikett als PDF oder PNG rendern.
Überprüfen, dass der Auftrag tatsächlich auf Papier gelandet ist.

Die genauen Endpunkt-Pfade und Parameternamen finden Sie in der Web Service Interface- und der External Application Integration-Dokumentation – dieser Artikel gibt Ihnen die Form und die Reihenfolge der Operationen, und die Dokumentation liefert Ihnen die Details auf Byte-Ebene.

Voraussetzungen, bevor Sie die API aufrufen

Vor der ersten Anfrage sollten Sie Folgendes bereithalten:

Ein LPSNG-Konto oder eine Edition, die die Web-Service-Schnittstelle enthält. Die Cloud Solution, die Embedded Edition auf einem Single-Board-Computer und die Mehrbenutzer-Enterprise Features bieten alle dieselbe Kernfunktionalität, die in Use Cases beschrieben ist – Web-UI, Label-Studio, Auftragswarteschlange, PDF-Generierung und die Web-Service-Schnittstelle.
Ein Etikettenlayout, das bereits im Label-Studio existiert, mit Feldern, die den Daten zugeordnet sind, die Sie senden möchten. Die API referenziert das Layout über einen Bezeichner; sie baut Layouts nicht spontan.
OAuth2-Anmeldedaten aus dem Registrierungsablauf, der zum Verbinden externer Systeme verwendet wird.
Einen beliebigen HTTPS-fähigen HTTP-Client. Python, Node, Go, curl – das Protokoll ist das egal.
Optional: einen Testdrucker oder den LPSNG Player, wenn Sie einen lokalen Rendering-Pfad wünschen, bevor Sie ein Gerät anschließen.

Schritt 1: Registrieren Sie Ihr externes System mit OAuth2

LPSNG verwendet ein vereinfachtes OAuth2-Registrierungsprotokoll, das externe Systeme mit einer einzigen URL verbindet. Das ist der Teil, den die meisten Integrationen falsch machen, wenn sie ihn selbst umsetzen: Token-Refresh und Geräteauthentifizierung gegen ein rohes Druckprotokoll von Hand zu implementieren, sind Wochen Arbeit, die nichts mit Etiketten zu tun haben.

Der verwaltete Ablauf ist ein einziger Schritt:

# 1. Open the registration URL that LPSNG generates for your external system.
#    You complete the consent step once, in a browser.
open "$REGISTRATION_URL"

# 2. Store the credentials LPSNG hands back for that registered system.
export LPSNG_CLIENT_ID="<client-id>"
export LPSNG_CLIENT_SECRET="<client-secret>"

# 3. Exchange them for a token your API calls will use.
#    Exact parameter names: see https://lpsng.rsj.de/en/oauth2.md

Zwei Dinge sind erwähnenswert:

Die Zustimmung ist ein einmaliger Schritt. Nach der Registrierung verwendet Ihre Anwendung die resultierenden Anmeldedaten bei jedem nachfolgenden API-Aufruf – Sie schicken nicht pro Druckauftrag einen Menschen durch einen Browser-Ablauf.
Es ist dasselbe Modell wie für ESL-Basisstationen. Wenn Sie später Regaletiketten anschließen, werden Sie das Muster sofort wiedererkennen. Details finden Sie in der ESL- und der ESL Interface-Dokumentation.

Speichern Sie das Token so, wie Sie jedes andere Geheimnis speichern würden: Umgebungsvariable oder Secret Manager, niemals im Repo.

Schritt 2: Gestalten Sie das Etikett einmal im Label-Studio

Öffnen Sie die Web-UI und bauen Sie das Layout wie ein Dokument: Textblöcke, Bilder, Barcodes und Feldplatzhalter dort, wo die API-Daten landen werden.

Ein paar Entscheidungen, die sich später auszahlen:

Verwenden Sie unterstützte Barcode-Symbologien. LPSNG rendert 1D- und 2D-Formate nativ – die Seite Barcode Formats listet auf, was verfügbar ist. Wenn Sie ein unterstütztes Format wählen, rendert die API es ohne zusätzlichen Aufwand auf Ihrer Seite.
Hängen Sie Python-Skriptblöcke an Felder an, wenn Sie Logik benötigen. Die Field Script API ermöglicht es einem Skriptblock, auf den Wert eines Feldes zuzugreifen und ihn vor dem Drucken zu ändern – praktisch zum Formatieren von Datumsangaben, zum Kürzen langer Lieferantennamen oder zum Ableiten einer Prüfziffer.

# Example: a script block attached to a field, formatting a raw value
# before it reaches the printer. See https://lpsng.rsj.de/api.html
value = str(value).strip().upper()

if len(value) > 30:
    value = value[:27] + "..."

Speichern Sie das Layout und notieren Sie seinen Bezeichner. Dieser Bezeichner ist das, worauf Ihr API-Aufruf verweist – behandeln Sie ihn wie einen Konfigurationswert, nicht wie einen magischen String, der im Code vergraben ist.
Halten Sie Layout und Daten getrennt. Das Layout definiert, wie ein Etikett aussieht; die Anfrage definiert, was es aussagt. Diese Trennung ist es, die es einem Layout ermöglicht, Tausende von Aufträgen zu bedienen.

Schritt 3: Übermitteln Sie einen Druckauftrag aus Ihrer Anwendung

Nun der Aufruf selbst. Die Form ist immer dieselbe: authentifizieren, das Etikett referenzieren, die Datennutzlast für die Felder übergeben.

import os
import requests

BASE  = os.environ["LPSNG_BASE_URL"]        # your LPSNG instance
TOKEN = os.environ["LPSNG_ACCESS_TOKEN"]    # from the OAuth2 registration

job = {
    "label": "shipping-label-4x6",   # identifier from the label studio
    "printer": "warehouse-01",       # a printer configured in LPSNG
    "data": {
        "order_no":  "SO-10432",
        "customer":  "Nordwind Handel GmbH",
        "sku":       "HND-2200-BLK",
        "qty":       "12",
        "barcode":   "SO-10432-HND-2200-BLK",
    },
}

resp = requests.post(
    f"{BASE}/<print-job-endpoint>",   # exact path: see the Web Service Interface docs
    json=job,
    headers={"Authorization": f"Bearer {TOKEN}"},
    timeout=30,
)
resp.raise_for_status()
print(resp.json())   # job identifier + status

Serverseitig gelangt der Auftrag in die Warteschlange und wird an den konfigurierten Drucker gesendet. Ihre Anwendung hält keine Verbindung zu einem Gerät offen und muss nicht wissen, ob dieser Drucker ZPL, EPL oder etwas anderes spricht.

Varianten, die es zu kennen lohnt:

Direktdruck. Wenn Sie möchten, dass das Etikett direkt an ein Gerät geht, anstatt in der Warteschlange zu warten, stellt die Schnittstelle einen Direktdruck-Pfad bereit.
Batching. Jeder Aufruf ist eine Etikettenreferenz plus Daten, sodass das Durchlaufen von Auftragspositionen nur eine Schleife in Ihrem Code ist – ein Auftrag pro Position, in der Reihenfolge, die Ihr Packplatz benötigt.

Für genaue Endpunkte, Parameternamen und Antwortfelder verwenden Sie die Referenzen Web Service Interface und External Application Integration.

Schritt 4: Rendern Sie ein einzelnes Etikett als PDF oder PNG

Rendern schlägt Drucken, wenn ein Mensch das Etikett zuerst ansehen muss oder wenn Sie einen Nachweis benötigen, dass es existierte:

Vorschauen in Ihrer eigenen UI, bevor sich jemand für einen Lauf entscheidet.
E-Mail-Anhänge für Lieferanten oder Kunden.
Freigabeschritte, bei denen ein Prüfer das Artwork absegnet.
Audit-Archive, die unabhängig von einem Drucker bestehen bleiben.

Der Aufruf sieht wie der Druckauftrag aus, außer dass er Bytes zurückgibt, anstatt Arbeit einzureihen:

# PDF for archiving or attaching
curl -sS -X POST "$LPSNG_BASE_URL/<render-endpoint>" \
  -H "Authorization: Bearer $LPSNG_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"label":"shipping-label-4x6","format":"pdf",
       "data":{"order_no":"SO-10432","sku":"HND-2200-BLK"}}' \
  -o label-SO-10432.pdf

# PNG for a preview thumbnail — same layout, same data, same output geometry
curl -sS -X POST "$LPSNG_BASE_URL/<render-endpoint>" \
  -H "Authorization: Bearer $LPSNG_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"label":"shipping-label-4x6","format":"png",
       "data":{"order_no":"SO-10432","sku":"HND-2200-BLK"}}' \
  -o label-SO-10432.png

Da beide Pfade dasselbe Layout und dieselben Daten verwenden, ist das, was Sie in der Vorschau sehen, auch das, was Sie drucken. Das ist der ganze Sinn dahinter, es in einem System zu erledigen, anstatt eine PDF-Bibliothek an einen Druckertreiber zu kleben.

Zwei praktische Hinweise:

Offline- oder Embedded-Rendering. Der LPSNG Player ist eine eigenständige Kommandozeilen-Druck-Engine, die ein Paket und Daten entgegennimmt und PDF, PNG, JSON, Druckausgabe oder ein ESL-Update erzeugt. Er ist das richtige Werkzeug, wenn Sie Ausgabe ohne einen Server-Roundtrip benötigen.
Cachen Sie aggressiv. Wiederkehrende Etiketten – dasselbe Regaletikett, dieselbe Paletten-ID – müssen nicht jedes Mal neu gerendert werden. Speichern Sie das PDF mit einem Schlüssel aus Layout + Daten-Hash und überspringen Sie den API-Aufruf.

Schritt 5: Überprüfen Sie, dass der Druckauftrag funktioniert hat

Ein HTTP 200 bedeutet, dass der Auftrag angenommen wurde. Es bedeutet nicht, dass ein Etikett aus einem Drucker gekommen ist. Überprüfen Sie in dieser Reihenfolge:

Prüfen Sie die Auftragswarteschlange in der Web-UI. Bestätigen Sie, dass der Auftrag angenommen und abgeschlossen wurde und dass er an den erwarteten Drucker ging.
Vergleichen Sie das Rendering mit der Realität. Legen Sie das PDF oder PNG neben das physische Etikett. Hier zeigen sich Skalierungsprobleme und Probleme mit der Ruhezone von Barcodes, und sie sind jetzt viel günstiger zu erkennen als beim Kunden vor Ort.
Scannen Sie den Barcode. Ein Lesegerät ist der einzige ehrliche Test dafür, ob die Daten den Roundtrip überstehen – prüfen Sie, dass der gescannte Wert Zeichen für Zeichen mit dem übereinstimmt, was Ihre Anwendung gesendet hat.
Protokollieren Sie die Antwort und den Auftragsbezeichner. Speichern Sie beides zu Ihrem internen Bestell- oder Versanddatensatz. Wenn jemand fragt „Wurde das mit einem Etikett versandt?", wollen Sie eine Antwort aus einer Datenbank, keine Vermutung.
Wenn Sie ESL verwenden, prüfen Sie auch das Display. Ein aktualisiertes Regaldisplay ist ein unabhängiges zweites Signal dafür, dass dieselben Daten den Dienst erreicht haben. Die ESL Interface und die ESL Binding API behandeln diese Seite.

Fehlerbehebung bei häufigen Problemen

Authentifizierungsfehler. Wenn Aufrufe anfangen, Auth-Fehler zurückzugeben, wurde das Token wahrscheinlich widerrufen oder die Registrierung des externen Systems hat sich geändert. Führen Sie die OAuth2-Registrierung erneut aus – sie ist konstruktionsbedingt ein Ein-Schritt-Ablauf, sodass die Wiederherstellung günstig ist. Siehe die OAuth2-Seite.

Leere oder fehlende Felder auf dem Etikett. Fast immer ein Schlüssel-Mismatch: Die Schlüssel in Ihrer data-Nutzlast müssen exakt mit den Feldnamen im Layout übereinstimmen, einschließlich Groß-/Kleinschreibung. Rendern Sie das Etikett als PNG und prüfen Sie es, bevor Sie den Drucker beschuldigen.

Falsche Barcode-Ausgabe. Prüfen Sie zwei Dinge: dass das von Ihnen gewählte Format in der Liste der unterstützten Barcode Formats steht und dass der Datentyp dem entspricht, was die Symbologie erwartet. Rein numerische Formate rendern bereitwillig Unsinn aus einem String mit Buchstaben darin.

Drucker empfängt keine Aufträge. Der Auftrag kann nur an einen Drucker gesendet werden, der in LPSNG konfiguriert und online ist. Wenn die Warteschlange den Auftrag dort liegen sieht, ist das Ziel das Problem, nicht Ihre Anfrage.

Das Rendering sieht anders aus als der Druck. Vergleichen Sie DPI und Etikettengröße zwischen dem Layout und dem physischen Medium. Ein Layout, das für eine Größe entworfen und an anders dimensioniertes Material gesendet wird, wird auf eine Weise skaliert, die die Barcode-Lesbarkeit beeinträchtigt.

FAQ

Brauche ich einen Druckertreiber oder ein SDK auf meinem Server, um Etiketten über die Web-Service-API zu drucken?

Nein. Next Generation Label Printing System übernimmt den Druck-Stack für Sie: Sie übermitteln einen Auftrag oder fordern ein Rendering über die Web-Service-API an, und der verwaltete Dienst kümmert sich um den Rest. Der LPSNG Player ist verfügbar, wenn Sie eine eigenständige Kommandozeilen-Engine für lokale Ausgabe benötigen.

Was ist der Unterschied zwischen dem Übermitteln eines Druckauftrags und dem Rendern eines einzelnen Etiketts?

Das Übermitteln eines Druckauftrags sendet das Etikett über die Auftragswarteschlange an den konfigurierten Drucker. Das Rendern gibt das Etikett als PDF oder PNG zurück, sodass Sie es in der Vorschau ansehen, archivieren oder anhängen können, ohne zu drucken. Beide verwenden dasselbe Layout und dieselben Daten, sodass die Ausgabe konsistent ist.

Wie funktioniert die OAuth2-Registrierung für externe Systeme?

LPSNG verwendet ein vereinfachtes OAuth2-Registrierungsprotokoll, das externe Systeme mit einer einzigen URL verbindet. Sie schließen den Zustimmungsschritt einmal ab, und die resultierenden Anmeldedaten werden für nachfolgende API-Aufrufe verwendet. Dasselbe Modell wird für ESL-Basisstationen verwendet, sodass das Muster über Integrationen hinweg konsistent ist.

Kann dieselbe API auch elektronische Regaletiketten aktualisieren?

Ja. LPSNG enthält eine herstellerneutrale JSON-Schnittstelle (ESLSEND) und eine Binding-API für ESL-Tags, sodass Sie sowohl gedruckte Etiketten als auch elektronische Regaletiketten aus derselben Integration verwalten können. Für einen tieferen Einblick lesen Sie unsere begleitenden Artikel zur ESL Binding API und zu electronic shelf label integration APIs.

Fazit

Das Muster ist kurz genug, um es im Kopf zu behalten: einmal mit OAuth2 registrieren, das Etikett einmal im Label-Studio gestalten und dann einen Auftrag übermitteln oder ein Rendering aus Ihrer Anwendung abrufen. Alles, was früher ein druckerspezifisches Problem war – Treiber, Befehlssprachen, Schriftenskalierung, Barcode-Bibliotheken – wird hinter einer API-Oberfläche behandelt, die Druckaufträge, Direktdruck, PDF- und PNG-Rendering sowie ESL-Updates abdeckt.

Next Generation Label Printing System ist der verwaltete Dienst, der daraus die gesamte Integration macht statt nur einen Teil davon. Beginnen Sie mit der Web Service Interface-Dokumentation für die genauen Endpunkte, gestalten Sie Ihr erstes Layout im Label-Studio und senden Sie einen Testauftrag an einen einzelnen Drucker, bevor Sie den Rest automatisieren. Wenn Sie noch Ihre Optionen abwägen, ist unser Zebra Designer alternative comparison eine sinnvolle nächste Lektüre.

So drucken Sie Etiketten über eine Web-Service-API: Ein Entwickler-Walkthrough