Integracja KSeF

KSeF (Krajowy System e-Faktur) to obecnie dominujący obszar zmian w EVAN. Integracja jest dwukierunkowa i w pełni asynchroniczna:

• Wysyłka faktur sprzedażowych → KSeF (wsadowo BATCH lub pojedynczo ONLINE).
• Pobieranie faktur zakupowych ← KSeF (asynchronicznie: Init → Status → Fetch).
• Weryfikacja statusu wysłanych dokumentów (UPO).
• Koszyk do ręcznego rozliczania pobranych faktur i dopasowania do zleceń.
• Korekty — zarówno przychodzące, jak i wysyłane.

Pakiety

Funkcje kryptograficzne (RSA/AES, częściowo w Javie): f_ksef_rsa_base64, f_java_ksef_encrypt, f_java_ksef_decrypt, f_ksef_ECQSS_decrypt_encrypt i pochodne.

Kluczowe tabele

Sesje i autoryzacja

• KSEF_SESJA, KSEF_SESJA_JWT — sesje (token, numer referencyjny, klucz AES, wektor inicjujący).
• KSEF_AUTH_TOKEN, KSEF_AUTH_TOKEN_JWT — tokeny dostępu/odświeżania.
• KSEF_AUTH_CERT, KSEF_PUBLIC_CERT, KSEF_ECQSS — certyfikaty i dane podpisu.

Wysyłka

• KSEF_SEND_BATCH_PROC / _DET / _CNF / _SUBPROC — proces wsadowy, dokumenty, konfiguracja, wielowątkowość.
• KSEF_SEND_ONLINE_PROC / _Q / _DET — wysyłka online i jej kolejka.
• FAKTURA_KSEF_SEND, FAKTURA_TRA_KSEF_SEND — status wysyłki (hash, numer KSeF, kod przetwarzania, QR, metoda).
• FAKTURA_KSEF_XML_ERR, FAKTURA_TRA_KSEF_XML_ERR, *_OSTRZEZENIA — błędy i ostrzeżenia XML.

Pobieranie i koszyk

• KSEF_INV_FETCH_PROC / _DET / _CNF — proces pobierania.
• KSEF_XML_FILE — surowe XML pobrane z KSeF (xml_data jako XMLType, subject_type, hash, środowisko).
• KSEF_KOSZYK, KSEF_KOSZYK_DOPASOWANIE — koszyk faktur i ich powiązanie ze zleceniami/sekcjami.
• FAKTURA_KSEF, FAKTURA_SPEC_KSEF — nagłówek i pozycje faktury przychodzącej.

Słowniki

S_KSEF_STATUS, S_KSEF_WERYFIKACJA, S_KSEF_REZUTLAT_WERYFIKACJI, S_KSEF_TYP_DOKUMENTU, S_KSEF_STAWKA_VAT, KSEF_STAWKA_VAT_MAPOWANIE, S_KSEF_FORMA_PLATNOSCI.

Przepływ: wysyłka faktury sprzedażowej (BATCH)

Sterowana przez KSEF_SEND_BATCH_PKG; dokumenty wybiera widok KSEF_SEND_V (UNION FAKTURA_TRA + FAKTURA).

1. p_create_proc → utworzenie procesu w KSEF_SEND_BATCH_PROC.
2. p_add_data → zebranie dokumentów do KSEF_SEND_BATCH_DET.
3. blokada edycji dokumentów (KSEF_STATUS := 'WAITING').
4. p_check_data → weryfikacja XML względem schematu XSD.
5. utworzenie archiwum ZIP → podział na paczki + szyfrowanie AES-256.
6. p_init_batch → autentykacja (KSEF_AUTH_PKG) i api/batch/Init → numer referencyjny.
7. p_upload_batch → api/batch/Upload (paczki), p_close_batch → api/batch/Finish.
8. odpytywanie statusu (common/Status, session/Status) → VERIFY_STATUS = UPO lub REJECTED.
9. zapis numeru KSeF i statusu na fakturze + metadanych w FAKTURA_TRA_KSEF_SEND.

Alternatywa: online — KSEF_SEND_ONLINE_PKG → api/online/Invoice/Send (bez archiwum/szyfrowania).

Przepływ: pobieranie faktury zakupowej (ASYNC)

Sterowane przez KSEF_INV_FETCH_BATCH_PKG:

1. utworzenie procesu (KSEF_INV_FETCH_PROC).
2. przygotowanie kontekstu kryptograficznego (certyfikaty publiczne wg subject_type).
3. online/Query/Invoice/Async/Init (z dateFrom/dateTo) → numer referencyjny elementu.
4. online/Query/Invoice/Async/Status/{ref} → OK / WAIT / ERROR.
5. online/Query/Invoice/Async/Fetch/... → zapis ZIP do KSEF_XML_FILE.
6. deszyfrowanie (AES + IV z KSEF_SESJA) i ekstrakcja XML z ZIP.
7. parsowanie do KSEF_KOSZYK (KSEF_KOSZYK_PKG.p_parse_xml_file).

Korekty

• Zakupowa (z KSeF): KSEF_KOSZYK z typem korekty; f_check_corrected_invoice_status ustala, czy faktura korygowana istnieje w EVAN (0 = brak / 1 = w koszyku / 2 = w EVAN); powiązanie przez KSEF_KOSZYK_DOPASOWANIE i POWIAZANY_DOKUMENT_ID. Gałąź korekta_zakupowa_KSEF dodaje m.in. obsługę braku numeru konta na fakturze korygowanej.
• Sprzedażowa (wysyłka): FAKTURA_TRA z typem KORE, licznik korekt, powiązanie z dokumentem bazowym; dalej jak zwykła faktura sprzedażowa.

Pojęcia domenowe

Powiązane widoki

KSEF_SEND_V (dokumenty do wysłania), KSEF_XML_FILE_*_V (parsing XML: nagłówki, pozycje, konta, terminy), KSEF_KOSZYK_SEKCJA_V / KSEF_KOSZYK_NIEDOPASOWANY_V (dopasowanie), KSEF_VAN_ZLECENIE_*_V / KSEF_VAN_AMOUNTS_*_V (powiązanie ze zleceniami i kwotami).