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 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 (ksef-test.mf.gov.pl) czy produkcyjnym (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: 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.