API KSeF - Jak Sparados pobiera e-faktury i łączy je z transakcjami klientów?
Updated: Feb 10
Wejście w życie wersji KSeF 2.0 to duże wydarzenie dla całego rynku usług finansowo-księgowych. Oficjalna dokumentacja API KSeF 2.0 została opublikowana 30 czerwca 2025 r. Wersja ta wprowadza nową strukturę logiczną faktury - FA(3) - która od 1 lutego 2026 r. stanie się obowiązująca i zastąpi obecnie obowiązującą strukturę logiczną FA(2).
Dla integratorów i dostawców oprogramowania oznacza to konieczność dostosowania swoich systemów - a środowisko testowe (integracyjne) zostało uruchomione 30 września 2025 r., natomiast środowisko przedprodukcyjne 15 października 2025 r.
Środowiska te pozwalają na przetestowanie wszystkich operacji w systemie KSeF na testowych danych fakturowych, które nie są prawnie wiążące. Środowisko przedprodukcyjne ponadto pozwala na przetestowanie uwierzytelnienia firm i pracowników używając prawdziwych danych i certyfikatów, które będą używane w środowisku produkcyjnym.
Dzięki temu Sparados otrzymał szansę, by zweryfikować mechanizmy komunikacji z KSeF, przetestować pobieranie i obsługę faktur oraz przygotować produkcyjną integrację - zanim system stanie się obowiązkowy dla wszystkich firm w Polsce.
Dlaczego Sparados postawił na integrację z KSeF?
Dla Sparados, który działa jako fintech (np. oferuje karty i obsługuje transakcje klientów), integracja z KSeF przynosi realne korzyści:
Automatyczne pobieranie faktur zakupowych przypisanych do transakcji kartowych, co stanowi znaczne ułatwienie dla księgowości firm, korzystających z systemu Sparados.
Automatyczne łączenie faktur z odpowiednimi transakcjami w historii zakupów - zapewnia to spójność danych, porządek i przejrzystość.
Usprawnienie pracy działów finansowych i księgowości - faktury trafiają do systemu automatycznie, co obniża potrzebę manualnego łączenia dokumentów z wyciągami.
Transparentność dla użytkowników: w aplikacji (mobilnej i webowej) widać status „KSeF Auto Matched”, dane kontrahenta, datę, numer KSeF - co daje pewność, że dokument odpowiada faktycznemu wydatkowi.
Taka integracja stawia Sparados w roli nowoczesnego integratora e-faktur, zwiększając automatyzację i łatwość zarządzania kosztami - i ustawia wysoki standard w automatyzacji procesów rozliczania kosztów.
Aspekty techniczne integracji KSeF 2.0 w Sparados
🔧 Specyfikacja API KSeF i środowisko testowe
API KSeF 2.0 to interfejs w stylu REST (z opcjami SOAP do wystawiania i pobierania faktur w formacie XML), z pełną specyfikacją w formacie OpenAPI 3.0.
Dokumentacja zawiera szczegółowe opisy endpointów, schematów danych, parametrów, przykładowe wywołania i odpowiedzi w językach takich jak C# i Java.
Środowisko integracyjne (testowe) jest dostępne od 30 września 2025 r., a środowisko przedprodukcyjne od 15 października 2025 r. - co umożliwia integratorom przygotowanie do produkcyjnego startu.
Dzięki temu Sparados mógł rozpocząć prace deweloperskie - generować zapytania, parsować odpowiedzi, testować przepływy, walidację oraz uwierzytelnianie logowania - zanim KSeF 2.0 stanie się obowiązkowy.
Uwierzytelnianie i uprawnienia
Aby móc przeglądać i pobierać faktury klientów biznesowych, Sparados musi posiadać:
Certyfikat KSeF - czyli cyfrowe poświadczenie tożsamości podmiotu, które uprawnia do komunikacji z API. Zgodnie z dokumentacją, wniosek o certyfikat można złożyć tylko dla danych tożsamościowych zgodnych z danymi, które mają być zawarte w certyfikacie, w tym przypadku na NIP Sparados.
Odpowiednie uprawnienia dostępu (czytania faktur) - czyli by autoryzowany podmiot (Sparados) mógł uzyskać dostęp do faktur zakupowych wystawionych na firmy-klientów. W kontekście KSeF 2.0 uprawnienia są nadawane przez podmiot, którego dane są w fakturze dla podmiotu upoważnionego w kontekście NIP lub PESEL.
Uprawnienia nadane przez firmę-klienta na NIP Sparados upoważnia Sparados - przy użyciu certyfikatu wydanego na nasz NIP - do wykonywania operacji określonych w danym uprawnieniu w imieniu klienta.
Dopiero po spełnieniu tych warunków API KSeF pozwala na rzeczywiste pobieranie faktur - także w imieniu klientów, jeśli klient nadał takowe uprawnienia.
Pobieranie faktur: metody i typowe scenariusze
Integracja Sparados z KSeF korzysta z głównych mechanizmów udostępnionych przez API:
Pobranie pojedynczej faktury po numerze (KSeF Number) - endpoint GET /invoices/ksef/{ksefNumber}. Po uwierzytelnieniu i z tokenem dostępu można bezpośrednio pobrać konkretną fakturę w formacie XML.
Pobranie listy metadanych faktur spełniających określone kryteria - endpoint POST /invoices/query/metadata. Zapytanie to umożliwia podanie filtrów, według których system ma zwracać faktury - np. zakres dat, typ faktury lub NIP kontrahenta. W odpowiedzi dostajemy metadane faktur w formacie JSON zawierające najważniejsze dane fakturowe.
Eksport faktur (asynchroniczniy) - gdy zapytanie dotyczy większej liczby faktur i potrzebujemy faktur w pełnym formacie XML, można użyć endpointu POST /invoices/exports, podając filtry i parametry szyfrowania. System generuje paczkę z fakturami zaszyfrowaną zgodnie z wymogami w tle, która jest później dostępna razem ze statusem eksportu w operacji GET /invoices/exports/{referenceNumber}.
W praktyce Sparados implementuje logikę: regularnie (np. co godzinę lub według harmonogramu) wysyła zapytanie o metadane faktur dla firm-klientów, pobiera nowe faktury, i następnie automatycznie próbuje je dopasować do transakcji kartowych - jeśli zgodność danych (np. kontrahent, NIP, kwota, data) jest wystarczająca.
Jak Sparados wykorzystuje integrację KSeF w praktyce?
Przyjęty przez Sparados workflow może wyglądać następująco:
Klient biznesowy - firma współpracująca ze Sparados - nadaje uprawnienia do odczytu faktur dla podmiotu-Sparados (poprzez moduł uprawnień w KSeF).
Sparados składa wniosek o swój własny certyfikat w systemie KSeF - co pozwala na uwierzytelnioną komunikację z API - robi to tylko raz, gdyż uprawniony certyfikat może działać w kontekście różnych NIPów klientów.
Klient włącza integrację w panelu korporacyjnym w zakładce KSeF z możliwością testu połączenia serwisu Sparados do systemu KSeF - dzięki temu system Sparados może wykonywać proces tylko dla zintegrowanych klientów.
W ustalonych interwałach (np. co godzinę) - subskrybuje lub wykonuje zapytania o metadane faktur dla wszystkich firm-klientów, których transakcje obsługuje.
Po otrzymaniu metadanych - wybiera nowe faktury, pobiera je i zaimportowuje do swojego systemu.
System Sparados automatycznie próbuje dopasować pobraną fakturę do konkretnej transakcji kartowej - jeśli dane się zgadzają, faktura zostaje oznaczona np. statusem „KSeF Auto Matched”. W interfejsie aplikacji (mobilnej lub webowej) użytkownik widzi: nazwę kontrahenta, datę faktury, numer KSeF oraz status.
W ten sposób dokumentacja kosztów i zakupów staje się automatyczna, spójna i uporządkowana - dział księgowo-finansowy nie musi ręcznie pobierać faktur, nadzorować czy pasują do transakcji, ani segregować dokumentów.
Dlaczego model Sparados może być wzorem dla fintechów i firm korzystających z kart?
Integracja z KSeF 2.0 daje Sparados przewagę w:
Automatyzacji - redukcja pracy manualnej, błędów i opóźnień w rozliczeniach.
Transparentności i zgodności - faktury pochodzą z oficjalnego systemu, mają numery KSeF, co zwiększa pewność kontroli podatkowej.
Wygodzie dla klienta - klient otrzymuje zestaw transakcji + faktur bez potrzeby samodzielnego pobierania dokumentów z systemu KSeF lub od dostawców.
Skalowalności - rozwiązanie łatwo rozszerzyć na kolejne firmy-klientów, bez konieczności indywidualnego onboardingu każdego dostawcy/faktury.
Dla fintechów oferujących karty i obsługę płatności B2B lub B2C, taki model może stać się standardem zarządzania kosztami i automatyzacji rozliczeń - co zwiększa efektywność i konkurencyjność.
Wyzwania i kluczowe warunki powodzenia integracji
Oczywiście, aby podejście Sparados działało sprawnie i bez problemów, konieczne są:
Nadanie uprawnień przez firmy-klientów - bez zgody (uprawnień do odczytu faktur) Sparados nie będzie mógł pobierać dokumentów. To wymaga dobrej komunikacji i zrozumienia korzyści przez klienta.
Posiadanie ważnego certyfikatu KSeF - integratorzy muszą dopełnić formalności. Certyfikat musi być wydany na dane podmiotu, który wykonuje integrację.
Poprawne implementowanie specyfikacji FA(3) i wymogów szyfrowania w API 2.0 - w tym szyfrowanie faktur (np. AES-256), właściwe generowanie zapytań, obsługa certyfikatów oraz eksportów asynchronicznych.
Prawidłowe mapowanie faktur na transakcje - system Sparados musi mieć logiczne reguły dopasowania (np. data, kwota, kontrahent, NIP), by automatyczne łączenie miało sens i nie generowało błędów.
Podsumowanie
Integracja Sparados z KSeF 2.0 pokazuje, jak nowoczesny integrator może wykorzystać publicznie udostępnione API do automatyzacji kluczowych procesów - w tym pobierania faktur zakupowych i ich łączenia z rzeczywistymi transakcjami. Wdrożenie opiera się na oficjalnej dokumentacji KSeF 2.0, wykorzystaniu certyfikatu oraz nadanych uprawnień, a także na mechanizmach REST API do pobierania pojedynczych faktur, metadanych oraz eksportów.
Dzięki temu Sparados zapewnia klientom i księgowości kompletny, uporządkowany i zautomatyzowany przepływ danych - minimalizując ręczne działania i zwiększając efektywność rozliczeń.