USB-Druckauftrag erstellen

POST https://www.expedy.fr/api/v2/devices/{device_uid}/usb/{usb_port}/print

Sendet einen Druckauftrag an einen Drucker, der an einem der USB-Anschlüsse Ihres Expedy-Geräts angeschlossen ist.

Basis-URL: https://www.expedy.fr/api/v2

Authentifizierung

Dieser Endpunkt erfordert einen Authorization-Header, der Ihre SID und Ihren TOKEN enthält, getrennt durch einen einzelnen Doppelpunkt.

Authorization: <SID>:<TOKEN>

Authorization: 9F3K7Q2WZ1ABCDEF:b1c2d3e4f5a6b7c8d9e0f1a2b3c4d5e6

⚠️ Dies ist kein Bearer-Token. Fügen Sie kein Bearer- oder Basic-Präfix hinzu — senden Sie den rohen Wert SID:TOKEN.

Beide Werte finden Sie in der Expedy-Konsole unter API. Alle Anfragen müssen über HTTPS (TLS) erfolgen.

Pfadparameter

Parameter	Typ	Erforderlich	Beschreibung
`device_uid`	`string`	Ja	UID des Geräts, in der Konsole unter Machines zu finden (z. B. `OOBBZ100PI`).
`usb_port`	`string`	Ja	Der USB-Anschluss, an dem der Drucker hängt: `1`, `2`, `3` oder `4`, passend zu den in der Konsole angezeigten Anschlüssen. Mit `/usb/scan/read` sehen Sie, was an welchem Anschluss steckt.

Ein Anschluss nimmt erst dann Aufträge an, wenn dort ein Drucker erkannt und konfiguriert wurde. Ist der Anschluss frei oder der Drucker daran nie konfiguriert worden, wird der Auftrag abgelehnt.

Anfragekörper

Content-Type: application/json

Parameter	Typ	Erforderlich	Beschreibung
`usb_msg`	`string`	Ja	Der zu druckende Inhalt, aufgebaut mit den Beleg-Layout-Tags (`<C>`, `<BOLD>`, `<IMG>`, `<QR>`, `<CUT/>`, …). Reiner Text, QR-Codes, Bilder oder eine PDF-URL.
`notification_url`	`string`	Nein	Eine URL, die der Druckdienst aufruft, sobald er den Auftrag an den Drucker übergeben hat. Damit schließen Sie den Kreis in Ihrem eigenen System, statt anzunehmen, dass gedruckt wurde.
`origin`	`string`	Nein	Eine frei wählbare Bezeichnung zur Kennzeichnung der Auftragsquelle (eine URI, ein App-Name, eine Abteilung…). Nützlich zum Filtern und Debuggen in Ihren Protokollen.
`printer_han`	`string`	Nein	Die Schrift, in der der Beleg gesetzt wird: `cn` Chinesisch, `kr` Koreanisch, `jp` Japanisch. Für lateinische Schriften weglassen. Siehe Asiatische Zeichen.

Beispielanfrage:

{
  "usb_msg": "<C><BOLD>ORDER #1234</BOLD></C>\n<C>Table 7</C>\n--------------------------------\n1 x Burger\n2 x Fries\n<CUT/>",
  "notification_url": "https://www.example.com/print-callback",
  "origin": "pos-kitchen-01"
}

cURL-Beispiel:

curl -X POST "https://www.expedy.fr/api/v2/devices/OOBBZ100PI/usb/1/print" \
  -H "Authorization: <SID>:<TOKEN>" \
  -H "Content-Type: application/json" \
  -d '{"usb_msg":"<C><BOLD>Hello</BOLD></C><CUT/>","origin":"my-app"}'

Asiatische Zeichen

Chinesisch, Japanisch und Koreanisch erfordern printer_han, gesetzt auf die Schrift, die Sie drucken.

Wert	Schrift
`cn`	Chinesisch
`kr`	Koreanisch
`jp`	Japanisch

1 wird weiterhin als Synonym für cn akzeptiert.

Standardmäßig wird der Beleg im Einzelbyte-Modus gesetzt: Jedes Zeichen wird über eine der Codepages des Druckers abgebildet. Keine Einzelbyte-Codepage enthält Hanzi, Kana oder Hangul — ohne diesen Parameter wird daher jedes solche Zeichen durch ein ? ersetzt, noch bevor der Auftrag das Gerät erreicht.

