Propozycja: model zdarzeń biznesowych i synchronizacja zmian dla faktur

[kw-cirf]

Ta propozycja stanowi formę publicznych konsultacji dotyczących dalszego rozwoju API KSeF. Na tym etapie celem jest zebranie szerokiego feedbacku od rynku. Po zakończeniu konsultacji i analizie uwag zostanie zaproponowany ostateczny kierunek dalszych prac oraz zakres implementacji.

Propozycja obejmuje dwa odrębne zagadnienia.

1. Zagadnienie techniczne
Celem jest wypracowanie docelowego mechanizmu wymiany informacji o zmianach, tj. sposobu synchronizacji dokumentów oraz powiązanych z nimi zdarzeń biznesowych. Przykłady zdarzeń użyte w opisie służą przede wszystkim zobrazowaniu samego zjawiska i potrzeb integracyjnych.

2. Katalog zdarzeń biznesowych
Drugi obszar dotyczy samego katalogu możliwych zdarzeń biznesowych. Jest to temat szerszy, wielowątkowy i wymagający osobnej dyskusji z uwzględnieniem różnych perspektyw biznesowych. Z tego względu warto, aby bardziej szczegółowe rozmowy dotyczące poszczególnych typów zdarzeń były prowadzone w odrębnych wątkach, tak aby nie zdominowały dyskusji o głównym celu tej propozycji, którym jest kierunek architektury i integracji.

Propozycja: Model zdarzeń biznesowych powiązanych z fakturami

Cel

Celem propozycji jest wprowadzenie modelu zdarzeń biznesowych powiązanych z fakturami w KSeF oraz powiązanego z nim mechanizmu pobierania zmian.

Model ten mógłby obejmować zarówno zdarzenia generowane w wyniku operacji wykonywanych na fakturze przez podmiot działający w dopuszczalnym kontekście, jak i inne zdarzenia biznesowe powiązane z fakturą.

Przykładowe scenariusze obejmują m.in. kwalifikację faktury, rejestrowanie zdarzeń płatniczych, dodawanie notatek i atrybutów biznesowych, oznaczanie pozycji faktury, zgłaszanie nadużyć, a także inne zdarzenia związane z obiegiem i obsługą faktury.

Założenie podstawowe

Rozszerzenie nie zmienia danych faktury ustrukturyzowanej zapisanej w KSeF.

Propozycja dotyczy wyłącznie zapisu i odczytu dodatkowych danych biznesowych prezentowanych w formie zdarzeń, w określonym kontekście, tak aby mogły służyć do ciągłej synchronizacji stanu faktur w systemach zewnętrznych.

Ograniczenia obecnego podejścia

Obecny model pobierania w KSeF został zaprojektowany jako mechanizm synchronizacji dokumentów pomiędzy centralnym repozytorium a lokalną bazą danych systemu zewnętrznego. Operacje biznesowe, takie jak filtrowanie, wyszukiwanie czy raportowanie, są wykonywane lokalnie.

Podejście to dobrze odpowiada na potrzeby związane z synchronizacją statycznych dokumentów. Pojawiają się jednak scenariusze, w których sama synchronizacja faktur nie jest wystarczająca, zwłaszcza gdy dodatkowe dane biznesowe zmieniają się w czasie, mogą być wielokrotnie aktualizowane i zależą od kontekstu podmiotu.

Proponowane podejście

W odpowiedzi na powyższe potrzeby proponowany jest model oparty na zdarzeniach biznesowych powiązanych z fakturą.

Każda zmiana dotycząca danych biznesowych faktury byłaby zapisywana jako osobne zdarzenie. Oznacza to, że zamiast nadpisywać jeden stan, system rejestrowałby kolejne zdarzenia opisujące dalszą obsługę faktury.

Każde zdarzenie powinno posiadać unikalny identyfikator oraz podstawowe metadane (np. datę utworzenia, autora), co umożliwia jego śledzenie oraz audyt.

Takie podejście umożliwiałoby aktualizowanie danych biznesowych faktury z zachowaniem historii zmian, zgodnie z rzeczywistym przebiegiem procesów biznesowych a aktualny stan faktury wynikałby z sekwencji zdarzeń.

Widoczność i zakres zdarzeń

Na etapie koncepcji można wyróżnić trzy podstawowe grupy zdarzeń:

1. Zdarzenia widoczne dla wszystkich podmiotów powiązanych z fakturą, np.:

• utworzenie faktury.

2. Zdarzenia widoczne wyłącznie dla podmiotu, który je wprowadził, np.:

• kwalifikację faktury wraz z opisem, np.:
  • do zaksięgowania,
  • wymaga wyjaśnienia,
  • wyłączona z księgowania;
