Creare un lavoro di stampa USB

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

Invia un lavoro di stampa a una stampante collegata a una delle porte USB del tuo dispositivo Expedy.

URL di base: https://www.expedy.fr/api/v2

Autenticazione

Questo endpoint richiede un'intestazione Authorization contenente il tuo SID e il tuo TOKEN, separati da un singolo carattere due punti.

Authorization: <SID>:<TOKEN>

Authorization: 9F3K7Q2WZ1ABCDEF:b1c2d3e4f5a6b7c8d9e0f1a2b3c4d5e6

⚠️ Questo non è un token Bearer. Non aggiungere un prefisso Bearer o Basic: invia il valore grezzo SID:TOKEN.

Entrambi i valori sono disponibili nella console Expedy, nella sezione API. Tutte le richieste devono essere effettuate tramite HTTPS (TLS).

Parametri del percorso

Parametro	Tipo	Obbligatorio	Descrizione
`device_uid`	`string`	Sì	UID del dispositivo, visibile nella console sotto Machines (es. `OOBBZ100PI`).
`usb_port`	`string`	Sì	La porta USB a cui è collegata la stampante: `1`, `2`, `3` o `4`, secondo le porte mostrate nella console. Usa `/usb/scan/read` per vedere cosa è collegato a ciascuna.

Una porta accetta lavori solo dopo che vi è stata rilevata e configurata una stampante. Se la porta è libera, o se la stampante collegata non è mai stata configurata, il lavoro viene rifiutato.

Corpo della richiesta

Content-Type: application/json

Parametro	Tipo	Obbligatorio	Descrizione
`usb_msg`	`string`	Sì	Il contenuto da stampare, costruito con i tag di layout dello scontrino (`<C>`, `<BOLD>`, `<IMG>`, `<QR>`, `<CUT/>`, …). Testo semplice, codici QR, immagini o l'URL di un PDF.
`notification_url`	`string`	No	Un URL che il servizio di stampa richiama una volta consegnato il lavoro alla stampante. Serve a chiudere il ciclo nel tuo sistema invece di dare per scontato che lo scontrino sia uscito.
`origin`	`string`	No	Un'etichetta libera per contrassegnare l'origine del lavoro (un URI, un nome di applicazione, un reparto…). Utile per filtrare ed eseguire il debug nei tuoi log.
`printer_han`	`string`	No	La scrittura con cui comporre lo scontrino: `cn` cinese, `kr` coreano, `jp` giapponese. Omettilo per le scritture latine. Vedi Caratteri asiatici.

Esempio di richiesta:

{
  "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"
}

Esempio cURL:

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"}'

Caratteri asiatici

Cinese, giapponese e coreano richiedono printer_han, impostato sulla scrittura che stai stampando.

Valore	Scrittura
`cn`	cinese
`kr`	coreano
`jp`	giapponese

1 resta accettato come sinonimo di cn.

Per impostazione predefinita lo scontrino è composto in modalità a byte singolo: ogni carattere è mappato tramite una delle code page della stampante. Nessuna code page a byte singolo contiene hanzi, kana o hangul, quindi senza questo parametro ognuno di quei caratteri viene sostituito da un ? ancora prima che il lavoro raggiunga il dispositivo.

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

Il valore deve corrispondere alla scrittura. Ognuno seleziona una codifica diversa e non si sovrappongono: il coreano inviato come cn esce come ?, esattamente come se il parametro fosse stato omesso.

La stampante deve disporre del font corrispondente. printer_han commuta il flusso in modalità multibyte; i glifi provengono dalla ROM dei font della stampante. Un modello venduto senza quel font non stamperà i caratteri nemmeno con il valore giusto, e una stampante destinata al mercato cinese contiene gli hanzi, il che non significa che contenga hangul o kana. Prova la scrittura che ti serve sul modello esatto che andrai a installare e contatta il supporto se il risultato non è leggibile.

Il testo latino non ne ha bisogno. Ometti printer_han per le lingue europee: i caratteri accentati sono gestiti dalla modalità predefinita.

Invia il contenuto in UTF-8 in tutte le modalità. L'API memorizza e restituisce esattamente ciò che riceve, quindi la cronologia di stampa nella console mostra il testo come è arrivato: è il modo più rapido per distinguere un problema di dati da uno di stampante.

Risposta `200 OK`

Il lavoro è stato accettato e messo in coda.

ℹ️ Un 200 conferma solo la ricezione lato server, non che lo scontrino sia stato stampato fisicamente. La consegna è asincrona: il dispositivo riceve il lavoro alla sua successiva connessione. In quel momento la stampante potrebbe essere offline, senza carta, spenta o irraggiungibile. Indica una notification_url se hai bisogno di sapere cosa è successo davvero.

Parametro	Tipo	Descrizione
`request_uid`	`string`	Identificatore univoco del lavoro di stampa accettato (es. `1X5ERXL94BYVWHP92DK3MCASUGJ`).
`last_ping`	`integer`	Timestamp Unix dell'ultimo contatto del dispositivo con il server. Un valore lontano nel tempo significa che il dispositivo non era online al momento dell'invio.

Esempio di risposta:

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

Vale la pena leggere last_ping a ogni chiamata: è il segnale meno costoso del fatto che un dispositivo è ammutolito.

Errori

Stato	Significato
`403`	Credenziali mancanti o non valide (`SID` / `TOKEN`), oppure il dispositivo non appartiene a questo account.
`404`	`device_uid` sconosciuto, o nessuna stampante configurata su quella `usb_port`.
`405`	Metodo HTTP errato: questo endpoint accetta solo `POST`.
`422`	`usb_msg` vuoto o malformato.
`500`	Il lavoro non ha potuto essere consegnato al dispositivo. Riprova e, se persiste, contatta il supporto.

Buone pratiche

Idempotenza. Ogni richiesta accettata produce una stampa. L'endpoint non deduplica: se riprovi dopo un errore di rete, proteggiti dalla doppia stampa dal tuo lato.
Mantieni usb_msg entro la larghezza della carta. 32 caratteri per riga a 58 mm, 48 a 80 mm. Vedi il riferimento del layout.
Prova con e senza immagini. Alcuni modelli di stampante rifiutano certi tipi di immagine e possono far fallire l'intero lavoro: verifica prima della produzione.

Endpoint correlati

GET https://www.expedy.fr/api/v2/devices/{device_uid}/usb/scan/read

Restituisce cosa è attualmente collegato a ciascuna porta USB, con produttore e modello rilevati. Usalo per scoprire su quale porta stampare e per confermare che una stampante sia ancora dove ti aspetti.

/usb/conf restituisce la configurazione salvata di ogni porta: larghezza della carta, modalità di stampa, modalità grafica.

SDK ed esempi

Preferisci un client pronto all'uso? Usa l'SDK ufficiale Node.js:

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