BazaPrawa.
Checklista kontroli podatkowej: 20 logów z KSeF, o które urząd zapyta najpierw
zespół BazaPrawa | 18 marca 2025
1. Dlaczego logi KSeF są kluczowe w kontroli?
Od wejścia KSeF 2.0 faktura ustrukturyzowana żyje w systemie: każdy status, korekta i odrzucenie pozostawia cyfrowy ślad. Organy podatkowe zaczynają kontrole właśnie od logów, bo:
- pozwalają natychmiast zidentyfikować luki między rejestrami a plikami JPK,
- dają niezaprzeczalny timestamp nadania UPO (Urzędowe Potwierdzenie Odbioru),
- wskazują, czy podatnik terminowo wysyłał korekty i czy nie manipulował podpisem.
2. Top-20 logów, o które urząd poprosi w pierwszym dniu
| # | Nazwa logu (pole w API) | Gdzie pobrać (endpoint) | Dlaczego ważny? |
|---|---|---|---|
| 1 | InvoiceHeader→KodKrajuNadania | GET /invoice/uuid | weryfikacja zgodności kraju wysyłki z VAT ID |
| 2 | InvoiceIdentifier→KSeFReferenceNumber | GET /invoice/uuid | unikalny identyfikator faktury – podstawa krzyżowego sprawdzenia |
| 3 | ProcessingStatus | GET /status/uuid | czy faktura została przyjęta, odrzucona czy w kolejce |
| 4 | TimestampSigned | GET /invoice/uuid/signature | dowód terminu wystawienia-podpisu |
| 5 | TimestampReceived | GET /status/uuid | data rejestracji w KSeF – klucz dla terminu odliczenia VAT |
| 6 | CorrectionChain | GET /corrections/uuid | pełna historia korekt FA(2)/FA(3) |
| 7 | EventLog – InvoiceSent | GET /events?type=sent | lista faktycznie wysłanych dokumentów (vs. planowane) |
| 8 | EventLog – InvoiceRejected | GET /events?type=rejected | wskaźnik błędów schemy i niezgodności NIP |
| 9 | EventLog – InvoiceCancelled | GET /events?type=cancelled | dowód prawidłowego anulowania błędnych faktur |
| 10 | BuyerConsentReceipt | GET /consents?buyerNip=… | pokazuje, od kiedy nabywca akceptuje faktury w KSeF |
| 11 | SellerGrantAuthority | GET /authorisations?nip=… | lista pełnomocnictw UPL-1/ tokenów API |
| 12 | SignatureHash | GET / | |
| 14 | CurrencyCode | GET /invoice/uuid | audyt różnic kursowych i zgodności z JPK_FA |
| 15 | InvoiceTotalGross | GET /invoice/uuid | szybka kontrola sumy brutto vs. JPK_VAT |
| 16 | TaxPointDate (DataSprzedazy) | GET /invoice/uuid | właściwy moment powstania obowiązku podatkowego |
| 17 | PaymentDueDate | GET /invoice/uuid | kontrola ulgi bad debt – 90 dni od terminu |
| 18 | SplitPaymentFlag | GET /invoice/uuid | weryfikacja obowiązkowej MPP |
| 19 | GTU Codes List | GET /invoice/uuid | czy prawidłowo kwalifikowano transakcje wyższego ryzyka |
| 20 | CustomTags (UserData) | GET /invoice/uuid/custom | Twoje dodatkowe pola – urząd je widzi! |
Tip: Eksportuj logi w formacie JSON lub CSV; XML zostaw auditors, bo żądają struktury maszynowej do analizy big-data.
3. Jak wyeksportować logi w 15 minut?
- Zaloguj się na konto techniczne w środowisku produkcyjnym KSeF.
- Użyj tokenu JWT z minimalnym zakresem
ksef:invoice:read. - Skrypt
GET /events?from=2024-01-01→ zapis doevents.json. - Skrypt
GET /invoice/{uuid}?include=header,summarypo UUID z events.json. - Konwersja do CSV (np.
jq -r), podziel plik na mniejsze bloki do 25 MB. - Spakuj ZIP i przygotuj opis struktury (plik README).
UWAGA: urząd może żądać dostępu "online" poprzez zdalną sesję – miej konto testowe gotowe do demonstracji.
4. Checklista przed wejściem audytora
- Zapewniony pełny export Top-20 logów w max. 24 h.
- Procedura integracyjna opisująca, kto generuje token API i jak długo jest ważny.
- Mapa pól KSeF → JPK (cross-reference) z datą ostatniej aktualizacji.
- Polityka archiwizacji: minimum 10 lat przechowywania logów zgodnie z rozporządzeniem MF.
- Instrukcja korekty – kiedy i kto wysyła FA(2)/ FA(3) oraz notę korygującą.
- Pełnomocnictwa UPL-1 oraz wewnętrzne uprawnienia RBAC.
- Raport integralności (hash SHA-256) wygenerowany w ostatnim kwartale.
5. FAQ
| Pytanie | Krótka odpowiedź |
|---|---|
| Czy urząd może żądać logów sprzed uruchomienia KSeF 2.0? | Tak, ale tylko w zakresie, w jakim faktury były dobrowolnie w KSeF. |
| Jak długo trzeba przechowywać SignatureHash? | Minimum 5 lat (Ordynacja), zalecane 10 lat ze względu na dyrektywę DAC7. |
| Czy można redagować dane w BuyerConsentReceipt? | Nie – log jest zapisywany w KSeF raz, bez możliwości edycji. |
| Co jeśli nie mam SplitPaymentFlag, a dotyczy to towarów w załączniku 15? | Fiskus uzna to za błąd ewidencji i może nałożyć 100 % sankcję VAT. |
6. Podsumowanie
Kontrola 2025+ zaczyna się od logów KSeF – to najprostsza droga dla fiskusa, by wychwycić braki, opóźnienia i nieprawidłowe GTU. Przygotuj eksport top-20, utwórz procedurę ich udostępniania i regularnie testuj integralność. Pół dnia pracy przed audytorem może oszczędzić tygodniowy maraton uzupełnień i ryzyko podwójnego podatku.
Źródła
- Ministerstwo Finansów – "Dokumentacja interfejsu KSeF API 2.4"
- MF, "KSeF FAQ – Kontrola podatkowa" (maj 2025)
- EY Flash Alert 04/2025 "KSeF: audyt logów kluczem do kontroli"
- Deloitte Polska, "KSeF readiness survey 2025"
- PwC Tax Blog "Jak uchronić się przed sankcjami 100 % VAT za brak MPP w KSeF"