Druckauftrag erstellen

POST https://www.expedy.fr/api/v2/printers/{printer_uid}/print

Sendet einen Druckauftrag an den angegebenen Cloud-Thermodrucker.

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>

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

Authorization: 9F3K7Q2WZ1ABCDEF:b1c2d3e4f5a6b7c8d9e0f1a2b3c4d5e6

Beide Werte finden Sie in der Expedy-Konsole unter API. Anfragen mit fehlendem oder ungültigem SID:TOKEN werden abgelehnt und geben einen Fehler-Umschlag zurück (siehe Fehler).

Alle Anfragen müssen über HTTPS (TLS) erfolgen.

Pfadparameter

Parameter	Typ	Erforderlich	Beschreibung
`printer_uid`	`string`	Ja	UID des Zieldruckers, in der Konsole unter Printers zu finden (z. B. `WP0RGS1SEDZ`). Das Zeichen `#` nicht mit angeben. Verwenden Sie `GET /printers/all`, um sie programmatisch abzurufen.

Anfragekörper

Content-Type: application/json

Parameter	Typ	Erforderlich	Beschreibung
`printer_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 — alles, was der Drucker unterstützt.
`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:

{
  "printer_msg": "<C><BOLD>ORDER #1234</BOLD></C>\n<C>Table 7</C>\n--------------------------------\n1 x Burger\n2 x Fries\n<CUT/>",
  "origin": "pos-kitchen-01"
}

cURL-Beispiel:

curl -X POST "https://www.expedy.fr/api/v2/printers/WP0RGS1SEDZ/print" \
  -H "Authorization: <SID>:<TOKEN>" \
  -H "Content-Type: application/json" \
  -d '{"printer_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.

{
  "printer_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 vom Expedy Cloud Print Server angenommen und in die Warteschlange gestellt.

ℹ️ Ein 200 bestätigt nur den serverseitigen Empfang — nicht, dass der Beleg physisch gedruckt wurde. Das Drucken erfolgt asynchron: Der Server übergibt den Auftrag an das Gerät, sobald es sich das nächste Mal verbindet. Ein 200 garantiert keine Papierausgabe, da der Drucker zu diesem Zeitpunkt offline, ohne Papier, ausgeschaltet oder über sein Netzwerk/seine SIM nicht erreichbar sein kann. Verwenden Sie die zurückgegebene request_uid, um den Auftrag in Ihren eigenen Protokollen und Supportanfragen zu referenzieren.

Parameter	Typ	Beschreibung
`request_uid`	`string`	Eindeutige Kennung des angenommenen Druckauftrags (z. B. `1X5ERXL94BYVWHP92DK3MCASUGJ`).

Beispielantwort:

{
  "request_uid": "1X5ERXL94BYVWHP92DK3MCASUGJ"
}

Fehler

Jeder Status, der nicht 2xx ist, gibt einen JSON-Umschlag mit einem message-Feld zurück, das das Problem beschreibt:

{
  "message": "Invalid printer"
}

Status	Bedeutung
`401` / `403`	Fehlende oder ungültige Zugangsdaten (`SID` / `TOKEN`).
`422`	Die Anfrage konnte nicht verarbeitet werden — z. B. eine unbekannte `printer_uid` oder ein fehlerhafter Körper.

Lesen Sie immer das message-Feld, anstatt sich allein auf den Statuscode zu verlassen.

Empfohlene Vorgehensweisen

Idempotenz. Jede angenommene Anfrage erzeugt einen Druck. Der Endpunkt entfernt keine Duplikate. Wenn Sie also nach einem Netzwerkfehler erneut senden, schützen Sie sich auf Ihrer Seite gegen doppeltes Drucken (z. B. indem Sie die request_uid nachverfolgen oder die Bestellung als gedruckt markieren, sobald ein 200 eingeht).
Mit und ohne Bilder testen. Manche Druckermodelle lehnen bestimmte Bildtypen ab und lassen den gesamten Auftrag fehlschlagen — vor dem Produktivbetrieb prüfen.
printer_msg innerhalb der Papierbreite halten. 32 Zeichen pro Zeile bei 58 mm, 48 bei 80 mm. Siehe die Layout-Referenz.

Drucker auflisten

So ermitteln Sie die printer_uid-Werte Ihres Kontos:

GET https://www.expedy.fr/api/v2/printers/all

Gibt die mit Ihrem Konto verbundenen Drucker zurück (Name, Papierbreite, UID, Status), unter Verwendung desselben Authorization: <SID>:<TOKEN>-Headers.

SDK & Beispiele

Bevorzugen Sie einen fertigen Client? Verwenden Sie das offizielle Node.js-SDK — es kapselt Authentifizierung, Druckerliste und Druckaufträge:

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