Czy można zautomatyzować analizę faktur z KSeF

Krótka odpowiedź

Tak. KSeF udostępnia API umożliwiające automatyczne pobieranie faktur. W połączeniu z narzędziami analitycznymi można zbudować w dużym stopniu zautomatyzowany system weryfikacji i analizy faktur.

Co umożliwia automatyzację

API KSeF

Ministerstwo Finansów udostępnia oficjalne API pozwalające m.in. na:

Uwaga: KSeF nie udostępnia mechanizmu typu „webhook” (czyli automatycznego powiadomienia o nowej fakturze w czasie rzeczywistym). W praktyce oznacza to, że system musi cyklicznie odpytywać API o nowe dokumenty.

Standaryzacja danych

Faktury w KSeF mają jednolity format (XML zgodny ze schematem FA(3)):

• Dane są uporządkowane i opisane (zamiast skanów lub PDF)
• Pola mają jednoznaczne znaczenie
• Dokument przechodzi walidację w KSeF przed przyjęciem

Dzięki temu nie ma potrzeby stosowania OCR ani ręcznego przepisywania danych.

Architektura automatycznej analizy

Przepływ danych

┌─────────────────┐     ┌─────────────────┐
│      KSeF       │────▶│   Connector     │
│   (API MF)      │     │   (pobieranie)  │
└─────────────────┘     └────────┬────────┘
│
▼
┌─────────────────┐
│  Parser XML     │
│  (ekstrakcja)   │
└────────┬────────┘
│
▼
┌─────────────────┐
│  Wzbogacanie    │
│  danych         │
└────────┬────────┘
│
▼
┌─────────────────┐
│  Analiza        │
│  ryzyka         │
└────────┬────────┘
│
▼
┌─────────────────┐
│  Wynik          │
│ (raport/alert)  │
└─────────────────┘

Komponenty systemu

1. Connector KSeF (pobieranie danych):

Poniższy kod jest uproszczonym przykładem koncepcyjnym. Nie pokazuje pełnego uwierzytelniania ani wszystkich endpointów z aktualnej dokumentacji API KSeF 2.0.

class KsefConnector:
    def __init__(self, token):
        self.base_url = settings.KSEF_API_BASE_URL
        self.session = self.authenticate(token)

    def get_invoices(self, date_from, date_to):
        endpoint = "/invoices/exports"
        payload = {
            'dateFrom': date_from,
            'dateTo': date_to
        }
        response = self.session.post(endpoint, json=payload)
        return response.json()

    def get_invoice_details(self, reference_number):
        endpoint = f"/invoices/{reference_number}"
        response = self.session.get(endpoint)
        return response.content  # XML

Uwaga: rzeczywiste API KSeF opiera się na bardziej złożonym mechanizmie eksportów i identyfikatorów (np. numer KSeF), dlatego implementacja musi być zgodna z aktualną dokumentacją MF.

2. Parser XML (odczyt danych):

class InvoiceParser:
    def parse(self, xml_content):
        root = ET.fromstring(xml_content)
        ns = {'fa': settings.FA3_NAMESPACE}

        return {
            'nip_seller': root.find('.//fa:Podmiot1//fa:NIP', ns).text,
            'name_seller': root.find('.//fa:Podmiot1//fa:Nazwa', ns).text,
            'nip_buyer': root.find('.//fa:Podmiot2//fa:NIP', ns).text,
            'number': root.find('.//fa:P_2', ns).text,
            'date': root.find('.//fa:P_1', ns).text,
            'amount_gross': Decimal(root.find('.//fa:P_15', ns).text),
        }

3. Wzbogacanie danych:

class DataEnricher:
    def enrich(self, invoice):
        # przykład: sprawdzenie rachunku na białej liście VAT
        result = self.check_whitelist(
            invoice['nip_seller'],
            invoice.get('bank_account')
        )

        invoice['whitelist_valid'] = result.account_in_list
        invoice['vat_status'] = result.vat_status

        return invoice

4. Analiza ryzyka:

class InvoiceAnalyzer:
    def analyze(self, invoice):
        alerts = []
        risk_score = 0

        if not invoice.get('whitelist_valid'):
            alerts.append(('WHITELIST_FAIL', 'wysokie ryzyko'))
            risk_score += 30

        if invoice.get('amount_gross', 0) > 50000:
            alerts.append(('HIGH_AMOUNT', 'średnie ryzyko'))
            risk_score += 15

        return {
            'alerts': alerts,
            'risk_score': risk_score
        }

