Jak działa API KSeF — architektura i workflow | KSeF Serwis

Jak działa API KSeF?

API KSeF to interfejs REST udostępniany przez Ministerstwo Finansów. Umożliwia programistyczną komunikację z Krajowym Systemem e-Faktur.

Architektura API

API KSeF działa w modelu sesyjnym:

1.Klient otwiera sesję interaktywną za pomocą tokena lub certyfikatu

2.W ramach sesji wykonuje operacje (wysyłka, odbiór faktur)

3.Po zakończeniu zamyka sesję

Środowiska

•Testowe: https://ksef-test.mf.gov.pl/api

•Produkcyjne: https://ksef.mf.gov.pl/api

Autoryzacja

KSeF obsługuje dwa mechanizmy autoryzacji:

1.Token — wygenerowany wcześniej klucz, idealny do automatyzacji

2.Certyfikat kwalifikowany — podpis elektroniczny, wymagany do zarządzania

Workflow wysyłki faktury

1.POST /api/online/Session/InitToken — otwórz sesję

2.PUT /api/online/Invoice/Send — wyślij fakturę XML

3.GET /api/online/Invoice/Status/{InvoiceElementReferenceNumber} — sprawdź status

4.GET /api/online/Invoice/Get/{KSeFReferenceNumber} — pobierz UPO

5.GET /api/online/Session/Terminate — zamknij sesję

Formaty danych

•Faktury: XML zgodny ze schematem FA(2)

•Komunikacja: JSON (żądania/odpowiedzi API)

•Podpisy: XMLDSig lub XAdES

Obsługa błędów

API KSeF zwraca kody błędów z opisem. Najczęstsze problemy:

•Nieprawidłowy token lub wygasła sesja

•Błędna struktura XML faktury

•Brak uprawnień

•Duplikat faktury

Podsumowanie

API KSeF jest dobrze udokumentowane, ale złożone. Proxy KSeF może znacząco uprościć integrację, obsługując za Ciebie autoryzację, podpisy i obsługę sesji.

Jak działa API KSeF — architektura i workflow