Instrukcja Modułu KSeF2 dla Odoo 18
Wersja: 18.4.29
Autor: Marius Johannes Kuc (aktualizacja FA(3):)
Licencja: OPLv1
Nowości:
- 18.4.29: POLE "ZAMAWIAJĄCY" -> SEKCJA "POZOSTAŁE INFORMACJE NA FAKTURZE" Nowe pole "Zamawiający (KSeF)" (ksef_zamawiajacy) na fakturze/korekcie
sprzedazy. Trafia do sekcji Fa/DodatkowyOpis schematu FA(3) jako para
Klucz="Zamawiajacy" / Wartosc=. W Aplikacji Podatnika MF
ta sekcja nazywa sie "Pozostale informacje na fakturze".
- Element fakultatywny: puste pole = nic nie wysylamy. Wartosc przycinana
do 256 znakow (TZnakowy). Emitowany w prawidlowym miejscu sekwencji Fa
wg XSD: po RodzajFaktury/bloku korekty, PRZED FaWiersz (schemat: po TP,
przed FakturaZaliczkowa). Wpiecie w zlym miejscu = blad 445.
- Nie jest drukowane na PDF - dane wylacznie dla KSeF (osobne od pola
"Warunki i postanowienia" drukowanego na wydruku).
- Zgloszenie klienta: potrzeba wskazania na e-fakturze osoby/dzialu, ktory
zamowil towar lub usluge.
- 18.4.28: rebrand domeny dokumentacyjnej z odoo.com.pl/ksef na perp.pl/apps/ksef. Bez zmian funkcjonalnych.
- 18.4.27: uzupełnienie changelogu i porządki dokumentacyjne.
- 18.4.26: hotfix KursWaluty (miejsce w XML).
- 18.4.25: faktury walutowe – KursWaluty + P_14_XW (VAT w PLN).
- 18.4.24: mapowanie P_13 zgodne z aktualnym schematem FA(3) + status zapłaty.
- 18.4.23: Korekty zmniejszające – ujemne wartości w P_8B/P_11/P_13/P_14/P_15.
- Numery seryjne i partii w FA(3): Automatyczne pobieranie numerów seryjnych/partii z ruchów magazynowych i umieszczanie ich w sekcji WarunkiTransakcji (NrPartiiTowaru) wysyłanej faktury XML.
- Kod wewnętrzny produktu (Indeks): Pole default_code z karty produktu jest teraz emitowane jako Indeks w każdym wierszu faktury FA(3), max 50 znaków.
- Kod kreskowy GTIN: Pole barcode z karty produktu jest emitowane jako GTIN (Globalny Numer Jednostki Handlowej) w wierszu FA(3), max 20 znaków.
- Nowość: Menu pomocy na formularzu faktury z instrukcjami wysyłki, ręcznego wprowadzania i obsługi korekt.
- Nowa funkcja: Drukowanie UPO w formacie PDF bezpośrednio z formularza faktury.
- Ręczne wprowadzanie numerów KSeF: Pola Status, Numer KSeF i Nr sesji KSeF są edytowalne do momentu pobrania UPO — umożliwia zaksięgowanie faktur wystawionych bezpośrednio w portalu KSeF.
- Konfigurowalna stopka SystemInfo: Pole w ustawieniach firmy pozwala ustawić nazwę systemu widoczną w wizualizacji faktury w KSeF.
- Stawka 0% KR / WDT / EX: Pełne rozdzielenie stawek zerowych zgodnie z enumeracją TStawkaPodatku w schemacie FA(3).
- Fix stawek np I / np II: Poprawione wartości P_12 dla usług poza terytorium kraju — poprzednio KSeF błędnie interpretował "np" jako "zw".
- Dodanie korekt KSeF:PEŁNE WSPARCIE KOREKT W SCHEMACIE FA(3).
- Kompletna przebudowa autoryzacji: Pełen cykl (challenge → ksef-token → redeem) oraz automatyczne odświeżanie tokenów.
- Inteligentne adnotacje podatkowe: Automatyczne wykrywanie Odwrotnego Obciążenia, Metody Kasowej i Mechanizmu Podzielonej Płatności (MPP obsługiwany przez moduł:l10n_pl_mpp).
- Bezpieczeństwo: Hashowanie SHA256 do weryfikacji integralności pliku oraz pełne szyfrowanie (AES-256-CBC + RSA-OAEP).
- Oczyszczony interfejs (UX): Usunięto zbędne przyciski np. Sprawdź status, wdrożono polskie etykiety, czytelne komunikaty błędów oraz wskaźniki statusu KSeF.
- Terminy i płatności: Rozszerzona obsługa terminów płatności i numerów kont bankowych zgodnie ze strukturą FA(3).
- AKTUALIZACJA KSEF: W tej wersji wprowadziliśmy potężne narzędzia, które automatycznie spawdzają dostęp do aktualizacji.
- Wbudowane Kody QR na wydrukach: Każda faktura pomyślnie przetworzona przez KSeF automatycznie generuje ministerialny kod QR. Kod ten jest natychmiastowo i trwale integrowany z wydrukiem PDF Twojego dokumentu w Odoo. To prawdziwy "game-changer" dla Twoich klientów! Wdrożyliśmy mechanizm anonimowego dostępu powiązany z kodem QR. Oznacza to, że Twój kontrahent może zeskanować kod z faktury (lub kliknąć w wygenerowany link) i natychmiast zweryfikować oraz pobrać oryginalną wizualizację dokumentu bezpośrednio z bramki Ministerstwa Finansów. Koniec z wymuszaniem na klientach logowania się do rządowych portali, zakładania kont czy posiadania tokenów – dostęp do dokumentu jest w 100% płynny i bezproblemowy.
- POZOSTAŁE ZMIANY: Optymalizacja zapytań API: Zmniejszono narzut sieciowy podczas sprawdzania statusów UPO.
- Ciekawostki: Zwiększona tolerancja na przerwy techniczne po stronie środowiska produkcyjnego MF.
🆕 Nowości w wersji 18.4.22:
- KRYTYCZNY FIX — CenaJedn (P_9A): Naprawiono wysyłanie brutto zamiast netto w polu CenaJedn dla pozycji z podatkami w trybie „Cena zawiera podatek" (price_include=True). Dotknięte były tylko faktury wystawiane przy cennikach brutto; sumy netto/VAT/brutto były poprawne, błąd widoczny wyłącznie w wizualizacji po stronie KSeF.
- Pełny audit price_include w pre-flight: Logowanie w INFO wszystkich linii z podatkami w trybie „Cena zawiera podatek" wraz z porównaniem ceny brutto/netto — ułatwia wykrycie niezamierzonej konfiguracji podatków.
Faktury wysłane przed 18.4.22 z podatkiem price_include=True mają w KSeF zawyżone CenaJedn o kwotę VAT (dokumenty w KSeF są niezmienialne po UPO). Szczegóły naprawy historycznych faktur — w changelogu modułu.
Spis Treści
1. Wprowadzenie
Moduł KSeF2 Integration umożliwia pełną integrację systemu Odoo 18 z Krajowym Systemem e-Faktur (KSeF). Pozwala na automatyzację procesów związanych z fakturami ustrukturyzowanymi.
Kluczowe funkcjonalności:
Wysyłanie faktur zgodnie ze schematem FA(3).
Automatyczne pobieranie numerów KSeF i statusów.
Zamykanie sesji oraz pobieranie Urzędowego Poświadczenia Odbioru (UPO).
2. Wymagania systemowe
| Komponent | Wymaganie |
| Odoo | Wersja 18.0 lub nowsza |
| Python | 3.10+ |
| Biblioteki | account (Księgowość), requests |
Wymagania KSeF: Aktywne konto na portalu podatnika, Token dostępowy (JWT), poprawny NIP firmy w Odoo.
3. Instalacja modułu
- Przygotowanie plików:
Rozpakuj archiwum i skopiuj folder do katalogu addons:cp -r ksef_2_patched /opt/odoo/addons/
- Aktualizacja listy aplikacji:
Włącz Tryb deweloperski, przejdź do menu Aplikacje i kliknij Aktualizuj listę aplikacji. - Instalacja:
Wyszukaj "KSeF", znajdź KSeF2 Integration i kliknij Instaluj.
4. Konfiguracja KSeF
4.1 Ustawienia firmy
Przejdź do Ustawienia -> Firmy -> [Twoja Firma] -> Zakładka KSeF.
| Pole | Opis | Wymagane |
| KSeF Environment | Środowisko API (Test/Demo/Produkcja) | Tak |
| KSeF Context Identifier | NIP firmy | Tak |
| KSeF Access Token | Token JWT wygenerowany w portalu | Tak |
UWAGA: Zacznij od środowiska Test (TE) aby zweryfikować poprawność danych przed wysyłką na produkcję.
5. Obsługa faktur
Aby wysłać fakturę, musi być ona w stanie Zaksięgowana.
Proces wysyłki:
- Otwórz fakturę sprzedaży.
- Kliknij przycisk Send to KSeF.
- System wygeneruje XML FA(3) i prześle go do bramki MF.
- Po otrzymaniu statusu accepted, faktura otrzyma oficjalny numer KSeF.
6. Struktura FA(3) - Informacje techniczne
Namespace: http://crd.gov.pl/wzor/2025/06/25/13775/
Przykładowy szkielet XML:
<?xml version="1.0" encoding="UTF-8"?>
<Faktura xmlns="http://crd.gov.pl/wzor/2025/06/25/13775/">
<Naglowek>...</Naglowek>
<Podmiot1>...</Podmiot1> <!-- Sprzedawca -->
<Podmiot2>...</Podmiot2> <!-- Nabywca -->
<Fa>
<KodWaluty>PLN</KodWaluty>
<P_1>2026-01-26</P_1>
<Adnotacje>...</Adnotacje>
</Fa>
</Faktura>Mapowanie Pól:
| Element | Opis | Źródło Odoo |
| P_1 | Data wystawienia | invoice_date |
| P_2 | Numer faktury | name |
| P_13_1 | Podstawa Netto 23% | tax_totals (base) |
7. Rozwiązywanie problemów
Błąd 401: Unauthorized
Token wygasł lub jest nieprawidłowy. Wygeneruj nowy token na portalu KSeF.
Błąd 400: Bad Request
XML nie jest zgodny ze schematem. Sprawdź czy NIP firmy i kontrahenta są uzupełnione oraz czy stawki VAT są przypisane do pozycji.
8. FAQ
Pytanie: Czy moduł obsługuje faktury zakupowe?
Odpowiedź: Nie, ten moduł służy do wysyłki (sprzedaży). Do faktur przychodzących wymagany jest moduł ksef_incoming.
Pytanie: Czy moduł waliduje XML przed wysłaniem?
Odpowiedź: Moduł generuje strukturę zgodną z FA(3), ale pełna walidacja biznesowa odbywa się po stronie serwerów Ministerstwa Finansów.
Dokumentacja przygotowana przez odoo.com.pl
Data aktualizacji: 2026-01-05
