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 integracje zewnetrznych systemow z Krajowym Systemem e-Faktur. API jest bezplatne i oparte na standardzie REST.
Podstawowe informacje
- Typ: REST API
- Format danych: JSON / XML
- Autoryzacja: Token sesji + pieczec/podpis kwalifikowany
- Srodowisko produkcyjne: ksef.mf.gov.pl
- Srodowisko 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 │
└───────────────────────┘ Glowne 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 byc 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 numerze referencyjnym KSeF. Zwraca pelna 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 kazdego wywolania API w naglowku
SessionToken. Sesja jest wazna przez okreslony czas (domyslnie 24h).
Wazne
Do automatycznej integracji (bez udzialu czlowieka) wymagana jest pieczec kwalifikowana. Podpis kwalifikowany wymaga interakcji uzytkownika przy kazdej sesji.
Format faktury XML
Faktury wysylane do KSeF musza byc zgodne ze 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>Pelna dokumentacja schemy dostepna jest na stronie ksef.mf.gov.pl .
Srodowisko testowe
Przed wdrozeniem produkcyjnym obowiazkowo przetestuj integracje na srodowisku testowym KSeF:
Dane srodowiska testowego:
- URL API:
- https://ksef-test.mf.gov.pl/api
- Portal testowy:
- https://ksef-test.mf.gov.pl
- Testowe NIP-y:
- Dostepne w dokumentacji MF
- Wsparcie:
- ksef@mf.gov.pl
Potrzebujesz pomocy z integracja?
Oferujemy uslugi integracji KSeF dla firm. Wdrozymy API, skonfigurujemy autoryzacje i przeszkolimy Twoj zespol.