Przejdź do głównej zawartości

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​

  1. (Opcjonalnie) Przy starcie aplikacji i po zapisaniu ustawień sprawdzarka pobiera token z adresu tokena.
  2. Po każdym skanie wysyła zapytanie na adres danych, w którym {code} zamienia na zeskanowany kod. Jeśli ma token, dodaje nagłówek Authorization: Bearer <token>.
  3. 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.

PoleCo wpisaćPrzykład
Url do tokenaAdres, który zwraca token.https://api.example.com/auth
GET / POSTMetoda zapytania o token.POST
Ciało zapytaniaTreść JSON wysyłana przy POST (pole widać tylko przy POST).{"user":"sprawdzarka","password":"…"}
Ścieżka do tokenaGdzie w odpowiedzi JSON jest token.token albo $.data.token

Dane towaru

PoleCo wpisaćPrzykład
Url do danychAdres zapytania o towar; {code} zostanie zamienione na odczytany kod.https://api.example.com/price?code={code}
GET / POSTMetoda zapytania o towar.GET
Ciało zapytaniaTreść 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ń.

REST API — najczęstsze pytania

Jak podłączyć sprawdzarkę cen HDWR do własnego systemu?
Wybierz źródło Rest API i podaj adres zapytania o towar z ciągiem {code} w miejscu kodu, np. https://api.example.com/price?code={code}, oraz ścieżki do nazwy i ceny w odpowiedzi JSON. Opcjonalnie podaj adres, z którego aplikacja pobierze token Bearer.
Dlaczego przy REST API sprawdzarka pokazuje Błąd pobierania danych zamiast Nie znaleziono produktu?
Przy REST API każda odpowiedź inna niż 2xx albo brak pola nazwy lub ceny w JSON-ie jest traktowana jako błąd. Jeśli API zwraca 404 dla nieznanego kodu, na ekranie pojawi się Błąd pobierania danych.
Czy aplikacja odnawia token REST API?
Nie. Token jest pobierany przy starcie aplikacji i po zapisaniu ustawień. Użyj tokena o długiej ważności; po jego wygaśnięciu uruchom aplikację ponownie.
Czy sprawdzarka obsługuje zwykły HTTP?
Tak, obsługuje http i https. W sieci lokalnej sklepu możesz użyć http, przy API w internecie używaj https.