KSeF API integracja: co musi umieć system w praktyce

Integracja własnego systemu z KSeF wymaga implementacji kilku kluczowych elementów. Oto co musi umieć dobra integracja.

1. Autoryzacja

KSeF API wymaga tokenu sesji. Kroki:

1. Autoryzacja tokenu API (wygenerowanego w panelu KSeF)
2. Inicjalizacja sesji interaktywnej
3. Użycie access token do kolejnych żądań
4. Zakończenie sesji po pracy

2. Wysyłka faktur (outgoing)

• Zbudowanie XML w schemacie FA(3)
• Wysyłka przez endpoint inicjalizujący sesję wysyłki
• Monitoring statusu referencji wysyłki
• Pobranie UPO po akceptacji

3. Odbiór faktur (incoming)

• Zapytanie o listę faktur za okres (query)
• Paginacja wyników
• Pobieranie XML dla każdej faktury
• Zapis lokalny i parsowanie

4. Obsługa błędów

• Retry z exponential backoff przy 503
• Walidacja XML przed wysyłką
• Log wszystkich żądań
• Monitoring tokenów (wygasanie)

Gotowy gateway zamiast własnej implementacji

KSeF Desk oferuje API Gateway, który obsługuje całą warstwę KSeF:

• Endpointy REST dla inbox, outbox, statusów
• Webhooki po zmianie statusu
• HMAC podpisane payloady
• Sandbox i produkcja

Zamiast pisać integrację od zera, możesz użyć KSeF Desk jako warstwy pośredniej dla swojego CRM/ERP.

Kiedy nie warto pisać wszystkiego od zera

Wiele zespołów zaczyna od myśli: „zrobimy tylko prosty konektor”. Potem pojawiają się retry, archiwum XML, statusy, UPO, różnice środowisk i logowanie błędów. Właśnie wtedy okazuje się, że warstwa pośrednia oszczędza czas i ryzyko.

FAQ

Czy sama wysyłka faktury przez API rozwiązuje temat integracji?

Nie. Równie ważne są odbiór, monitoring, archiwizacja i obsługa błędów.

Powiązane tematy i kolejne kroki

Integrację z KSeF warto analizować razem z tymi materiałami:

• Token czy certyfikat KSeF: co wybrać w 2026 roku,
• KSeF: statusy wysyłki i typowe błędy walidacji FA(3),
• Co to jest UPO w KSeF i gdzie je sprawdzić?.

Od strony pojęć zobacz także FA(3) w KSeF i numer KSeF.