KSeF Konsulting

IT i operacje

Integracja KSeF z ERP

Integracja z KSeF to nie tylko endpoint wysyłki. Trzeba obsłużyć strukturę FA(3), uwierzytelnienie, certyfikaty, statusy, retry, logi i realny obieg dokumentów.

Materiał informacyjny. Nie stanowi porady podatkowej ani prawnej.

01

Który system jest źródłem prawdy dla faktury.

02

Jak przechowywać statusy, numer KSeF i historię wysyłki.

03

Jak zarządzać certyfikatami i tokenami w okresie przejściowym.

Dla kogo

  • Dla zespołów IT i administratorów ERP.
  • Dla osób odpowiedzialnych za fakturowanie, monitoring i integracje.
  • Dla software house'ów i integratorów przygotowujących klienta do KSeF.

Najpierw ustal

  • Który system jest źródłem prawdy dla faktury.
  • Jak przechowywać statusy, numer KSeF i historię wysyłki.
  • Jak zarządzać certyfikatami i tokenami w okresie przejściowym.
  • Jak wygląda retry, gdy błąd jest techniczny, a jak gdy biznesowy.

Co zrobić krok po kroku

  1. Pobierz aktualną dokumentację API KSeF 2.0 i schemy FA(3) z oficjalnych źródeł.
  2. Zmapuj pola faktury z ERP do FA(3) i oznacz dane wymagające uzupełnienia.
  3. Zaprojektuj uwierzytelnianie, certyfikaty, role serwisowe i rotację dostępu.
  4. Oddziel walidację biznesową od błędów technicznych i niedostępności.
  5. Zaimplementuj kolejkę, retry, idempotencję procesu i status dokumentu.
  6. Dodaj logi audytowe: kto, kiedy, jaki dokument, jaki status, jaki komunikat.
  7. Monitoruj faktury bez numeru KSeF, błędy walidacji i dokumenty w trybach szczególnych.

API KSeF 2.0 i FA(3)

Ministerstwo Finansów opublikowało dokumentację API KSeF 2.0, specyfikację OpenAPI, SDK i materiały wspierające integratorów. To powinno być źródło kontraktu technicznego, a nie opis z cudzej prezentacji.

FA(3) zmienia sposób myślenia o danych faktury. Integracja powinna walidować kompletność danych przed wysyłką, bo poprawianie dokumentu po fakcie jest droższe niż dobry gate w systemie źródłowym.

Retry i error handling

Nie każdy błąd wolno ponawiać automatycznie. Błąd sieciowy, limit API, błąd schemy i brak danych kontrahenta to różne sytuacje. Wdrożenie powinno rozróżniać komunikaty techniczne od biznesowych i kierować je do właściwej osoby.

Dobry monitoring pokazuje liczbę dokumentów wysłanych, oczekujących, odrzuconych, ponawianych i wystawionych w trybie offline. Bez tego zespół pracuje na skrzynce mailowej i zrzutach ekranu.

Księgowa perspektywa PIT-Lab

KSeF ujawnia miejsca, w których firma nie ma właściciela danych: opis usług, akceptacja kosztów, wyjątki, załączniki, powiązanie dokumentu z zamówieniem. Integracja z ERP jest tylko częścią układanki.

PIT-Lab jest biurem rachunkowym, więc linkujemy do niego tam, gdzie potrzebne jest księgowe spojrzenie na dokumenty, koszty, terminy i odpowiedzialność po stronie firmy.

Najczęstsze błędy

  • Brak kolejki i statusów pośrednich.
  • Traktowanie każdego błędu jak awarii technicznej.
  • Brak rotacji i ewidencji certyfikatów.
  • Brak dashboardu dokumentów bez numeru KSeF.
  • Testy bez danych z realnych integracji.

Kontrola integracji

  • Kontrakt API i wersja schemy.

  • Mapowanie pól FA(3).

  • Uwierzytelnianie i certyfikaty.

  • Kolejka, retry i statusy.

  • Logi audytowe.

  • Monitoring wyjątków.

  • Procedury offline.

FAQ

Czy API KSeF 2.0 jest tylko dla dużych firm?

Nie. API jest istotne wszędzie tam, gdzie firma chce integrować KSeF z systemem fakturowym, ERP lub obiegiem dokumentów zamiast pracować ręcznie.

Czy wystarczy walidacja XML?

Nie. Walidacja XML jest konieczna, ale proces musi obsłużyć statusy, błędy biznesowe, ponowienia, logi i pracę ludzi.

Na podstawie