Poziomy automatyzacji

Poziom 1: Automatyczne pobieranie

Zakres:

• Cykliczne pobieranie faktur z KSeF
• Zapisywanie w systemie (np. baza danych, pliki)
• Powiadomienia o nowych dokumentach

Korzyści:

• Brak ręcznego logowania do KSeF
• Centralne archiwum faktur

Poziom 2: Automatyczna walidacja

Zakres:

• Sprawdzenie rachunku na białej liście VAT
• Proste kontrole matematyczne
• Wykrywanie duplikatów

Korzyści:

• Szybsze wykrywanie błędów
• Ograniczenie ryzyka

Poziom 3: Automatyczna analiza ryzyka

Zakres:

• Ocena wiarygodności faktury
• Analiza historii kontrahenta
• Wykrywanie nietypowych zdarzeń

Korzyści:

• Lepsza kontrola nad płatnościami
• Wczesne wykrywanie potencjalnych oszustw

Poziom 4: Automatyzacja procesu (workflow)

Zakres:

• Automatyczne oznaczanie faktur niskiego ryzyka
• Kierowanie trudniejszych przypadków do weryfikacji
• Integracja z systemami księgowymi i płatnościami

Korzyści:

• Mniej pracy ręcznej
• Lepsza organizacja procesów

Dostępne narzędzia

Rozwiązania gotowe

Jeżeli głównym problemem jest samo wykrywanie nowych dokumentów, zobacz też jak sprawdzić, czy inna firma wystawiła na Ciebie fakturę. Tam opisujemy różnicę między ręcznym sprawdzaniem KSeF a powiadomieniami z własnego monitoringu.

Własne rozwiązanie

Kiedy warto:

• Duża liczba faktur
• Specyficzne potrzeby biznesowe
• Integracja z własnymi systemami

Przykład harmonogramu

Codzienny cykl

06:00 - Pobranie faktur z KSeF (np. z ostatniej doby)
06:05 - Przetworzenie danych
06:10 - Wzbogacenie danych (np. biała lista)
06:15 - Analiza ryzyka
06:20 - Generowanie raportu

W praktyce częstotliwość zależy od potrzeb – może to być kilka razy dziennie lub częściej.

ROI automatyzacji

Przykładowe wyliczenie

Przed automatyzacją:

• 500 faktur/miesiąc
• 5 min na fakturę
• ≈ 42 godziny pracy

Po automatyzacji:

• 80% bez ręcznej weryfikacji
• 20% wymaga sprawdzenia

Efekt: znaczące ograniczenie czasu pracy i kosztów.

Dodatkowe korzyści

• Mniejsze ryzyko oszustwa
• Mniej błędów
• Szybszy obieg dokumentów

FAQ

Czy potrzebuję programisty?

Nie zawsze. Do prostych zastosowań dostępne są gotowe narzędzia. Przy bardziej zaawansowanej automatyzacji – najczęściej tak.

Jak uzyskać dostęp do API KSeF?

Wymagane jest konto w KSeF oraz odpowiednie uwierzytelnienie (np. token, podpis kwalifikowany lub profil zaufany – zgodnie z aktualną dokumentacją MF).

Czy automatyzacja jest bezpieczna?

To zależy od rozwiązania. W praktyce stosuje się m.in.:

• szyfrowanie danych
• kontrolę dostępu
• rejestrowanie operacji (tzw. ślad audytowy)

Od kiedy automatyzacja ma sens?

Zwykle już od kilkudziesięciu faktur miesięcznie, ale istotny jest też poziom ryzyka – nawet jedna błędna, fałszywa albo scamowa faktura może generować duże straty.

Powiązane artykuły

• Jak działa automatyczna analiza faktur – technologia i mechanizmy oceny
• Jak analizować faktury masowo pod kątem ryzyka – analiza wielu faktur jednocześnie
• Czym jest indeks wiarygodności faktury – metodologia oceny i scoring
• KSeF: pobieranie faktur krok po kroku – skąd brać faktury do analizy
• Wizualizacja faktury KSeF — podgląd, PDF i ograniczenia – XML jako źródło, PDF do podglądu

Treść ma charakter informacyjny i edukacyjny. Nie stanowi porady prawnej ani podatkowej.