• opis faktury,
• zdarzenia dotyczące pozycji faktury wraz z opisem, np.:
  • do zaksięgowania,
  • wymaga wyjaśnienia,
  • wyłączona z księgowania;
• opis pozycji,
• zgłoszenia dotyczące nadużycia, np.:
  • próba wyłudzenia nienależnej zapłaty,
  • faktura zawiera wyłącznie niechciane treści reklamowe,
  • faktura zawiera podejrzane linki,
  • masowa wysyłka faktur,
  • podszywanie się pod zaufaną instytucję,
  • inny powód.
• własne dane w postaci atrybutów, np. w modelu klucz–wartość.

3. Zdarzenia widoczne dla podmiotów, który je wprowadził, oraz dla innego wskazanego podmiotu, np.:

• powiązanie faktury z identyfikatorem wewnętrznym nabywcy - zdarzenie opisujące przypisanie do faktury własnego identyfikatora wewnętrznego przez nabywcę.

Ostateczny katalog i klasyfikacja wymaga osobnej dyskusji z uczestnikami rynku, w szczególności z producentami oprogramowania i integratorom. W niniejszym dokumencie skupiono się na koncepcji i ogólnym kierunku rozwiązania.

Przykłady

Poniżej przedstawiono przykładowe zdarzenia ilustrujące sposób działania proponowanego modelu. Przykłady mają charakter poglądowy i nie stanowią docelowej specyfikacji technicznej.

[
  {
    "eventId": 100001,
    "createdDate": "2026-04-10T08:15:12.0000000+00:00",
    "createdBy": {
      "context": {
        "identifier": "5356751957",
        "type": "Nip"
      },
      "subject": {
        "identifier": "5356751957",
        "type": "Nip"
      }
    },
    "type": "InvoiceCreated",
    "ksefNumber": "5356751957-20260410-1A2B3C4D5E6F-7A",
    "data": {
      "invoiceNumber": "FV/04/2026/001"
    }
  },
  {
    "eventId": 100002,
    "createdDate": "2026-04-10T09:02:44.0000000+00:00",
    "createdBy": {
      "context": {
        "identifier": "9523838080",
        "type": "Nip"
      },
      "subject": {
        "identifier": "9523838080",
        "type": "Nip"
      }
    },
    "type": "InvoiceLineExcludedFromSettlement",
    "ksefNumber": "5356751957-20260410-1A2B3C4D5E6F-7A",
    "data": {
      "invoiceLineNumber": 2,
      "reasonCode": "PrivateExpense",
      "reasonDescription": "Zakup prywatny"
    }
  }
]

[
  {
    "eventId": 200001,
    "createdDate": "2026-04-11T07:45:03.0000000+00:00",
    "createdBy": {
      "context": {
        "identifier": "1220718651",
        "type": "Nip"
      },
      "subject": {
        "identifier": "1220718651",
        "type": "Nip"
      }
    },
    "type": "InvoiceCreated",
    "ksefNumber": "1220718651-20260411-ABCDEF123456-9F",
    "data": {
      "invoiceNumber": "FV/04/2026/145"
    }
  },
  {
    "eventId": 200002,
    "createdDate": "2026-04-11T10:11:28.0000000+00:00",
    "createdBy": {
      "context": {
        "identifier": "9123456789",
        "type": "Nip"
      },
      "subject": {
        "identifier": "9123456789",
        "type": "Nip"
      }
    },
    "type": "AbuseReported",
    "ksefNumber": "1220718651-20260411-ABCDEF123456-9F",
    "data": {
      "abuseReportNumber": "RPT-20260411-000002",
      "reasonCode": "SuspiciousLinks",
      "reasonDescription": "Faktura zawiera podejrzane linki",
      "comment": "Link w stopce prowadzi do zewnętrznej strony logowania."
    }
  },
  {
    "eventId": 200003,
    "createdDate": "2026-04-11T10:39:54.0000000+00:00",
    "createdBy": {
      "context": {
        "identifier": "9123456789",
        "type": "Nip"
      },
      "subject": {
        "identifier": "9123456789",
        "type": "Nip"
      }
    },
    "type": "AbuseReportWithdrawn",
    "ksefNumber": "1220718651-20260411-ABCDEF123456-9F",
    "data": {
      "abuseReportNumber": "RPT-20260411-000002",
      "comment": "Zgłoszenie wycofano po dodatkowej weryfikacji."
    }
  },
  {
    "eventId": 200004,
    "createdDate": "2026-04-11T11:02:17.0000000+00:00",
    "createdBy": {
      "context": {
        "identifier": "9123456789",
        "type": "Nip"
      },
      "subject": {
        "identifier": "9123456789",
        "type": "Nip"
      }
    },
    "type": "AbuseReported",
    "ksefNumber": "1220718651-20260411-ABCDEF123456-9F",
    "data": {
      "abuseReportNumber": "RPT-20260411-000003",
      "reasonCode": "Impersonation",
      "reasonDescription": "Podszywanie się pod zaufaną instytucję",
      "comment": "Treść faktury sugeruje powiązanie z innym podmiotem."
    }
  }
]

