JSON API dla aplikacji mobilnych i zewnętrznych

Integracja nie powinna zależeć od znaczników strony WWW

Platforma firmowa przestaje być odizolowaną witryną, gdy podłącza się do niej aplikację mobilną, stanowisko kierowcy, portal wewnętrzny, terminal lub usługę partnera. Próba wykorzystania do tego stron HTML szybko tworzy kruchą zależność od projektu graficznego. Bezpośredni dostęp do bazy danych jest jeszcze bardziej niebezpieczny: klient zewnętrzny zaczyna powielać reguły biznesowe, ignorować prawa i zależeć od wewnętrznego schematu przechowywania.

Sapphire I.C.D.S. udostępnia do tych zadań oddzielne środowisko integracyjne: HTTPS JSON API. Przyjmuje ono ustrukturyzowane żądania i zwraca odpowiedzi maszynowe, nie renderuje stron użytkownika i nie wymaga od klienta znajomości bazy serwerowej. Publiczny Roadmap odnotowuje to środowisko jako wydaną podstawę dla klientów natywnych i integracji biznesowych.

JSON jest formatem wymiany, a nie całą architekturą

Sam JSON nie czyni integracji niezawodną. Znaczenie ma to, kto definiuje dostępną komendę, jak sprawdzany jest użytkownik i gdzie wykonuje się walidację biznesową. W Sapphire I.C.D.S. systemowe API odpowiada za uwierzytelnienie, natomiast moduły publikują komendy dziedzinowe przez osobny kontrakt. Klient przekazuje działanie i dane, ale to serwer wybiera odpowiedzialny moduł, sprawdza żądanie i tworzy wynik.

Dzięki temu interfejs WWW, aplikacja mobilna i system zewnętrzny mogą korzystać z tej samej logiki dziedzinowej. Na przykład operacja zapisu wyniku dostawy powinna jednakowo sprawdzać trasę, sklep, produkt i prawa wykonawcy niezależnie od ekranu, z którego wysłano żądanie. Klient odpowiada za wygodny interfejs, a moduł za poprawność procesu.

Sesja i tożsamość są weryfikowane przez serwer

API obsługuje podstawowy cykl życia sesji klienta: logowanie, pobieranie bieżącego potwierdzonego użytkownika, odnawianie dostępu i wylogowanie. Po udanym logowaniu klient otrzymuje krótkotrwały token dostępu oraz osobny token odświeżania. Odświeżenie zastępuje tę parę, dlatego aplikacja musi zapisać nowe wartości atomowo i nie może powtarzać udanej operacji ze starą wartością.

Kluczowa zasada mówi, że pola użytkownika, grupy lub obiektu w JSON nie dowodzą uprawnień. Serwer wyprowadza tożsamość ze sprawdzonej sesji i dopiero potem określa dostępny zakres danych. Moduł logistyczny nie może na przykład pokazać innej trasy tylko dlatego, że klient podał identyfikator innego kierowcy. Powiązanie z rolą biznesową jest rozstrzygane na serwerze.

Moduły publikują tylko jawne działania

Wydzielone API nie otwiera automatycznie wszystkich funkcji Sapphire I.C.D.S. Moduł musi implementować dostawcę API i wymienić obsługiwane komendy. Pozwala to wydawać integracje etapami: najpierw bezpieczny odczyt, następnie wąskie zmiany, a po weryfikacji bardziej złożone procesy robocze. Moduł bez kontraktu zewnętrznego nie staje się dostępny tylko dlatego, że go zainstalowano.

Komendy zmieniające stan muszą używać żądań przeznaczonych do modyfikacji, a odczyt może pozostać osobną operacją. Serwer zwraca zrozumiałe kody wyniku dla błędnego żądania, wygasłej sesji, odmowy dostępu, niewłaściwej metody lub czasowo niedostępnej zależności. Aplikacja kliencka otrzymuje zdefiniowaną ścieżkę obsługi zamiast strony błędu HTML.

