Passa al contenuto principale

REST API

La fonte Rest API permette di collegare il lettore di prezzi a qualsiasi sistema che, dato un codice, restituisca in JSON il nome e il prezzo di un prodotto, ad es. un negozio online, un sistema POS o un tuo servizio middleware.

Come funziona​

  1. (Facoltativo) All'avvio dell'app e dopo il salvataggio delle impostazioni, il lettore ottiene un token dall'URL del token.
  2. Dopo ogni scansione invia una richiesta all'URL dei dati, in cui {code} viene sostituito dal codice scansionato. Se dispone di un token, aggiunge l'intestazione Authorization: Bearer <token>.
  3. Legge dalla risposta JSON il nome, il prezzo e, facoltativamente, l'EAN, usando i percorsi che indichi.

Funzionano sia http:// sia https://. L'app attende circa 10 secondi per una risposta.

Campi​

Token (facoltativo): lascia vuoto Url to token se l'API non richiede autenticazione.

CampoCosa inserireEsempio
Url to tokenL'indirizzo che restituisce il token.https://api.example.com/auth
GET / POSTMetodo della richiesta del token.POST
Body requestIl corpo JSON inviato con POST (il campo è visibile solo per POST).{"user":"pricechecker","password":"…"}
Path to tokenDove si trova il token nella risposta JSON.token o $.data.token

Dati del prodotto

CampoCosa inserireEsempio
Url to dataL'indirizzo della richiesta del prodotto; {code} viene sostituito dal codice scansionato.https://api.example.com/price?code={code}
GET / POSTMetodo della richiesta del prodotto.GET
Body requestIl corpo JSON per POST; qui puoi usare anche {code}.{"ean":"{code}"}
Path to namePercorso del nome del prodotto nella risposta.product.name
Path to pricePercorso del prezzo; il valore deve essere un numero.product.price
Path to EAN (optional)Percorso del codice EAN mostrato sotto il prezzo. Vuoto = sotto il prezzo viene mostrato il codice scansionato.product.ean

I percorsi usano la sintassi JsonPath: product.name e $.product.name equivalgono, un elemento di array è ad es. $.items[0].price. Le richieste POST vengono inviate con l'intestazione Content-Type: application/json; charset=utf-8.

Esempio​

La richiesta dopo la scansione del codice 5901234567890:

GET https://api.example.com/price?code=5901234567890
Authorization: Bearer eyJhbGciOi...

Una risposta che il lettore di prezzi comprende:

{
"product": {
"name": "Coffee beans 1 kg",
"price": 59.99,
"ean": "5901234567890"
}
}

Impostazioni: Path to name product.name, Path to price product.price, Path to EAN product.ean. Restituisci il prezzo come numero con il punto decimale: il lettore lo formatta secondo il campo Price format.

Requisiti dell'API​

  • Per un prodotto trovato, l'API risponde con uno stato 2xx e un JSON che contiene il nome e il prezzo.
  • Qualsiasi altra risposta (ad es. 404 per un codice sconosciuto, 401 per un token non valido, un campo mancante nel JSON) mostra Data download error sullo schermo. Con REST API l'app non mostra «Product not found»: se vuoi che i clienti distinguano questi casi, restituisci ad es. il nome «Product not available» con prezzo 0.
  • Il codice viene inserito nell'URL senza codifica. I codici EAN e i simboli tipici non creano problemi; se i tuoi simboli contengono spazi o caratteri speciali, usa una richiesta POST con il codice nel corpo.
  • Il token viene ottenuto solo all'avvio dell'app e dopo il salvataggio delle impostazioni: l'app non lo rinnova da sola. Usa un token di lunga durata o una chiave che non scada; dopo la scadenza del token, riavviare l'app risolve il problema.

Il Connection test nelle impostazioni verifica solo la richiesta del token. Quando l'URL del token è vuoto il test riesce sempre: la verifica reale consiste nel scansionare alcuni prodotti dopo aver salvato le impostazioni.

REST API — FAQ

Come collego il lettore di prezzi HDWR al mio sistema?
Scegli la fonte Rest API e inserisci l'indirizzo della richiesta del prodotto con il segnaposto {code} dove va il codice, ad es. https://api.example.com/price?code={code}, più i percorsi del nome e del prezzo nella risposta JSON. Facoltativamente inserisci un indirizzo da cui l'app ottiene un token Bearer.
Perché con REST API il lettore mostra Data download error invece di Product not found?
Con REST API ogni risposta diversa da 2xx, o una risposta priva del campo del nome o del prezzo, è trattata come errore. Se l'API restituisce 404 per un codice sconosciuto, lo schermo mostra Data download error.
L'app rinnova il token della REST API?
No. Il token viene ottenuto all'avvio dell'app e dopo il salvataggio delle impostazioni. Usa un token di lunga durata; dopo la sua scadenza riavvia l'app.
Il lettore di prezzi supporta il semplice HTTP?
Sì, supporta http e https. Nella rete locale del negozio puoi usare http; per un'API su Internet usa https.