Aktualizacja: 6 września 2026 r. Ten artykuł opisuje historyczny etap zmian dokumentacji API 1.3.2. Nie należy go traktować jako samodzielnego potwierdzenia zgodności każdego środowiska ani każdej funkcji produktu z najnowszym dokumentem technicznym MF.
Według weryfikacji wykonanej 6 września 2026 r. dokument OpenAPI środowiska produkcyjnego wskazywał wersję 1.3.2, środowisko testowe wskazywało 1.3.3, a MF opublikowało także dokumentację integracyjną oznaczoną 1.3.5. Numery te dotyczą różnych artefaktów i środowisk, dlatego przed integracją trzeba sprawdzić bieżący dokument właściwego endpointu.
Co zmieniło się od wersji 1.3.0?
Wersja 1.3.0 była istotnym etapem porządkowania integracji z CRU JSFP. Zmiany dotyczyły przede wszystkim ujednolicenia identyfikacji umów, rozszerzenia informacji zwracanych w odpowiedziach API, dodania opcjonalnego identyfikatora umowy nadawanego w systemie zewnętrznym oraz poprawy walidacji danych przesyłanych przez API.
Najważniejsze różnice względem 1.3.0 dotyczą obsługi wycofania informacji o umowie z publikacji, doprecyzowania zasad przekazywania danych osoby fizycznej spoza Polski oraz uzupełnienia struktury odpowiedzi endpointu /withdraw w zakresie obsługi błędów.
Nowy zakres API: wycofanie z publikacji informacji o umowie
Najważniejszą zmianą funkcjonalną po wersji 1.3.0 jest dodanie endpointu /withdraw, który umożliwia wycofanie z publikacji informacji o umowach.
To ważne rozróżnienie: nie chodzi o zwykłe „usunięcie umowy” z lokalnej ewidencji ani o techniczne skasowanie rekordu w systemie jednostki. Chodzi o obsługę procesu wycofania informacji opublikowanej w CRU JSFP, zgodnie z zakresem przewidzianym w dokumentacji API.
Z perspektywy jednostki oznacza to konieczność zapewnienia w systemie mechanizmu, który pozwala kontrolować nie tylko publikację i aktualizację danych, ale również sytuacje następcze — w tym przypadki, w których informacja o umowie nie powinna dalej pozostawać opublikowana w dotychczasowym zakresie.
System Ewidencja Umów JSFP obsługuje proces wycofania informacji z publikacji. Zakres i rezultat każdej operacji należy jednak potwierdzać odpowiedzią właściwego środowiska API; wycofanie nie jest tym samym co usunięcie lokalnego rekordu ani automatyczne usunięcie historii.
Doprecyzowanie danych osoby fizycznej spoza Polski
Aktualizacja dokumentacji objęła również doprecyzowanie zasad przekazywania danych osoby fizycznej spoza Polski.
To istotny obszar, ponieważ w danych kontrahentów i stron umów mogą występować przypadki, które nie mieszczą się w standardowym modelu identyfikacji właściwym dla podmiotów krajowych. W praktyce system obsługujący integrację z CRU JSFP musi rozróżniać typy stron umowy i odpowiednio walidować dane przed ich przekazaniem.
Dokumentacja 1.3.2 doprecyzowała strukturę danych takich osób. Samo deklarowanie zgodności z numerem dokumentu nie wystarcza jednak do potwierdzenia poprawności konkretnego rekordu: przed wysyłką trzeba zweryfikować typ strony, wymagany kod kraju i dane właściwe dla danego kontrahenta.
Precyzyjniejsza obsługa błędów endpointu /withdraw
Kolejna zmiana dotyczy struktury odpowiedzi endpointu /withdraw. W odpowiedzi dotyczącej błędów dodano pole agreementId w elementach tablicy errors.
To techniczna zmiana, ale ma praktyczne znaczenie. Jeżeli operacja wycofania z publikacji obejmuje więcej niż jedną umowę albo jeżeli API zwraca błąd dotyczący konkretnej pozycji, system powinien umożliwiać jednoznaczne ustalenie, której umowy dotyczy problem.
Pole agreementId może ułatwiać diagnostykę po stronie integratora. Jest to opis kontraktu API. Nie oznacza automatycznie, że każdy interfejs użytkownika prezentuje diagnostykę zbiorczą dla poszczególnych elementów operacji /withdraw.
Co to oznacza dla użytkowników systemu?
Dla użytkowników systemu Ewidencja Umów JSFP istotne są przede wszystkim obsługiwane procesy: publikacja, aktualizacja, pobieranie danych opublikowanej umowy, status operacji oraz wycofanie informacji z publikacji.
Artykuł nie potwierdza obsługi wyszukiwania streszczeń przez endpoint /summary ani pełnej diagnostyki błędów zbiorczego /withdraw w interfejsie produktu. Funkcje te należy oceniać według aktualnej dokumentacji produktu i wyniku testu integracyjnego.
Przed uruchomieniem integracji należy porównać wersję i schemat OpenAPI właściwego środowiska MF z wersją obsługiwaną przez wdrożenie systemu.
Podsumowanie
Wersja 1.3.2 rozszerza zakres o obsługę wycofania z publikacji informacji o umowach, doprecyzowanie danych osoby fizycznej spoza Polski oraz precyzyjniejszą obsługę błędów endpointu /withdraw.
Wdrożenie systemu obsługuje podstawowe procesy integracyjne związane z publikacją, aktualizacją i wycofaniem. Pełną zgodność należy potwierdzać osobno dla konkretnego środowiska i bieżącego schematu OpenAPI MF.
Źródła
- Ministerstwo Finansów — Dodatkowa opcja w API systemu CRU JSFP, komunikat z 24 czerwca 2026 r.
- Ministerstwo Finansów — Niezbędna modyfikacja dodatkowej opcji API do systemu CRU JSFP, komunikat z 26 czerwca 2026 r.
- Ministerstwo Finansów — dokumentacja integracyjna API CRU JSFP
- Dokument OpenAPI środowiska testowego CRU JSFP — wersję należy sprawdzić bezpośrednio przed integracją.