• Klient mobilny wysyła tylko potrzebne dane i przechowuje tokeny w chronionej pamięci urządzenia.
• Środowisko API sprawdza sesję, metodę żądania i dopuszczalny rozmiar danych wejściowych.
• Moduł sprawdza reguły dziedzinowe, zakres użytkownika i dozwolone przejścia stanu.
• Baza danych pozostaje za warstwą serwerową i nie jest bezpośrednio udostępniana klientowi.

Odpowiednie scenariusze biznesowe

JSON API jest szczególnie użyteczne, gdy pracownik działa poza głównym back-office. W logistyce może to być lista przypisanych tras, dane punktu, zapis dostarczonej ilości, zwrotu lub stanu dokumentu. W księgowości może chodzić o pobranie słownika i wysłanie potwierdzonej operacji. W aplikacji zewnętrznej może to być odczyt dozwolonego stanu i uruchomienie konkretnej komendy bez symulowania działań przeglądarki.

Publiczny Roadmap wymienia logistykę, księgowość i procesy terenowe jako naturalne kierunki rozwoju. Nie oznacza to, że dla każdego scenariusza istnieje już uniwersalny endpoint. Gotowość zależy od zestawu komend API zainstalowanego modułu. Przed rozpoczęciem projektu integracyjnego strony powinny przygotować macierz operacji, danych, ról i wersji.

JSON API nie jest zewnętrznym MCP

Oba środowiska używają ustrukturyzowanych danych, lecz obsługują inne klasy klientów. JSON API jest przeznaczone dla aplikacji mobilnych i firmowych z wcześniej zaprojektowanym procesem użytkownika. Zewnętrzny MCP służy zgodnym klientom AI, które odkrywają narzędzia i wywołują je podczas sesji agentowej. Ich uprawnień i zasad publikacji nie należy traktować jako zamiennych.

API nie jest też zdalną konsolą SQL, generatorem dowolnych raportów ani obietnicą dostępu do każdej tabeli. Udostępnia komendy biznesowe, za które odpowiada moduł. Ten poziom abstrakcji jest odporniejszy na zmiany schematu przechowywania i bezpieczniejszy w wieloletnim utrzymaniu.

Co musi obsługiwać aplikacja kliencka

Klient natywny musi poprawnie obsługiwać wygaśnięcie tokenu dostępu, wymianę tokenu odświeżania, wylogowanie, utratę sieci i ponowne wysłanie. W operacjach zmieniających stan szczególnie ważne jest rozróżnienie potwierdzonej odmowy od niepewnego wyniku transportowego. Bez uzgodnionej idempotencji nie wolno automatycznie powtarzać działania, które mogło zostać wykonane na serwerze. Lokalna pamięć podręczna nie może być źródłem aktualnych praw.

Zespół techniczny określa również wersjonowanie kontraktów, dzienniki, limity żądań i strategię zgodności wstecznej. Platforma udostępnia wspólne środowisko modułowe, ale jakość konkretnego produktu mobilnego zależy od dyscypliny klienta i kompletności opublikowanego kontraktu biznesowego.

Droga wdrożenia

Pracę należy rozpocząć od inwentaryzacji scenariuszy użytkownika, a nie od listy tabel. Dla każdego kroku strony określają pola wejściowe, odpowiedź, rolę, zakres danych, dozwolone przejścia i zachowanie przy powtórzeniu. Następnie moduł publikuje minimalny zestaw komend, zespół mobilny buduje interfejs, a wspólne testy obejmują scenariusze poprawne i zabronione.

Dla właściciela firmy rezultatem jest możliwość tworzenia własnych aplikacji bez powielania logiki serwera. Dyrektor techniczny otrzymuje kontrolowaną granicę integracji ze wspólnym uwierzytelnianiem i modułowymi komendami. JSON API rozszerza Sapphire I.C.D.S. poza interfejs WWW, zachowując dane, prawa i reguły procesu w autorytatywnym środowisku serwerowym.