KSeF API pobieranie faktur
Co musisz wiedzieć
Krajowy System e-Faktur (KSeF) jest centralnym systemem administracji skarbowej do wystawiania i otrzymywania faktur ustrukturyzowanych w formacie XML.
Na tej stronie znajdziesz uporządkowane informacje dotyczące tematu: KSeF API pobieranie faktur. Opis koncentruje się na aktualnych przepisach oraz komunikatach Ministerstwa Finansów.
Instrukcja krok po kroku
1. Uwierzytelnij się i uzyskaj accessToken
Wykonaj proces autoryzacji: pobierz challenge (POST /api/v2/auth/challenge), podpisz AuthTokenRequest, uzyskaj accessToken. Token JWT jest wymagany do wszystkich operacji pobierania faktur.
2. Wyszukaj faktury
Użyj endpointu POST /api/v2/invoices/query/metadata z odpowiednimi filtrami: zakres dat, NIP kontrahenta, typ faktury (sprzedaż/zakup). Pamiętaj o paginacji przy dużej liczbie wyników.
3. Pobierz pojedynczą fakturę
Użyj endpointu GET /api/v2/invoices/ksef/{ksefNumber}, aby pobrać konkretną fakturę po numerze KSeF. Faktura jest zwracana w formacie XML zgodnym z oryginalnym schematem (FA2 lub FA3).
4. Eksportuj paczki faktur
Do masowego pobierania użyj endpointu POST /api/v2/invoices/exports. Zastosuj filtry po dacie lub kontrahencie. Przestrzegaj limitów rate limiting przy masowym pobieraniu.
5. Przetwórz pobrane faktury
Zaimportuj pobrane pliki XML do swojego systemu księgowego. Większość programów oferuje automatyczne parsowanie struktury FA(2)/FA(3). Wygeneruj wizualizacje PDF jeśli potrzebujesz czytelnej formy.
Najczęstsze problemy i rozwiązania
Nie mogę pobrać faktury – błąd autoryzacji
Sprawdź, czy masz uprawnienie InvoiceRead i czy token JWT jest ważny. Upewnij się, że próbujesz pobrać fakturę przypisaną do Twojego NIP (jako sprzedawca lub nabywca).
Pobrana faktura ma inny format niż oczekiwany
Faktury są przechowywane w oryginalnej strukturze (FA1, FA2 lub FA3). API zwraca fakturę w formacie, w jakim została wystawiona. Sprawdź datę wystawienia faktury.
Jak pobrać wiele faktur jednocześnie?
Użyj endpointu POST /invoices/exports do eksportu paczki faktur. Zastosuj filtry po dacie lub kontrahencie. Pamiętaj o limitach rate limiting przy masowym pobieraniu.
Endpointy pobierania faktur
| Endpoint | Metoda | Opis |
|---|---|---|
| /api/v2/invoices/ksef/{ksefNumber} | GET | Pobranie pojedynczej faktury po numerze KSeF |
| /api/v2/invoices/query/metadata | POST | Wyszukiwanie faktur z filtrami |
| /api/v2/invoices/exports | POST | Eksport paczki faktur |
Filtrowanie faktur
API KSeF umożliwia filtrowanie faktur po: zakresie dat wystawienia, numerze NIP kontrahenta, typie faktury (sprzedaż jako sprzedawca, zakup jako nabywca), statusie przetwarzania. Szczegółowe opcje filtrowania znajdziesz w dokumentacji OpenAPI.
Format zwracanych faktur
Faktury są zwracane w oryginalnym formacie XML zgodnym ze schematem, w jakim zostały wystawione: FA(1), FA(2) lub FA(3). System nie konwertuje starszych struktur. Przetwarzanie wymaga obsługi wszystkich wersji schematów.
Rate limiting i limity
API KSeF stosuje limity liczby żądań: na sekundę, minutę i godzinę. Limity różnią się w zależności od środowiska (test/produkcja) i typu operacji. Przy masowym pobieraniu implementuj retry z backoffem i rozłóż żądania w czasie.
FAQ
Jak pobrać fakturę z KSeF przez API?
Fakturę pobierasz przez endpoint GET /invoices/ksef/{ksefNumber}, podając numer identyfikacyjny KSeF faktury. Do pobierania wielu faktur możesz użyć endpointu POST /invoices/query/metadata z odpowiednimi filtrami.
W jakim formacie zwracane są faktury z API KSeF?
Faktury zwracane są w formacie XML zgodnym ze strukturą logiczną FA(2) lub FA(3). API umożliwia również eksport paczek faktur przez endpoint POST /invoices/exports.
Czy mogę filtrować faktury po dacie lub kontrahencie?
Tak, API KSeF umożliwia filtrowanie faktur po różnych kryteriach, w tym po dacie wystawienia, numerze NIP kontrahenta i innych parametrach. Szczegółowe opcje filtrowania znajdziesz w dokumentacji endpointu query.
Jak długo faktury są dostępne do pobrania z KSeF?
Faktury przechowywane są w KSeF przez minimum 10 lat i przez cały ten czas są dostępne do pobrania przez API. System eliminuje konieczność lokalnego archiwizowania faktur.