Pobieranie zmian

Aktualny mechanizm przyrostowego pobierania faktur opiera się na synchronizacji w oknach czasowych z wykorzystaniem daty PermanentStorage oraz mechanizmu stabilnego High Water Mark (HWM). Takie podejście, przy obecnej funkcjonalności, jest wystarczające do wiarygodnego pobierania dokumentów i utrzymania synchronizacji zintegrowanych systemów.

Wraz z wprowadzeniem zdarzeń biznesowych podejście to wymaga rozszerzenia o mechanizm pobierania strumienia zdarzeń biznesowych dla wszystkich faktur widocznych w danym kontekście.

Mechanizm ten byłby oparty na stabilnym strumieniu zdarzeń oraz technicznym identyfikatorze każdego zdarzenia. Identyfikator oparty na monotonicznie rosnącej wartości numerycznej (np. eventId) pozwalałby w prosty i jednoznaczny sposób wyznaczać zakresy przyrostów. W ramach danego kontekstu możliwe byłoby jednoczesne pobieranie zdarzeń dla różnych kategorii podmiotu występujących na fakturze (Subject1, Subject2, Subject3, SubjectAuthorized), zgodnie z warunkami określonymi w zapytaniu.

Aktualny kontrakt pobierania, oparty na datach biznesowych i służący do odczytu bieżących stanów faktur, zostałby utrzymany oraz rozszerzony tak, aby uwzględniał bieżący stan dokumentu wynikający zarówno z danych faktury, jak i z późniejszych zdarzeń biznesowych.

Dodatkowo rozważane jest udostępnienie mechanizmów wspierających podstawową weryfikację kompletności i jakości danych po stronie systemów zintegrowanych.

Rozszerzenie API

Na poziomie koncepcji rozszerzenie API obejmowałoby następujące grupy operacji:

Odczyt

• pobranie lub eksport listy zdarzeń,
• pobranie aktualnego stanu faktury wynikającego ze zdarzeń,
• rozszerzenie obecnych metod pobierania metadanych o dodatkowe zdarzenia biznesowe (aktualny stan faktury).

Zapis

• wykonywanie operacji na fakturach skutkujących utworzeniem nowych zdarzeń biznesowych

Kwestie pozostające do dalszej dyskusji

Na obecnym etapie celem jest potwierdzenie kierunku przedstawionej propozycji, tj. samego podejścia opartego na zdarzeniach biznesowych oraz powiązanego z nim modelu pobierania zmian.

Dopiero w kolejnym kroku zasadne będzie przejście do bardziej szczegółowych rozstrzygnięć technicznych, takich jak:

• dokładny model danych zdarzeń,
• sposób reprezentacji "aktualnego stanu",
• zakres słowników i enumów,
• zasady uprawnień do odczytu i zapisu zdarzeń biznesowych,
• limity zapytań.

[Dzyszla]

Samo raportowanie - zdecydowanie powinno być jako dziennik zmian publikowane. Z możliwością pobierania przyrostowego. Tylko, na litość, niech znacznikiem będzie już zwykły integer, a nie jakieś czasowe! Oczywiście także z możliwością odpytań niezależnych (jak o faktury).

Popieram też, że jednocześnie do zapytań o faktury nalezy dodać pola z aktualnym stanem. Czyli zarówno mogę pytać dziennik o ostatnie zmiany, jak i mogę zapytać konkretną fakturę, co z nią aktualnie jest (bez potrzeby dowiadywania się, kiedy zmiana następowała).

Co do katalogu - to tu chyba powinny nastąpić konsultacje społeczne, a nie tylko deweloperskie.

[kw-cirf]

id zdarzenia:

Identyfikator oparty na monotonicznie rosnącej wartości numerycznej (np. eventId) pozwalałby w prosty i jednoznaczny sposób wyznaczać zakresy przyrostów

aktualny stan:

Aktualny kontrakt pobierania, oparty na datach biznesowych i służący do odczytu bieżących stanów faktur, zostałby utrzymany oraz rozszerzony tak, aby uwzględniał bieżący stan dokumentu wynikający zarówno z danych faktury, jak i z późniejszych zdarzeń biznesowych.

