Odoo Engineers – Support & Development

Gregory Rutecki

CEO & CTO @ Cosmonauts.dev

Zespół Odoo Support: przejmujemy utrzymanie Odoo i budujemy moduły pod biznes. Wsparcie, rozwój i integracje – Cosmonauts.dev.

E-mail: help@cosmonauts.dev

Odwiedź cosmonauts.dev

Polish Invoicing + KSeF 2.0 (Polska)

Moduł Polish Invoicing + KSeF 2.0 łączy Odoo 19 z polskim fakturowaniem i Krajowym Systemem e-Faktur (KSeF). Składa się z dwóch części: Polish Invoicing (polskie fakturowanie w Odoo) oraz KSeF 2.0 (wysyłka i odbiór e-faktur przez API). Autor: Cosmonauts.dev Sp. z o.o.

Co dodaje Polish Invoicing (polskie fakturowanie)

Część Polish Invoicing rozszerza Odoo o wymagania polskiego prawa podatkowego i księgowego:

• Data sprzedaży (P_6) – pole na fakturze, wydruku i w eksporcie (wymaga modułu l10n_pl Poland - Accounting)
• Typ faktury wg słownika KSeF: VAT, ZAL, ROZ, KOR, KOR_ZAL, KOR_ROZ – ustalany z linii lub ręcznie
• Dziennik ZAL/ROZ – osobny dziennik „KSeF Faktury zaliczkowe i rozliczeniowe” (KSEFZAL) z własną numeracją
• GTU (Grupy Towarów i Usług) na produktach
• Zwolnienia z VAT (P_19A) – podstawy prawne, stawki „zw” i „np”
• MPP (mechanizm podzielonej płatności) – adnotacja na wydruku faktury
• Forma płatności (gotówka, przelew, karta, inne)
• Nabywcy: polski NIP, NrVatUE (UE), BrakID (osoby fizyczne / spoza UE)
• Odwrotne obciążenie, samofakturowanie, metoda kasowa, procedury marży
• Waluty obce – kurs z tabeli Odoo (KursWalutyZ)
• Wydruk faktury – dostosowany do polskich wymagań (data sprzedaży, MPP itd.)

Co dodaje KSeF 2.0 (integracja z e-fakturami)

Część KSeF 2.0 zapewnia integrację z Krajowym Systemem e-Faktur (API v2, schemat FA(3)):

• Wysyłanie faktur – faktury sprzedaży i korekty do KSeF (środowisko Test / Demo / Produkcja)
• Uwierzytelnianie – token systemowy z portalu KSeF (NIP + token), pobieranie tokenów dostępu/odświeżania
• Automatyczna wysyłka – opcjonalna wysyłka do KSeF po zatwierdzeniu faktury (od razu lub z opóźnieniem)
• Status KSeF – sprawdzanie statusu, numer faktury KSeF, UPO (Urzędowe Potwierdzenie Odbioru), zamykanie sesji
• Odbiór faktur kosztowych – pobieranie z KSeF faktur przychodzących (jako nabywca)
• Faktury zakupowe z KSeF – tworzenie w Odoo faktur zakupowych i rachunków korygujących na podstawie odebranych e-faktur
• Konfiguracja na firmie – zakładki KSeF 2.0 (wysyłanie) oraz KSeF 2.0 Odbieranie Faktur (harmonogram, synchronizacja)

Spis treści

1. Opis funkcjonalności (Polish Invoicing / KSeF 2.0)
2. W skrócie
3. Dziennik ZAL/ROZ i odinstalowanie
4. Wysyłanie faktur do KSeF
5. Odbieranie faktur kosztowych z KSeF
6. Wymagania
7. Obsługiwane scenariusze
8. Bezpieczeństwo
9. Znane ograniczenia
10. Licencja i autor

2. W skrócie

