Przejdź do treści

Przygotowanie systemu pod KSeF

Navigator nie łączy się z Krajowym Systemem e-Faktur (KSeF) bezpośrednio. Komunikację obsługuje serwis pośredniczący (KSeF API) dostarczany przez firmę Archman:

  • Navigator wywołuje serwis, uwierzytelniając się kluczem API.
  • Serwis pośredniczący przechowuje dane uwierzytelniające firm (token KSeF lub certyfikat KSeF), loguje się w ich imieniu do KSeF, szyfruje i wysyła faktury, pobiera faktury i UPO, generuje wizualizacje PDF i kody QR.
  • KSeF sprawdza, czy osoba lub token, którym serwis się uwierzytelnia, ma uprawnienia w kontekście danej firmy.

Ten artykuł opisuje przygotowanie całości. Sposób korzystania z akcji KSeF w obiegach opisuje artykuł Integracja z KSeF.

Kolejność konfiguracji

  1. Przygotowanie uprawnień i danych uwierzytelniających w KSeF: token KSeF albo certyfikat KSeF.
  2. Instalacja i konfiguracja serwisu pośredniczącego: wybór środowiska KSeF i kluczy API.
  3. Konfiguracja firm w serwisie: przypisanie tokena lub certyfikatu do NIP-u firmy.
  4. Połączenie Navigatora z serwisem: adres serwisu i klucz API.
  5. Kartoteki w Navigatorze: firmy, stawki VAT, formy płatności i waluty.

Środowiska KSeF

Ministerstwo Finansów udostępnia trzy środowiska KSeF:

Środowisko Przeznaczenie Adres API Adres kodów QR
Testowe (TEST) Testy integracji. Można używać certyfikatów samopodpisanych, a dane nie są odizolowane od innych integratorów, dlatego nie wprowadzaj prawdziwych danych https://api-test.ksef.mf.gov.pl https://qr-test.ksef.mf.gov.pl
Przedprodukcyjne (DEMO) Końcowe testy w warunkach zbliżonych do produkcji https://api-demo.ksef.mf.gov.pl https://qr-demo.ksef.mf.gov.pl
Produkcyjne (PROD) Faktury z pełną mocą prawną https://api.ksef.mf.gov.pl https://qr.ksef.mf.gov.pl

Jedna instalacja serwisu pośredniczącego łączy się z jednym środowiskiem. Żeby równolegle testować integrację i pracować produkcyjnie, potrzebne są dwie instalacje serwisu, np. dla testowej i produkcyjnej instalacji Navigatora. Opis środowisk zawiera dokumentacja API KSeF.

Przygotowanie po stronie KSeF

Uprawnieniami, tokenami i certyfikatami zarządza się w Aplikacji Podatnika KSeF. Sposób logowania, nadawania uprawnień i generowania tokenów oraz certyfikatów opisują podręczniki KSeF dostępne na stronie Pliki do pobrania KSeF 2.0.

Wymagane uprawnienia

Tożsamość, którą serwis loguje się do KSeF (token albo właściciel certyfikatu), musi mieć w kontekście firmy następujące uprawnienia:

Uprawnienie w KSeF Do czego jest potrzebne
Wystawianie faktur (InvoiceWrite) Wysyłanie faktur, sprawdzanie statusu sesji i faktur wysłanych w sesji, pobieranie UPO
Przeglądanie faktur (InvoiceRead) Pobieranie faktur z KSeF, także pobieranie pojedynczej faktury po numerze KSeF

Jeżeli firma tylko wysyła faktury albo tylko je odbiera, wystarczy jedno z tych uprawnień.

Token KSeF czy certyfikat KSeF

Serwis może logować się do KSeF na dwa sposoby:

  • Token KSeF: generowany w kontekście firmy. Uprawnienia wybiera się przy generowaniu tokena, dlatego trzeba zaznaczyć co najmniej uprawnienia z tabeli wyżej. Token jest poufny: przechowuj go w bezpiecznym miejscu.
  • Certyfikat KSeF typu Authentication: potwierdza tożsamość osoby lub podmiotu, który o niego wnioskował. Sam certyfikat nie niesie uprawnień: KSeF sprawdza uprawnienia jego właściciela w kontekście firmy. Przy wniosku o certyfikat podaje się hasło, którym zaszyfrowany jest klucz prywatny. Do instalacji w serwisie potrzebne będą: plik certyfikatu, plik klucza prywatnego i to hasło.

Jeżeli dla firmy skonfigurowano i token, i certyfikat, serwis używa tokena.

Certyfikat Offline (opcjonalny)

Certyfikat KSeF typu Offline służy wyłącznie do generowania kodu QR potwierdzającego autentyczność wystawcy (Kod II), wymaganego na fakturach wystawianych w trybie offline. Nie pozwala logować się do KSeF. W Navigatorze jest potrzebny do akcji Wygeneruj kod QR do potwierdzenia autentyczności wystawcy (Kod II) i do opcji Dołącz QR kod II w podglądzie faktury w PDF. Certyfikat jest jednego typu: nie można wystawić certyfikatu, który łączy funkcje Authentication i Offline.

