| Availability |
Odoo Online
Odoo.sh
On Premise
|
| Odoo Apps Dependencies |
•
Invoicing (account)
• Discuss (mail) |
| Lines of code | 1736 |
| Technical Name |
ksef_2_FA3 |
| License | OPL-1 |
| Website | https://www.perp.pl/apps/ksef |
| Versions | 18.0 |
Integracja z KSeF 2.0 v18.4.28
Kompletna integracja Odoo dla wysyłania e-Faktur do Krajowego Systemu e-Faktur zgodna ze schematem FA(3).
Nazwa techniczna modułu: ksef_2_FA3
🆕 Nowości w wersji 18.4.28:
- 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
CenaJedndla 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. Wymagania
- Odoo 18 z aplikacją Fakturowanie
- Python cryptography - zainstaluj w środowisku hosta/Dockera:
pip install cryptography - Token systemowy KSeF - uzyskany z platformy ap.ksef.mf.gov.pl
- NIP firmy zarejestrowany w Krajowym Systemie e-Faktur
2. Konfiguracja firmy
Ścieżka: Ustawienia → Firmy → [Twoja firma] → zakładka KSeF
Pola konfiguracyjne
| Pole | Opis | Przykład |
|---|---|---|
| Środowisko KSeF | Wybór środowiska do którego wysyłane są dane API | Testowe / Demo / Produkcyjne |
| NIP firmy (dla KSeF) | 10 cyfr bez kresek i spacji (podmiot wysyłający) | 1234567890 |
| Token systemowy KSeF | Główny token z platformy KSeF do uwierzytelnienia | eyJhbGciOiJSUzI1NiIs... |
Jak uzyskać token systemowy?
- Zaloguj się na Platformie KSeF
- Przejdź do: Ustawienia → Zarządzanie tokenami
- Kliknij "Generuj nowy token"
- Wybierz typ: Token autoryzacyjny
- Skopiuj wygenerowany token i wklej w ustawieniach firmy w Odoo.
3. Test połączenia z KSeF
Status połączenia
| Status | Znaczenie |
|---|---|
| Nie testowano | Połączenie dla danej firmy nie było jeszcze sprawdzane |
| Połączono | Autoryzacja w API udana, aktywne tokeny sesyjne zostały zapisane |
| Błąd połączenia | Problem z połączeniem, zweryfikuj komunikat wyświetlany obok wskaźnika |
Co robi przycisk "Połącz z KSeF"?
Wysyła żądanie
Wysyła żądanie
challenge do API KSeF, paruje je z wygenerowanym przez Ministerstwo kluczem RSA, następnie bezinwazyjnie wymienia Twój token systemowy na roboczy token dostępu (JWT). System Odoo zarządza tymi tokenami i odświeża je w tle.
4. Wysyłka faktur i pobieranie UPO
Akcje powiązane z wysyłką do KSeF są dostępne bezpośrednio z poziomu formularza faktury (po jej zatwierdzeniu).
Przyciski operacyjne
| Przycisk | Funkcja | Kiedy używać |
|---|---|---|
| Wyślij do KSeF | Generuje XML FA(3), otwiera szyfrowaną sesję i przekazuje paczkę do MF. | Gdy faktura jest zatwierdzona (status KSeF: Wersja robocza). |
| Zamknij sesję | Zamyka aktywną sesję online dla przetworzonych dokumentów. | Gdy wysłano wszystkie niezbędne faktury w danej iteracji. |
| Pobierz UPO | Pobiera, dekoduje i załącza do Odoo Urzędowe Poświadczenie Odbioru. | Kiedy MF przetworzy fakturę i nada jej poprawny Numer KSeF (wymaga zamkniętej sesji). |
5. Obsługa adnotacji podatkowych (Automatyzacja)
Wersja 18.4.6 wprowadza asystenta mapowania podatków, który w locie analizuje dokument przed wygenerowaniem XML:
- Mechanizm Podzielonej Płatności (MPP) / Samofakturowanie: System dynamicznie weryfikuje istnienie dedykowanych pól konfiguracyjnych (np. pochodzących z rozszerzenia MPP Odoo Pro EXTREME) i flaguje dokument w schemacie XML.
- Odwrotne Obciążenie: Moduł sam analizuje stawki VAT na liniach faktury. Jeśli napotka w nazwie stawki lub grupie podatkowej słowa kluczowe (np. "odwrotne", "reverse charge"), odpowiedni znacznik `P_18` zostanie dodany do pliku FA(3).
- Metoda Kasowa: Synchronizuje się automatycznie z głównymi ustawieniami księgowymi firmy w Odoo.
6. Struktura API KSeF 2.0 (Dla zaawansowanych)
Schemat faktur: FA(3)
Namespace:
Adresy API używane w module są automatycznie dopasowywane na podstawie wyboru środowiska.
Namespace:
http://crd.gov.pl/wzor/2025/06/25/13775/Adresy API używane w module są automatycznie dopasowywane na podstawie wyboru środowiska.
1. POST /auth/challenge
2. POST /auth/ksef-token (Z wykorzystaniem RSA-OAEP publicznego klucza MF)
3. POST /auth/token/redeem
4. POST /sessions/online (AES-256)
5. POST /sessions/online/{ref}/invoices (Hashowane SHA-256, szyfrowane AES-CBC)
6. POST /sessions/online/{ref}/close
7. GET /sessions/{ref}/upo/{upoRef}
7. Rozwiązywanie problemów
Błąd: Brak tokenu dostępu KSeF
Przejdź do ustawień firmy i kliknij przycisk "Połącz z KSeF", aby wymusić pobranie pierwszego tokenu sesyjnego.
Przejdź do ustawień firmy i kliknij przycisk "Połącz z KSeF", aby wymusić pobranie pierwszego tokenu sesyjnego.
401 Unauthorized / 403 Forbidden
Token wygasł lub NIP w systemie nie zgadza się z NIP-em konta, na którym wygenerowano token platformy. Upewnij się, że użyto poprawnego klucza. Odoo automatycznie dba o odświeżenie tokena, chyba że stary został zablokowany przez MF.
Token wygasł lub NIP w systemie nie zgadza się z NIP-em konta, na którym wygenerowano token platformy. Upewnij się, że użyto poprawnego klucza. Odoo automatycznie dba o odświeżenie tokena, chyba że stary został zablokowany przez MF.
Błąd szyfrowania ("No module named cryptography")
Biblioteka kryptograficzna nie jest dostępna w Twoim kontenerze Dockera lub środowisku wirtualnym. Użyj polecenia:
Biblioteka kryptograficzna nie jest dostępna w Twoim kontenerze Dockera lub środowisku wirtualnym. Użyj polecenia:
pip install cryptography
Ostrzeżenie (Środowisko Testowe)
Pamiętaj, że bramka
Pamiętaj, że bramka
api-test.ksef.mf.gov.pl może w godzinach wieczornych odrzucać żądania z powodu prac serwisowych Ministerstwa. Faktury wysyłane tam NIE MAJĄ skutku prawnego.
Odoo Proprietary License v1.0 This software and associated files (the "Software") may only be used (executed, modified, executed after modifications) if you have purchased a valid license from the authors, typically via Odoo Apps, or if you have received a written agreement from the authors of the Software (see the COPYRIGHT file). You may develop Odoo modules that use the Software as a library (typically by depending on it, importing it and using its resources), but without copying any source code or material from the Software. You may distribute those modules under the license of your choice, provided that this license is compatible with the terms of the Odoo Proprietary License (For example: LGPL, MIT, or proprietary licenses similar to this one). It is forbidden to publish, distribute, sublicense, or sell copies of the Software or modified copies of the Software. The above copyright notice and this permission notice must be included in all copies or substantial portions of the Software. THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
Please log in to comment on this module