{
  "usb_msg": "<C><BOLD>주문 #1234</BOLD></C>\n<CUT/>",
  "printer_han": "kr"
}

Der Wert muss zur Schrift passen. Jeder wählt eine andere Kodierung, und sie überschneiden sich nicht: Koreanisch als cn gesendet kommt als ? heraus, genau wie ohne den Parameter.

Der Drucker muss die passende Schrift mitbringen. printer_han schaltet den Datenstrom in den Multibyte-Modus; die Glyphen selbst stammen aus dem Schrift-ROM des Druckers. Ein Modell ohne diese Schrift druckt die Zeichen auch mit dem richtigen Wert nicht, und ein für den chinesischen Markt bestimmter Drucker führt Hanzi mit, was nicht bedeutet, dass er Hangul oder Kana mitführt. Testen Sie die benötigte Schrift auf genau dem Modell, das Sie ausrollen, und wenden Sie sich an den Support, wenn das Ergebnis nicht lesbar ist.

Lateinischer Text braucht ihn nicht. Lassen Sie printer_han bei europäischen Sprachen weg; Zeichen mit Akzent werden im Standardmodus verarbeitet.

Senden Sie Ihren Inhalt in jedem Modus als UTF-8. Die API speichert und liefert genau das, was sie empfängt — der Druckverlauf in der Konsole zeigt den Text also so, wie er angekommen ist. Das ist der schnellste Weg, ein Datenproblem von einem Druckerproblem zu unterscheiden.

Antwort `200 OK`

Der Auftrag wurde angenommen und in die Warteschlange gestellt.

ℹ️ Ein 200 bestätigt nur den serverseitigen Empfang — nicht, dass der Beleg physisch gedruckt wurde. Die Zustellung erfolgt asynchron: Das Gerät erhält den Auftrag bei seiner nächsten Verbindung. Der Drucker kann zu diesem Zeitpunkt offline, ohne Papier, ausgeschaltet oder nicht erreichbar sein. Geben Sie eine notification_url an, wenn Sie wissen müssen, was tatsächlich passiert ist.

Parameter	Typ	Beschreibung
`request_uid`	`string`	Eindeutige Kennung des angenommenen Druckauftrags (z. B. `1X5ERXL94BYVWHP92DK3MCASUGJ`).
`last_ping`	`integer`	Unix-Zeitstempel des letzten Kontakts des Geräts mit dem Server. Ein weit zurückliegender Wert bedeutet, dass das Gerät beim Senden nicht online war.

Beispielantwort:

{
  "last_ping": 1641509604,
  "request_uid": "1X5ERXL94BYVWHP92DK3MCASUGJ"
}

last_ping lohnt sich bei jedem Aufruf: Es ist das billigste Signal dafür, dass ein Gerät verstummt ist.

Fehler

Status	Bedeutung
`403`	Fehlende oder ungültige Zugangsdaten (`SID` / `TOKEN`), oder das Gerät gehört nicht zu diesem Konto.
`404`	Unbekannte `device_uid` oder kein konfigurierter Drucker an diesem `usb_port`.
`405`	Falsche HTTP-Methode — dieser Endpunkt akzeptiert nur `POST`.
`422`	`usb_msg` leer oder fehlerhaft.
`500`	Der Auftrag konnte nicht an das Gerät übergeben werden. Erneut versuchen, bei anhaltendem Fehler den Support kontaktieren.

Empfohlene Vorgehensweisen

Idempotenz. Jede angenommene Anfrage erzeugt einen Druck. Der Endpunkt entfernt keine Duplikate: Wenn Sie nach einem Netzwerkfehler erneut senden, schützen Sie sich auf Ihrer Seite gegen doppeltes Drucken.
usb_msg innerhalb der Papierbreite halten. 32 Zeichen pro Zeile bei 58 mm, 48 bei 80 mm. Siehe die Layout-Referenz.
Mit und ohne Bilder testen. Manche Druckermodelle lehnen bestimmte Bildtypen ab und lassen den gesamten Auftrag fehlschlagen — vor dem Produktivbetrieb prüfen.

SDK & Beispiele

Bevorzugen Sie einen fertigen Client? Verwenden Sie das offizielle Node.js-SDK:

👉 github.com/ExpedyDev/expedy-sdk-node