Wprowadzenie

Moduły KSeF bazują na stałych szablonach – zmiana jednego pola w strukturze MF wymaga aktualizacji kodu. Nasze podejście jest inne. Dostarczamy silnik, który oddziela warstwę komunikacji API od logiki biznesowej ERP. Dla integratora oznacza to koniec walki z kodem w plikach XML wewnątrz Pythona.

Nowa rola integratora

Konfiguruje kanały komunikacji, zarządza certyfikatami i nadzoruje przepływ dokumentów w kolejkach asynchronicznych. Nie musi znać każdego pola faktury FA(3) – skupia się na stabilności połączenia.

Dlaczego ta rola jest kluczowa

To integrator zapewnia, że system 'rozmawia' z bramką Ministerstwa Finansów. Dzięki oddzieleniu kryptografii od runtime’u Odoo, integrator może bezpiecznie zarządzać sesjami interaktywnymi bez ryzyka blokowania procesów biznesowych.

Schemat XSD jako źródło danych

Importer struktury do node’ów a to oznacza:

• brak ręcznego pisania struktury FA(3)

• zgodność z targetNamespace

• minOccurs/maxOccurs odwzorowane w node

• enumeracje, typy proste, complexType

W klasycznym podejściu:

• struktura jest „zahardkodowana”.

Tu:

XSD → model → JSON → XML

To jest system generatywny, nie ręczny.

Provider jest wymienialny

Możesz dodać:

• KSeF

• PEPPOL

• eDoreczenia

• LocalDir

• SFTP

• API bankowe

• dowolny system

Bez zmiany XET.

To daje:

Jeden silnik mapowania → wiele kanałów transportowych.

Obsługa trybu OFFLINE jako overlay

• osobny AbstractModel

• nie modyfikuje core providera

• legal_deadline

• monitor cron

• auto-resend

To jest czysta separacja logiki.

W większości integracji:

• offline jest if/else w kodzie.

Tu:

Offline jest osobną warstwą domenową.

Kontrola procesów przez CRON + DB lock

W providerze KSeF masz:

• _cron_process_ksef_queue

• FOR UPDATE NOWAIT

• hard lock

• limit przetworzeń

• retry logic

To jest architektura odporna na:

• równoległe wykonania

• duplikaty

• race condition

W standardowych modułach często:

• brak transakcyjnego locka.

Co jest realną przewagą nad innymi rozwiązaniami w Odoo?

Cecha	Typowa integracja	XET + Provider
Struktura XML	Zakodowana w Python	Konfigurowalna (node tree)
Zmiana XSD	Zmiana kodu	Reimport schemy
Wiele kanałów	Oddzielne moduły	Jeden silnik + plugin
Workflow	Często uproszczony	Rozdzielony state / status
Offline	IF w kodzie	Overlay model
Wersjonowanie	Brak	UUID + JSON
Migracje	Trudne	JSON 2.0 eksport/import
Skalowalność	Ograniczona	Architektura rozszerzalna

Architektura oparta na elastyczności

Zamiast 'hardkodować' pola faktury, stworzyliśmy system warstwowy. Każdy element – od generowania XML, przez walidację, aż po wysyłkę – jest wymienny i konfigurowalny."

XET

eXtensible Exchange Template (XET) to serce systemu. 

XET to format szablonu (JSON), który mapuje pola z obiektów Odoo (np. account.move) na konkretne węzły XML wymagane przez MF.

• Zaleta: Gdy Ministerstwo Finansów zmienia strukturę XSD, nie zmieniasz kodu modułu. Importujesz nowy szablon XET i gotowe."

• Zaleta: stwórz szablon obsługi dokumentów, i wymianiej go z innymi. Wgraj do innego Odoo - zwyczajnie przenieś.

• Zaleta: wersjonuj, wspópracuj z inymi integratorami przy jego powstawaniu. 

Warstwa komunikacji

Obsługuje sesje interaktywne KSeF, proces podpisywania dokumentów i autoryzację. Całość działa w tle (asynchronicznie), więc wysyłka 1000 faktur nie zawiesza pracy księgowości.

Oddzielna warstwa komunikacji zapewnia możliwość pracy zespołów handlowych, w tym samym czasie wystawiających zamówienia i faktury.

Dlaczego to jest przewaga w długim terminie?

1. Zmiana schemy MF → reimport XSD

2. Nowy kanał (np. e-Doręczenia) → nowy provider

3. Inny kraj → nowy XET template

4. Nowy dokument → bez zmiany core

Architektura nie jest jednorazowa - jest systemowa.

Co jest ważne technicznie

Sesja interaktywna

Moduł realizuje komunikację z bramką MF w oparciu o model sesji interaktywnej. Oznacza to, że system nawiązuje stabilne połączenie, w ramach którego może przesyłać wiele dokumentów, monitorować ich stan i odbierać potwierdzenia w sposób ciągły. Integrator nie musi martwić się o ręczne zarządzanie tokenami sesyjnymi dla każdego zapytania – silnik robi to automatycznie.

Zarządzanie stanem i UPO

Dzięki sesji interaktywnej, proces pobierania Urzędowego Poświadczenia Odbioru (UPO) jest zintegrowany z cyklem życia dokumentu w Odoo. System 'pilnuje' otwartej sesji do momentu uzyskania finalnego statusu z KSeF.

Harmonogram

Podpisywanie dokumentów i nawiązywanie sesji odbywa się z wykorzystaniem bezpiecznych metod autoryzacji. Cała warstwa 'ciężkiej' kryptografii jest odseparowana od logiki biznesowej Odoo, co zapewnia wysoką wydajność (nie blokuje procesora serwera podczas wysyłki).

Instalacja

4. Skonfiguruj providery i szablony z poziomu interfejsu.

Dokumentacja i dalsze kroki

- integrację z KSeF.