• Wygeneruj token w portalu KSeF i wklej go w Odoo (Ustawienia → Firmy → KSeF 2.0).
• Kliknij „Pobierz tokeny KSeF” – połączenie z API będzie gotowe.
• Wysyłaj faktury ręcznie (przycisk na fakturze) albo włącz wysyłkę automatyczną.
• Odebrane faktury kosztowe: Fakturowanie → KSeF 2.0 → Odebrane faktury KSeF; z nich możesz tworzyć faktury zakupowe.

3. Dziennik ZAL/ROZ i odinstalowanie

Moduł dodaje dziennik „KSeF Faktury zaliczkowe i rozliczeniowe” (kod KSEFZAL). Przy księgowaniu faktury zaliczkowe (ZAL) i rozliczeniowe (ROZ) są przenoszone do tego dziennika, żeby numeracja nie mieszała się ze zwykłymi FV. Firma musi mieć co najmniej jeden dziennik sprzedaży – inaczej przy pierwszej ZAL/ROZ moduł wyświetli błąd z prośbą o utworzenie dziennika.

Po odinstalowaniu modułu dziennik „KSeF Faktury zaliczkowe i rozliczeniowe” oraz faktury w nim zapisane zostają w bazie – Odoo nie usuwa dzienników ani dokumentów. Możesz je dalej przeglądać i księgować; ewentualne usunięcie dziennika trzeba wykonać ręcznie w Konfiguracji.

4. Wysyłanie faktur do KSeF

Krok 1: Token w portalu KSeF

Wejdź na portal KSeF (Ministerstwo Finansów), przejdź do Tokeny → Generuj token. Wybierz środowisko (Test / Demo / Produkcja) i wygeneruj token. Skopiuj go w całości – wkleisz go w Odoo.

Krok 2: Konfiguracja w Odoo

Otwórz Ustawienia → Firmy → [Twoja firma], zakładka KSeF 2.0. Uzupełnij:

Kliknij Pobierz tokeny KSeF. Gdy zobaczysz „Status połączenia z API”, połączenie działa. Opcjonalnie włącz Automatyczną wysyłkę potwierdzonych faktur i ustaw opóźnienie (od razu, 2 min, 15 min, 2 h).

Krok 3: Jak wysyłać faktury

Opcja A – automatycznie. Włącz w firmie „Automatyczna wysyłka potwierdzonych faktur do KSeF” i wybierz „Kiedy wysłać?”. Po potwierdzeniu faktury moduł wyśle ją do KSeF sam (od razu lub z opóźnieniem). Nie musisz nic klikać na każdej fakturze.

Opcja B – ręcznie. Na każdej fakturze (Fakturowanie → Faktury) otwórz zakładkę KSeF 2.0 i kliknij Wyślij do KSeF. Potem możesz: Sprawdź status KSeF, Zamknij sesję KSeF, w „Szczegóły sesji KSeF 2.0” – Pobierz UPO (Urzędowe Potwierdzenie Odbioru).

Typ faktury (zaliczkowa, końcowa itd.) ustawia się sam; jeśli trzeba, możesz go zmienić w polu „Typ faktury KSeF” na fakturze.

Lista faktur

Na liście faktur (Fakturowanie → Faktury) możesz dodać kolumnę Status KSeF i filtrować po statusie (np. tylko zaakceptowane lub niewysłane).

5. Odbieranie faktur kosztowych z KSeF

Moduł pobiera z KSeF faktury skierowane do Twojej firmy (jako nabywca). Możesz je przeglądać, odświeżać listę i na ich podstawie tworzyć w Odoo faktury zakupowe lub rachunki korygujące.

Czy odbiór jest automatyczny? Tak, jeśli włączysz obie opcje w Ustawienia → Firmy → [Twoja firma] → KSeF 2.0 Odbieranie Faktur: Odbieraj faktury przychodzące z KSeF oraz Pobieraj nowe faktury w tle (harmonogram). Zadanie cron sprawdza co minutę; faktyczne pobieranie następuje co N minut (domyślnie 15). Interwał możesz zmienić w Ustawienia → Techniczne → Parametry → Parametry systemowe (klucz: cosmonautsdev_pl_invoicing_ksef_2_0.incoming_fetch_interval_minutes). Możesz też synchronizować ręcznie przyciskiem na liście.

