Audyt techniczny — jawność metadanych faktur KSeF w JSON na bramce WAF obsługiwanej przez Impervę

1. Pytanie audytowe

Czy przez publiczną bramkę API/WAF systemu KSeF — którą, zgodnie z wcześniej wskazanym audytem infrastrukturalnym, obsługuje Imperva — przepływają w postaci jawnej metadane faktur w formacie JSON, obejmujące numery NIP i nazwy kontrahentów, kwoty netto, VAT i brutto, walutę, numer i typ faktury oraz daty operacyjne, i czy mechanizm ten dotyczy kompletnego zbioru faktur obsługiwanych przez system? Audyt https://www.mpolska24.pl/post/21091/audyt-infrastruktury-sieciowej-bramka-waf-systemu-ksef-20 wykazał dla api.ksef.mf.gov.pl delegację CNAME do impervadns.net, fingerprinty X-CDN: Imperva i trasę do adresów Imperva/Incapsula, co technicznie uzasadnia traktowanie tej warstwy jako publicznej bramki edge/WAF Impervy.

2. Krok 1 — Czy oficjalne API KSeF ma endpoint do pobierania metadanych faktur

2.1 Komenda

2.2 Wynik

W oficjalnej specyfikacji OpenAPI KSeF pojawia się ścieżka: /invoices/query/metadata oraz inne ścieżki z grupy /invoices/..., co potwierdza, że jest to część oficjalnego API pobierania faktur. Endpoint /invoices/query/metadata jest wprost opisany jako „Pobranie listy metadanych faktur”. 

2.3 Interpretacja

To rozstrzyga pierwszy element tezy. Metadane faktur nie są tu hipotezą ani rekonstrukcją pośrednią. One istnieją wprost w oficjalnej specyfikacji KSeF jako osobny zasób API. Skoro zasób ten jest wystawiony pod publicznym hostem API KSeF, to z definicji przechodzi przez tę samą warstwę edge/WAF, którą wcześniejszy audyt przypisał Impervie.

3. Krok 2 — Czy metadane są zwracane w JSON

3.1 Komenda

3.2 Wynik

Definicja endpointu pokazuje odpowiedź 200 z typem treści application/json oraz schematem QueryInvoicesMetadataResponse. W przykładzie odpowiedzi znajduje się tablica invoices.

3.3 Interpretacja

To usuwa wszelką mgłę pojęciową. Tu nie chodzi o XML faktury, lecz o jawny, oficjalny, kontraktowy JSON API. Skoro odpowiedź jest application/json, to po terminacji TLS na warstwie WAF te dane występują w postaci czytelnej warstwy aplikacyjnej HTTP/JSON. A skoro warstwa ta jest — według audytu infrastrukturalnego — obsługiwana przez Impervę, to JSON jest dla niej technicznie widoczny.

4. Krok 3 — Jaki jest zakres pól w metadanych

4.1 Komenda

4.2 Wynik

Schemat InvoiceMetadata zawiera jako pola wymagane m.in. invoiceNumber, issueDate, invoicingDate, acquisitionDate, permanentStorageDate, seller, buyer, netAmount, grossAmount, vatAmount, currency, invoiceType, ksefNumber. W obiekcie seller wymagany jest nip. 

Przykład odpowiedzi dla POST /invoices/query/metadata pokazuje rekord z polami:

4.3 Interpretacja

To rozstrzyga drugi element tezy. Zakres metadanych nie jest domniemany. Jest literalnie zapisany w kontrakcie API i w przykładzie odpowiedzi. W szczególności obejmuje on: numery NIP, pełne nazwy kontrahentów, kwoty netto, VAT i brutto, walutę, numer faktury, typ faktury oraz daty operacyjne.

Inaczej mówiąc: jeżeli ktoś twierdzi, że przez bramkę WAF lecą tylko „niewinne techniczne znaczniki”, to dokumentacja KSeF temu przeczy. Lecą dane biznesowe o bardzo wysokiej rozdzielczości.

5. Krok 4 — Czy to dotyczy tylko pojedynczych lookupów, czy ogólnego przeglądania zbioru faktur

5.1 Komenda

5.2 Wynik