Więcej o certyfikatach i tokenach: Certyfikaty KSeF, Tokeny KSeF, Uprawnienia.

Serwis pośredniczący

Serwis jest dostępny w ramach licencji dla klientów Archman z aktywnym wsparciem. Instalację przeprowadza zespół wdrożeniowy Archman. Gdy chcesz zainstalować serwis samodzielnie, wersję instalacyjną i instrukcję przekaże opiekun z firmy Archman.

Po instalacji warto wiedzieć, gdzie serwis przechowuje dane:

  • Konfiguracja firm (NIP, token KSeF, odciski certyfikatów) jest zapisywana w pliku bazy danych database\ksefApi.db w katalogu aplikacji serwisu. Plik zawiera tokeny KSeF, dlatego chroń dostęp do niego i uwzględnij go w kopiach zapasowych.
  • Certyfikaty są instalowane w magazynie certyfikatów Windows (Osobisty) konta, na którym działa serwis.
  • Logi są zapisywane w katalogu logs aplikacji i przechowywane przez 30 dni.

Plik konfiguracyjny serwisu

Ustawienia serwisu znajdują się w pliku appsettings.json w katalogu aplikacji. Można je też przekazać zmiennymi środowiskowymi.

Ustawienie Opis
ApiSettings:BaseUrl Adres API KSeF, czyli wybór środowiska.
ApiSettings:BaseQrUrl Adres kodów QR KSeF. Musi wskazywać to samo środowisko.
ApiSettings:LighthouseBaseUrl Adres usługi Latarnia KSeF, z której serwis odczytuje status działania KSeF. Dla środowiska testowego: https://api-latarnia-test.ksef.mf.gov.pl, dla produkcyjnego: https://api-latarnia.ksef.mf.gov.pl
Authorization Lista kluczy API (ApiKey), którymi mogą się uwierzytelniać aplikacje korzystające z serwisu. Jeden z tych kluczy wpisz w ustawieniach Navigatora
Swagger:Enabled Włącza stronę Swagger z opisem i testowaniem metod serwisu. Domyślnie wyłączona

Konfiguracja firmy w serwisie

Dla każdej firmy, która ma wysyłać lub pobierać faktury, w serwisie zapisuje się:

  • NIP firmy,
  • token KSeF albo odcisk palca (thumbprint) certyfikatu Authentication zainstalowanego w serwisie,
  • opcjonalnie odcisk palca certyfikatu Offline.

Konfigurację wykonuje administrator serwera serwisu albo opiekun z firmy Archman. Przekaż mu token KSeF albo pliki certyfikatu z kluczem prywatnym i hasłem. Gdy nie chcesz przekazywać hasła osobom trzecim, zainstaluj certyfikat samodzielnie metodą opisaną niżej i przekazać już tylko odcisk palca.

NIP

NIP w konfiguracji serwisu musi być zapisany dokładnie tak samo jak NIP kontrahenta przypisanego do firmy w Navigatorze, bo po nim serwis wyszukuje konfigurację. Zalecamy zapis samych cyfr, bez kresek i spacji, w obu miejscach.

Metody serwisu (dla administratora serwera)

Metody można wywołać z dowolnego narzędzia HTTP albo ze strony Swagger serwisu (jeżeli jest włączona). Każde wywołanie musi zawierać nagłówek ApiKey z jednym z kluczy zapisanych w ustawieniu Authorization.

Instalacja certyfikatu: POST /certificate/install

Metoda tworzy z certyfikatu i klucza prywatnego plik PFX, instaluje go w magazynie certyfikatów (Osobisty) konta, na którym działa serwis, i zwraca odcisk palca certyfikatu. Parametry (formularz multipart/form-data):

Parametr Opis
certificate Plik certyfikatu KSeF (PEM)
privateKey Plik klucza prywatnego zaszyfrowanego hasłem (PEM)
password Hasło do klucza prywatnego podane przy wniosku o certyfikat

Metodę wywołaj osobno dla certyfikatu Authentication i dla certyfikatu Offline. Certyfikat można też zainstalować ręcznie w magazynie Osobisty konta serwisu. Odcisk palca odczytasz wtedy z właściwości certyfikatu.

Zapis konfiguracji firmy: PUT /configuration/{nip}

Treść żądania (JSON):

Pole Opis
name Nazwa firmy (informacyjnie)
ksefToken Token KSeF
ksefCertificateThumbprintForAuthentication Odcisk palca certyfikatu Authentication
ksefCertificateThumbprintForOffline Odcisk palca certyfikatu Offline

Zapis zastępuje całą konfigurację firmy

Pola pominięte w żądaniu zostaną wyczyszczone. Serwis nigdy nie zwraca zapisanego tokena (odczyt pokazuje tylko, czy token istnieje), dlatego przy zmianie certyfikatu trzeba ponownie podać token, jeżeli ma zostać zachowany.

