Pierwsze kroki
Ta strona opisuje wszystko, co potrzebujesz przed wysłaniem pierwszej faktury do KSeF - wymagania wstępne Dolibarr, konfiguracja portalu KSeF, instalacja modułu i pełna instrukcja konfiguracji.
Na tej stronie
Zanim zaczniesz
Instalacja Dolibarr
Jeśli nie masz jeszcze działającego Dolibarr, musisz go najpierw zainstalować. Nie będziemy tutaj opisywać pełnej instalacji i podstawowej konfiguracji, bo jest to dobrze udokumentowane gdzie indziej. Oto kilka przydatnych punktów startowych:
Oficjalna strona Dolibarr
Wiki Dolibarr: Instalacja i aktualizacja
TechRepublic: Jak zainstalować Dolibarr na Ubuntu Server
Film od Wasz Informatyk
Oficjalne filmy instruktażowe Dolibarr
Moduł testowaliśmy na Dolibarr v22.0.3 i v23.0.1 i będziemy go utrzymywać tak długo, jak istnieje nasza firma, ponieważ sami go używamy. W przypadku gdybyśmy zakończyli działalność, kod jest open-source, więc inni mogą go sforkować i kontynuować rozwój.
Wymagany jest PHP 7.4 lub nowszy z rozszerzeniami OpenSSL, cURL, DOM, mbstring, JSON i Zip. Większość standardowych instalacji PHP już je zawiera.
Włącz wymagane moduły Dolibarr
Przed instalacją modułu KSeF upewnij się, że następujące moduły Dolibarr są włączone (Strona główna -> Ustawienia -> Moduły/Aplikacje):
Fakturowanie - oczywiście wymagane
Kody kreskowe - potrzebne do generowania kodów QR na PDF-ach
Wielowalutowość - wymagane do obsługi faktur w walutach obcych (EUR/USD/itp.) i kursów NBP.
Skonfiguruj swoją firmę
Przejdź do Strona główna -> Ustawienia -> Firma/Organizacja i wypełnij:
Nazwa firmy i adres - pojawiają się na fakturach wysyłanych do KSeF
Kraj - musi być ustawiony na Polskę (w przeciwnym razie po co Ci KSeF?)
NIP - wpisz go w pole Professional ID 1 (moduł zmieni jego etykietę na NIP po zastosowaniu nadpisań tłumaczeń, więcej o tym poniżej)
Numer VAT - jeśli posiadasz numer VAT UE, przechowywany w polu VAT
KRS/REGON/BDO - opcjonalne, ale warto wypełnić; wpisuje się je odpowiednio w pola Professional ID 2, 3 i 4.
Jeśli chcesz zmienić przypisanie danych do pól (np. przechowywać NIP w Professional ID 3), moduł umożliwia ich przemapowanie (zobacz Konfiguracja zaawansowana poniżej).
Skonfiguruj kontrahentów
Każdy klient i dostawca w Dolibarr powinien mieć:
Prawidłowo ustawiony kraj - moduł wykorzystuje kraj kontrahenta do określenia sposobu identyfikacji nabywcy w XML KSeF. Polscy nabywcy są identyfikowani po NIP, nabywcy z UE po numerze VAT UE, a nabywcy spoza UE po zagranicznym numerze podatkowym. Zawsze ustawiaj kraj!
NIP lub numer VAT - polscy klienci potrzebują wypełnionego NIP-u, a klienci z UE numeru VAT
Adres - warto podać dane adresowe na potrzeby fakturowania
Jeśli migrujesz z innego systemu ERP i masz wielu kontrahentów bez ustawionych krajów, moduł postara się odgadnąć prawidłową wartość, ale warto uporządkować dane, żeby zmniejszyć ryzyko potencjalnych problemów.
Portal KSeF i dane uwierzytelniające
Środowiska
KSeF posiada trzy oddzielne środowiska, każde z własnym portalem i danymi uwierzytelniającymi:
Test - do nauki systemu - używasz fikcyjnych danych firmy, logujesz się bez specjalnych poświadczeń i wysyłasz fikcyjne faktury. Faktury nie mają znaczenia prawnego
Demo - do testów z prawdziwymi danymi firmy i prawdziwymi poświadczeniami, ale faktury nadal nie mają znaczenia prawnego
Produkcja - prawdziwe faktury ze znaczeniem prawnym. Wysłanych faktur nie można cofnąć - w przypadku błędu konieczne jest wystawienie korekty.
Ważne: Każde środowisko ma oddzielne dane uwierzytelniające. Token lub certyfikat wygenerowany w portalu Demo nie zadziała w Produkcji i odwrotnie. Gdy będziesz gotowy do pracy na żywo, będziesz potrzebować nowych poświadczeń z portalu Produkcyjnego.
Uwierzytelnianie: tokeny i certyfikaty
Masz dwie opcje uwierzytelniania w KSeF:
Tokeny są prostsze w konfiguracji - zaloguj się do portalu KSeF pieczęcią kwalifikowaną lub podpisem, wygeneruj token autoryzacyjny i wklej go w ustawieniach modułu. Ważność tokenów jest obecnie ustawiona do końca 2026 roku, ale może zostać przedłużona w miarę dojrzewania systemu.
Certyfikaty - są dwa rodzaje: certyfikaty online i offline. Certyfikat offline jest niezbędny do wystawiania faktur offline podczas awarii KSeF, a certyfikat online może zastąpić uwierzytelnianie tokenem.
Na początek token to najszybsza droga. Możesz przejść na certyfikaty w późniejszym czasie. Ponadto tokeny mają konfigurowalne uprawnienia i mogą być bezpieczniejsze, jeśli nie masz pełnej kontroli nad instalacją.
Pozyskiwanie poświadczeń
1. Przejdź do portalu KSeF dla wybranego środowiska
Test: https://ap-test.ksef.mf.gov.pl/web/
Demo: https://ap-demo.ksef.mf.gov.pl/web/
Produkcja: https://ap.ksef.mf.gov.pl/web/
2. Zaloguj się jedną z dostępnych metod uwierzytelniania
3. Wygeneruj token autoryzacyjny (dla uwierzytelniania tokenem) lub certyfikat (dla uwierzytelniania certyfikatem).
Uprawnienia - najczęstszy problem
Po wygenerowaniu tokena lub zarejestrowaniu certyfikatu musisz również skonfigurować uprawnienia (Uprawnienia) w portalu KSeF. To najczęstsza przyczyna błędów uwierzytelniania i zaskakuje niemal każdego przy pierwszym użyciu systemu KSeF.
Jeśli prowadzisz osobę prawną, np. sp. z o.o., musisz również upewnić się, że złożyłeś odpowiedni formularz ZAW-FA do Urzędu Skarbowego, aby nadać początkowe uprawnienia osobie działającej w imieniu firmy. W przeciwnym razie nie będziesz mógł się zalogować i nadawać uprawnień.
Przejdź do sekcji "Uprawnienia" w aplikacji KSeF i upewnij się, że nadałeś wystarczające uprawnienia do wysyłania i pobierania faktur. Jeśli otrzymujesz błędy HTTP 403 przy wysyłaniu faktur i zweryfikowałeś, że używasz właściwych poświadczeń dla danego środowiska, to najprawdopodobniej właśnie ten problem z uprawnieniami!
Instalacja modułu KSeF dla Dolibarr
1. Pobierz najnowszy plik ZIP modułu ze strony wydań na GitHub
2. W Dolibarr przejdź do Strona główna -> Ustawienia -> Moduły/Aplikacje
3. Wybierz zakładkę "Wdróż/Zainstaluj moduł zewnętrzny"
4. Prześlij plik ZIP modułu
5. Wyskakujące okno potwierdzi sukces, a moduł KSeF pojawi się na liście modułów
6. Włącz go i możesz rozpocząć konfigurację
Po włączeniu modułu zobaczysz zakładkę KSeF na fakturach oraz nowe wpisy w menu dla faktur przychodzących i statusu wysyłek.
Zweryfikuj konfigurację: Zakładka "O module" zawiera wbudowany moduł sprawdzania wymagań systemowych, który pokazuje zielony/czerwony status dla każdej zależności. Jeśli cokolwiek jest na czerwono, zajmij się tym przed dalszymi krokami!
Po aktualizacji: Przy aktualizacji do nowej wersji dobrą praktyką jest wyłączenie i ponowne włączenie modułu, aby niektóre zmiany mogły zostać zastosowane. Pozwala to na prawidłowe wykonanie migracji bazy danych, które mogą być wymagane w przyszłych aktualizacjach. Twoja konfiguracja (tokeny, certyfikaty, ustawienia) jest domyślnie zachowywana podczas tego procesu. Jest też opcja czyszczenia wszystkiego przy wyłączeniu, jeśli chcesz zacząć od nowa, ale domyślnie jest wyłączona. Zobacz Automatyzacja i dodatkowe funkcje, aby dowiedzieć się więcej o procedurze aktualizacji.
Uprawnienia użytkowników
Moduł rejestruje dwa uprawnienia, które możesz przypisywać przez system uprawnień Dolibarr (Strona główna -> Ustawienia -> Użytkownicy i grupy)
Odczyt zgłoszeń KSeF - podgląd zakładki KSeF na fakturach, listy faktur przychodzących i stron statusu
Tworzenie/aktualizacja zgłoszeń KSeF - wysyłanie faktur do KSeF, synchronizacja faktur przychodzących i import
Konfiguracja modułu (ustawienia/tokeny/certyfikaty) jest zawsze ograniczona do użytkowników z uprawnieniami administratora. Jeśli masz wielu użytkowników, przypisz uprawnienia KSeF po włączeniu modułu, ponieważ nowe uprawnienia nie są automatycznie nadawane istniejącym użytkownikom.
Konfiguracja modułu
Przejdź do Strona główna -> Ustawienia -> Moduły -> KSeF i kliknij ikonę koła zębatego obok modułu. Strona ustawień zawiera kilka sekcji, które omówimy po kolei. Mniej popularne opcje są opisane w sekcji Konfiguracja zaawansowana.
Konfiguracja podstawowa
NIP firmy - automatycznie pobierany z ustawień firmy. Domyślnie czyta z pola Professional ID 1, które jest standardowym miejscem na NIP w instalacjach Dolibarr. Jeśli Twoja konfiguracja przechowuje NIP w innym polu, jest lista rozwijana do zmiany źródła (zobacz Konfiguracja zaawansowana)
Numer VAT UE - zawsze pobierany z pola VAT (tva_intra w Dolibarr) i nie można go zmienić
KRS/REGON/BDO - opcjonalne, uwzględniane w XML faktury wychodzącej, jeśli te pola są wypełnione. Każde z nich ma konfigurowane pole źródłowe, tak samo jak NIP firmy.
Środowisko - wybierz Test, Demo lub Produkcję. Przy wyborze Produkcji pojawia się ostrzeżenie przypominające, że wysłane faktury mają moc prawną.
Metoda uwierzytelniania
Wybierz między uwierzytelnianiem tokenem a certyfikatem. Aktywna metoda jest podświetlona. Jeśli nie skonfigurowałeś jeszcze certyfikatu, ta opcja jest wyłączona z informacją, co jest potrzebne.
Konfiguracja tokena - wklej swój token autoryzacyjny z portalu KSeF. Token jest przechowywany bezpiecznie i po zapisaniu wyświetla się jako "Token skonfigurowany" - nie można go ponownie podejrzeć.
Konfiguracja certyfikatu - prześlij certyfikat (plik .crt) i klucz prywatny (plik .key), podaj hasło, a następnie kliknij zapisz. Rób to krok po kroku. W przypadku problemu wyjaśnienie pojawi się w oknie dialogowym. Możliwe jest też przypadkowe przesłanie certyfikatu offline zamiast online i odwrotnie, więc jeśli dostęp do KSeF zwraca błąd o nieprawidłowym typie certyfikatu, to prawdopodobnie właśnie to się stało.
Automatyczny wybór - jeśli skonfigurowałeś tylko jedną metodę uwierzytelniania, moduł użyje jej automatycznie. Ręczny wybór jest potrzebny tylko wtedy, gdy obie metody są skonfigurowane.
Ustawienia interfejsu
Dodaj kod QR do PDF - po włączeniu zaakceptowane faktury otrzymują kod QR weryfikacyjny na standardowych PDF-ach Dolibarr. Wymaga modułu Kody kreskowe.
Kolor przycisków - pozwala zmienić kolor przycisków akcji na stronach faktur - domyślnie czerwony.
Usuń dane konfiguracyjne przy wyłączeniu modułu - po włączeniu prawie wszystkie ustawienia są usuwane przy wyłączaniu modułu. Domyślnie wyłączone.
Opcjonalne pola FA(3)
Te opcje kontrolują opcjonalne dane uwzględniane w XML faktury KSeF. Włączaj je w zależności od tego, jakie dane faktycznie masz w Dolibarr. Włączenie GTIN, gdy Twoje kody kreskowe nie są poprawnymi kodami GTIN/EAN, spowoduje błędy walidacji.
Kod klienta (NrKlienta) - uwzględnia kod klienta z Dolibarr
Kod produktu (Indeks) - uwzględnia referencję produktu w pozycjach faktury
Kod kreskowy GTIN/EAN - uwzględnia kody kreskowe produktów jako GTIN. Włączaj tylko jeśli Twoje kody to prawdziwe kody GTIN/EAN, a nie kody wewnętrzne
Jednostka miary - uwzględnia jednostkę miary produktów
Niektóre pola bankowe są uwzględniane automatycznie, bez przełącznika. Jeśli Twoje konto bankowe w Dolibarr ma wypełniony kod SWIFT/BIC lub nazwę banku, te dane zawsze trafiają do XML faktury obok numeru konta. Dodatkowe opcjonalne pola (opis konta bankowego, miejsce wystawienia, źródło daty sprzedaży) są opisane w sekcji Konfiguracja zaawansowana poniżej.
Wielowalutowość / Ustawienia NBP
Tryb stosowania kursu NBP
Przy przeliczaniu faktur w walutach obcych z użyciem kursu NBP często występuje niewielka różnica między kursem przechowywanym w Dolibarr a obowiązującym kursem NBP. To ustawienie kontroluje, która strona jest zachowywana w przypadku takiej zmiany.
Zachowaj walutę bazową - kwota w PLN nie ulega zmianie, a kwota w walucie obcej jest przeliczana na podstawie aktualnego kursu
Zachowaj walutę obcą - kwota w walucie obcej nie ulega zmianie, a kwota w PLN jest przeliczana na podstawie aktualnego kursu
Więcej o tym, jak to działa w praktyce, znajdziesz w sekcji Faktury walutowe w Wysyłanie faktur.
Ustawienia importu
Te opcje kontrolują domyślne zachowanie przy imporcie faktur przychodzących (szczegóły importu znajdziesz w Odbieranie i import faktur).
Auto-tworzenie dostawców podczas importu zbiorczego - dostawcy, którzy nie zostaną dopasowani do istniejących kontrahentów, są automatycznie tworzeni na podstawie danych z faktury
Auto-tworzenie produktów podczas importu zbiorczego - niedopasowane produkty są automatycznie tworzone. Jeśli wyłączone, niedopasowane pozycje są importowane jako opisy tekstowe.
Użyj kodu produktu dostawcy jako referencji produktu - przy auto-tworzeniu produktów kod dostawcy (pole indeks/P_7) jest używany jako referencja produktu zamiast automatycznej numeracji Dolibarr opartej na ustawieniach modułu Produkty.
Te domyślne wartości są zapamiętywane z ostatniego importu zbiorczego.
Wykluczenia klientów
Niektórzy klienci nie potrzebują wysyłania faktur do KSeF, na przykład klienci B2C itp. Dodaj ich do listy wykluczeń tutaj lub wyklucz bezpośrednio z karty kontrahenta. Gdy klient jest wykluczony, funkcje modułu związane z KSeF nie pojawiają się na stronie przy wystawianiu faktur dla tego klienta.
Nadpisania tłumaczeń
Domyślnie Dolibarr nie wyświetla wszystkich pól identyfikacyjnych. Moduł może nadpisać te tłumaczenia, aby NIP, KRS, REGON i BDO wyświetlały się poprawnie na kartach kontrahentów i w całym interfejsie, co ułatwia zachowanie spójności. Robi to poprzez aktualizację tabel nadpisań tłumaczeń na podstawie konfiguracji pól źródłowych na górze strony.
Wybierz języki (obecnie en_US i pl_PL) i kliknij "Zastosuj nadpisania tłumaczeń". Wystarczy to zrobić raz, chyba że zmienisz mapowanie pól powyżej. Jeśli z jakiegoś powodu chcesz cofnąć te nadpisania, kliknij "Usuń nadpisania tłumaczeń", co usunie te zmiany z tabeli nadpisań.
Konfiguracja zaawansowana
Przemapowanie pola źródłowego NIP - Lista rozwijana "Pole źródłowe" przy NIP firmy kontroluje, z którego pola Dolibarr pobierany jest NIP (domyślnie: Professional ID 1). Lista zawiera pola Professional ID od 1 do 6 oraz pole VAT Intra, dzięki czemu moduł może dostosować się do niestandardowych konfiguracji, gdzie identyfikatory trafiły do innych pól. Ta sama opcja pola źródłowego jest dostępna dla KRS, REGON i BDO. Jeśli przypiszesz wiele identyfikatorów do tego samego pola źródłowego, moduł ostrzeże Cię przy zapisie - zwykle oznacza to błąd konfiguracji.
Opis konta bankowego - uwzględnia etykietę konta bankowego w sekcji płatności. Włączaj tylko jeśli nazwy Twoich kont mają sens dla zewnętrznych odbiorców. Numer konta, SWIFT/BIC i nazwa banku są zawsze uwzględniane automatycznie - ten przełącznik kontroluje jedynie opcjonalne pole etykiety.
Miejsce wystawienia - opcjonalne miasto/lokalizacja wystawienia faktury. Może pobierać z adresu firmy lub używać wartości niestandardowej.
Domyślne źródło daty sprzedaży - kontroluje automatyczne wypełnianie daty sprzedaży. "Data powiązanej dostawy/zamówienia" priorytetyzuje datę wysyłki, potem datę dostawy zamówienia, potem datę zamówienia, a na końcu datę faktury. "Data faktury" zawsze używa daty faktury. Moduł dodaje do faktur pole dodatkowe "Data sprzedaży", które zawsze można ręcznie nadpisać przed wysyłką.
Przetestuj połączenie
Gdy wszystko jest skonfigurowane, zweryfikuj działanie przed wysłaniem jakiejkolwiek faktury. Na stronie ustawień lub w zakładce "Jak używać" znajdziesz przyciski testowe:
Sprawdź KSeF Lighthouse - sprawdza status API KSeF pod kątem ogłoszonych awarii lub trybu konserwacji
Test połączenia - weryfikuje, czy moduł może połączyć się z API KSeF dla wybranego środowiska
Test uwierzytelniania tokenem - weryfikuje, czy token jest prawidłowy i akceptowany
Test uwierzytelniania certyfikatem - weryfikuje, czy certyfikat jest prawidłowy (dostępne tylko po skonfigurowaniu certyfikatu)
Jeśli brakuje przycisków testu tokena lub certyfikatu, prawdopodobnie ich jeszcze nie skonfigurowałeś!
Jeśli test połączenia przechodzi, ale uwierzytelnianie nie działa, problem prawie na pewno leży w uprawnieniach. Wróć do portalu KSeF i sprawdź "Uprawnienia" - upewnij się, że Twoje poświadczenia mają wymagane uprawnienia do wysyłania i odbierania faktur.