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://ksef-test.mf.gov.pl) czy produkcyjnym (https://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://ksef-test.mf.gov.pl/api/v2, dla produkcji: https://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
Do wysyłania faktur użyj POST /api/v2/invoices/send. 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/invoices/{invoiceId}/status, aby sprawdzić status przetwarzania faktury. 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/{id} | GET | Pobranie faktury po ID |
| /api/v2/invoices/{id}/status | GET | Status przetwarzania faktury |
| /api/v2/invoices/query | POST | Wyszukiwanie faktur |
Środowiska API KSeF
| Środowisko | URL | Przeznaczenie |
|---|---|---|
| Testowe (TE) | https://ksef-test.mf.gov.pl/api/v2 | Testy integracji, self-signed certs |
| Demo (TR) | https://ksef-demo.mf.gov.pl/api/v2 | Testy z rzeczywistymi danymi |
| Produkcyjne (PRD) | https://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 (POST /invoices), pobierania faktur (GET /invoices), pobierania statusu faktury, 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.
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ą dwa środowiska: testowe (dla deweloperów, dostępne od września 2025) oraz produkcyjne (aktywne od lutego 2026). Środowisko testowe pozwala na bezpieczne testowanie integracji przed wdrożeniem produkcyjnym.
Powiązane tematy
Przydatne serwisy
Status KSeF
Pierwszy serwis prezentuje informacje o statusie samego KSeF, drugi – komunikaty techniczne Ministerstwa Finansów.