REST API
Źródło Rest API pozwala podłączyć sprawdzarkę do dowolnego systemu, który po podaniu kodu towaru zwraca jego nazwę i cenę w formacie JSON – np. sklepu internetowego, systemu POS albo własnej usługi pośredniczącej.
Jak to działa
- (Opcjonalnie) Przy starcie aplikacji i po zapisaniu ustawień sprawdzarka pobiera token z adresu tokena.
- Po każdym skanie wysyła zapytanie na adres danych, w którym
{code}zamienia na zeskanowany kod. Jeśli ma token, dodaje nagłówekAuthorization: Bearer <token>. - Z odpowiedzi JSON odczytuje nazwę, cenę i opcjonalnie EAN – według podanych ścieżek.
Działa zarówno http://, jak i https://. Na odpowiedź aplikacja czeka około 10 sekund.
Pola
Token (opcjonalnie) – zostaw Url do tokena pusty, jeśli API nie wymaga logowania.
| Pole | Co wpisać | Przykład |
|---|---|---|
| Url do tokena | Adres, który zwraca token. | https://api.example.com/auth |
| GET / POST | Metoda zapytania o token. | POST |
| Ciało zapytania | Treść JSON wysyłana przy POST (pole widać tylko przy POST). | {"user":"sprawdzarka","password":"…"} |
| Ścieżka do tokena | Gdzie w odpowiedzi JSON jest token. | token albo $.data.token |
Dane towaru
| Pole | Co wpisać | Przykład |
|---|---|---|
| Url do danych | Adres zapytania o towar; {code} zostanie zamienione na odczytany kod. | https://api.example.com/price?code={code} |
| GET / POST | Metoda zapytania o towar. | GET |
| Ciało zapytania | Treść JSON przy POST; tu także możesz użyć {code}. | {"ean":"{code}"} |
| Ścieżka do nazwy | Ścieżka do nazwy towaru w odpowiedzi. | product.name |
| Ścieżka do ceny | Ścieżka do ceny; wartość musi być liczbą. | product.price |
| Ścieżka do EAN (opcjonalnie) | Ścieżka do kodu EAN pokazywanego pod ceną. Puste pole = pod ceną będzie zeskanowany kod. | product.ean |
Ścieżki zapisuje się w składni JsonPath: product.name i $.product.name znaczą to samo, element tablicy to np. $.items[0].price. Zapytania POST są wysyłane z nagłówkiem Content-Type: application/json; charset=utf-8.
Przykład
Zapytanie po zeskanowaniu kodu 5901234567890:
GET https://api.example.com/price?code=5901234567890
Authorization: Bearer eyJhbGciOi...
Odpowiedź, którą sprawdzarka rozumie:
{
"product": {
"name": "Kawa ziarnista 1 kg",
"price": 59.99,
"ean": "5901234567890"
}
}
Ustawienia: Ścieżka do nazwy product.name, Ścieżka do ceny product.price, Ścieżka do EAN product.ean. Cenę podawaj z kropką jako liczbę – sprawdzarka sformatuje ją według pola Format ceny.
Wymagania wobec API
- Dla znalezionego towaru API odpowiada kodem 2xx i JSON-em, w którym są nazwa i cena.
- Każda inna odpowiedź (np. 404 dla nieznanego kodu, 401 przy nieważnym tokenie, brak pola w JSON-ie) daje na ekranie Błąd pobierania danych. Przy REST API aplikacja nie pokazuje komunikatu „Nie znaleziono produktu” – jeśli chcesz rozróżniać te sytuacje dla klienta, zwracaj np. nazwę „Brak towaru” z ceną 0.
- Kod jest wstawiany do adresu bez kodowania znaków. Kody EAN i typowe symbole nie sprawiają kłopotu; jeśli Twoje symbole mają spacje lub znaki specjalne, użyj zapytania POST z kodem w ciele.
- Token jest pobierany tylko przy starcie aplikacji i po zapisaniu ustawień – aplikacja nie odnawia go sama. Użyj tokena o długiej ważności albo klucza, który nie wygasa; po wygaśnięciu tokena pomaga ponowne uruchomienie aplikacji.
Test połączenia w ustawieniach sprawdza tylko pobranie tokena. Gdy adres tokena jest pusty, test zawsze kończy się sukcesem – prawdziwy sprawdzian to skan kilku towarów po zapisaniu ustawień.