Przejdź do treści

API

MobiSkan WMS udostępnia interfejs REST nad HTTP, z którego korzysta panel, aplikacja kolektora, konektory ERP oraz integracje własne klienta.

Adres i dokumentacja tras

W instalacji natywnej serwer udostępnia panel i API pod jednym adresem, a trasy API mają wtedy przedrostek /api. Wyjątkiem są trasy używane przez kolektory (/sync/* i /collector-auth/*), sprawdzenie gotowości serwera oraz metryki - te pozostają na ścieżkach bez przedrostka.

Pełna, zawsze aktualna lista tras wraz ze schematami danych jest dostępna w interfejsie dokumentacji API pod adresem /docs. Poza środowiskiem deweloperskim ekran ten jest udostępniany wyłącznie wtedy, gdy skonfigurowano dla niego dane dostępowe.

API nie ma wersjonowania w ścieżce.

Uwierzytelnianie

System rozróżnia cztery niezależne rodzaje tożsamości. Nigdy się nie mieszają - o tym, jaka tożsamość jest wymagana, decyduje konkretna trasa.

Tożsamość Sposób uwierzytelnienia Zastosowanie
Użytkownik panelu token dostępowy JWT w nagłówku Authorization: Bearer, odświeżany tokenem w ciasteczku panel przeglądarkowy
Operator terminala token dostępowy JWT wydany po zalogowaniu operatora na urządzeniu zapis danych z kolektora
Sparowane urządzenie lub konektor ERP nieprzezroczysty token długożyciowy w nagłówku Authorization: Bearer pobieranie danych przed zalogowaniem operatora, integracja ERP
Właściciel instalacji osobny token JWT zarządzanie firmami na instalacji

Logowanie użytkownika panelu

Logowanie wymaga trzech wartości: identyfikatora firmy, loginu i hasła. Login jest unikalny wyłącznie w obrębie firmy, więc sam login nie wystarczy do identyfikacji konta.

W odpowiedzi zwracany jest token dostępowy, dane użytkownika oraz komplet jego uprawnień. Token odświeżający jest zwracany w ciasteczku niedostępnym dla skryptów.

Tokeny API

Token API to długożyciowy klucz przypisany do urządzenia lub konektora. Tokeny zakłada się w Ustawienia > Narzędzia > Integracja MobiSkan Kolektor.

Zarządzanie tokenami API

Zasady:

  • pełna wartość tokenu jest pokazywana wyłącznie raz, zaraz po wygenerowaniu - system przechowuje jedynie jej skrót kryptograficzny i cztery ostatnie znaki do rozpoznania na liście,
  • token przekazuje się w nagłówku Authorization: Bearer <token>,
  • unieważnienie tokenu odbiera dostęp natychmiast,
  • każdy token urządzenia zajmuje jedno miejsce w limicie licencji.

Token urządzenia otwiera dostęp do tras odczytowych synchronizacji. Zapis danych wymaga dodatkowo zalogowanej sesji operatora terminala. Szczegóły: Synchronizacja kolektora.

Token konektora ERP powstaje w procesie konfiguracji integracji i ma dodatkowe uprawnienie pozwalające zalogować się jako systemowe konto konektora.

Izolacja firm

Tożsamość zawiera informację o firmie. Każde żądanie jest ograniczone do danych tej firmy - zarówno w warstwie aplikacji, jak i w samej bazie danych. Nie ma sposobu, żeby jednym tokenem sięgnąć po dane innej firmy.

Konwencje

Konwencja Szczegół
Nazwy zasobów liczba mnoga w formie z myślnikami, na przykład currencies, goods-base, inbound-documents, pick-documents
Dokumenty z pozycjami odczyt i zapis dokumentu, lista i zapis jego pozycji, zamknięcie dokumentu oraz zakończenie szkicu jako osobne operacje
Walidacja wejścia pola nieznane w kontrakcie powodują odrzucenie żądania, a nie ciche zignorowanie
Listy o dużym wolumenie stronicowanie, wyszukiwanie, filtrowanie i sortowanie po stronie serwera
Ilości i kwoty liczby dziesiętne o stałej precyzji, nigdy liczby zmiennoprzecinkowe
Identyfikatory UUID, nie kolejne liczby
Znaczniki czasu zawsze ze strefą czasową

Idempotencja

Każda operacja zmieniająca dane może przyjąć opcjonalny identyfikator polecenia wygenerowany przez klienta. Powtórzenie tej samej operacji z tym samym identyfikatorem zwraca zapisany wcześniej wynik zamiast wykonywać ją drugi raz.

Chroni to przed skutkami zerwanego połączenia i ponowienia żądania: podwójnym zamknięciem dokumentu albo podwójnym zliczeniem tego samego skanu.

Kontrola współbieżności

Dokumenty i pozycje stanu mają numer wersji. Operacja zapisu może przekazać oczekiwaną wersję - jeśli nie zgadza się ona z aktualną, żądanie jest odrzucane błędem konfliktu wersji zamiast po cichu nadpisać cudzą zmianę. Nie ma trybu scalania ani zasady "ostatni wygrywa".

Kształt odpowiedzi błędu

Każdy błąd zwraca obiekt JSON o stałej strukturze:

Pole Znaczenie
code ustalony kod błędu, patrz tabela niżej
message opis błędu
correlationId identyfikator żądania, ten sam co w logu serwera
details dodatkowe informacje, gdy występują
messageKey klucz komunikatu do własnego tłumaczenia po stronie klienta
params parametry komunikatu

Pole correlationId warto zapisywać po stronie klienta - pozwala jednoznacznie odnaleźć odpowiadający wpis w logu serwera przy zgłoszeniu problemu.

Kody błędów

Kod Znaczenie
VALIDATION_ERROR nieprawidłowe dane wejściowe
NOT_FOUND zasób nie istnieje
CONFLICT operacja sprzeczna z bieżącym stanem
VERSION_CONFLICT niezgodność wersji, ktoś zmienił zasób w międzyczasie
INSUFFICIENT_STOCK za mało towaru na stanie
DUPLICATE_COMMAND powtórzone polecenie o tym samym identyfikatorze
UNAUTHORIZED brak lub nieprawidłowa tożsamość
FORBIDDEN brak uprawnienia albo brak ważnej licencji
INTERNAL_ERROR błąd po stronie serwera
STORAGE_QUOTA_EXCEEDED przekroczony limit miejsca na pliki

Limity

Limit Wartość
Rozmiar ciała żądania 1 MB
Wgrywane zdjęcie towaru 5 MB
Liczba żądań nieuwierzytelnionych 300 na minutę z jednego adresu IP
Logowanie, odświeżenie sesji, rejestracja firmy 10 na minutę
Logowanie operatora terminala 10 na minutę
Aktywacja licencji 5 na minutę

Ruch uwierzytelniony ważnym tokenem panelu nie podlega limitowi ogólnemu - normalna praca w panelu legalnie generuje setki żądań na minutę. Podpis tokenu jest sprawdzany kryptograficznie, więc podrobiony nagłówek nie daje obejścia.

Limit dla terminali jest liczony per urządzenie, a nie per adres IP - wiele terminali w jednym magazynie dzieli zwykle jeden adres publiczny.

Licencja a dostęp do API

Instalacja bez ważnej licencji odrzuca praktycznie każde żądanie. Wyjątkiem są trasy sprawdzenia stanu serwera, metryki oraz sprawdzenie i aktywacja licencji. Patrz Licencja.

Bezpieczeństwo połączenia

Kolektory łączą się z serwerem przez połączenie szyfrowane, z certyfikatem przypinanym po odcisku przekazanym w kodzie QR parowania. Żądania wychodzące z serwera - webhooki i zapytania do konektorów - są zabezpieczone przed przekierowaniem na adresy wewnętrzne.

Zdjęcia towarów nigdy nie są pobierane bezpośrednio z magazynu plików. Każde żądanie przechodzi przez serwer aplikacji, który autoryzuje dostęp podpisem i terminem ważności zaszytym w adresie.

Powiązane strony