Skip to main content

REST API

Sursa Rest API îți permite să conectezi verificatorul de preț la orice sistem care returnează în format JSON denumirea și prețul unui produs pentru un cod dat — de exemplu un magazin online, un sistem POS sau propriul serviciu intermediar.

Cum funcționează​

  1. (Opțional) La pornirea aplicației și după salvarea setărilor, verificatorul de preț obține un token de la adresa URL a tokenului.
  2. După fiecare scanare trimite o cerere către adresa URL a datelor, în care {code} este înlocuit cu codul scanat. Dacă are un token, adaugă antetul Authorization: Bearer <token>.
  3. Citește din răspunsul JSON denumirea, prețul și, opțional, EAN-ul — folosind căile pe care le indici.

Funcționează atât http://, cât și https://. Aplicația așteaptă un răspuns aproximativ 10 secunde.

Câmpuri​

Token (opțional) — lasă Url to token gol dacă API-ul nu necesită autentificare.

CâmpCe introduciExemplu
Url to tokenAdresa care returnează tokenul.https://api.example.com/auth
GET / POSTMetoda cererii pentru token.POST
Body requestCorpul JSON trimis cu POST (câmpul este vizibil doar pentru POST).{"user":"pricechecker","password":"…"}
Path to tokenUnde se află tokenul în răspunsul JSON.token sau $.data.token

Datele produsului

CâmpCe introduciExemplu
Url to dataAdresa cererii pentru produs; {code} este înlocuit cu codul scanat.https://api.example.com/price?code={code}
GET / POSTMetoda cererii pentru produs.GET
Body requestCorpul JSON pentru POST; poți folosi {code} și aici.{"ean":"{code}"}
Path to nameCalea către denumirea produsului în răspuns.product.name
Path to priceCalea către preț; valoarea trebuie să fie un număr.product.price
Path to EAN (optional)Calea către codul EAN afișat sub preț. Gol = sub preț se afișează codul scanat.product.ean

Căile folosesc sintaxa JsonPath: product.name și $.product.name înseamnă același lucru, iar un element de tablou se scrie, de exemplu, $.items[0].price. Cererile POST sunt trimise cu antetul Content-Type: application/json; charset=utf-8.

Exemplu​

Cererea după scanarea codului 5901234567890:

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

Un răspuns pe care verificatorul de preț îl înțelege:

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

Setări: Path to name product.name, Path to price product.price, Path to EAN product.ean. Returnează prețul ca număr cu punct zecimal — verificatorul de preț îl formatează conform câmpului Price format.

Cerințe pentru API​

  • Pentru un produs găsit, API-ul răspunde cu un status 2xx și cu un JSON care conține denumirea și prețul.
  • Orice alt răspuns (de exemplu 404 pentru un cod necunoscut, 401 pentru un token invalid, un câmp lipsă în JSON) afișează pe ecran Data download error. Cu REST API aplicația nu afișează „Product not found” — dacă vrei ca clienții să poată distinge aceste cazuri, returnează, de exemplu, denumirea „Product not available” cu prețul 0.
  • Codul este inserat în URL fără codificare. Codurile EAN și simbolurile obișnuite nu creează probleme; dacă simbolurile tale conțin spații sau caractere speciale, folosește o cerere POST cu codul în corp.
  • Tokenul este obținut doar la pornirea aplicației și după salvarea setărilor — aplicația nu îl reînnoiește singură. Folosește un token cu valabilitate lungă sau o cheie care nu expiră; după expirarea tokenului ajută repornirea aplicației.

Connection test din setări verifică doar cererea pentru token. Când adresa URL a tokenului este goală, testul reușește întotdeauna — verificarea reală este scanarea câtorva produse după salvarea setărilor.

REST API — întrebări frecvente

Cum conectez verificatorul de preț HDWR la propriul sistem?
Alege sursa Rest API și introdu adresa cererii pentru produs cu substituentul {code} în locul în care trebuie să apară codul, de exemplu https://api.example.com/price?code={code}, plus căile către denumire și preț din răspunsul JSON. Opțional, introdu o adresă de la care aplicația obține un token Bearer.
De ce afișează verificatorul de preț Data download error în loc de Product not found cu REST API?
Cu REST API, orice răspuns diferit de 2xx sau un răspuns fără câmpul pentru denumire ori preț este tratat ca eroare. Dacă API-ul returnează 404 pentru un cod necunoscut, ecranul afișează Data download error.
Reînnoiește aplicația tokenul REST API?
Nu. Tokenul este obținut la pornirea aplicației și după salvarea setărilor. Folosește un token cu valabilitate lungă; după expirarea lui, repornește aplicația.
Acceptă verificatorul de preț HTTP simplu?
Da, acceptă atât http, cât și https. În rețeaua locală a magazinului poți folosi http; pentru un API de pe internet folosește https.