Integracje

API EZD RP — Piaskownica, Swagger, klucze, integracje

API REST EZD RP umożliwia integrację systemów zewnętrznych: dodawanie dokumentów do RPW, zakładanie spraw, pobieranie załączników, synchronizację JRWA. Jak uzyskać dostęp do Piaskownicy, jak korzystać ze Swaggera, jak zarządzać kluczami i upload-tokenami.

Stan na 2026-05-13 • Bazujemy na oficjalnych źródłach NASK / gov.pl

API EZD RP to interfejs REST udostępniający funkcje systemu systemom zewnętrznym — od dodawania dokumentów do RPW, przez zakładanie spraw, po zarządzanie metadanymi i załącznikami. Dokumentacja jest publicznie utrzymywana w formacie Swagger / OpenAPI.

Co API EZD RP pozwala zrobić

  • Dodawanie dokumentu do RPW — pełny scenariusz z metadanymi, załącznikami, dekretacją
  • Zakładanie sprawy z numerem JRWA i pełną metryką
  • Pobieranie listy spraw / dokumentów dla użytkownika lub komórki
  • Pobieranie załączników (poprzez tokeny dostępowe)
  • Aktualizacja statusu sprawy z systemu dziedzinowego (np. system FK)
  • Synchronizacja JRWA między EZD RP a innym systemem klasy EZD
  • Subskrypcja webhook'ów o zdarzeniach (nowy dokument, zmiana statusu)

Piaskownica API

Gov.pl udostępnia środowisko Piaskownicy do testowania integracji bez wpływu na dane produkcyjne. To rekomendowany pierwszy krok każdej integracji — pozwala sprawdzić, czy oprogramowanie systemu zewnętrznego komunikuje się poprawnie z EZD RP, zanim zostanie podłączone do produkcji.

  • Dostęp przez wniosek na gov.pl — typowo 5-10 dni roboczych
  • Środowisko z przykładowymi danymi (organizacja testowa, użytkownicy, JRWA)
  • Identyczne API jak na produkcji — różnica tylko w endpoincie i kluczach
  • Bezpieczne testy bez ryzyka uszkodzenia danych jednostki

Uwierzytelnianie i klucze

API EZD RP używa kluczy API powiązanych z kontekstem użytkownika lub aplikacji. Każda operacja zapisu (dodanie dokumentu, zakładanie sprawy) jest realizowana w kontekście użytkownika — to ważne dla audytu i odpowiedzialności.

  • Klucz API aplikacji — identyfikuje system zewnętrzny (np. system FK)
  • Kontekst użytkownika — w którego imieniu wykonywana jest operacja
  • Upload-token — krótkoterminowy token dostępu do plików (zwykle ~minuty)
  • Scopes / uprawnienia — ograniczenie zakresu klucza (np. tylko odczyt, tylko dla wybranych spraw)
Klucz API ≠ konto użytkownika
Częsty błąd integratora: traktowanie klucza API jak loginu. Klucz API to identyfikator aplikacji — musi działać w kontekście konkretnego użytkownika, którego można zaudytować w logach EZD RP.

Najczęstsze scenariusze integracji

Scenariusz 1: dodawanie faktury z systemu FK do RPW

  1. System FK pobiera fakturę (np. z KSeF, e-Doręczeń lub własnego mechanizmu)
  2. Wywołuje endpoint `POST /upload-token` aby dostać token na upload pliku
  3. Wywołuje `POST /files` z plikiem PDF (z użyciem upload-tokena)
  4. Wywołuje `POST /rpw` z metadanymi + ID pliku — dokument trafia do RPW EZD RP
  5. Otrzymuje `id_dokumentu` — może go zapisać po stronie FK do referencji

Scenariusz 2: zakładanie sprawy z systemu dziedzinowego

  1. System dziedzinowy (np. system rekrutacji studentów) wykrywa nowy wniosek
  2. Wywołuje `POST /sprawy` z numerem JRWA, metadanymi wnioskodawcy, opisem
  3. Otrzymuje numer sprawy — przekazuje go z powrotem do wnioskodawcy
  4. Korespondencja w tej sprawie obsługiwana w EZD RP, statusy synchronizowane przez webhook

Najczęstsze błędy integracyjne

Co najczęściej idzie nie tak
  • Klucz API bez kontekstu użytkownika → błąd 403 / brak audytu
  • Próba uploadu pliku bez wcześniejszego upload-tokena → błąd 401
  • Niezgodność JRWA między systemami → odrzucenie sprawy
  • Brak obsługi rate-limit (zbyt szybkie wywołania) → tymczasowy 429
  • Testy pisane od razu na produkcji zamiast w Piaskownicy → ryzyko uszkodzenia danych jednostki
  • Brak retry / idempotencji — przy chwilowej awarii sieci dokument trafia 2× do RPW

Dokumentacja Swagger / OpenAPI

Pełna referencja API jest publicznie utrzymywana w formacie Swagger UI — dostępna z poziomu gov.pl. Dla wersji v2 dokumentacja zawiera: pełną listę endpointów, modele danych, przykładowe request/response, kody błędów. To pierwsze źródło prawdy dla każdego integratora.

Źródła oficjalne
Skonsultuj integrację z systemem dziedzinowym

Pomożemy zaprojektować integrację: REST, kolejność wywołań, obsługa błędów, testy w Piaskownicy, deploy na produkcję.

Umów konsultację

Najczęstsze pytania

Czy dostęp do API jest płatny?

Nie — API EZD RP jest darmowe. Płatne są ewentualne prace integracyjne po stronie systemu dziedzinowego (po stronie tego producenta).

Ile trwa uzyskanie dostępu do Piaskownicy?

Typowo 5-10 dni roboczych od złożenia wniosku przez gov.pl. Wniosek można składać równolegle z innymi pracami przygotowawczymi.

Czy mogę testować na produkcji bez Piaskownicy?

Można, ale nie należy. Każdy błąd w integracji wprost wpływa na dane jednostki (RPW, sprawy). Piaskownica eliminuje to ryzyko.

Czy API obsługuje webhook'i / push?

Tak — można subskrybować zdarzenia (nowy dokument, zmiana statusu sprawy, podpisanie). Webhook'i wysyłane są z EZD RP do endpointu systemu zewnętrznego.

Czy upload-token ma limit czasu?

Tak — upload-token to krótkoterminowy token, typowo kilka minut. Po wygaśnięciu trzeba pobrać nowy. Konkretne wartości w aktualnym Swaggerze.

Czytaj dalej

KSeF
Integracja EZD RP z KSeF — konfiguracja, certyfikat, odbiór faktur
EZD RP od stycznia 2026 r. ma natywną integrację z Krajowym Systemem e-Faktur — automatycznie pobiera faktury i rejestruje je w RPW. Jak wygenerować certyfikat KSeF, jak skonfigurować konto techniczne, co zrobić, gdy faktury nie są pobierane.
e-Doręczenia
e-Doręczenia w EZD RP — PURDE, PUH, konfiguracja, troubleshooting
e-Doręczenia w EZD RP: wysyłka w trybie PURDE i PUH, różnice między wariantami systemu A i B, konfiguracja krok po kroku, diagnostyka typowych problemów (brak zakładki, błędy uprawnień, problemy z odbiorcami bez ADE).
Wdrożenie
Wdrożenie EZD RP krok po kroku — przewodnik dla urzędu
Pełny proces wdrożenia EZD RP — od decyzji i audytu, przez konfigurację i integracje, po szkolenia i start produkcyjny. Etapy, role w zespole, ryzyka, harmonogram.