KSeF 2.0 – narzędzia integracyjne

Zestaw skryptów Python umożliwiających konfigurację, autoryzację i komunikację z systemem Krajowego Systemu e-Faktur (KSeF) w wersji 2.0.

Struktura projektu

Pliki konfiguracyjne:

• ksef.ini – konfiguracja wielu firm oraz osób upoważnionych do ich obsługi.
• ksefconfig.py – moduł wczytujący konfigurację z ksef.ini, importowany przez pozostałe skrypty.

Skrypty inicjalizacyjne i konfiguracyjne

t-00-setup.py

• Pobiera dane w ksef.ini (NIP/PESEL).
• Pobiera certyfikaty KSeF dla środowisk: demo, test, prod.
• Zapisuje certyfikaty w plikach odpowiednich dla wybranej wersji.

t-01-cert-make.py <indeks_firmy>

• Generuje certyfikat self-signed z wymaganymi przez KSeF polami dla firmy oraz osoby o podanym numerze firmy.
• Zapisuje certyfikat w formacie wymaganym do dalszych operacji.
• Przykład: t-01-cert-make.py 1

Zarządzanie danymi testowymi

Firmy:

• t-02-test-data-firma-01-create.py <indeks> – rejestruje firmę w KSeF.
• t-02-test-data-firma-02-remove.py <indeks> – usuwa firmę w KSeF.
• t-02-test-data-firma-03-perm-01-grant.py <indeks> – nadaje osobie uprawnienia do obsługi firmy.
• t-02-test-data-firma-03-perm-02-query.py – lista udzielonych uprawnień.

Osoby:

• t-02-test-data-osoba-01-create.py <indeks_firmy> – dodaje osobę do firmy.
• t-02-test-data-osoba-01-remove.py <indeks_firmy> – usuwa osobę z firmy.

Proces autoryzacji

Aby uzyskać tokeny dostępu do KSeF, wykonaj sekwencyjnie:

t-03-auth-01-challenge.py <indeks> <typ>
t-03-auth-02-sign.py <indeks> <typ>
t-03-auth-03-xades.py <indeks> <typ>
t-03-auth-04-reference.py <indeks> <typ>
t-03-auth-05-redeem.py <indeks> <typ>

Przykład

    t-03-auth-01-challenge.py 1 f
    t-03-auth-02-sign.py 1 f
    t-03-auth-03-xades.py 1 f
    t-03-auth-04-reference.py 1 f
    t-03-auth-05-redeem.py 1 f

Odświeżanie tokena autoryzacyjnego

    t-03-auth-06-refresh.py <indeks> <typ>

Przykład:

t-03-auth-06-refresh.py 1 f

Alternatywna autoryzacja tokenem (ważna do końca 2026):

t-api-auth-token.py <indeks> <typ>
t-03-auth-07-token.py <indeks>

Parametry autoryzacji:
f – uprawnienia w imieniu firmy (np. 1 f).
o – uprawnienia w imieniu osoby (np. 1 o).

Operacje na fakturach (po autoryzacji)

Generowanie faktur testowych:

Przykład – generuje 5 faktur od firmy 1 dla firmy 2:

fv.py 1 2 5

Pobranie listy otwartych sesji:

t-10-session-01-list.py 1 f

lista faktur wystawionych w ciągu ostatnich 30 dni:

t-50-get-fa-list.py 1 f

pobranie faktury po numerze KSeF:

t-50-get-fa-get.py 1 f numer_ksef 

pobranie paczki faktur z ostatnich 30 dni jako archiwum ZIP.

t-50-get-fa-package.py 1 f

Sesja online

t-10-session-online.py 1 f [opcje]

Przykład - otwarcie sesji dla firmy 1:

t-10-session-online.py 1 f -o

Opcje:
-o – otwarcie sesji (tworzy plik {cfg.prefix}-session.json).

-c – zamknięcie sesji (usuwa plik sesji).

-s <faktura.xml> – wysłanie pojedynczej faktury.

-t – sprawdzenie statusu wysłanych faktur.

-u <faktura.xml> – pobranie UPO dla faktury (wymaga pliku <faktura.xml>.ref).

Uwaga: Skrypt można wywoływać wielokrotnie z opcjami -s, -t, -u. W przypadku wygaśnięcia tokena (401 Unauthorized) należy go odnowić (t-03-auth-06-refresh.py ).

Sesja wsadowa (batch)

t-10-session-batch.py 1 f [opcje]

Przykład - przygotowanie faktur do wsyłki:

t-10-session-batch.py 1 f -z

Opcje:
-z – przygotowanie danych:
pakuje pliki firmy do archiwum ZIP, dzieli archiwum na części i szyfruje je, usuwa pliki źródłowe i archiwum.

-o – otwarcie sesji wsadowej.

-s – wysyłanie zaszyfrowanych części do KSeF (części z statusem 201 są usuwane lokalnie).

-c – zakończenie sesji wsadowej.

-t – pobranie statusu sesji.

Uwaga: Przy statusie 401 (token nieważny) należy go odnowić (t-03-auth-06-refresh.py ). Opcję -t można wykonywać wielokrotnie aż do uzyskania końcowego statusu sesji (200). Każdy krok aktualizuje plik {cfg.prefix}-session.json.

Uwagi techniczne

1. Wymagane jest środowisko Python z zainstalowanymi bibliotekami.
   Jak stworzyć venv i zainstalować biblioteki (Należy wykonać po kolei w terminalu będąc w głównym katalogu repo):
   Linux:

   python3 -m venv venv
   source ./venv/bin/activate
   pip install -r ./requirements.txt

   Windows:

   python -m venv venv
   .\venv\Scripts\activate
   pip install -r .\requirements.txt

   Uwaga: Może zdarzzyć się, że należy zamienić python3 na python albo na odwrót

2. Przed pierwszym użyciem należy skonfigurować ksef.ini i wykonać t-00-setup.py.

3. Wszystkie operacje wymagają ważnego tokena autoryzacyjnego.

4. Środowisko pracy (demo/test/prod) jest określane przez konfigurację w ksef.ini.