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
- (Facoltativo) All'avvio dell'app e dopo il salvataggio delle impostazioni, il lettore ottiene un token dall'URL del token.
- 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'intestazioneAuthorization: Bearer <token>. - 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.
| Campo | Cosa inserire | Esempio |
|---|---|---|
| Url to token | L'indirizzo che restituisce il token. | https://api.example.com/auth |
| GET / POST | Metodo della richiesta del token. | POST |
| Body request | Il corpo JSON inviato con POST (il campo è visibile solo per POST). | {"user":"pricechecker","password":"…"} |
| Path to token | Dove si trova il token nella risposta JSON. | token o $.data.token |
Dati del prodotto
| Campo | Cosa inserire | Esempio |
|---|---|---|
| Url to data | L'indirizzo della richiesta del prodotto; {code} viene sostituito dal codice scansionato. | https://api.example.com/price?code={code} |
| GET / POST | Metodo della richiesta del prodotto. | GET |
| Body request | Il corpo JSON per POST; qui puoi usare anche {code}. | {"ean":"{code}"} |
| Path to name | Percorso del nome del prodotto nella risposta. | product.name |
| Path to price | Percorso 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.