IRZplus REST API dla dostawcy środków identyfikacji (DSI) (20260626)

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).

Udostępnianie zatwierdzonemu przez Agencję dostawcy środków identyfikacji numerów identyfikacyjnych przydzielonych producentowi w aplikacji IRZplus, którymi posiadacz oznakuje swoje zwierzęta po zakupie środków identyfikacji. Numery udostępniane są na podstawie dokumentu zamówienia wskazanego producenta. Usługa służy integracji systemów dostawców środków identyfikacji z systemem IRZplus.