Pobieranie faktur z KSeF przez API: jak to działa w skrócie
Aktualizacja:
Pobieranie faktur z KSeF przez API wygląda tak: uwierzytelniasz się (challenge, potem token zaszyfrowany kluczem publicznym MF albo podpis XAdES), pytasz o faktury, na których firma jest nabywcą, i odbierasz metadane albo pełne paczki XML w eksporcie asynchronicznym. Synchronizację prowadzisz przyrostowo, z zachowaniem niskich limitów zapytań.
Poniżej znajdziesz mapę tego procesu dla programisty lub integratora. Bez kodu produkcyjnego. Szczegóły, nazwy pól i aktualne wersje interfejsu sprawdzaj zawsze w oficjalnej dokumentacji.
Gdzie jest oficjalna dokumentacja
Dokumentacja i specyfikacja API KSeF są w publicznym repozytorium CIRFMF/ksef-docs. To jedyne źródło, na którym warto opierać implementację.
Interfejs się zmienia, więc nie kopiuj rozwiązań z forów ani starych przykładów bez porównania ich z repozytorium. Przed każdym większym wdrożeniem przejrzyj historię zmian.
Środowiska: TEST, DEMO i PROD
KSeF udostępnia trzy środowiska. Każde służy do czegoś innego.
| Środowisko | Do czego służy |
|---|---|
| TEST | Dane testowe, swobodne eksperymenty i pierwsza integracja |
| DEMO | Konfiguracja jak na produkcji, sprawdzenie zachowania przed wdrożeniem |
| PROD | Faktury z mocą prawną, prawdziwe dane firm |
Rozsądna kolejność to TEST, potem DEMO, na końcu PROD. Tokenów i danych z jednego środowiska nie traktuj jako ważnych w innym.
Uwierzytelnienie: challenge, token lub XAdES
Sesja zaczyna się od pobrania wyzwania (challenge). Potem masz dwie drogi:
- Token: szyfrujesz go kluczem publicznym Ministerstwa Finansów i odsyłasz razem z odpowiedzią na challenge.
- Podpis XAdES: podpisujesz żądanie certyfikatem (kwalifikowanym lub certyfikatem KSeF).
Do integracji, która ma tylko czytać faktury, najczęściej wybiera się token. Jak go utworzyć i na co uważać, opisuje poradnik jak wygenerować token KSeF. Jeśli rozważasz drugą drogę, porównanie znajdziesz w tekście certyfikat KSeF a token.
O tokenie pamiętaj:
- jest pokazywany tylko raz, przy utworzeniu, więc od razu zapisz go w bezpiecznym magazynie sekretów,
- nowsze tokeny mogą mieć ograniczony okres ważności i mogą wymagać zatwierdzenia,
- po wygaśnięciu logowanie kończy się błędem (token poza okresem ważności), więc Twoja aplikacja powinna to rozpoznać i powiadomić użytkownika,
- właściciel firmy może token w każdej chwili unieważnić.
Uprawnienie i rola nabywcy
Faktury kosztowe to te, na których firma występuje jako nabywca, czyli Podmiot2 w strukturze faktury. W API odpowiada temu zapytanie w roli Subject2.
Do samego odbioru wystarczy uprawnienie do przeglądania faktur (InvoiceRead). Nie proś o więcej, niż potrzebujesz. Token bez prawa do wystawiania faktur ogranicza skutki ewentualnego wycieku. Różnice między Podmiotem2 a Podmiotem3 i to, jak je uwzględnić w wyszukiwaniu, omawia osobny tekst o fakturach zakupowych i roli Podmiot2.
Metadane czy eksport asynchroniczny
Masz dwa sposoby pozyskiwania danych.
Zapytanie o metadane
Zwraca listę faktur z podstawowymi informacjami, bez pełnej treści. Dobrze nadaje się do szybkiego sprawdzenia, czy pojawiło się coś nowego, i do budowania listy w interfejsie.
Eksport asynchroniczny
Zlecasz eksport, czekasz na jego przygotowanie i pobierasz paczkę. Paczka jest szyfrowana. Po odszyfrowaniu dostajesz ZIP z plikami XML faktur i plikiem metadanych. Jedna paczka mieści do 10 000 faktur lub 1 GB.
Pamiętaj, że oryginałem faktury jest XML w schemie FA(3). PDF to tylko wizualizacja, którą generujesz z XML po swojej stronie.
Pobieranie przyrostowe i znacznik HWM
Nie pobieraj za każdym razem wszystkiego od nowa. Synchronizacja przyrostowa opiera się na dacie trwałego zapisu faktury w KSeF i znaczniku HWM (high water mark), który wskazuje, do którego miejsca dane są już kompletne.
W praktyce:
- Zapamiętaj ostatni bezpieczny punkt synchronizacji.
- Przy kolejnym przebiegu pytaj o faktury od tego punktu.
- Deduplikuj po numerze KSeF, bo zakresy mogą się nakładać.
- Dopiero po poprawnym zapisie przesuń punkt dalej.
Data trwałego zapisu ma tu znaczenie, bo nie każda faktura trafia do systemu w dniu wystawienia. Faktury offline sprzedawca może przesłać do KSeF z opóźnieniem, więc opieranie się wyłącznie na dacie wystawienia grozi pominięciem dokumentów.
Limity zapytań i błąd 429
Limity na produkcji są niskie. Zapytania o metadane i eksporty są rzędu 20 na godzinę na kontekst. Zalecany cykl synchronizacji to co najmniej 15 minut.
Po przekroczeniu limitu dostaniesz błąd 429 z nagłówkiem Retry-After. Respektuj go: odczekaj wskazany czas, zamiast ponawiać od razu. Przy wielu firmach (np. w biurze rachunkowym) rozłóż harmonogram tak, żeby nie wszystkie konteksty odpytywać w tej samej minucie.
Na co jeszcze uważać w integracji
- Nie wszystko jest w KSeF. Faktury od zagranicznych dostawców bez polskiego NIP zwykle przychodzą poza systemem (e-mailem, w panelu dostawcy).
- Brak powiadomień po stronie KSeF. Nie ma standardowego powiadomienia nabywcy o nowej fakturze, więc informowanie użytkownika musisz zbudować sam.
- Wygasający token. Monitoruj błędy logowania i z wyprzedzeniem przypominaj o odnowieniu.
- Bezpieczeństwo. Tokeny i pobrane faktury przechowuj zaszyfrowane, z kontrolą dostępu.
Jeśli potrzebujesz tylko pojedynczej faktury, a nie stałej integracji, prostsze będzie ręczne pobranie. Opisuje to poradnik jak pobrać fakturę z KSeF. Więcej tematów technicznych i praktycznych znajdziesz w Poradniku KSeF.
Jeśli nie chcesz utrzymywać własnej integracji, ksefapp robi to za Ciebie: sprawdza KSeF co około 15 minut tokenem tylko do przeglądania faktur, niczego w systemie nie zmienia. Start przed 1.01.2027, możesz już teraz zapisać się na listę ksefapp.
Najczęściej zadawane pytania
Czy do pobierania faktur przez API potrzebuję certyfikatu?
Nie musisz. Uwierzytelnić się możesz tokenem zaszyfrowanym kluczem publicznym MF albo podpisem XAdES z certyfikatem. Do integracji, która tylko czyta faktury, zwykle wystarcza token z uprawnieniem do przeglądania.
Którą metodę wybrać: metadane czy eksport?
Metadane sprawdzają się do szybkiej kontroli, czy są nowe faktury, i do budowy listy. Eksport asynchroniczny daje pełne pliki XML w szyfrowanej paczce. Wiele integracji łączy oba sposoby.
Jak często mogę odpytywać KSeF?
Limity na produkcji są niskie, rzędu 20 zapytań o metadane i eksportów na godzinę na kontekst. Zalecany cykl synchronizacji to co najmniej 15 minut. Po błędzie 429 odczekaj czas z nagłówka Retry-After.
Jak uniknąć duplikatów przy synchronizacji?
Synchronizuj przyrostowo według daty trwałego zapisu i znacznika HWM, a każdą fakturę identyfikuj po numerze KSeF. Punkt synchronizacji przesuwaj dopiero po poprawnym zapisaniu danych.
Na którym środowisku zacząć?
Zacznij od TEST, gdzie pracujesz na danych testowych. Potem sprawdź zachowanie na DEMO, które ma konfigurację jak produkcja. Dopiero na końcu przejdź na PROD, gdzie faktury mają moc prawną.
Ostatnia aktualizacja: 17 listopada 2026. Tekst ma charakter informacyjny i nie jest poradą prawną ani podatkową. W wątpliwościach skonsultuj się z księgową lub sprawdź komunikaty Ministerstwa Finansów.