1. Przeglądanie listy

Wejdź w Fakturowanie → KSeF 2.0 → Odebrane faktury KSeF. Zobaczysz listę faktur odebranych z KSeF (numer KSeF, kontrahent, daty, status). Kliknij wiersz, aby zobaczyć szczegóły.

2. Synchronizacja

Aby pobrać nowe faktury lub zaktualizować dane, użyj przycisku Synchronizuj odebrane faktury KSeF. Moduł zapyta KSeF i zaktualizuje listę.

3. Faktura kosztowa z KSeF (ZAL, ROZ, KOR)

Otwórz wybraną odebraną fakturę i kliknij Utwórz fakturę kosztową (lub Zaksięguj jako fakturę zakupową). Moduł odczytuje z KSeF typ faktury: VAT (zwykła), ZAL (zaliczkowa), ROZ (rozliczeniowa), KOR (korekta). Dla zwykłej, zaliczkowej i rozliczeniowej powstaje w Odoo faktura zakupowa (in_invoice); dla korekty (KOR) – rachunek korygujący (in_refund). Kontrahent, pozycje i kwoty są uzupełniane z XML – dokument gotowy do księgowania.

6. Wymagania

Odoo 19.0. Moduły: web, account, sale, l10n_pl (Poland - Accounting). Python: cryptography. W Dockerze – jedna linia w Dockerfile (patrz wyżej).

7. Obsługiwane scenariusze

• Faktury krajowe ze stawkami VAT: 23%, 8%, 5%, 0% krajowe, 0% WDT
• Stawka zw (zwolniony z VAT, art. 43) i np (nie podlega VAT)
• Korekty (KOR, KOR_ZAL, KOR_ROZ) z danymi faktury korygowanej i numerem KSeF
• Faktury zaliczkowe (ZAL) i rozliczeniowe (ROZ) z osobnym dziennikiem i numeracją
• Mechanizm podzielonej płatności (MPP / split payment) z adnotacją na wydruku
• Odwrotne obciążenie (reverse charge), samofakturowanie, metoda kasowa, procedury marży
• Nabywcy: polski NIP, NrVatUE (firmy z UE), BrakID (osoby fizyczne / spoza UE)
• Waluta obca z kursem waluty (KursWalutyZ z tabeli kursów Odoo)
• Forma płatności (gotówka, przelew, karta, inne)
• Data sprzedaży (P_6) na fakturze, wydruku i w XML do KSeF
• Odbiór faktur kosztowych z KSeF i tworzenie faktur zakupowych

8. Bezpieczeństwo

Tokeny KSeF (systemowy, dostępu, odświeżania) są przechowywane w bazie danych PostgreSQL. Zabezpiecz dostęp do bazy danych (silne hasło, ograniczony dostęp sieciowy, szyfrowane backupy). Tokeny wyświetlane są w UI jako „********...” i nie są widoczne w formularzach. Edycja ustawień KSeF wymaga uprawnień Administracja + Księgowość.

9. Znane ograniczenia

• Faktury RR (rolnik ryczałtowy) – nieobsługiwane
• Nowe środki transportu WDT (P_22) – nieobsługiwane
• OSS/IOSS (One Stop Shop) – nieobsługiwane
• Procedura uproszczona tranzyt (P_23) – pole na fakturze, ale bez automatycznej detekcji
• Kurs waluty pobierany z tabeli Odoo (res.currency.rate), nie bezpośrednio z API NBP

10. Licencja i autor

Licencja: Other proprietary. Autor: Cosmonauts.dev Sp. z o.o. – https://cosmonauts.dev. Szczegóły w pliku LICENSE.