KSeF API 2.0 – dokumentacja i integracja
KSeF API 2.0 to aktualna wersja interfejsu programistycznego udostępnianego przez Ministerstwo Finansów do komunikacji z Krajowym Systemem e-Faktur. Dla zespołów, które już mają za sobą integrację z wcześniejszą wersją systemu, oznacza to konieczność weryfikacji, co się zmieniło. Dla tych, którzy dopiero zaczynają — dobry moment, żeby od razu budować integrację zgodną z aktualną specyfikacją, zamiast bazować na nieaktualnych źródłach.
Dlaczego numeracja wersji API ma znaczenie
KSeF jest systemem rozwijanym — Ministerstwo Finansów publikuje kolejne wersje specyfikacji, które mogą wprowadzać zmiany w strukturze żądań, sposobie uwierzytelniania czy dostępnych funkcjonalnościach. Dla integratora oznacza to jedno: dokumentacja, z której korzystasz, musi być aktualna względem wersji API, z którą faktycznie się integrujesz. Kod napisany pod starszą wersję specyfikacji może przestać działać poprawnie po aktualizacji systemu, jeśli nie zostanie zweryfikowany względem nowej dokumentacji.
Gdzie szukać aktualnej dokumentacji
Podstawowym, referencyjnym źródłem informacji o API KSeF 2.0 jest oficjalna dokumentacja publikowana przez Ministerstwo Finansów — to tam znajdziesz aktualne nazwy endpointów, wymagane parametry, kody błędów i szczegóły dotyczące uwierzytelniania. Jeśli korzystasz z warstwy pośredniczącej (jak API KSeFService), dodatkowym źródłem jest dokumentacja dostawcy, która powinna być na bieżąco aktualizowana wraz ze zmianami w specyfikacji Ministerstwa Finansów — w naszym przypadku dokumentację znajdziesz pod adresem /docs/api.php, wraz z przykładami użycia pod /docs/api_use.php.
Co warto wiedzieć przed rozpoczęciem integracji
- Środowiska testowe. KSeF udostępnia oddzielne środowiska do testów, niezależne od produkcji — integrację zawsze zaczynaj od nich, niezależnie od wersji API.
- Schemat FA(3). Struktura faktury ustrukturyzowanej to element, który zmienia się rzadziej niż sama warstwa API, ale wciąż wymaga weryfikacji względem aktualnego XSD przy każdej większej aktualizacji systemu.
- Uwierzytelnianie. Metody potwierdzania tożsamości w KSeF mogą się różnić w zależności od kontekstu i wersji API — warto to zweryfikować osobno, opisujemy to szerzej w artykule o autoryzacji, tokenach i certyfikatach.
- Zmiany nie zawsze są wsteczne kompatybilne. Integracja zbudowana sztywno pod jedną wersję specyfikacji, bez marginesu na zmiany, wymaga częstszych interwencji przy każdej aktualizacji systemu.
Jak zaprojektować integrację odporną na zmiany
Niezależnie od tego, czy integrujesz się bezpośrednio z API Ministerstwa Finansów, czy przez warstwę pośredniczącą, kilka zasad architektonicznych zmniejsza ryzyko, że kolejna aktualizacja KSeF wymusi przebudowę integracji od podstaw:
- Oddziel logikę biznesową od komunikacji z API. Jeśli mapowanie danych faktury na strukturę FA(3) jest odizolowane od reszty Twojego systemu, zmiana w API wymaga modyfikacji jednego miejsca w kodzie, a nie całej aplikacji.
- Nie zakładaj sztywnej struktury odpowiedzi tam, gdzie to możliwe. Parsowanie odpowiedzi API w sposób odporny na dodanie nowych, opcjonalnych pól ogranicza ryzyko, że drobna zmiana w API złamie Twoją integrację.
- Monitoruj komunikaty o zmianach. Ministerstwo Finansów publikuje changelogi API — warto mieć proces, w którym ktoś w zespole je regularnie przegląda, zamiast dowiadywać się o zmianie po fakcie, z błędów na produkcji.
- Rozważ warstwę pośredniczącą. Jeśli utrzymywanie zgodności z kolejnymi wersjami API KSeF nie jest częścią Twojego głównego biznesu, przeniesienie tej odpowiedzialności na wyspecjalizowanego dostawcę bywa efektywniejsze niż samodzielne śledzenie zmian.
Podsumowanie
KSeF API 2.0 to bieżąca, rozwijana wersja interfejsu integracyjnego — a nie stały, zamknięty standard. Dobra integracja uwzględnia to od samego początku: opiera się na aktualnej dokumentacji, zachowuje elastyczność wobec przyszłych zmian i korzysta ze środowisk testowych, zanim cokolwiek trafi na produkcję.
Chcesz zintegrować się z KSeF bez samodzielnego śledzenia każdej zmiany w specyfikacji? Sprawdź dokumentację API KSeFService lub skontaktuj się z nami.
