Baza wiedzy o serwisach administracji publicznej

Jak zintegrować system z CRU JSFP przez API?

Autor: FabianOstatnia aktualizacja: ~3 min czytania

Jednostki, które zawierają dużo umów, nie muszą wpisywać ich ręcznie. Ministerstwo Finansów udostępnia API, przez które system finansowo-księgowy, system zamówień albo elektroniczny obieg dokumentów może publikować i aktualizować umowy w CRU JSFP. Opis dotyczy dokumentacji integracyjnej w wersji 1.3.6 (kontrakt OpenAPI 1.3.4).

Co umożliwia API CRU?

  • publikację nowych umów i aktualizację opublikowanych,
  • wycofanie umów z publikacji,
  • pobranie szczegółów umowy po jej identyfikatorze,
  • przeglądanie streszczeń umów z filtrowaniem i stronicowaniem,
  • masowe sprawdzenie, czy umowy o podanych identyfikatorach istnieją w systemie.

Jakie są adresy API?

Adres bazowy wszystkich endpointów:

  • środowisko testowe – https://jsfp-cru-test.mf.gov.pl/v1/api/publish
  • środowisko produkcyjne – https://jsfp.rejestrumow.gov.pl/v1/api/publish

Dokumentacja: testowa i produkcyjna. API działa wyłącznie przez HTTPS z publicznie zaufanym certyfikatem.

Jak uzyskać klucz API?

Każde wywołanie wymaga nagłówka X-API-KEY. Klucz generuje użytkownik z rolą publikującego:

  1. Zaloguj się do CRU JSFP i wybierz kontekst jednostki.
  2. Wejdź w „Moje dane”, a potem „Klucz API”.
  3. W zakładce „Zarządzanie kluczem API” kliknij „Generuj klucz” i potwierdź.
  4. Skopiuj klucz – zostanie wyświetlony tylko raz. Po zamknięciu okna nie da się go odczytać ponownie.

Klucz jest powiązany z kontekstem jednostki, w którym go wygenerowano.

Jak długo ważny jest klucz API?

Sześć miesięcy od wygenerowania. Potem zostaje zablokowany. Zostaje też zablokowany, gdy użytkownik straci rolę publikującego. Klucz można zablokować samodzielnie przyciskiem „Zablokuj klucz”. Historię kluczy widzi sam użytkownik oraz administrator jednostki.

Dobra praktyka. Wpisz datę wygaśnięcia klucza do kalendarza zespołu IT z wyprzedzeniem kilku tygodni. Przechowuj klucz w menedżerze sekretów, a nie w kodzie źródłowym. Klucz nie powinien należeć do pracownika, który wkrótce odchodzi.

Jakie endpointy udostępnia API?

  • POST /agreements – publikacja i aktualizacja umów w paczkach,
  • POST /withdraw – wycofanie umów z publikacji,
  • GET /{agreementId} – szczegóły umowy,
  • GET /summary – lista streszczeń umów z filtrami: numerUmowy, przedmiotUmowy, agreementIds, externalSystemIds, dataZawarciaUmowyOd, dataZawarciaUmowyDo (łączone warunkiem „i”), z parametrami offset, limit i sortDirection. Umowy robocze nie są zwracane,
  • GET /status – sprawdzenie, czy umowy o podanych agreementIds lub externalSystemIds istnieją (ALREADY_EXISTS albo NOT_EXISTS).

Przykład wywołania:

curl -X GET \
  "https://jsfp-cru-test.mf.gov.pl/v1/api/publish/summary?offset=0&limit=20" \
  -H "X-API-KEY: TWOJ_KLUCZ_API"

Jakie są limity wywołań?

  • POST /agreements – 3 żądania na sekundę na jeden klucz API, bez kolejkowania (nadmiarowe żądanie może zostać od razu odrzucone, zwykle kodem 429),
  • maksymalnie 500 umów w jednym żądaniu, zalecane paczki po 100–200,
  • przekroczenie 500 elementów kończy się błędem 400.

Ministerstwo zaleca wysyłać paczki sekwencyjnie, z odstępem około sekundy, bez równoległych wywołań na ten sam klucz.

Jakie statusy umów obsługuje API?

Publikować, aktualizować i wycofywać przez API można tylko umowy opublikowane, dla których nie rozpoczęto zmian w aplikacji. Pobierać szczegóły i listy można dla umów w statusach: przekazana do publikacji, usunięta przed publikacją, weryfikowana, opublikowana i wycofana z publikacji.

Dobre praktyki integracji

  • przechowuj agreementId jako główny identyfikator umowy w swoim systemie,
  • przekazuj własny identyfikator w polu externalSystemId – ułatwi to wyszukiwanie i sprawdzanie statusów,
  • obsługuj wynik każdej umowy osobno na podstawie map success i errors,
  • przed wdrożeniem przetestuj integrację w środowisku testowym – zobacz Jak uzyskać dostęp do środowiska testowego CRU JSFP?.

Szczegóły pól i walidacji opisujemy w artykule Publikacja umów przez API CRU – pola, strony umowy i walidacje.

Stan na 11 października 2026 r. Artykuł ma charakter informacyjny i nie stanowi porady prawnej.

Źródło: opracowano na podstawie materiałów Ministerstwa Finansów o Centralnym Rejestrze Umów JSFP (gov.pl/web/finanse, w tym najczęściej zadawanych pytań, podręcznika użytkownika i dokumentacji API) udostępnianych na licencji CC BY-SA 4.0. Treść została opracowana od nowa własnymi słowami i uzupełniona; artykuł udostępniamy na tej samej licencji.