Pozostałe metody:

Metoda Opis
GET /configuration Lista skonfigurowanych firm
GET /configuration/{nip} Konfiguracja jednej firmy: nazwa, informacja, czy jest token, odciski certyfikatów, daty dodania i zmiany
DELETE /configuration/{nip} Usunięcie konfiguracji firmy
GET /version Wersja serwisu

Aktualizacja ze starszej wersji serwisu

Starsze wersje serwisu przechowywały konfigurację firm w sekcji Authorization pliku appsettings.json (pola Nip, KsefToken, KsefCertificateThumbprint). Przy pierwszym uruchomieniu nowej wersji, gdy baza konfiguracji jest jeszcze pusta, serwis automatycznie przenosi te wpisy do bazy.

Połączenie Navigatora z serwisem

W Ustawienia > Pozostałe > Ustawienia, w sekcji KSeF, uzupełnij dwa pola:

  • Adres API KSeF: adres serwisu pośredniczącego, np. https://ksef.firma.pl/.
  • ApiKey API KSeF: jeden z kluczy API zapisanych w ustawieniu Authorization serwisu. Klucz jest przechowywany w postaci zaszyfrowanej, a po zapisaniu wyświetlany jako gwiazdki.

Bez tych ustawień każda akcja KSeF kończy się błędem.

Aktualizacja serwisu z poziomu Navigatora

Jeżeli serwis jest zainstalowany w IIS na tym samym serwerze co Navigator, a jego witryna ma powiązanie (binding) z hostem z pola Adres API KSeF, Navigator może aktualizować również serwis. Na zakładce Aktualizacja w Ustawienia > Pozostałe > Ustawienia widoczne są pola Aktualna wersja KSeF API, Dostępne wersje KSeF API i Aktualizuj KSeF API. Po zaznaczeniu aktualizacji serwis jest aktualizowany razem z Navigatorem. Przebieg aktualizacji opisuje artykuł Ustawienia systemu.

Kartoteki w Navigatorze

Firmy

W Ustawienia > Kartoteki > Firmy każda firma korzystająca z KSeF musi mieć przypisanego kontrahenta z poprawnym polskim NIP-em. Akcje KSeF identyfikują firmę w serwisie po tym NIP-ie, a przy generowaniu faktury dane kontrahenta firmy trafiają do sekcji sprzedawcy (Podmiot1).

Stawki VAT

W Ustawienia > Kartoteki > Stawki VAT kod każdej stawki używanej na fakturach musi być jednym z kodów KSeF. Pozycja ze stawką o innym kodzie trafi do faktury bez stawki VAT, a przy imporcie nie zostanie dopasowana.

Kod Znaczenie
23, 22, 8, 7, 5, 4, 3 Stawki procentowe
0 KR Stawka 0% dla sprzedaży towarów i świadczenia usług na terytorium kraju
0 WDT Stawka 0% dla wewnątrzwspólnotowej dostawy towarów
0 EX Stawka 0% dla eksportu towarów
zw Zwolnione z podatku
oo Odwrotne obciążenie
np I Niepodlegające opodatkowaniu: dostawy towarów i świadczenie usług poza terytorium kraju
np II Niepodlegające opodatkowaniu na terytorium kraju

Formy płatności

W Ustawienia > Kartoteki > Formy płatności każdej formie płatności przypisz w polu Forma płatności KSeF jedną z form KSeF: Gotówka, Karta, Bon, Czek, Kredyt, Przelew, Płatność mobilna lub Płatność inna. Forma bez przypisania nie trafi do wysyłanej faktury, a przy imporcie forma płatności na dokumencie pozostanie pusta.

Waluty

W Ustawienia > Kartoteki > Waluty symbol waluty musi być kodem ISO (np. PLN, EUR, USD). Przy generowaniu faktury symbol trafia do pola kodu waluty, a przy imporcie waluta jest wyszukiwana po symbolu. Gdy spodziewasz się faktur w innej walucie, dodaj ją wcześniej.

Najczęstsze błędy

Komunikat Przyczyna
Adres KSeF.API nie może być pusty Brak adresu serwisu w ustawieniach Navigatora
ApiKey KSeF.API nie może być puste Brak klucza API w ustawieniach Navigatora
Niewłaściwy API Key / Brak API Key Klucz w Navigatorze nie odpowiada żadnemu kluczowi w ustawieniu Authorization serwisu
Brak konfiguracji dla podanego numeru NIP W serwisie nie ma firmy o NIP-ie kontrahenta firmy z Navigatora (sprawdź zapis NIP-u)
Nie znaleziono metod uwierzytelnienia (certyfikat lub token KSeF) Firma w serwisie nie ma ani tokena, ani certyfikatu Authentication
Nie znaleziono certyfikatu dla odcisku Certyfikatu o podanym odcisku nie ma w magazynie Osobisty konta serwisu
Brak odcisku palca certyfikatu KSeF offline Próba wygenerowania Kodu II bez skonfigurowanego certyfikatu Offline

Co dalej