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¶
- Przygotowanie uprawnień i danych uwierzytelniających w KSeF: token KSeF albo certyfikat KSeF.
- Instalacja i konfiguracja serwisu pośredniczącego: wybór środowiska KSeF i kluczy API.
- Konfiguracja firm w serwisie: przypisanie tokena lub certyfikatu do NIP-u firmy.
- Połączenie Navigatora z serwisem: adres serwisu i klucz API.
- 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.dbw 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
logsaplikacji 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
Authorizationserwisu. 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¶
- Integracja z KSeF: akcje KSeF w procedurach obiegu.