Creare un lavoro di stampa

Inviare 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

Parametro	Tipo	Obbligatorio	Descrizione
`printer_uid`	`string`	Sì	UID della stampante di destinazione, visibile nella console sotto Printers (es. `WP0RGS1SEDZ`). Non includere il simbolo `#`. Usa `GET /printers/all` per recuperarlo a livello di codice.

Corpo della richiesta

Content-Type: application/json

Parametro	Tipo	Obbligatorio	Descrizione
`printer_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: qualsiasi cosa supportata dalla stampante.
`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.

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

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.

Parametro	Tipo	Descrizione
`request_uid`	`string`	Identificatore univoco del lavoro di stampa accettato (es. `1X5ERXL94BYVWHP92DK3MCASUGJ`).

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

Stato	Significato
`401` / `403`	Credenziali mancanti o non valide (`SID` / `TOKEN`).
`422`	La richiesta non ha potuto essere elaborata — es. un `printer_uid` sconosciuto o un corpo malformato.

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