[amynarek]

Tylko, na litość, niech znacznikiem będzie już zwykły integer, a nie jakieś czasowe!

O jaki znacznik chodzi?

[Dzyszla]

@kw-cirf a tak, nie doczytałem (na przykładzie się zatrzymałem). No zdecydowanie to powinno być po id. @amynarek Ten do pobierania przyrostowego tego dziennika, co ma być.

Tak jeszcze co do uwag (wejdę trochę jednak na ten katalog) - dopisywanie IdWew ok, ale bardzo boję się, że po pierwsze te wewnętrzne zaczną jeszcze bardziej wybiórczo widzieć, a poza tym będa pytania, czemu nie ma usuwania/zmieniania. Czasem lepiej nie dawać za dużo, jeśli nie chce się dawać jeszcze więcej. Do rozważenia, czy potrafilibyście też takie wykonać operacje.

[adad-dev]

Nie widzę w założeniach bardzo istotnej dla biur rachunkowych możliwości zadekretowania faktury w firmie (tj. kontekście) - czyli opisania jak dana faktura ma być zaksięgowana. Przed obowiązkowym KSeF klienci biur rachunkowych dostarczali biurom papierowe faktury z opisami czego te faktury dotyczą, jak je należy w związku z tym zaksięgować (np. dotyczące pojazdów, dotyczące zakupów towarów albo środków trwałych albo pozostałych wydatków, itp. itd.). Teraz tego brak; biura rachunkowe i integratorzy wypracowują nowe metody przekazywania tych informacji, ale skoro rozszerzacie tak funkcjonalność KSeF, to obsłużcie i to. Oczywiście może nie wszyscy będą chcieli z tego (i innych zmian, o których w tym wątku mowa) korzystać, bo możliwości inwigilacji obywateli/podatników robią się przy tym coraz bardziej monstrualne. Dlatego wszystko o czym tu mowa chyba powinno być opcjonalne, a jeśli nie, to raczej umocowane w ustawie.

[gps65]

Już teraz w jawnym, niezaszyfrowanym JSON idą metadane faktur, które pozwalają operatorowi bramki WAF, czyli amerykańskiej Impervie, którą posiada francuski koncern Thales, dokładnie zmapować cały polski biznes, co dla ich wywiadów jest bezcenne, pozwala w pełni sterować polskimi firmami, doprowadzając je do bankructwa. To po co dodawać obcym wywiadom więcej informacji, więcej danych o zdarzeniach biznesowych? To już będzie totalna inwigilacja. Po co to?

[amynarek]

@adad-dev

Nie widzę w założeniach bardzo istotnej dla biur rachunkowych możliwości zadekretowania faktury w firmie (tj. kontekście) - czyli opisania jak dana faktura ma być zaksięgowana.

Temu służyć może to:

własne dane w postaci atrybutów, np. w modelu klucz–wartość.

"rodzaj": "koszt"
"kategoria": "paliwo"
"nr_rej": "WN 7123R"

Czyż nie?

[Dzyszla]

No ale to w samej fakturze można spokojnie zawrzeć.
Jeśli już by iść w tym temacie, to wydaje mi się, że pomocne byłyby proste oznaczenie "towarowa/kosztowa". Więcej na poziomie meta nie trzeba.

[jacekkarczmarczyk]

Sprzedawca miałby zapisywać w fakturze informacje jak nabywca ma ją rozliczyć?

[amynarek]

Sprzedawca miałby zapisywać w fakturze informacje jak nabywca ma ją rozliczyć?

No nie, to się dodaje w ramach swojego kontekstu. Nabywca opisuje i jego księgowa, logując się w jego kontekście, to widzi.

[jacekkarczmarczyk]

No ale to sprzedawca tworzy fakturę, której potem nabywca ani nikt inny już nie można już zmienić, chyba, że przez "w fakturze" masz na myśli coś innego niż "w XMLu faktury"

[Dzyszla]

Ogólnie wszyscy mają wielkie narzekanie na to, że nie można na wstępie podzielić faktur towarowych od kosztowych, tylko muszą otwierać XML i oglądać, co w nim jest. Takie szczegóły jak numery rejestracyjne można zawrzeć w XML faktury, bo to nie wpływa na podział odpowiedzialności (magazyn/koszty), ale taki krok wcześniej do podziału to wszyscy mi narzekają. Oczywiście w większości to sam Podmiot1 to dzieli (Orlen = koszt, Żabka = Towar), ale są też kontrahenci, co sprzedają i jedno i drugie.