Schemat InvoiceQueryFilters wymaga jedynie dwóch pól: subjectType i dateRange. Pozostałe filtry, takie jak ksefNumber, invoiceNumber, amount, sellerNip, buyerIdentifier, currencyCodes, invoiceTypes, są opcjonalne. Opis subjectType wskazuje role: Subject1 — sprzedawca, Subject2 — nabywca, Subject3, SubjectAuthorized. Opis dateRange mówi wprost, że według tego zakresu filtrowane są faktury.

Definicja samego endpointu mówi dodatkowo o limicie 10 000 rekordów na zestaw filtrów, paginacji przez pageOffset, pageSize, oraz o scenariuszu przyrostowym opartym o hasMore i isTruncated.

5.3 Interpretacja

To nie jest lookup po jednym numerze KSeF. To jest ogólny mechanizm przeglądania i pobierania metadanych faktur według zakresu czasu i roli podmiotu. Gdyby system był zbudowany inaczej, wymagane byłyby zwykle konkretne identyfikatory dokumentu. Tymczasem tutaj wystarczy rola podmiotu i przedział czasu. To oznacza, że API jest zaprojektowane do masowego, systemowego pobierania metadanych całych zbiorów faktur, nie tylko jednostkowych rekordów.

6. Krok 5 — Czy dokumentacja mówi o kompletności i braku pominięć

6.1 Komenda

6.2 Wynik

Dokument „Przyrostowe pobieranie faktur” stwierdza, że przylegające okna czasowe z HWM zapewniają ciągłość i „eliminują ryzyko pominięcia jakiejkolwiek faktury”, a iteracja przez typy podmiotów „zapewnia kompletność danych”.

Ten sam dokument opisuje POST /invoices/exports jako mechanizm eksportu paczek faktur oraz wskazuje, że po rozpakowaniu archiwum pobierany jest plik JSON z metadanymi, deserializowany do InvoicePackageMetadata, którego rekordy są dodawane do listy metadanych.

W dokumentacji zapisano też, że paczka eksportu zawiera plik _metadata.json, a każdy jego element jest obiektem typu InvoiceMetadata, takim jak zwracany przez endpoint POST /invoices/query/metadata.

6.3 Interpretacja

To domyka słowo „każdej” w sensie technicznym. Dokumentacja nie opisuje luźnego przykładu czy pomocniczej listy. Opisuje oficjalny mechanizm synchronizacji, którego celem jest kompletne pobieranie faktur bez pominięć, przy użyciu metadanych InvoiceMetadata w JSON. Zatem te metadane nie dotyczą marginalnych wyjątków. Dotyczą kompletnego procesu obsługi faktur w KSeF.

7. Odpowiedź

Tak. W oparciu o audyt infrastrukturalny https://www.mpolska24.pl/post/21091/audyt-infrastruktury-sieciowej-bramka-waf-systemu-ksef-20  oraz oficjalną dokumentację OpenAPI i dokumentację przyrostowego pobierania faktur można technicznie stwierdzić, że:

przez publiczną bramkę API/WAF systemu KSeF obsługiwaną przez Impervę przepływają jawne metadane faktur w formacie JSON, obejmujące NIP-y i nazwy kontrahentów, kwoty netto, VAT i brutto, walutę, numer i typ faktury oraz daty operacyjne.

W świetle dokumentacji przyrostowego pobierania można też uznać, że mechanizm ten dotyczy kompletnego zbioru faktur obsługiwanych przez system, ponieważ dokumentacja mówi o eliminacji ryzyka pominięcia jakiejkolwiek faktury i o zapewnieniu kompletności danych.

8. Interpretacja całości

Mechanizm jest prosty.

Najpierw klient komunikuje się z publicznym hostem API KSeF. Ten host, według audytu infrastrukturalnego, jest wystawiony przez warstwę edge/WAF Impervy. Następnie oficjalne API KSeF udostępnia endpoint POST /invoices/query/metadata, który zwraca listę metadanych faktur jako application/json. Schemat tych metadanych obejmuje dane identyfikacyjne i ekonomiczne kontrahentów oraz pełny zestaw podstawowych parametrów faktury. Dokumentacja mechanizmu przyrostowego pobierania opisuje ten proces jako kompletny i niepomijający faktur.

Wniosek jest brutalnie prosty: na warstwie WAF Impervy obecny jest nie tylko ruch „techniczny”, ale jawny strumień biznesowych metadanych faktur KSeF w JSON.

Wykonanie audytu: Grzegorz GPS Świderski. Sformatowanie tekstu: ChatGPT 5.4 Thinking