Creare un lavoro di stampa

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

Invia un lavoro di stampa alla stampante termica cloud designata.

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>

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

Authorization: 9F3K7Q2WZ1ABCDEF:b1c2d3e4f5a6b7c8d9e0f1a2b3c4d5e6

Entrambi i valori sono disponibili nella console Expedy, nella sezione API. Le richieste con un SID:TOKEN mancante o non valido vengono rifiutate e restituiscono un involucro di errore (vedi Errori).

Tutte le richieste devono essere effettuate tramite HTTPS (TLS).

Parametri del percorso

Corpo della richiesta

Content-Type: application/json

Esempio di richiesta:

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

Esempio cURL:

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

Caratteri asiatici

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

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.

{
  "printer_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 dal server di stampa cloud Expedy.

ℹ️ Un 200 conferma solo la ricezione lato server, non che lo scontrino sia stato stampato fisicamente. La stampa è asincrona: il server consegna il lavoro al dispositivo alla sua successiva connessione. Un 200 non garantisce l'uscita su carta, perché in quel momento la stampante potrebbe essere offline, senza carta, spenta o irraggiungibile sulla sua rete/SIM. Usa il request_uid restituito per fare riferimento al lavoro nei tuoi log e nelle richieste di assistenza.

Esempio di risposta:

{
  "request_uid": "1X5ERXL94BYVWHP92DK3MCASUGJ"
}

Errori

Qualsiasi stato diverso da 2xx restituisce un involucro JSON con un campo message che descrive il problema:

{
  "message": "Invalid printer"
}

Leggi sempre il campo message invece di affidarti al solo codice di stato.

Buone pratiche

• Idempotenza. Ogni richiesta accettata produce una stampa. L'endpoint non deduplica, quindi se riprovi dopo un errore di rete, proteggiti dalla doppia stampa dal tuo lato (es. tracciando il request_uid, o contrassegnando l'ordine come stampato alla ricezione di un 200).
• 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.
• Mantieni printer_msg entro la larghezza della carta. 32 caratteri per riga a 58 mm, 48 a 80 mm. Vedi il riferimento del layout.

Elenca le stampanti

Per scoprire i valori printer_uid del tuo account:

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

Restituisce le stampanti collegate al tuo account (nome, larghezza della carta, UID, stato), usando la stessa intestazione Authorization: <SID>:<TOKEN>.

SDK ed esempi

Preferisci un client pronto all'uso? Usa l'SDK ufficiale Node.js: incapsula l'autenticazione, l'elenco delle stampanti e i lavori di stampa:

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