Integracja z API KSeF – jak to działa i jak wdrożyć ją w swojej firmie
Krajowy System e-Faktur (KSeF) udostępnia API, przez które firmy mogą automatycznie wysyłać i odbierać faktury ustrukturyzowane, bez logowania się ręcznie do portalu Ministerstwa Finansów. Dla firm wystawiających więcej niż kilka faktur miesięcznie integracja z API KSeF to nie luksus, tylko warunek utrzymania sensownego tempa pracy — ręczne wprowadzanie każdej faktury osobno w interfejsie webowym KSeF nie skaluje się nawet przy umiarkowanym wolumenie sprzedaży.
Czym właściwie jest API KSeF
API KSeF to interfejs programistyczny udostępniony przez Ministerstwo Finansów, pozwalający systemom informatycznym firm komunikować się bezpośrednio z Krajowym Systemem e-Faktur — bez udziału człowieka klikającego w przeglądarce. Przez API można m.in.:
- uwierzytelnić się w KSeF (certyfikatem kwalifikowanym, tokenem lub podpisem zaufanym),
- wysyłać faktury ustrukturyzowane w formacie XML zgodnym ze schematem FA(3),
- pobierać faktury wystawione przez kontrahentów na dany podmiot,
- pobierać Urzędowe Poświadczenie Odbioru (UPO) potwierdzające przyjęcie dokumentu przez system,
- sprawdzać status przetworzenia wcześniej wysłanych dokumentów.
Samo API jest darmowe i publicznie dostępne — problemem nie jest dostęp do niego, tylko zbudowanie i utrzymanie integracji, która poprawnie obsługuje wszystkie jego wymagania techniczne.
Co jest potrzebne do integracji z API KSeF
- Uwierzytelnienie — certyfikat kwalifikowany (autoryzacyjny), token KSeF lub podpis zaufany, w zależności od wybranej metody logowania do systemu.
- Poprawny format dokumentu — faktura musi być wygenerowana jako XML zgodny ze schematem logicznym FA(3), z zachowaniem właściwej kolejności elementów wymaganej przez XSD.
- Obsługa limitów zapytań — KSeF ogranicza liczbę żądań w jednostce czasu; integracja musi to uwzględniać, zwłaszcza przy wysyłce lub pobieraniu większej liczby dokumentów.
- Obsługa kontekstów autoryzacji — w zależności od scenariusza (własna firma, biuro rachunkowe działające w czyimś imieniu, delegacja uprawnień) API wymaga poprawnego określenia kontekstu, w którym działa dana sesja.
- Środowisko testowe — KSeF udostępnia oddzielne środowisko testowe (TEST), w którym można bezpiecznie zweryfikować integrację przed uruchomieniem na produkcji.
Dwie ścieżki wdrożenia integracji
1. Integracja własna, budowana od zera
Firma (lub jej dział IT) buduje integrację samodzielnie: obsługę uwierzytelniania, generowanie i walidację XML FA(3), komunikację z endpointami KSeF, obsługę błędów i limitów, przechowywanie certyfikatów. To podejście daje pełną kontrolę nad rozwiązaniem, ale wiąże się z realnym kosztem czasowym — API KSeF, mimo że dobrze udokumentowane, ma sporo niuansów (m.in. specyfika XSD, obsługa różnych typów faktur — zaliczkowych, korygujących, eksportowych — oraz zmieniająca się wraz z kolejnymi wersjami specyfikacja), które trzeba poznać metodą prób i błędów albo dogłębnej analizy dokumentacji.
2. Gotowe API pośredniczące (np. ksefservice.pl)
Zamiast integrować się bezpośrednio z surowym API Ministerstwa Finansów, firma korzysta z usługi pośredniczącej, która already obsługuje całą złożoność techniczną — generowanie poprawnego XML, zarządzanie certyfikatami, obsługę limitów i błędów — i udostępnia uproszczone, ustandaryzowane API (zwykle REST + JSON) do wysyłki i odbioru faktur. W praktyce oznacza to wysłanie zamówienia czy danych faktury w prostym formacie JSON, a resztę — konwersję do XML, walidację, komunikację z KSeF — przejmuje usługa pośrednicząca.
Jak wybrać między tymi ścieżkami
| Kryterium | Integracja własna | Gotowe API |
|---|---|---|
| Czas wdrożenia | Tygodnie–miesiące | 60 minut |
| Utrzymanie zgodności ze zmianami KSeF | Po stronie firmy | Po stronie dostawcy |
| Wymagana wiedza techniczna | Wysoka (XML, XSD, certyfikaty) | Podstawowa (REST/JSON) |
| Pełna kontrola nad kodem | Tak | Częściowa |
Typowe zastosowania integracji z API KSeF
- automatyczne wystawianie faktur z zamówień w sklepie internetowym lub na marketplace'ach,
- generowanie faktur bezpośrednio z systemu księgowego lub ERP,
- samofakturowanie i masowa wysyłka faktur w imieniu wielu kontrahentów,
- odbiór i archiwizacja faktur zakupowych do rozliczeń VAT i JPK,
- obsługa wielu podmiotów z jednego systemu — dla biur rachunkowych.
Podsumowanie
Integracja z API KSeF jest technicznie osiągalna do zbudowania samodzielnie, ale wymaga czasu, wiedzy o niuansach schematu FA(3) i bieżącego śledzenia zmian w specyfikacji. Gotowe API pośredniczące skraca ten proces do minut zamiast tygodni, przenosząc odpowiedzialność za zgodność techniczną na dostawcę usługi.
Chcesz sprawdzić, jak szybko możesz uruchomić integrację z KSeF? Skontaktuj się z nami lub zapoznaj się z dokumentacją API.
