IRZplus REST API — usługi wspólne (ALL) (20260626)

Dostęp do API wymaga autoryzacji o charakterze globalnym (obowiązuje wszystkie endpointy). Tożsamość i uprawnienia weryfikowane są na podstawie tokenu OpenID Connect (JWT) wydawanego przez system SSO ARiMR (Keycloak), realm ewniosekplus, klient aplikacja-irzplus. Token przekazywany jest w nagłówku Authorization: Bearer <token>.

Token można pobrać wywołując endpoint POST /realms/ewniosekplus/protocol/openid-connect/token (sekcja Autoryzacja; serwer SSO ARiMR) — np. grant password z client_id=aplikacja-irzplus. Otrzymany access_token należy wkleić w oknie Authorize w Swagger UI, aby był dołączany do kolejnych wywołań. Brak autoryzacji lub brak wymaganych uprawnień skutkuje odrzuceniem żądania (odpowiednio HTTP 401 i HTTP 403).

Dostęp do API wymaga autoryzacji. Autoryzacja ma charakter globalny i obowiązuje wszystkie endpointy udostępniane w ramach niniejszego API; podlegają jej systemy integrujące się z IRZplus. Token autoryzacyjny przekazywany jest w nagłówku HTTP Authorization: Bearer <token>. Mechanizm autoryzacji jest zdefiniowany technicznie w specyfikacji (securitySchemes) i nie jest opisywany indywidualnie dla poszczególnych usług; szczegóły procesu uzyskania tokenu opisuje dokumentacja zewnętrzna. Brak autoryzacji lub brak wymaganych uprawnień skutkuje odrzuceniem żądania (odpowiednio HTTP 401 i HTTP 403).

API stosuje standardowe kody odpowiedzi HTTP:

• 200 — operacja zakończona sukcesem,
• 400 — błąd walidacji danych wejściowych,
• 401 — brak autoryzacji (brak lub nieważny token JWT),
• 403 — brak uprawnień do wykonania operacji,
• 500 — wewnętrzny błąd serwera (oraz pozostałe błędy techniczne z grupy 5xx).

Błędy biznesowe (np. negatywny wynik walidacji danych zgłoszenia czy brak dostępu do danych wskazanego producenta) są zwracane z kodem HTTP 200, a opis przyczyny znajduje się w polu komunikat w treści odpowiedzi. Dla usług wyszukiwania brak wyników spełniających kryteria nie jest traktowany jako błąd — zwracana jest pusta lista z kodem HTTP 200.

• Daty — format ISO 8601 <RRRR-MM-DD> (np. 2026-05-15).
• Kodowanie — UTF-8.
• Słowniki — pola referencyjne odwołują się do słowników systemu IRZplus; wartość słownikowa jest reprezentowana jako obiekt KodOpisWartosciDto (kod + opis).

Pola lokalizacyjne (wojewodztwo, powiat, gmina, miejscowosc, ulica) w strukturach adresowych pochodzą z państwowego rejestru TERYT (Krajowy Rejestr Urzędowy Podziału Terytorialnego Kraju prowadzony przez Główny Urząd Statystyczny), a nie ze słowników IRZplus. Kategorie kodów:

• TERC — województwa (2 cyfry), powiaty (2 cyfry), gminy (kod 2 cyfry + rodzaj gminy 1 cyfra),
• SIMC — miejscowości (7 cyfr),
• ULIC — ulice (5 cyfr).

Wartości mają strukturę hierarchiczną (województwo → powiat → gmina → miejscowość → ulica) i są udostępniane przez usługę danych terytorialnych IRZplus. Pole rodzajGminy zawiera typ wpisu TERC (gmina miejska, wiejska, miejsko-wiejska, miasto i obszar wiejski w gminie miejsko-wiejskiej).

Usługi udostępniające dane słownikowe systemu IRZplus na potrzeby integracji system-system (S2S). Zwracają komplet słowników wraz z ich wartościami (kod + opis), do których odwołują się pola referencyjne pozostałych usług API. Audytorium: integratorzy zewnętrzni, pracownicy posiadacza oraz Związek Hodowców Koni. Integrator powinien pobrać i buforować słowniki, a następnie rozwijać kody słownikowe zwracane i przyjmowane przez pozostałe usługi.

Pozyskanie tokenu dostępu (OpenID Connect) z systemu SSO ARiMR (Keycloak), realm ewniosekplus. Token służy do autoryzacji wywołań pozostałych usług API.