KSeF API endpointy
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 endpointy. Opis koncentruje się na aktualnych przepisach oraz komunikatach Ministerstwa Finansów.
Instrukcja krok po kroku
1. Zapoznaj się z dokumentacją OpenAPI
Pobierz specyfikację OpenAPI ze strony https://ksef.podatki.gov.pl/ksef-na-okres-obligatoryjny/wsparcie-dla-integratorow. Dokument zawiera pełną listę endpointów, metod HTTP, parametrów i przykładowych odpowiedzi.
2. Wybierz środowisko pracy
Zdecyduj, czy pracujesz ze środowiskiem testowym (https://api-test.ksef.mf.gov.pl) czy produkcyjnym (https://api.ksef.mf.gov.pl). Do testów integracji używaj środowiska testowego – nie wymaga ono certyfikatu kwalifikowanego.
3. Skonfiguruj bazowy URL
Ustaw bazowy URL API w swoim kliencie HTTP. Dla środowiska testowego: https://api-test.ksef.mf.gov.pl/api/v2, dla produkcji: https://api.ksef.mf.gov.pl/api/v2.
4. Zaimplementuj autoryzację
Przed wywołaniem endpointów operacyjnych musisz uzyskać accessToken. Proces autoryzacji obejmuje: pobranie challenge, podpisanie dokumentu AuthTokenRequest i wymianę na token JWT.
5. Wywołaj endpoint testowy
Przetestuj połączenie wywołując prosty endpoint, np. GET /api/v2/health lub GET /api/v2/security/public-key-certificates, aby zweryfikować poprawność konfiguracji.
Najczęstsze problemy i rozwiązania
Nie wiem, jakiego endpointu użyć do wysyłki faktury
Faktury wysyła się w ramach sesji: w sesji interaktywnej przez POST /api/v2/sessions/online/{referenceNumber}/invoices, w sesji wsadowej w ramach paczki ZIP przesyłanej po otwarciu sesji POST /api/v2/sessions/batch. Faktura musi być w formacie XML zgodnym ze schematem FA(3). Wymagany jest ważny accessToken z uprawnieniem InvoiceWrite.
Endpoint zwraca błąd 404 – nie znaleziono
Sprawdź, czy używasz poprawnego adresu URL środowiska (testowe vs produkcyjne) i czy endpoint istnieje w dokumentacji API 2.0. Upewnij się, że ścieżka URL jest poprawna.
Jak sprawdzić status wysłanej faktury?
Użyj endpointu GET /api/v2/sessions/{referenceNumber}/invoices/{invoiceReferenceNumber}, aby sprawdzić status przetwarzania faktury w danej sesji. Status zawiera informacje o walidacji i nadaniu numeru KSeF.
Kategorie endpointów API KSeF 2.0
API KSeF 2.0 dzieli endpointy na kategorie: autoryzacja (/auth/), sesje (/sessions/), faktury (/invoices/), uprawnienia (/permissions/), certyfikaty (/certificates/), dane testowe (/testdata/). Każda kategoria odpowiada za określony obszar funkcjonalny systemu.
Endpointy autoryzacji
| Endpoint | Metoda | Opis |
|---|---|---|
| /api/v2/auth/challenge | POST | Pobranie challenge do uwierzytelniania |
| /api/v2/auth/xades-signature | POST | Uwierzytelnianie podpisem XAdES |
| /api/v2/auth/ksef-token | POST | Uwierzytelnianie tokenem KSeF |
| /api/v2/auth/token/redeem | POST | Wymiana na accessToken/refreshToken |
| /api/v2/auth/token/refresh | POST | Odświeżenie accessToken |
Endpointy faktur
| Endpoint | Metoda | Opis |
|---|---|---|
| /api/v2/sessions/online/{ref}/invoices | POST | Wysłanie faktury w sesji interaktywnej |
| /api/v2/invoices/ksef/{ksefNumber} | GET | Pobranie faktury po numerze KSeF |
| /api/v2/sessions/{ref}/invoices/{invoiceRef} | GET | Status przetwarzania faktury w sesji |
| /api/v2/invoices/query/metadata | POST | Wyszukiwanie metadanych faktur |
Środowiska API KSeF
| Środowisko | URL | Przeznaczenie |
|---|---|---|
| Testowe (TE) | https://api-test.ksef.mf.gov.pl/api/v2 | Testy integracji, self-signed certs |
| Demo (DEMO) | https://api-demo.ksef.mf.gov.pl/api/v2 | Konfiguracja zbliżona do produkcyjnej, końcowa walidacja integracji (bez danych rzeczywistych) |
| Produkcyjne (PRD) | https://api.ksef.mf.gov.pl/api/v2 | Realne dokumenty, skutki prawne |
FAQ
Jakie endpointy udostępnia API KSeF?
API KSeF udostępnia endpointy do: wysyłania faktur w ramach sesji interaktywnej lub wsadowej (np. POST /sessions/online/{referenceNumber}/invoices), pobierania faktur (np. GET /invoices/ksef/{ksefNumber}), pobierania statusu faktury i sesji, obsługi załączników oraz autoryzacji i uwierzytelniania użytkowników. Pełna dokumentacja dostępna jest w formacie OpenAPI.
Gdzie znajdę dokumentację API KSeF 2.0?
Pełna dokumentacja API KSeF 2.0 (specyfikacje OpenAPI/JSON, SDK dla Javy i .NET) dostępna jest na stronie Ministerstwa Finansów: https://ksef.podatki.gov.pl/ksef-na-okres-obligatoryjny/wsparcie-dla-integratorow. Dla prostszej integracji (wysyłanie JSON zamiast XML) możesz rozważyć serwis KSeFAPI.dev – proste API do KSeF.
Czy API KSeF używa standardu REST?
Tak, API KSeF opiera się na standardzie REST i OpenAPI, co oznacza typowe dla integracji endpointy HTTP (POST, GET, PUT, DELETE). Dokumentacja zawiera opisy endpointów, metody uwierzytelniania oraz przykłady użycia.
Jakie środowiska API KSeF są dostępne?
Dostępne są trzy środowiska: testowe TE (do testowania integracji, dopuszcza certyfikaty self-signed), demo/przedprodukcyjne (odpowiada konfiguracji produkcyjnej, do końcowej walidacji integracji) oraz produkcyjne PRD (realne dokumenty, pełna moc prawna). Środowisko testowe pozwala na bezpieczne testowanie integracji przed wdrożeniem produkcyjnym.
Powiązane tematy
Przydatne serwisy
Status i komunikaty
API i narzędzia
Pierwsza grupa – status systemu KSeF i komunikaty techniczne Ministerstwa Finansów, druga – narzędzia do integracji z KSeF i walidacji faktur.