API KSeF - Dokumentacja techniczna
Przewodnik dla programistow po integracji z Krajowym Systemem e-Faktur. Poznaj endpointy, metody autoryzacji i przyklady implementacji.
Szybkie linki dla programistow
Wprowadzenie do API KSeF
API KSeF to interfejs programistyczny udostepniony przez Ministerstwo Finansow, umozliwiajacy integrację zewnetrznych systemow z Krajowym Systemem e-Faktur. API jest bezpłatne i oparte na standardzie REST.
Podstawowe informacje
- Typ: REST API
- Format danych: JSON / XML
- Autoryzacja: Token sesji + pieczęć/podpis kwalifikowany
- Środowisko produkcyjne: ksef.mf.gov.pl
- Środowisko testowe: ksef-test.mf.gov.pl
Architektura API
Schemat komunikacji:
┌─────────────────┐ ┌──────────────┐ ┌─────────────┐
│ Twoj System │─────▶│ API KSeF │─────▶│ KSeF DB │
│ (Klient API) │◀─────│ Gateway │◀─────│ (Faktury) │
└─────────────────┘ └──────────────┘ └─────────────┘
│ │
│ 1. Autoryzacja │
│ 2. Wysylanie faktur │
│ 3. Pobieranie faktur │
│ 4. UPO/statusy │
└───────────────────────┘ Główne endpointy API
/api/online/Session/InitSigned Inicjalizacja sesji
Rozpoczyna sesje autoryzowana. Wymaga podpisanego tokenu inicjalizacyjnego. Zwraca token sesji do uzytku w kolejnych wywolaniach.
Przykladowa odpowiedz:
{"sessionToken": {"token": "abc123...", "context": {...}}} /api/online/Invoice/Send Wysylanie faktury
Wysyla fakture do KSeF. Faktura musi być w formacie XML zgodnym ze schema FA(2). Zwraca numer referencyjny i status przetwarzania.
Wymagane naglowki:
SessionToken: <token_sesji> Content-Type: application/xml
/api/online/Invoice/Get/{ksef_reference} Pobieranie faktury
Pobiera fakture po numerże referencyjnym KSeF. Zwraca pełna strukture faktury w formacie XML.
/api/online/Invoice/Status/{reference} Status faktury
Sprawdza status przetwarzania faktury. Uzywaj do monitorowania czy faktura zostala poprawnie przetworzona przez KSeF.
/api/online/Invoice/UPO/{reference} Pobranie UPO
Pobiera Urzedowe Poswiadczenie Odbioru (UPO) dla faktury. UPO potwierdza przyjetie faktury przez KSeF i jest dowodem jej wystawienia.
Autoryzacja w API
API KSeF wymaga dwuetapowej autoryzacji:
- 1
Inicjalizacja sesji
Przygotuj token inicjalizacyjny, podpisz go pieczecia/podpisem kwalifikowanym i wyslij do endpointu InitSigned. Otrzymasz token sesji.
- 2
Uzywanie tokenu sesji
Dolacz token sesji do każdego wywolania API w naglowku
SessionToken. Sesja jest ważna przez okreslony czas (domyslnie 24h).
Ważne
Do automatycznej integracji (bez udzialu czlowieka) wymagana jest pieczęć kwalifikowana. Podpis kwalifikowany wymaga interakcji uzytkownika przy kazdej sesji.
Format faktury XML
Faktury wysylane do KSeF muszą być zgodne że schema FA(2) opublikowana przez Ministerstwo Finansow. Przykladowa struktura:
<?xml version="1.0" encoding="UTF-8"?>
<Faktura xmlns="http://crd.gov.pl/wzor/2023/06/29/12648/">
<Naglowek>
<KodFormularza kodSystemowy="FA (2)">FA</KodFormularza>
<WariantFormularza>2</WariantFormularza>
<DataWytworzeniaFa>2026-01-15T10:30:00</DataWytworzeniaFa>
</Naglowek>
<Podmiot1>
<!-- Dane sprzedawcy -->
</Podmiot1>
<Podmiot2>
<!-- Dane nabywcy -->
</Podmiot2>
<Fa>
<!-- Dane faktury: pozycje, sumy, VAT -->
</Fa>
</Faktura>Pełna dokumentacja schemy dostępna jest na stronie ksef.mf.gov.pl .
Środowisko testowe
Przed wdrozeniem produkcyjnym obowiazkowo przetestuj integrację na środowisku testowym KSeF:
Dane środowiska testowego:
- URL API:
- https://ksef-test.mf.gov.pl/api
- Portal testowy:
- https://ksef-test.mf.gov.pl
- Testowe NIP-y:
- Dostępne w dokumentacji MF
- Wsparcie:
- ksef@mf.gov.pl
Potrzebujesz pomocy z integracja?
Oferujemy usługi integracji KSeF dla firm. Wdrozymy API, skonfigurujemy autoryzacje i przeszkolimy Twoj zespol.