Instrukcja Modułu KSeF2 dla Odoo 18
Wersja: 18.2.0
Autor: Marius Johannes Kuc (aktualizacja FA(3):)
Licencja: OPLv1
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
