Przygotowanie do integracji z KSeF¶
Wprowadzenie¶
W wersji 2.0 KSeF wprowadzono wiele zmian, zarówno w budowie schemy jak i w działaniu systemu. Zmiany te są systematycznie odwzorowywane w funkcjonalności Navigatora zgodnie z harmonogramem uruchamiania kolejnych funkcjonalności KSeF.
Zmiany te pociągają za sobą konieczność rekonfiguracji systemu, jeżeli mieliśmy przygotowane środowisko pod wersję 1.0. Należy zmienić konfigurację oraz przerobić procesy odpowiedzialne za wysyłanie i pobieranie faktur.
Od strony Navigatora też pojawiły się zmiany. System Navigator nie łączy się bezpośrednio z systemem KSeF, konieczna jest instalacja serwisu pośredniczącego z którym komunikuje się Navigator. Serwis jest autorstwa firmy Archman i jest dostępny, w ramach licencji, dla wszystkich klientów firmy z aktywnym wsparciem. Instalacja systemu jest dokonywana przez zespoły wdrożeniowe Archman, jeżeli klient chce samodzielnie zainstalować serwis powinien się zwrócić do swojego opiekuna w firmie Archman który przekaże aktualną wersję instalacyjną serwisu oraz instrukcję instalacji.
Należy pamiętać, że funkcjonują trzy środowiska: testowe, demonstracyjne (preprodukcyjne) oraz produkcyjne. Moduł MCU opisywany niżej służy tylko do certyfikatów dla środowiska produkcyjnego natomiast Aplikacje podatnika oraz interfejsy komunikacyjne są dostępne dla wszystkich trzech środowisk. Należy wybrać to środowisko, którego aktualnie chcemy używać np. do testów systemu.
Warto systematycznie śledzić strony Ministerstwa Finansów, zwłaszcza stronę z pytaniami i odpowiedziami dotyczącymi KSeF. Znajdziemy tam najnowsze informacje o statusie uruchomienia systemu oraz praktyczne porady dotyczące konkretnych sytuacji.
Warto zapoznać się z materiałami Ministerstwa Finansów zamieszonymi na stronie Pliki do pobrania KSeF 2.0
W szczególności warto zapoznać się z podręcznikami KSeF:
Część I -- rozpoczęcie korzystania z KSeF
Część II -- wystawianie i otrzymywanie faktur w KSeF
Część III -- dodatkowe funkcjonalności w KSeF
Część IV -- KSeF w JST i GV oraz pozostałe modele uprawnień
Zanim zaczniemy...¶
Przed konfiguracji Navigatora do współpracy z KSeF należy przygotować uprawnienia w KSeF. W tym celu należy zalogować się do Aplikacji podatnika Potrzebujemy do tego:
- W przypadku jednoosobowej działalności:
- Elektronicznie, przez stronę KSeF -- jeżeli posiadamy profil zaufany lub podpis kwalifikowany zawierający NIP lub PESEL
- Papierowo -- poprzez złożenie formularza ZAW-FA
- Spółka lub inny podmiot
- Elektronicznie, przez stronę KSeF -- jeżeli posiadamy elektroniczną pieczęć kwalifikowaną zawierającą NIP
- Papierowo -- poprzez złożenie formularza ZAW-FA
- Kwestie zamówienia podpisu kwalifikowanego lub pieczęci elektronicznej należy przeprowadzić indywidualnie z dostawcami usług uwierzytelniania. O szczegółach można przeczytać na stronie Podpis kwalifikowany | Biznes.gov.pl -- Serwis informacyjno-usługowy dla przedsiębiorcy
- Po uzyskaniu dostępu do konta można nadać uprawnienia dla innych osób pracujących w firmie (np. głównej księgowej) lub podmiotom współpracującym (np. zewnętrznej firmie księgowej). Nadając uprawnienia trzeba się dobrze zastanowić, jakie uprawnienia powinny mieć te osoby.
Więcej na temat uwierzytelnienia w systemie KSeF można przeczytać na stronach Ministerstwa Finansów
Adresy serwisów dla wszystkich środowisk KSeF:
| Środowisko | API | Aplikacja do wizualizacji kodów QR | Aplikacja podatnika |
|---|---|---|---|
| Środowisko testowe (TE) | https://api-test.ksef.mf.gov.pl | https://qr-test.ksef.mf.gov.pl | https://ap-test.ksef.mf.gov.pl |
| Środowisko demonstracyjne / przedprodukcyjne (TR) | https://api-demo.ksef.mf.gov.pl | https://qr-demo.ksef.mf.gov.pl | https://ap-demo.ksef.mf.gov.pl |
| Środowisko produkcyjne (PRD) | https://api.ksef.mf.gov.pl | https://qr.ksef.mf.gov.pl | https://ap.ksef.mf.gov.pl |
Po wybraniu jednej z opcji pojawi się ekran z wyborem identyfikatora firmy. Należy uzupełnić pole oznaczone gwiazdką czyli np. wpisać NIP firmy.
Po kliknięciu w przycisk Uwierzytelnij, w zależności od wybranej metody, zostaniemy przekierowani na stronę Profilu zaufanego lub zostanie pobrany plik XML. Należy go podpisać i wgrać do MCU poprzez stronę.
Po zalogowaniu widzimy dostępne opcje: Uprawnienia i Certyfikaty
Możemy podglądnąć kto ma dostęp do systemu oraz wygenerować certyfikat
Przed wygenerowaniem certyfikatu należy sprawdzić czy dysponujemy odpowiednimi uprawnieniami. W przypadku tokena uprawnienia wskazujemy przy jego generowaniu, w przypadku certyfikatu uprawnienia są identyczne jak uprawnienia osoby, która jest zalogowana do systemu i która generuje certyfikat.
W MCU wygląda uprawnienia dla zalogowanego użytkownika
Aby zobaczyć uprawnienia wszystkich użytkowników którym nadano uprawnienia wchodzimy w zakładkę Zarządzaj uprawnieniami.
Jak widzimy na przykładach, jeżeli nie prowadzimy jednoosobowej działalności gospodarczej to po zalogowaniu się jako właściciel lub przy pomocy pieczęcie mamy jedynie uprawnienia do zarządzania uprawnieniami. Oznacza to, że nie możemy wystawiać faktur czy przeglądać faktur. Należy pamiętać, że uprawnienia użytkownika mają wpływ na uprawnienia certyfikatu który wystawiamy więc wystawiając certyfikat z tego konta nie będzie możliwości wysłania i pobrania faktur w Navigatorze. W takiej sytuacji należy dodać nowego użytkownika do systemu i nadać mu odpowiednie uprawnienia.
W tym przykładzie dodajemy uprawnienia dla osoby fizycznej która posługuje się profilem zaufanym. Wszystkie opcje dotyczące zakładania nowych użytkowników są opisane w dokumentacji MCU.
Na potrzeby komunikacji Navigatora potrzebujemy trzech uprawnień:
Wystawiania faktur -- uprawnienie daje nam możliwość tworzenia i wysyłania faktur do KSeF
Przeglądania faktur -- uprawnienia daje nam możliwość pobierania faktur z KSeF
Przeglądania historii sesji -- uprawnienie daje nam możliwość sprawdzania statusu wysłanych faktur oraz pobierania Urzędowego Potwierdzenia Odbioru
Przy dodawaniu należy zaznaczyć te opcje:
Po założeniu konta i zalogowaniu się na niego powinniśmy w Moich uprawnieniach widzieć taki zakres uprawnień (tu w aplikacji podatnika):
Uprawnienia dla zalogowanego użytkownika możemy sprawdzić w zakładce Uprawnienia > Moje uprawnienia. Może się okazać, że osoba generująca certyfikat nie ma odpowiednich uprawnień i nie może ich zmienić, należy wtedy zgłosić się do osoby która zakładała konto by zmieniła uprawnienia.
Generowanie certyfikatu lub tokena¶
Generacja tokenu wygląda w następujący sposób:
W aplikacji MCU możemy złożyć wniosek o nowy certyfikat
Możemy też przeglądać listę wygenerowanych certyfikatów.
UWAGA: System MCU służy wyłącznie do generowania certyfikatów dla wersji produkcyjnej. Możemy posłużyć się tym certyfikatem do zalogowania się do aplikacji klienckiej również w wersji preprodukcyjnej i tam wygenerować certyfikat lub token.
Warto zwrócić uwagę na konfigurację tokenu -- musimy tu zaznaczyć opcje uprawnień które będą przypisane do tokenu. Na potrzeby integracji Navigatora z KSeF potrzebujemy uprawnień do przeglądania faktur oraz wysyłania faktur.
Należy pamiętać o skopiowaniu tokeny we właściwym momencie, jeżeli nie skopiujemy tokenu po odświeżeniu strony i wyjdziemy z niej -- nie będziemy w stanie pobrać tokenu.
Generowanie certyfikatu wygląda następująco:
W tym przypadku należy podać nazwę certyfikatu i hasło. Nie musimy podawać uprawnień gdyż certyfikat daje takie same uprawnienia jakie mamy po zalogowaniu do systemu. Logując się jako właściciel lub pieczęcią firmową mamy pełne uprawnienia, logując się jako dodany pracownik mamy takie uprawnienia, jakie zostały nam nadane przy zakładaniu konta.
Jak widzimy na animacji system wymaga odpowiednio dobranego hasła. Wpisując na bieżąco hasło widzimy na znacznikach czy spełniamy wszystkie wymagania. Jeżeli któryś będzie na czerwono to nie uda nam się wygenerować hasła.
Po naciśnięciu przycisku Generuj powinien pobrać się plik o nazwie „wpisana nazwa certyfikatu".key Plik zawiera klucz prywatny, który jest niezbędny do wgrania certyfikatu do systemu.
Przy generowaniu certyfikatu należy pamiętać, że mamy w systemie dwa certyfikaty:
Uwierzytelnienie w systemie KSeF: służy do komunikacji online z systemem KSeF. Jest on wymagany do standardowej integracji
Podpis linku do weryfikacji wystawcy: służy do generowania kodu QR w trybach offline i awaryjnym. Nie jest wymagany do standardowej pracy ale jeżeli nie będziemy go mieć to nie wystawimy faktury w sytuacji gdy KSeF nie będzie działał.
Uwaga: powyższe przykłady zostały pokazane na wersji demo systemu, do której każdy może się dostać znając NIP firmy, co widać na pierwszej animacji. Dostęp do wersji preprodukcyjnej oraz produkcyjnej wymaga pieczęci firmowej lub podpisu kwalifikowanego.
W obu systemach mamy następujące informacje:
- Numer seryjny -- unikalny identyfikator certyfikatu
- Nazwa własna -- nazwa nadana przez Ciebie
- Przeznaczenie -- typ certyfikatu (uwierzytelnienie lub offline)
- Identyfikator podmiotu -- NIP lub PESEL
- Nazwa właściciela -- imię i nazwisko lub nazwa podmiotu
- Status:
- Aktywny -- można używać
- Zablokowany -- w trakcie unieważniania
- Unieważniony -- nie można używać
- Wygasły -- minęła data ważności
- Ważny od/do -- okres ważności
- Data ostatniego użycia
Należy zwrócić uwagę na daty ważności -- po dacie Ważny do certyfikat przestanie działać.
Jak widzimy na zrzucie mamy dwa certyfikaty: Podpis linku i Uwierzytelnienie. Potrzebne nam są oba, jeden służy do komunikacji poprzez API a drugi do podpisywania faktury offline.
Ostatnią rzeczą, którą musimy zrobić to wygenerować skrót podpisu. Wystarczy pobrać certyfikat, wgrać go do magazynu certyfikatów Windows a następnie odszukać go wśród certyfikatów i wybrać opcję tworzenia skrótu.
Wgranie certyfikatu¶
Certyfikat możemy wgrać ręcznie do magazyny certyfikatów Windows lub użyć metody udostępnionej przez serwis KSeF dostarczony przez firmę Archman.
Przed wgraniem certyfikatu ręcznie należy odpowiednio przygotować wygenerowany klucz prywatny oraz certyfikat. Będziemy potrzebować biblioteki OpenSSL (https://pl.wikipedia.org/wiki/OpenSSL). Jeżeli biblioteka nie jest zainstalowana należy ją wcześniej zainstalować.
Po zainstalowaniu OpenSSL należy wykonać polecenie, sprawdzając czy ścieżki do programu i do plików się zgadzają:
C:\Program Files\OpenSSL-Win64\bin>openssl pkcs12 -export -out C:\KSEF\cert_export.pfx -inkey C:\KSEF\NavigatorKSEF.key -in C:\KSEF\NavigatorKSEF.crt
gdzie:
NavigatorKSEF.key -- klucz prywatny wygenerowany w aplikacji podatkowej lub w MCU
NavigatorKSEF.crt -- certyfikat wygenerowany w aplikacji podatkowej lub w MCU
cert_export.pfx -- połączony certyfikat który należy wgrać do magazynu Windows
Teraz wystarczy uruchomić aplikacje zarządzania certyfikatami. Można to zrobić np. naciskając Win+ R na klawiaturze, wpisując certmgr.msc i nacisnąć enter. Ewentualnie dwukrotnie kliknąć na wygenerowany certyfikat i postępować zgodnie ze wskazówkami kreatora. Całość oczywiście należy wykonać na serwerze, na którym jest zainstalowany serwis KSeF.
Wgrywając certyfikat ręcznie należy pamiętać, by znalazł się on w magazynie lokalnym użytkownika, z którego uprawnieniami uruchamiamy serwis Navigatora. Dobrze jest na tym kroku skorzystać z pomocy administratora systemu lub opiekuna ze strony firmy Archman.
Jeżeli korzystamy z serwisu do instalacji certyfikatu powinniśmy znaleźć metodę Install. Adres serwisu jest ustalany podczas wdrożenia więc administrator systemu powinien go wskazać. Metoda Install jest pierwszą metodą z listy, na samej górze.
Potrzebujemy podać trzy parametry:
Certyfikate: pobieramy go z MCU lub z aplikacji podatnika. Jeżeli nie zapisaliśmy certyfikatu zaraz po wygenerowaniu możemy przejść na listę certyfikatów i pobrać wskazany certyfikat
Private Key: Klucz prywatny który został wygenerowany podczas składania wniosku o wygenerowanie certyfikatu. Klucz prywatny znajduje się w pliku, który został pobrany po naciśnięciu przycisku Generuj.
Password: Hasło, które podaliśmy w momencie składania wniosku o certyfikat.
Konfiguracja serwisu pośredniczącego¶
Niestety, to nie koniec konfiguracji certyfikatu. Po wgraniu certyfikatu do magazyny certyfikatów Windows należy jeszcze skonfigurować serwis pośredniczący. Jest to czynność techniczna, polegająca na dopisaniu odpowiednich parametrów do pliku konfiguracyjnego serwisu więc najlepiej przekazać to zadanie administratorowi systemu lub opiekunowi ze strony Archman.
Dlaczego jest to takie skomplikowane? Należy pamiętać, że certyfikaty podpisujemy własnymi poświadczeniami i zabezpieczamy swoim hasłem. Nie jest dobrą praktyką przekazywanie hasła osobom trzecim, choćby to były osoby zaufane. Dlatego najlepiej samodzielnie wgrać certyfikat do magazynu certyfikatów. Z tego powodu tak zbudowaliśmy system.
Do konfiguracji potrzebny jest nam tzw. odcisk palca (thumbprint). Najprościej znaleźć go w menadżerze certyfikatów. Wystarczy wpisać w wyszukiwarce Windows „Zarządzaj certyfikatami użytkowników" i uruchomić wyszukany program. Pojawi się okno podobne do tego poniżej.
Szukamy w Osobisty > Certyfikaty certyfikatu, który wgraliśmy. Powinien się on nazywać tak, jak go nazwaliśmy przy generowaniu
Następnie należy go otworzyć, przejść do zakładki Szczegóły i na samym dole będzie odcisk palca. Kopiujemy go i przekazujemy administratorowi lub opiekunowi.
Uwaga: Cała sekcja związana z wygrywaniem i instalacją dotyczy sytuacji, gdy używamy certyfikatów. Jeżeli używamy tokenów to wystarczy skopiować token i przekazać go opiekunowi.
Po stronie Navigatora¶
Równolegle z przygotowaniami po stronie KSeF należy przygotować Navigatora365 do współpracy z KSeF. Navigator używa do komunikacji zewnętrznego serwisu, który jest dostarczany przez firmę Archman. W przypadku instalacji w chmurze Archman, serwis jest dostępny jednak przy instalacjach on-premise należy go zainstalować samodzielnie. Serwis jest udostępniany bezpłatnie klientom posiadającym licencje Navigatora365 wraz z instrukcją instalacji i uruchomienia. Z serwisem komunikujemy się poprzez Rest API. W dalszej części tego artykułu omówione zostaną techniczne aspekty komunikacji. Przykładowa konfiguracja procesów integracyjnych na bazie standardowej aplikacji Zakupy znajduje się w oddzielnym artykule .
Dostępne metody w serwisie KSeF¶
Certificate - zarządzanie certyfikatami¶
Install - instalowanie certyfikatów¶
Metoda: POST
Content-Type: multipart/form-data
Parametry:
certificat - plik z certyfikatem wygenerowanym w Aplikacji podatnika. Z reguły jest to plik z rozszerzeniem pfx
privateKey - klucz prywatny, utworzony podczas generowania certyfikatu. Z reguły jest to plik z rozszerzeniem key
password - hasło do klucza prywatnego
Działanie tej metody zostało omówione w sekcji o wgrywaniu certyfikatu
Health - sprawdzanie dostępności serwisu¶
Status - zwraca stan serwisu KSeF¶
Metoda: GET Content-type: brak
Metoda nie wymaga żadnych parametrów, zwraca jsona zawierającego informacje o stanie serwisu.
Przykładowy json zwracany przez serwis:
Kliknij żeby rozwinąć
{
"status": "TOTAL_FAILURE",
"messages": [
{
"id": "K/2026/AWR/02",
"eventId": 1003,
"category": "TOTAL_FAILURE",
"type": "FAILURE_START",
"title": "Wystąpiła całkowita awaria",
"text": "Od godziny 13:27 31 stycznia trwa całkowita awaria...",
"start": "2026-01-31T11:27:00+00:00",
"end": null,
"version": 1,
"published": "2026-01-31T11:35:00+00:00"
},
{
"id": "K/2026/AWR/01",
"eventId": 1002,
"category": "FAILURE",
"type": "FAILURE_START",
"title": "Wystąpiła awaria",
"text": "Od godziny 12:13 31 stycznia trwa awaria...",
"start": "2026-01-31T10:13:00+00:00",
"end": null,
"version": 1,
"published": "2026-01-31T10:13:00+00:00"
}
]
}
Invoice - przetwarzanie faktur¶
- Generowanie XML
- Wysyłka interaktywna faktury
- Wysyłka wsadowa faktur
- Pobranie faktury po numerze KSeF
- Pobranie interaktywne faktur
- Pobranie wsadowe faktur
- Przetwarzanie pliku XML
Generate - generowanie pliku XML faktury¶
Metoda: POST
Content-Type: application/json
Jako parametr należy podać json zawierający opis faktury. Przykład jsona znajduje się poniżej:
Po poprawnym wywołaniu metody serwis zwróci plik XML w standardzie schemy KSeF.
Przykładowy wygląd pliku json:
Kliknij żeby rozwinąć
{
"seller": {
// Sprzedawca
"taxpayerPrefix": null, // Kod (prefiks) podatnika VAT UE
"eoriNumber": null, // Numer w Unijnym Systemie Rejestracji i Identyfikacji Podmiotów Gospodarczych (EORI)
"taxIdentificationNumber": null, // NIP
"name": null, // Nazwa
"address": {
// Adres
"countryCode": null, // Kod kraju
"line1": null, // Linia 1 adresu
"line2": null, // Linia 2 adresu
"globalLocationNumber": null // Globalny Numer Lokalizacyjny (GLN)
},
"mailingAddress": {
// Adres (korespondencyjny)
"countryCode": null, // Kod kraju
"line1": null, // Linia 1 adresu
"line2": null, // Linia 2 adresu
"globalLocationNumber": null // Globalny Numer Lokalizacyjny (GLN)
},
"contactDetails": [
// Dane kontaktowe
{
"phoneNumber": null, // Numer telefonu
"emailAddress": null // Adres e-mail
}
],
"taxpayerStatus": null // Status podatnika (enum: "W stanie likwidacji" | "W postępowaniu restrukturyzacyjnym" | "W stanie upadłości" | "Przedsiębiorstwo w spadku")
},
"buyer": {
// Nabywca
"eoriNumber": null, // Numer w Unijnym Systemie Rejestracji i Identyfikacji Podmiotów Gospodarczych (EORI)
"taxIdentificationNumber": null, // NIP
"euCode": null, // Kod (prefiks) nabywcy VAT UE
"euVatNumber": null, // Numer identyfikacyjny VAT nabywcy
"countryCode": null, // Kod kraju nadania innego identyfikatora podatkowego
"idNumber": null, // Identyfikator podatkowy inny niż NIP oraz numer VAT UE
"name": null, // Nazwa
"address": {
// Adres
"countryCode": null, // Kod kraju
"line1": null, // Linia 1 adresu
"line2": null, // Linia 2 adresu
"globalLocationNumber": null // Globalny Numer Lokalizacyjny (GLN)
},
"mailingAddress": {
// Adres (korespondencyjny)
"countryCode": null, // Kod kraju
"line1": null, // Linia 1 adresu
"line2": null, // Linia 2 adresu
"globalLocationNumber": null // Globalny Numer Lokalizacyjny (GLN)
},
"contactDetails": [
// Dane kontaktowe
{
"phoneNumber": null, // Numer telefonu
"emailAddress": null // Adres e-mail
}
],
"customerNumber": null, // Numer klienta
"localGovernmentUnit": null, // Jednostka samorządu terytorialnego (JST)
"memberOfVatGroup": null // Członek grupy VAT (GV)
},
"thirdParties": [
// Strony trzecie
{
"eoriNumber": null, // Numer w Unijnym Systemie Rejestracji i Identyfikacji Podmiotów Gospodarczych (EORI)
"taxIdentificationNumber": null, // NIP
"internalId": null, // Identyfikator wewnętrzny z NIP
"euCode": null, // Kod (prefiks) nabywcy VAT UE
"euVatNumber": null, // Numer identyfikacyjny VAT nabywcy
"countryCode": null, // Kod kraju nadania innego identyfikatora podatkowego
"idNumber": null, // Identyfikator podatkowy inny niż NIP oraz numer VAT UE
"name": null, // Nazwa
"address": {
// Adres
"countryCode": null, // Kod kraju
"line1": null, // Linia 1 adresu
"line2": null, // Linia 2 adresu
"globalLocationNumber": null // Globalny Numer Lokalizacyjny (GLN)
},
"mailingAddress": {
// Adres (korespondencyjny)
"countryCode": null, // Kod kraju
"line1": null, // Linia 1 adresu
"line2": null, // Linia 2 adresu
"globalLocationNumber": null // Globalny Numer Lokalizacyjny (GLN)
},
"contactDetails": [
// Dane kontaktowe
{
"phoneNumber": null, // Numer telefonu
"emailAddress": null // Adres e-mail
}
],
"role": {
// Rola
"thirdPartyRole": null, // Role strony trzeciej (enum m.in. "Faktor", "Odbiorca", "Wystawca faktury", "Dokonujący płatności", "Rola inna", ...)
"roleDescription": null, // Opis roli
"share": null // Udział
},
"customerNumber": null // Numer klienta
}
],
"general": {
// Ogólne
"currencyCode": null, // Kod waluty
"dateOfIssue": null, // Data wystawienia (YYYY-MM-DD)
"placeOfInvoiceIssuance": null, // Miejsce wystawienia faktury
"nextInvoiceNumber": null, // Kolejny numer faktury
"warehouseDocumentNumbers": [
// Numery dokumentów magazynowych
null
],
"dateOfDelivery": null, // Data dostawy/wykonania usługi (YYYY-MM-DD)
"periodStartDate": null, // Data początkowa okresu
"periodEndDate": null, // Data końcowa okresu
"values": {
// Wartości
"p_13_1": null, // (PDF/P_13_1) Suma wartości sprzedaży netto ze stawką podstawową (aktualnie 23% albo 22%); dla zaliczek: kwota zaliczki netto; dla korekt: kwota różnicy (art. 106j ust. 2 pkt 5)
"p_14_1": null, // (PDF/P_14_1) Kwota podatku od sumy sprzedaży netto ze stawką podstawową (23%/22%); dla zaliczek: wg wzoru z art. 106f ust. 1 pkt 3; dla korekt: kwota różnicy
"p_14_1W": null, // (PDF/P_14_1W) Jak wyżej, ale dla waluty obcej: kwota podatku przeliczona wg Działu VI (art. 106e ust. 11)
"p_13_2": null, // (PDF/P_13_2) Suma wartości sprzedaży netto ze stawką obniżoną pierwszą (aktualnie 8% albo 7%); zaliczki/korekty analogicznie
"p_14_2": null, // (PDF/P_14_2) Kwota podatku od sumy sprzedaży netto ze stawką 8%/7%; zaliczki/korekty analogicznie
"p_14_2W": null, // (PDF/P_14_2W) Jak wyżej, ale dla waluty obcej: kwota podatku przeliczona wg Działu VI (art. 106e ust. 11)
"p_13_3": null, // (PDF/P_13_3) Suma wartości sprzedaży netto ze stawką obniżoną drugą (aktualnie 5%); zaliczki/korekty analogicznie
"p_14_3": null, // (PDF/P_14_3) Kwota podatku od sumy sprzedaży netto ze stawką 5%; zaliczki/korekty analogicznie
"p_14_3W": null, // (PDF/P_14_3W) Jak wyżej, ale dla waluty obcej: kwota podatku przeliczona wg Działu VI (art. 106e ust. 11)
"p_13_4": null, // (PDF/P_13_4) Suma wartości sprzedaży netto objętej ryczałtem dla taksówek osobowych; zaliczki/korekty analogicznie
"p_14_4": null, // (PDF/P_14_4) Kwota podatku od sumy sprzedaży netto dla ryczałtu taksówek osobowych; zaliczki/korekty analogicznie
"p_14_4W": null, // (PDF/P_14_4W) Jak wyżej, ale dla waluty obcej: kwota podatku przeliczona wg Działu VI (art. 106e ust. 11)
"p_13_5": null, // (PDF/P_13_5) Suma wartości sprzedaży netto w procedurze szczególnej (dział XII rozdz. 6a); zaliczki/korekty analogicznie
"p_14_5": null, // (PDF/P_14_5) Kwota podatku od wartości dodanej w procedurze szczególnej (dział XII rozdz. 6a); zaliczki/korekty analogicznie
"p_13_6_1": null, // (PDF/P_13_6_1) Suma wartości sprzedaży objętej stawką 0% z wyłączeniem WDT i eksportu; zaliczki/korekty analogicznie
"p_13_6_2": null, // (PDF/P_13_6_2) Suma wartości sprzedaży objętej stawką 0% w przypadku WDT; korekty: kwota różnicy
"p_13_6_3": null, // (PDF/P_13_6_3) Suma wartości sprzedaży objętej stawką 0% w przypadku eksportu; zaliczki/korekty analogicznie
"p_13_7": null, // (PDF/P_13_7) Suma wartości sprzedaży zwolnionej od podatku; zaliczki/korekty analogicznie
"p_13_8": null, // (PDF/P_13_8) Suma wartości sprzedaży dla dostawy/świadczenia poza terytorium kraju (z wyłączeniami P_13_5 i P_13_9); zaliczki/korekty analogicznie
"p_13_9": null, // (PDF/P_13_9) Suma wartości świadczenia usług z art. 100 ust. 1 pkt 4 ustawy; zaliczki/korekty analogicznie
"p_13_10": null, // (PDF/P_13_10) Suma wartości sprzedaży w procedurze odwrotnego obciążenia (m.in. art. 17 ust. 1 pkt 7 i 8) oraz innych krajowych przypadków; zaliczki/korekty analogicznie
"p_13_11": null, // (PDF/P_13_11) Suma wartości sprzedaży w procedurze marży (art. 119 i 120); zaliczki/korekty analogicznie
"p_15": null // (PDF/P_15) Kwota należności ogółem; dla zaliczek: kwota zapłaty; dla art. 106f ust. 3: kwota pozostała do zapłaty; dla korekt: korekta kwoty(kwot) z faktur korygowanych
},
"ordersExchangeRate": null, // Kurs waluty zamówień
"annotation": {
// Adnotacje
"checkoutMethod": null, // Metoda kasowa
"selfBilling": null, // Samo fakturowanie
"reverseCharge": null, // Odwrotne obciążenie
"splitPaymentMechanism": null, // Mechanizm podzielonej płatności
"provisionOfActForTaxExemption": null, // Przepis ustawy o zwolnieniu z podatku
"provisionOfDirectiveForTaxExemption": null, // Przepis dyrektywy o zwolnieniu z podatku
"anotherLegalBasisForTaxExemption": null, // Inna podstawa prawna do zwolnienia z podatku
"newMeansOfTransport": null, // Wewnątrzwspólnotowe dostawy nowych środków transportu
"obligationToIssueVat22Document": null, // Obowiązek wystawienia dokumentu VAT-22
"simplifiedTripartiteProcedure": null, // Procedura uproszczona
"secondHandGoods": null, // Towary używane
"worksOfArt": null, // Dzieła sztuki
"travelAgencies": null, // Biura podróży
"collectorsAndAntiques": null // Przedmioty kolekcjonerskie i antyki
},
"invoiceType": null, // Rodzaj faktury (enum: "Podstawowa" | "Zaliczkowa" | "Rozliczeniowa" | "Korygująca fakturę podstawową" | "Korygująca fakturę zaliczkową" | "Korygująca fakturę rozliczeniową" | "Uproszczona")
"reasonForCorrection": null, // Przyczyna korekty dla faktur korygujących
"correctionEffectType": null, // Typ skutku korekty (enum: "W dacie ujęcia faktury pierwotnej" | "W dacie wystawienia faktury korygującej" | "W dacie innej")
"correctionInvoiceIdentificationData": [
// Dane identyfikacyjne dla faktury korygowanej
{
"dateOfIssue": null, // Data wystawienia faktury, której dotyczy faktura korygująca
"correctionInvoiceNumber": null, // Numer faktury korygowanej
"kSeFNumberOfCorrectionInvoice": null // Numer KSeF faktury korygowanej
}
],
"correctedInvoicePeriod": null, // Okres, do którego odnosi się udzielany opust lub udzielana obniżka
"correctCorrectionInvoiceNumber": null, // Poprawny numer faktury korygowanej
"correctAmount": null, // Kwota zapłaty/pozostała do zapłaty dla faktury korygującej
"receiptBased": null, // Faktura do paragonu (FP)
"transferPricing": null, // Istniejące powiązania (TP)
"additionalDescription": [
// Dodatkowy opis
{
"invoiceItemNumber": null, // Numer pozycji faktury
"typeOfInformation": null, // Rodzaj informacji
"informationContent": null // Treść informacji
}
],
"advanceInvoices": [
// Faktury zaliczkowe
{
"advanceInvoiceNumber": null, // Numer faktury zaliczkowej wystawionej poza KSeF
"ksefNumberAdvanceInvoice": null // Numer identyfikujący fakturę zaliczkową w KSeF
}
],
"positions": [
// Pozycje
{
"universalUniqueInvoiceLineNumber": null, // Uniwersalny unikalny numer wiersza faktury (UU_ID)
"dateOfDelivery": null, // Data dostawy/wykonania usługi (YYYY-MM-DD)
"name": null, // Nazwa towaru lub usługi
"index": null, // Indeks (wewnętrzny kod towaru lub usługi)
"gtin": null, // GTIN (Globalny Numer Jednostki Handlowej)
"pkwiu": null, // PKWiU (Symbol Polskiej Klasyfikacji Wyrobów i Usług)
"cn": null, // Symbol Nomenklatury Scalonej
"pkob": null, // Symbol Polskiej Klasyfikacji Obiektów Budowlanych
"measure": null, // Miara
"quantity": null, // Ilość
"netUnitPrice": null, // Cena jednostkowa netto
"grossUnitPrice": null, // Cena jednostkowa brutto
"discount": null, // Kwota opustu lub obniżki ceny
"netValue": null, // Wartość netto
"grossValue": null, // Wartość brutto
"taxValue": null, // Wartość podatku
"taxRate": null, // Stawki krajowe podatku VAT (enum: "23","22","8","7","5","4","3","0 KR","0 WDT","0 EX","zw","oo","np I","np II")
"taxRateOss": null, // Stawka podatku OSS
"annex15": null, // Znacznik dla towaru lub usług z załącznika nr 15 do ustawy
"exciseDutyAmount": null, // Kwota podatku akcyzowego zawarta w cenie towaru
"gtu": null, // Symbol GTU (enum: "GTU_01" ... "GTU_13")
"procedure": null, // Oznaczenie procedury (enum: "WSTO_EE","IED","TT_D","I_42","I_63","B_SPV","B_SPV_DOSTAWA","B_MPV_PROWIZJA")
"exchangeRate": null, // Kurs waluty
"beforeRevision": null // Czy stan przed korektą
}
],
"settlement": {
// Rozliczenie
"charges": [
// Obciążenia
{
"amount": null, // Kwota obciążenia
"reason": null // Powód obciążenia
}
],
"deductions": [
// Odliczenia
{
"amount": null, // Kwota odliczenia
"reason": null // Powód odliczenia
}
],
"amountDue": null, // Do zapłaty
"toBeSettled": null // Do rozliczenia
},
"payment": {
// Płatność
"paymentInformation": null, // Informacja o płatności (enum: "Zapłacono" | "Zapłacono całość w częściach" | "Zapłacono w części" | "Brak zapłaty")
"paymentDate": null, // Data zapłaty
"partialPayments": [
// Zapłaty częściowe
{
"partialPaymentDate": null, // Data zapłaty częściowej
"partialPaymentAmount": null, // Kwota zapłaty częściowej
"paymentMethod": null // Forma płatności (enum: "Gotówka","Karta","Bon","Czek","Kredyt","Przelew","Mobilna","Płatność inna")
}
],
"paymentTerms": [
// Terminy płatności
{
"term": null, // Termin płatności
"termDescription": {
// Opis terminu płatności
"quantity": null, // Ilość
"unit": null, // Jednostka
"initialEvent": null // Zdarzenie początkowe
}
}
],
"paymentMethod": null, // Forma płatności (enum: "Gotówka","Karta","Bon","Czek","Kredyt","Przelew","Mobilna","Płatność inna")
"otherPaymentDescription": null, // Opis płatności innej
"bankAccountNumbers": [
// Numery rachunku bankowego
{
"fullAccountNumber": null, // Pełny numer rachunku
"swift": null, // Kod SWIFT
"ownAccountBank": null, // Rachunek własny banku (enum: "Rachunek do rozliczeń wierzytelności nabytych" | "Rachunek do pobierania należności i przekazywania ich dostawcy" | "Rachunek gospodarki własnej, niebędący rozliczeniowym")
"bankName": null, // Nazwa banku
"accountDescription": null // Opis rachunku
}
],
"faktorBankAccountNumbers": [
// Numery rachunku bankowego faktora
{
"fullAccountNumber": null, // Pełny numer rachunku
"swift": null, // Kod SWIFT
"ownAccountBank": null, // Rachunek własny banku
"bankName": null, // Nazwa banku
"accountDescription": null // Opis rachunku
}
],
"skonto": {
// Skonto
"skontoConditions": null, // Warunki skonta
"skontoAmount": null // Wysokość skonta
}
},
"orderTerms": {
// Warunki transakcji
"contracts": [
// Umowy
{
"agreementDate": null, // Data umowy
"contractNumber": null // Numer umowy
}
],
"orders": [
// Zamówienia
{
"orderDate": null, // Data zamówienia
"orderNumber": null // Numer zamówienia
}
],
"batchNumbers": [
// Numery partii towaru
null
],
"contractualRate": null, // Kurs umowny
"contractualCurrency": null, // Waluta umowna
"deliveryTerms": null, // Warunki dostawy
"transport": [
// Transport
{
"transportType": null, // Rodzaj transportu (enum m.in. "Transport morski","Transport kolejowy","Transport drogowy","Transport lotniczy","Przesyłka pocztowa","Stałe instalacje przesyłowe","Żegluga śródlądowa")
"otherTransportDescription": null, // Opis innego środka transportu
"cargoDescription": null, // Opis ładunku (enum m.in. "Paleta","Kontener",...)
"otherCargoDescription": null, // Opis innego ładunku
"packingUnit": null, // Jednostka opakowania
"shipmentFrom": {
// Adres miejsca wysyłki
"countryCode": null, // Kod kraju
"line1": null, // Linia 1 adresu
"line2": null, // Linia 2 adresu
"globalLocationNumber": null // GLN
},
"shipmentVia": [
// Wysyłka przez
{
"countryCode": null, // Kod kraju
"line1": null, // Linia 1 adresu
"line2": null, // Linia 2 adresu
"globalLocationNumber": null // GLN
}
],
"shipmentTo": {
// Adres miejsca docelowego
"countryCode": null, // Kod kraju
"line1": null, // Linia 1 adresu
"line2": null, // Linia 2 adresu
"globalLocationNumber": null // GLN
},
"carrier": {
// Przewoźnik
"taxIdentificationNumber": null, // NIP
"name": null, // Nazwa
"address": {
// Adres
"countryCode": null, // Kod kraju
"line1": null, // Linia 1 adresu
"line2": null, // Linia 2 adresu
"globalLocationNumber": null // GLN
}
}
}
]
},
"orders": [
// Zamówienia (wiersze)
{
"universalUniqueOrderId": null, // Uniwersalny unikalny numer wiersza zamówienia lub umowy (UU_IDZ)
"name": null, // Nazwa towaru lub usługi
"index": null, // Indeks (wewnętrzny kod towaru lub usługi)
"gtin": null, // GTIN
"pkwiu": null, // PKWiU
"cn": null, // CN
"pkob": null, // PKOB
"measure": null, // Miara
"quantity": null, // Ilość
"netUnitPrice": null, // Cena jednostkowa netto
"netValue": null, // Wartość netto
"taxValue": null, // Wartość podatku
"taxRate": null, // Stawki krajowe podatku VAT
"taxRateOss": null, // Stawka podatku OSS
"annex15": null, // Znacznik załącznik nr 15
"gtu": null, // Symbol GTU
"procedure": null, // Oznaczenie procedury
"exciseDutyAmount": null, // Kwota podatku akcyzowego zawarta w cenie towaru
"beforeRevision": null // Czy stan przed korektą
}
]
},
"footer": {
// Stopka
"information": [
// Informacje
{
"footerInvoice": null // Stopka faktury
}
],
"registers": [
// Rejestry
{
"fullName": null, // Pełna nazwa
"krs": null, // KRS
"regon": null, // REGON
"bdo": null // BDO
}
]
}
}
Należy pamiętać, że niektóre wartości muszą należeć do słownika. Poniżej jest lista słowników używanych w komunikacji z KSeF
Kliknij, żeby rozwinąć
{
"NavigatorKSeF_Enums": {
"InvoiceType": [
"Podstawowa",
"Zaliczkowa",
"Rozliczeniowa",
"Korygująca fakturę podstawową",
"Korygująca fakturę zaliczkową",
"Korygująca fakturę rozliczeniową",
"Uproszczona"
],
"TaxRate": [
"23", "22", "8", "7", "5", "4", "3",
"0 KR", "0 WDT", "0 EX", "zw", "oo", "np I", "np II"
],
"Gtu": [
"GTU_01", "GTU_02", "GTU_03", "GTU_04", "GTU_05",
"GTU_06", "GTU_07", "GTU_08", "GTU_09", "GTU_10",
"GTU_11", "GTU_12", "GTU_13"
],
"Procedure": [
"WSTO_EE", "IED", "TT_D", "I_42", "I_63",
"B_SPV", "B_SPV_DOSTAWA", "B_MPV_PROWIZJA"
],
"PaymentMethod": [
"Gotówka", "Karta", "Bon", "Czek", "Kredyt",
"Przelew", "Mobilna", "Płatność inna"
],
"PaymentInformation": [
"Zapłacono", "Zapłacono całość w częściach",
"Zapłacono w części", "Brak zapłaty"
],
"CorrectionEffectType": [
"W dacie ujęcia faktury pierwotnej",
"W dacie wystawienia faktury korygującej",
"W dacie innej"
],
"ThirdPartyRole": [
"Rola inna", "Faktor", "Odbiorca", "Podmiot pierwotny",
"Dodatkowy nabywca", "Wystawca faktury", "Dokonujący płatności",
"JST – wystawca", "JST – odbiorca", "Członek GV – wystawca",
"Członek GV – odbiorca", "Pracownik"
],
"TransportType": [
"Transport morski", "Transport kolejowy", "Transport drogowy",
"Transport lotniczy", "Przesyłka pocztowa",
"Stałe instalacje przesyłowe", "Żegluga śródlądowa"
],
"CargoDescription": [
"Bańka", "Beczka", "Butla", "Karton", "Kanister", "Klatka",
"Kontener", "Kosz/koszyk", "Łubianka", "Opakowanie zbiorcze",
"Paczka", "Pakiet", "Paleta", "Pojemnik",
"Pojemnik do ładunków masowych stałych",
"Pojemnik do ładunków masowych w postaci płynnej",
"Pudełko", "Puszka", "Skrzynia", "Worek"
],
"OwnAccountBank": [
"Rachunek do rozliczeń wierzytelności nabytych",
"Rachunek do pobierania należności i przekazywania ich dostawcy",
"Rachunek gospodarki własnej, niebędący rozliczeniowym"
],
"TaxpayerStatus": [
"W stanie likwidacji",
"W postępowaniu restrukturyzacyjnym",
"W stanie upadłości",
"Przedsiębiorstwo w spadku"
],
"InvoicingMode": [
"online",
"offline"
]
}
}
Send – wysyłka pojedynczej faktury KSeF¶
Metoda: POST
Header:
nip – string zawierający NIP podmiotu wysyłającego fakturę
apiKey – apiKey dla serwisu skojarzony z wystawcą faktury. Api key jest generowany podczas konfiguracji serwisu KSeF
Content-Type: application/json
Jako parametr należy podać json zawierający opis faktury. Składnia jsona jest identyczna jak przy metodzie Generate, można użyć jsona pokazanego w przykładzie powyżej.
Po poprawnym wywołaniu metody serwis zwróci numer sesji KSeF. Ten numer należy gdzieś zachować gdyż służy on np. do pobrania potwierdzenia (UPO).
Batch - wysyłka paczki faktur do KSeF¶
Metoda: POST
Header:
nip – string zawierający NIP podmiotu wysyłającego fakturę
apiKey – apiKey dla serwisu skojarzony z wystawcą faktury. Api key jest generowany podczas konfiguracji serwisu KSeF
Content-Type: multipart/form-data
Jako parametr należy podać plik ZIP zawierający spakowane XML-e faktur.
Po poprawnym wywołaniu metody serwis zwróci numer sesji KSeF. Ten numer należy gdzieś zachować gdyż służy on np. do pobrania potwierdzenia
KSeFNumber - pobranie faktury z KSeF po numerze KSeF¶
Metoda: GET
Header:
nip – string zawierający NIP podmiotu wysyłającego fakturę
apiKey – apiKey dla serwisu skojarzony z wystawcą faktury. Api key jest generowany podczas konfiguracji serwisu KSeF
subjectType - parametr określa dla jakich podmiotów pobierać faktury
Dostępne parametry:
- subject1 - pobierasz faktury, w których NIP (pierwszy parametr) zgadza się z NIP-em sprzedawcy
- subject2 - pobierasz faktury, w których NIP (pierwszy parametr) zgadza się z NIP-em kupującego
- subject3 - pobierasz faktury, w których NIP
- subjectAuthorized - dotyczy faktur które zostały udostępnione/pobrane w kontekście podmiotu uprawnionego (autoryzowanego) — tzn. czy działasz jako podmiot mający nadane uprawnienia do dostępu do faktur danego NIP (np. właściciel podmiotu, pełnomocnik, biuro rachunkowe z nadanym dostępem).
Path:
ksefNumber - numer KSeF faktury, którą chcemy pobrać
Jako rezultat zwracany jest plik XML faktury
Get – pobranie interaktywne faktur z KSeF¶
Metoda: GET
Header:
nip – string zawierający NIP podmiotu wysyłającego fakturę
apiKey – apiKey dla serwisu skojarzony z wystawcą faktury. Api key jest generowany podczas konfiguracji serwisu KSeF
Query:
subjectType - parametr określa dla jakich podmiotów pobierać faktury
Dostępne parametry:
- subject1 - pobierasz faktury, w których NIP (pierwszy parametr) zgadza się z NIP-em sprzedawcy
- subject2 - pobierasz faktury, w których NIP (pierwszy parametr) zgadza się z NIP-em kupującego
- subject3 - pobierasz faktury, w których NIP (pierwszy parametr) zgadza sie z NIP-em podmiotu trzeciego
- subjectAuthorized - dotyczy faktur które zostały udostępnione/pobrane w kontekście podmiotu uprawnionego (autoryzowanego) — tzn. czy działasz jako podmiot mający nadane uprawnienia do dostępu do faktur danego NIP (np. właściciel podmiotu, pełnomocnik, biuro rachunkowe z nadanym dostępem).
from - data i czas od której pobieramy faktury. Data powinna być podana w formacie ISO czyli yyyy-MM-ddTHH:mm:ss.fffz
to - data i czas do której pobieramy faktury. Data powinna być podana w formacie ISO czyli yyyy-MM-ddTHH:mm:ss.fffz
Po poprawnym wywołaniu metody serwis zwróci json z danymi faktury oraz plikiem HTML z obrazem faktury zakodowanym w base64. Poniżej prezentowany jest przykładowy json
Kliknij żeby rozwinąć
[
{
"invoiceSummary": {
"ksefNumber": "9452174401-20260104-01004043B14A-DB",
"invoiceNumber": "Vat/2026/1/3771697e-0de6-4176-86ab-4fd16523e88e",
"issueDate": "2026-01-04T00:00:00+01:00",
"invoicingDate": "2026-01-04T10:52:39.848+00:00",
"acquisitionDate": "2026-01-04T10:52:40.346+00:00",
"permanentStorageDate": "2026-01-04T10:52:40.602441+00:00",
"seller": {
"nip": "9452174401",
"name": "Navigator365"
},
"buyer": {
"identifier": {
"type": "nip",
"value": "6772286732"
},
"name": null
},
"netAmount": 9.99,
"grossAmount": 12.29,
"vatAmount": 2.3,
"currency": "PLN",
"invoicingMode": "online",
"invoiceType": "vat",
"formCode": {
"systemCode": "FA (3)",
"schemaVersion": "1-0E",
"value": "FA"
},
"isSelfInvoicing": false,
"hasAttachment": false,
"invoiceHash": "H+2PJsyNZVemJw49Sy1SisZ+1wWcuOPtOzidLHPmR2g=",
"hashOfCorrectedInvoice": null,
"thirdSubjects": null,
"authorizedSubject": null
},
"invoiceXml": "<?xml version=\"1.0\" encoding=\"utf-8\"?><Faktura xmlns:xsi=\"http://www.w3.org/2001/XMLSchema-instance\" xmlns:xsd=\"http://www.w3.org/2001/XMLSchema\" xmlns=\"http://crd.gov.pl/wzor/2025/06/25/13775/\"><Naglowek><KodFormularza kodSystemowy=\"FA (3)\" wersjaSchemy=\"1-0E\">FA</KodFormularza><WariantFormularza>3</WariantFormularza><DataWytworzeniaFa>2026-01-04T11:52:38Z</DataWytworzeniaFa><SystemInfo>Navigator</SystemInfo></Naglowek><Podmiot1><DaneIdentyfikacyjne><NIP>9452174401</NIP><Nazwa>Navigator365</Nazwa></DaneIdentyfikacyjne><Adres><KodKraju>PL</KodKraju><AdresL1>ul. Test-Krucza 17, 31-150 Kraków</AdresL1></Adres></Podmiot1><Podmiot2><DaneIdentyfikacyjne><NIP>6772286732</NIP></DaneIdentyfikacyjne><Adres><KodKraju>PL</KodKraju><AdresL1>ul. Test-Krucza 17, 31-150 Kraków</AdresL1></Adres><JST>2</JST><GV>2</GV></Podmiot2><Fa><KodWaluty>PLN</KodWaluty><P_1>2026-01-04</P_1><P_2>Vat/2026/1/3771697e-0de6-4176-86ab-4fd16523e88e</P_2><P_13_1>9.99</P_13_1><P_14_1>2.3</P_14_1><P_15>12.29</P_15><Adnotacje><P_16>2</P_16><P_17>2</P_17><P_18>2</P_18><P_18A>2</P_18A><Zwolnienie><P_19N>1</P_19N></Zwolnienie><NoweSrodkiTransportu><P_22N>1</P_22N></NoweSrodkiTransportu><P_23>2</P_23><PMarzy><P_PMarzyN>1</P_PMarzyN></PMarzy></Adnotacje><RodzajFaktury>VAT</RodzajFaktury><FaWiersz><NrWierszaFa>1</NrWierszaFa><P_7>Towar</P_7><P_8A>sztuka</P_8A><P_8B>1</P_8B><P_9A>9.99</P_9A><P_11>9.99</P_11><P_12>23</P_12></FaWiersz></Fa></Faktura>"
},
{
"invoiceSummary": {
"ksefNumber": "9452174401-20260104-0100C090B14A-43",
"invoiceNumber": "Vat/2026/1/e506e481-d21a-4890-8400-913290574674",
"issueDate": "2026-01-04T00:00:00+01:00",
"invoicingDate": "2026-01-04T10:52:40.776+00:00",
"acquisitionDate": "2026-01-04T10:52:40.966+00:00",
"permanentStorageDate": "2026-01-04T10:52:41.085836+00:00",
"seller": {
"nip": "9452174401",
"name": "Navigator365"
},
"buyer": {
"identifier": {
"type": "nip",
"value": "6772286732"
},
"name": null
},
"netAmount": 9.99,
"grossAmount": 12.29,
"vatAmount": 2.3,
"currency": "PLN",
"invoicingMode": "online",
"invoiceType": "vat",
"formCode": {
"systemCode": "FA (3)",
"schemaVersion": "1-0E",
"value": "FA"
},
"isSelfInvoicing": false,
"hasAttachment": false,
"invoiceHash": "CUZzVYDkW9HBW0Pbqyre3Vg4egk9flMcMyjieYV5Lj0=",
"hashOfCorrectedInvoice": null,
"thirdSubjects": null,
"authorizedSubject": null
},
"invoiceXml": "<?xml version=\"1.0\" encoding=\"utf-8\"?><Faktura xmlns:xsi=\"http://www.w3.org/2001/XMLSchema-instance\" xmlns:xsd=\"http://www.w3.org/2001/XMLSchema\" xmlns=\"http://crd.gov.pl/wzor/2025/06/25/13775/\"><Naglowek><KodFormularza kodSystemowy=\"FA (3)\" wersjaSchemy=\"1-0E\">FA</KodFormularza><WariantFormularza>3</WariantFormularza><DataWytworzeniaFa>2026-01-04T11:52:38Z</DataWytworzeniaFa><SystemInfo>Navigator</SystemInfo></Naglowek><Podmiot1><DaneIdentyfikacyjne><NIP>9452174401</NIP><Nazwa>Navigator365</Nazwa></DaneIdentyfikacyjne><Adres><KodKraju>PL</KodKraju><AdresL1>ul. Test-Krucza 17, 31-150 Kraków</AdresL1></Adres></Podmiot1><Podmiot2><DaneIdentyfikacyjne><NIP>6772286732</NIP></DaneIdentyfikacyjne><Adres><KodKraju>PL</KodKraju><AdresL1>ul. Test-Krucza 17, 31-150 Kraków</AdresL1></Adres><JST>2</JST><GV>2</GV></Podmiot2><Fa><KodWaluty>PLN</KodWaluty><P_1>2026-01-04</P_1><P_2>Vat/2026/1/3771697e-0de6-4176-86ab-4fd16523e88e</P_2><P_13_1>9.99</P_13_1><P_14_1>2.3</P_14_1><P_15>12.29</P_15><Adnotacje><P_16>2</P_16><P_17>2</P_17><P_18>2</P_18><P_18A>2</P_18A><Zwolnienie><P_19N>1</P_19N></Zwolnienie><NoweSrodkiTransportu><P_22N>1</P_22N></NoweSrodkiTransportu><P_23>2</P_23><PMarzy><P_PMarzyN>1</P_PMarzyN></PMarzy></Adnotacje><RodzajFaktury>VAT</RodzajFaktury><FaWiersz><NrWierszaFa>1</NrWierszaFa><P_7>Towar</P_7><P_8A>sztuka</P_8A><P_8B>1</P_8B><P_9A>9.99</P_9A><P_11>9.99</P_11><P_12>23</P_12></FaWiersz></Fa></Faktura>"
}
]
Jak można zauważyć w przykładzie, przesłane dane są tablicą dokumentów. W jednym wywołaniu możemy otrzymać kilka dokumentów faktur dlatego przy pobieraniu faktur w systemie, w procesie pobierania powinniśmy skorzystać z pętli po elementach jsona i dla każdego rekordu utworzyć jeden dokument. Przykład takiego procesu opisany jest w tym dokumencie .
Export - pobieranie wsadowe faktur z KSeF¶
Metoda: GET
Header:
nip – string zawierający NIP podmiotu wysyłającego fakturę
apiKey – apiKey dla serwisu skojarzony z wystawcą faktury. Api key jest generowany podczas konfiguracji serwisu KSeF
Query:
subjectType - parametr określa dla jakich podmiotów pobierać faktury
Dostępne parametry:
- subject1 - pobierasz faktury, w których NIP (pierwszy parametr) zgadza się z NIP-em sprzedawcy
- subject2 - pobierasz faktury, w których NIP (pierwszy parametr) zgadza się z NIP-em kupującego
- subject3 - pobierasz faktury, w których NIP (pierwszy parametr) zgadza sie z NIP-em podmiotu trzeciego
- subjectAuthorized - dotyczy faktur które zostały udostępnione/pobrane w kontekście podmiotu uprawnionego (autoryzowanego) — tzn. czy działasz jako podmiot mający nadane uprawnienia do dostępu do faktur danego NIP (np. właściciel podmiotu, pełnomocnik, biuro rachunkowe z nadanym dostępem).
from - data i czas od której pobieramy faktury. Data powinna być podana w formacie ISO czyli yyyy-MM-ddTHH:mm:ss.fffz
to - data i czas do której pobieramy faktury. Data powinna być podana w formacie ISO czyli yyyy-MM-ddTHH:mm:ss.fffz
Po poprawnym wywołaniu metody serwis zwróci json z danymi faktury. W jsonie zawarty jest XML faktury, który należy później przetworzyć przy pomocy metody process. Poniżej prezentowany jest przykładowy json z fakturą
Kliknij żeby rozwinąć
[
{
"invoiceSummary": {
"ksefNumber": "9452174401-20260104-01004043B14A-DB",
"invoiceNumber": "Vat/2026/1/3771697e-0de6-4176-86ab-4fd16523e88e",
"issueDate": "2026-01-04T00:00:00+01:00",
"invoicingDate": "2026-01-04T10:52:39.848+00:00",
"acquisitionDate": "2026-01-04T10:52:40.346+00:00",
"permanentStorageDate": "2026-01-04T10:52:40.602441+00:00",
"seller": {
"nip": "9452174401",
"name": "Navigator365"
},
"buyer": {
"identifier": {
"type": "nip",
"value": "6772286732"
},
"name": null
},
"netAmount": 9.99,
"grossAmount": 12.29,
"vatAmount": 2.3,
"currency": "PLN",
"invoicingMode": "online",
"invoiceType": "vat",
"formCode": {
"systemCode": "FA (3)",
"schemaVersion": "1-0E",
"value": "FA"
},
"isSelfInvoicing": false,
"hasAttachment": false,
"invoiceHash": "H+2PJsyNZVemJw49Sy1SisZ+1wWcuOPtOzidLHPmR2g=",
"hashOfCorrectedInvoice": null,
"thirdSubjects": null,
"authorizedSubject": null
},
"invoiceXml": "<?xml version=\"1.0\" encoding=\"utf-8\"?><Faktura xmlns:xsi=\"http://www.w3.org/2001/XMLSchema-instance\" xmlns:xsd=\"http://www.w3.org/2001/XMLSchema\" xmlns=\"http://crd.gov.pl/wzor/2025/06/25/13775/\"><Naglowek><KodFormularza kodSystemowy=\"FA (3)\" wersjaSchemy=\"1-0E\">FA</KodFormularza><WariantFormularza>3</WariantFormularza><DataWytworzeniaFa>2026-01-04T11:52:38Z</DataWytworzeniaFa><SystemInfo>Navigator</SystemInfo></Naglowek><Podmiot1><DaneIdentyfikacyjne><NIP>9452174401</NIP><Nazwa>Navigator365</Nazwa></DaneIdentyfikacyjne><Adres><KodKraju>PL</KodKraju><AdresL1>ul. Test-Krucza 17, 31-150 Kraków</AdresL1></Adres></Podmiot1><Podmiot2><DaneIdentyfikacyjne><NIP>6772286732</NIP></DaneIdentyfikacyjne><Adres><KodKraju>PL</KodKraju><AdresL1>ul. Test-Krucza 17, 31-150 Kraków</AdresL1></Adres><JST>2</JST><GV>2</GV></Podmiot2><Fa><KodWaluty>PLN</KodWaluty><P_1>2026-01-04</P_1><P_2>Vat/2026/1/3771697e-0de6-4176-86ab-4fd16523e88e</P_2><P_13_1>9.99</P_13_1><P_14_1>2.3</P_14_1><P_15>12.29</P_15><Adnotacje><P_16>2</P_16><P_17>2</P_17><P_18>2</P_18><P_18A>2</P_18A><Zwolnienie><P_19N>1</P_19N></Zwolnienie><NoweSrodkiTransportu><P_22N>1</P_22N></NoweSrodkiTransportu><P_23>2</P_23><PMarzy><P_PMarzyN>1</P_PMarzyN></PMarzy></Adnotacje><RodzajFaktury>VAT</RodzajFaktury><FaWiersz><NrWierszaFa>1</NrWierszaFa><P_7>Towar</P_7><P_8A>sztuka</P_8A><P_8B>1</P_8B><P_9A>9.99</P_9A><P_11>9.99</P_11><P_12>23</P_12></FaWiersz></Fa></Faktura>"
},
{
"invoiceSummary": {
"ksefNumber": "9452174401-20260104-0100C090B14A-43",
"invoiceNumber": "Vat/2026/1/e506e481-d21a-4890-8400-913290574674",
"issueDate": "2026-01-04T00:00:00+01:00",
"invoicingDate": "2026-01-04T10:52:40.776+00:00",
"acquisitionDate": "2026-01-04T10:52:40.966+00:00",
"permanentStorageDate": "2026-01-04T10:52:41.085836+00:00",
"seller": {
"nip": "9452174401",
"name": "Navigator365"
},
"buyer": {
"identifier": {
"type": "nip",
"value": "6772286732"
},
"name": null
},
"netAmount": 9.99,
"grossAmount": 12.29,
"vatAmount": 2.3,
"currency": "PLN",
"invoicingMode": "online",
"invoiceType": "vat",
"formCode": {
"systemCode": "FA (3)",
"schemaVersion": "1-0E",
"value": "FA"
},
"isSelfInvoicing": false,
"hasAttachment": false,
"invoiceHash": "CUZzVYDkW9HBW0Pbqyre3Vg4egk9flMcMyjieYV5Lj0=",
"hashOfCorrectedInvoice": null,
"thirdSubjects": null,
"authorizedSubject": null
},
"invoiceXml": "<?xml version=\"1.0\" encoding=\"utf-8\"?><Faktura xmlns:xsi=\"http://www.w3.org/2001/XMLSchema-instance\" xmlns:xsd=\"http://www.w3.org/2001/XMLSchema\" xmlns=\"http://crd.gov.pl/wzor/2025/06/25/13775/\"><Naglowek><KodFormularza kodSystemowy=\"FA (3)\" wersjaSchemy=\"1-0E\">FA</KodFormularza><WariantFormularza>3</WariantFormularza><DataWytworzeniaFa>2026-01-04T11:52:38Z</DataWytworzeniaFa><SystemInfo>Navigator</SystemInfo></Naglowek><Podmiot1><DaneIdentyfikacyjne><NIP>9452174401</NIP><Nazwa>Navigator365</Nazwa></DaneIdentyfikacyjne><Adres><KodKraju>PL</KodKraju><AdresL1>ul. Test-Krucza 17, 31-150 Kraków</AdresL1></Adres></Podmiot1><Podmiot2><DaneIdentyfikacyjne><NIP>6772286732</NIP></DaneIdentyfikacyjne><Adres><KodKraju>PL</KodKraju><AdresL1>ul. Test-Krucza 17, 31-150 Kraków</AdresL1></Adres><JST>2</JST><GV>2</GV></Podmiot2><Fa><KodWaluty>PLN</KodWaluty><P_1>2026-01-04</P_1><P_2>Vat/2026/1/3771697e-0de6-4176-86ab-4fd16523e88e</P_2><P_13_1>9.99</P_13_1><P_14_1>2.3</P_14_1><P_15>12.29</P_15><Adnotacje><P_16>2</P_16><P_17>2</P_17><P_18>2</P_18><P_18A>2</P_18A><Zwolnienie><P_19N>1</P_19N></Zwolnienie><NoweSrodkiTransportu><P_22N>1</P_22N></NoweSrodkiTransportu><P_23>2</P_23><PMarzy><P_PMarzyN>1</P_PMarzyN></PMarzy></Adnotacje><RodzajFaktury>VAT</RodzajFaktury><FaWiersz><NrWierszaFa>1</NrWierszaFa><P_7>Towar</P_7><P_8A>sztuka</P_8A><P_8B>1</P_8B><P_9A>9.99</P_9A><P_11>9.99</P_11><P_12>23</P_12></FaWiersz></Fa></Faktura>"
}
]
Process - przetwarzanie pliku XML do jsona¶
Metoda: POST
Content-Type: multipart/form-data
Jako parametr należy podać plik XML zawierający dane faktury.
Po poprawnym wywołaniu metody serwis zwróci json z zawartoscia faktury. Ten json może byc użyty w akcji Zmień wartość pola do wypełnienia pól formularza.
Przykładowy wygląd pliku json:
Kliknij żeby rozwinąć
{
"seller": {
// Sprzedawca
"taxpayerPrefix": null, // Kod (prefiks) podatnika VAT UE
"eoriNumber": null, // Numer w Unijnym Systemie Rejestracji i Identyfikacji Podmiotów Gospodarczych (EORI)
"taxIdentificationNumber": null, // NIP
"name": null, // Nazwa
"address": {
// Adres
"countryCode": null, // Kod kraju
"line1": null, // Linia 1 adresu
"line2": null, // Linia 2 adresu
"globalLocationNumber": null // Globalny Numer Lokalizacyjny (GLN)
},
"mailingAddress": {
// Adres (korespondencyjny)
"countryCode": null, // Kod kraju
"line1": null, // Linia 1 adresu
"line2": null, // Linia 2 adresu
"globalLocationNumber": null // Globalny Numer Lokalizacyjny (GLN)
},
"contactDetails": [
// Dane kontaktowe
{
"phoneNumber": null, // Numer telefonu
"emailAddress": null // Adres e-mail
}
],
"taxpayerStatus": null // Status podatnika (enum: "W stanie likwidacji" | "W postępowaniu restrukturyzacyjnym" | "W stanie upadłości" | "Przedsiębiorstwo w spadku")
},
"buyer": {
// Nabywca
"eoriNumber": null, // Numer w Unijnym Systemie Rejestracji i Identyfikacji Podmiotów Gospodarczych (EORI)
"taxIdentificationNumber": null, // NIP
"euCode": null, // Kod (prefiks) nabywcy VAT UE
"euVatNumber": null, // Numer identyfikacyjny VAT nabywcy
"countryCode": null, // Kod kraju nadania innego identyfikatora podatkowego
"idNumber": null, // Identyfikator podatkowy inny niż NIP oraz numer VAT UE
"name": null, // Nazwa
"address": {
// Adres
"countryCode": null, // Kod kraju
"line1": null, // Linia 1 adresu
"line2": null, // Linia 2 adresu
"globalLocationNumber": null // Globalny Numer Lokalizacyjny (GLN)
},
"mailingAddress": {
// Adres (korespondencyjny)
"countryCode": null, // Kod kraju
"line1": null, // Linia 1 adresu
"line2": null, // Linia 2 adresu
"globalLocationNumber": null // Globalny Numer Lokalizacyjny (GLN)
},
"contactDetails": [
// Dane kontaktowe
{
"phoneNumber": null, // Numer telefonu
"emailAddress": null // Adres e-mail
}
],
"customerNumber": null, // Numer klienta
"localGovernmentUnit": null, // Jednostka samorządu terytorialnego (JST)
"memberOfVatGroup": null // Członek grupy VAT (GV)
},
"thirdParties": [
// Strony trzecie
{
"eoriNumber": null, // Numer w Unijnym Systemie Rejestracji i Identyfikacji Podmiotów Gospodarczych (EORI)
"taxIdentificationNumber": null, // NIP
"internalId": null, // Identyfikator wewnętrzny z NIP
"euCode": null, // Kod (prefiks) nabywcy VAT UE
"euVatNumber": null, // Numer identyfikacyjny VAT nabywcy
"countryCode": null, // Kod kraju nadania innego identyfikatora podatkowego
"idNumber": null, // Identyfikator podatkowy inny niż NIP oraz numer VAT UE
"name": null, // Nazwa
"address": {
// Adres
"countryCode": null, // Kod kraju
"line1": null, // Linia 1 adresu
"line2": null, // Linia 2 adresu
"globalLocationNumber": null // Globalny Numer Lokalizacyjny (GLN)
},
"mailingAddress": {
// Adres (korespondencyjny)
"countryCode": null, // Kod kraju
"line1": null, // Linia 1 adresu
"line2": null, // Linia 2 adresu
"globalLocationNumber": null // Globalny Numer Lokalizacyjny (GLN)
},
"contactDetails": [
// Dane kontaktowe
{
"phoneNumber": null, // Numer telefonu
"emailAddress": null // Adres e-mail
}
],
"role": {
// Rola
"thirdPartyRole": null, // Role strony trzeciej (enum m.in. "Faktor", "Odbiorca", "Wystawca faktury", "Dokonujący płatności", "Rola inna", ...)
"roleDescription": null, // Opis roli
"share": null // Udział
},
"customerNumber": null // Numer klienta
}
],
"general": {
// Ogólne
"currencyCode": null, // Kod waluty
"dateOfIssue": null, // Data wystawienia (YYYY-MM-DD)
"placeOfInvoiceIssuance": null, // Miejsce wystawienia faktury
"nextInvoiceNumber": null, // Kolejny numer faktury
"warehouseDocumentNumbers": [
// Numery dokumentów magazynowych
null
],
"dateOfDelivery": null, // Data dostawy/wykonania usługi (YYYY-MM-DD)
"periodStartDate": null, // Data początkowa okresu
"periodEndDate": null, // Data końcowa okresu
"values": {
// Wartości
"p_13_1": null, // (PDF/P_13_1) Suma wartości sprzedaży netto ze stawką podstawową (aktualnie 23% albo 22%); dla zaliczek: kwota zaliczki netto; dla korekt: kwota różnicy (art. 106j ust. 2 pkt 5)
"p_14_1": null, // (PDF/P_14_1) Kwota podatku od sumy sprzedaży netto ze stawką podstawową (23%/22%); dla zaliczek: wg wzoru z art. 106f ust. 1 pkt 3; dla korekt: kwota różnicy
"p_14_1W": null, // (PDF/P_14_1W) Jak wyżej, ale dla waluty obcej: kwota podatku przeliczona wg Działu VI (art. 106e ust. 11)
"p_13_2": null, // (PDF/P_13_2) Suma wartości sprzedaży netto ze stawką obniżoną pierwszą (aktualnie 8% albo 7%); zaliczki/korekty analogicznie
"p_14_2": null, // (PDF/P_14_2) Kwota podatku od sumy sprzedaży netto ze stawką 8%/7%; zaliczki/korekty analogicznie
"p_14_2W": null, // (PDF/P_14_2W) Jak wyżej, ale dla waluty obcej: kwota podatku przeliczona wg Działu VI (art. 106e ust. 11)
"p_13_3": null, // (PDF/P_13_3) Suma wartości sprzedaży netto ze stawką obniżoną drugą (aktualnie 5%); zaliczki/korekty analogicznie
"p_14_3": null, // (PDF/P_14_3) Kwota podatku od sumy sprzedaży netto ze stawką 5%; zaliczki/korekty analogicznie
"p_14_3W": null, // (PDF/P_14_3W) Jak wyżej, ale dla waluty obcej: kwota podatku przeliczona wg Działu VI (art. 106e ust. 11)
"p_13_4": null, // (PDF/P_13_4) Suma wartości sprzedaży netto objętej ryczałtem dla taksówek osobowych; zaliczki/korekty analogicznie
"p_14_4": null, // (PDF/P_14_4) Kwota podatku od sumy sprzedaży netto dla ryczałtu taksówek osobowych; zaliczki/korekty analogicznie
"p_14_4W": null, // (PDF/P_14_4W) Jak wyżej, ale dla waluty obcej: kwota podatku przeliczona wg Działu VI (art. 106e ust. 11)
"p_13_5": null, // (PDF/P_13_5) Suma wartości sprzedaży netto w procedurze szczególnej (dział XII rozdz. 6a); zaliczki/korekty analogicznie
"p_14_5": null, // (PDF/P_14_5) Kwota podatku od wartości dodanej w procedurze szczególnej (dział XII rozdz. 6a); zaliczki/korekty analogicznie
"p_13_6_1": null, // (PDF/P_13_6_1) Suma wartości sprzedaży objętej stawką 0% z wyłączeniem WDT i eksportu; zaliczki/korekty analogicznie
"p_13_6_2": null, // (PDF/P_13_6_2) Suma wartości sprzedaży objętej stawką 0% w przypadku WDT; korekty: kwota różnicy
"p_13_6_3": null, // (PDF/P_13_6_3) Suma wartości sprzedaży objętej stawką 0% w przypadku eksportu; zaliczki/korekty analogicznie
"p_13_7": null, // (PDF/P_13_7) Suma wartości sprzedaży zwolnionej od podatku; zaliczki/korekty analogicznie
"p_13_8": null, // (PDF/P_13_8) Suma wartości sprzedaży dla dostawy/świadczenia poza terytorium kraju (z wyłączeniami P_13_5 i P_13_9); zaliczki/korekty analogicznie
"p_13_9": null, // (PDF/P_13_9) Suma wartości świadczenia usług z art. 100 ust. 1 pkt 4 ustawy; zaliczki/korekty analogicznie
"p_13_10": null, // (PDF/P_13_10) Suma wartości sprzedaży w procedurze odwrotnego obciążenia (m.in. art. 17 ust. 1 pkt 7 i 8) oraz innych krajowych przypadków; zaliczki/korekty analogicznie
"p_13_11": null, // (PDF/P_13_11) Suma wartości sprzedaży w procedurze marży (art. 119 i 120); zaliczki/korekty analogicznie
"p_15": null // (PDF/P_15) Kwota należności ogółem; dla zaliczek: kwota zapłaty; dla art. 106f ust. 3: kwota pozostała do zapłaty; dla korekt: korekta kwoty(kwot) z faktur korygowanych
},
"ordersExchangeRate": null, // Kurs waluty zamówień
"annotation": {
// Adnotacje
"checkoutMethod": null, // Metoda kasowa
"selfBilling": null, // Samo fakturowanie
"reverseCharge": null, // Odwrotne obciążenie
"splitPaymentMechanism": null, // Mechanizm podzielonej płatności
"provisionOfActForTaxExemption": null, // Przepis ustawy o zwolnieniu z podatku
"provisionOfDirectiveForTaxExemption": null, // Przepis dyrektywy o zwolnieniu z podatku
"anotherLegalBasisForTaxExemption": null, // Inna podstawa prawna do zwolnienia z podatku
"newMeansOfTransport": null, // Wewnątrzwspólnotowe dostawy nowych środków transportu
"obligationToIssueVat22Document": null, // Obowiązek wystawienia dokumentu VAT-22
"simplifiedTripartiteProcedure": null, // Procedura uproszczona
"secondHandGoods": null, // Towary używane
"worksOfArt": null, // Dzieła sztuki
"travelAgencies": null, // Biura podróży
"collectorsAndAntiques": null // Przedmioty kolekcjonerskie i antyki
},
"invoiceType": null, // Rodzaj faktury (enum: "Podstawowa" | "Zaliczkowa" | "Rozliczeniowa" | "Korygująca fakturę podstawową" | "Korygująca fakturę zaliczkową" | "Korygująca fakturę rozliczeniową" | "Uproszczona")
"reasonForCorrection": null, // Przyczyna korekty dla faktur korygujących
"correctionEffectType": null, // Typ skutku korekty (enum: "W dacie ujęcia faktury pierwotnej" | "W dacie wystawienia faktury korygującej" | "W dacie innej")
"correctionInvoiceIdentificationData": [
// Dane identyfikacyjne dla faktury korygowanej
{
"dateOfIssue": null, // Data wystawienia faktury, której dotyczy faktura korygująca
"correctionInvoiceNumber": null, // Numer faktury korygowanej
"kSeFNumberOfCorrectionInvoice": null // Numer KSeF faktury korygowanej
}
],
"correctedInvoicePeriod": null, // Okres, do którego odnosi się udzielany opust lub udzielana obniżka
"correctCorrectionInvoiceNumber": null, // Poprawny numer faktury korygowanej
"correctAmount": null, // Kwota zapłaty/pozostała do zapłaty dla faktury korygującej
"receiptBased": null, // Faktura do paragonu (FP)
"transferPricing": null, // Istniejące powiązania (TP)
"additionalDescription": [
// Dodatkowy opis
{
"invoiceItemNumber": null, // Numer pozycji faktury
"typeOfInformation": null, // Rodzaj informacji
"informationContent": null // Treść informacji
}
],
"advanceInvoices": [
// Faktury zaliczkowe
{
"advanceInvoiceNumber": null, // Numer faktury zaliczkowej wystawionej poza KSeF
"ksefNumberAdvanceInvoice": null // Numer identyfikujący fakturę zaliczkową w KSeF
}
],
"positions": [
// Pozycje
{
"universalUniqueInvoiceLineNumber": null, // Uniwersalny unikalny numer wiersza faktury (UU_ID)
"dateOfDelivery": null, // Data dostawy/wykonania usługi (YYYY-MM-DD)
"name": null, // Nazwa towaru lub usługi
"index": null, // Indeks (wewnętrzny kod towaru lub usługi)
"gtin": null, // GTIN (Globalny Numer Jednostki Handlowej)
"pkwiu": null, // PKWiU (Symbol Polskiej Klasyfikacji Wyrobów i Usług)
"cn": null, // Symbol Nomenklatury Scalonej
"pkob": null, // Symbol Polskiej Klasyfikacji Obiektów Budowlanych
"measure": null, // Miara
"quantity": null, // Ilość
"netUnitPrice": null, // Cena jednostkowa netto
"grossUnitPrice": null, // Cena jednostkowa brutto
"discount": null, // Kwota opustu lub obniżki ceny
"netValue": null, // Wartość netto
"grossValue": null, // Wartość brutto
"taxValue": null, // Wartość podatku
"taxRate": null, // Stawki krajowe podatku VAT (enum: "23","22","8","7","5","4","3","0 KR","0 WDT","0 EX","zw","oo","np I","np II")
"taxRateOss": null, // Stawka podatku OSS
"annex15": null, // Znacznik dla towaru lub usług z załącznika nr 15 do ustawy
"exciseDutyAmount": null, // Kwota podatku akcyzowego zawarta w cenie towaru
"gtu": null, // Symbol GTU (enum: "GTU_01" ... "GTU_13")
"procedure": null, // Oznaczenie procedury (enum: "WSTO_EE","IED","TT_D","I_42","I_63","B_SPV","B_SPV_DOSTAWA","B_MPV_PROWIZJA")
"exchangeRate": null, // Kurs waluty
"beforeRevision": null // Czy stan przed korektą
}
],
"settlement": {
// Rozliczenie
"charges": [
// Obciążenia
{
"amount": null, // Kwota obciążenia
"reason": null // Powód obciążenia
}
],
"deductions": [
// Odliczenia
{
"amount": null, // Kwota odliczenia
"reason": null // Powód odliczenia
}
],
"amountDue": null, // Do zapłaty
"toBeSettled": null // Do rozliczenia
},
"payment": {
// Płatność
"paymentInformation": null, // Informacja o płatności (enum: "Zapłacono" | "Zapłacono całość w częściach" | "Zapłacono w części" | "Brak zapłaty")
"paymentDate": null, // Data zapłaty
"partialPayments": [
// Zapłaty częściowe
{
"partialPaymentDate": null, // Data zapłaty częściowej
"partialPaymentAmount": null, // Kwota zapłaty częściowej
"paymentMethod": null // Forma płatności (enum: "Gotówka","Karta","Bon","Czek","Kredyt","Przelew","Mobilna","Płatność inna")
}
],
"paymentTerms": [
// Terminy płatności
{
"term": null, // Termin płatności
"termDescription": {
// Opis terminu płatności
"quantity": null, // Ilość
"unit": null, // Jednostka
"initialEvent": null // Zdarzenie początkowe
}
}
],
"paymentMethod": null, // Forma płatności (enum: "Gotówka","Karta","Bon","Czek","Kredyt","Przelew","Mobilna","Płatność inna")
"otherPaymentDescription": null, // Opis płatności innej
"bankAccountNumbers": [
// Numery rachunku bankowego
{
"fullAccountNumber": null, // Pełny numer rachunku
"swift": null, // Kod SWIFT
"ownAccountBank": null, // Rachunek własny banku (enum: "Rachunek do rozliczeń wierzytelności nabytych" | "Rachunek do pobierania należności i przekazywania ich dostawcy" | "Rachunek gospodarki własnej, niebędący rozliczeniowym")
"bankName": null, // Nazwa banku
"accountDescription": null // Opis rachunku
}
],
"faktorBankAccountNumbers": [
// Numery rachunku bankowego faktora
{
"fullAccountNumber": null, // Pełny numer rachunku
"swift": null, // Kod SWIFT
"ownAccountBank": null, // Rachunek własny banku
"bankName": null, // Nazwa banku
"accountDescription": null // Opis rachunku
}
],
"skonto": {
// Skonto
"skontoConditions": null, // Warunki skonta
"skontoAmount": null // Wysokość skonta
}
},
"orderTerms": {
// Warunki transakcji
"contracts": [
// Umowy
{
"agreementDate": null, // Data umowy
"contractNumber": null // Numer umowy
}
],
"orders": [
// Zamówienia
{
"orderDate": null, // Data zamówienia
"orderNumber": null // Numer zamówienia
}
],
"batchNumbers": [
// Numery partii towaru
null
],
"contractualRate": null, // Kurs umowny
"contractualCurrency": null, // Waluta umowna
"deliveryTerms": null, // Warunki dostawy
"transport": [
// Transport
{
"transportType": null, // Rodzaj transportu (enum m.in. "Transport morski","Transport kolejowy","Transport drogowy","Transport lotniczy","Przesyłka pocztowa","Stałe instalacje przesyłowe","Żegluga śródlądowa")
"otherTransportDescription": null, // Opis innego środka transportu
"cargoDescription": null, // Opis ładunku (enum m.in. "Paleta","Kontener",...)
"otherCargoDescription": null, // Opis innego ładunku
"packingUnit": null, // Jednostka opakowania
"shipmentFrom": {
// Adres miejsca wysyłki
"countryCode": null, // Kod kraju
"line1": null, // Linia 1 adresu
"line2": null, // Linia 2 adresu
"globalLocationNumber": null // GLN
},
"shipmentVia": [
// Wysyłka przez
{
"countryCode": null, // Kod kraju
"line1": null, // Linia 1 adresu
"line2": null, // Linia 2 adresu
"globalLocationNumber": null // GLN
}
],
"shipmentTo": {
// Adres miejsca docelowego
"countryCode": null, // Kod kraju
"line1": null, // Linia 1 adresu
"line2": null, // Linia 2 adresu
"globalLocationNumber": null // GLN
},
"carrier": {
// Przewoźnik
"taxIdentificationNumber": null, // NIP
"name": null, // Nazwa
"address": {
// Adres
"countryCode": null, // Kod kraju
"line1": null, // Linia 1 adresu
"line2": null, // Linia 2 adresu
"globalLocationNumber": null // GLN
}
}
}
]
},
"orders": [
// Zamówienia (wiersze)
{
"universalUniqueOrderId": null, // Uniwersalny unikalny numer wiersza zamówienia lub umowy (UU_IDZ)
"name": null, // Nazwa towaru lub usługi
"index": null, // Indeks (wewnętrzny kod towaru lub usługi)
"gtin": null, // GTIN
"pkwiu": null, // PKWiU
"cn": null, // CN
"pkob": null, // PKOB
"measure": null, // Miara
"quantity": null, // Ilość
"netUnitPrice": null, // Cena jednostkowa netto
"netValue": null, // Wartość netto
"taxValue": null, // Wartość podatku
"taxRate": null, // Stawki krajowe podatku VAT
"taxRateOss": null, // Stawka podatku OSS
"annex15": null, // Znacznik załącznik nr 15
"gtu": null, // Symbol GTU
"procedure": null, // Oznaczenie procedury
"exciseDutyAmount": null, // Kwota podatku akcyzowego zawarta w cenie towaru
"beforeRevision": null // Czy stan przed korektą
}
]
},
"footer": {
// Stopka
"information": [
// Informacje
{
"footerInvoice": null // Stopka faktury
}
],
"registers": [
// Rejestry
{
"fullName": null, // Pełna nazwa
"krs": null, // KRS
"regon": null, // REGON
"bdo": null // BDO
}
]
}
}
Należy pamiętać, że niektóre wartości muszą należeć do słownika. Poniżej jest lista słowników używanych w komunikacji z KSeF
Kliknij, żeby rozwinąć
{
"NavigatorKSeF_Enums": {
"InvoiceType": [
"Podstawowa",
"Zaliczkowa",
"Rozliczeniowa",
"Korygująca fakturę podstawową",
"Korygująca fakturę zaliczkową",
"Korygująca fakturę rozliczeniową",
"Uproszczona"
],
"TaxRate": [
"23", "22", "8", "7", "5", "4", "3",
"0 KR", "0 WDT", "0 EX", "zw", "oo", "np I", "np II"
],
"Gtu": [
"GTU_01", "GTU_02", "GTU_03", "GTU_04", "GTU_05",
"GTU_06", "GTU_07", "GTU_08", "GTU_09", "GTU_10",
"GTU_11", "GTU_12", "GTU_13"
],
"Procedure": [
"WSTO_EE", "IED", "TT_D", "I_42", "I_63",
"B_SPV", "B_SPV_DOSTAWA", "B_MPV_PROWIZJA"
],
"PaymentMethod": [
"Gotówka", "Karta", "Bon", "Czek", "Kredyt",
"Przelew", "Mobilna", "Płatność inna"
],
"PaymentInformation": [
"Zapłacono", "Zapłacono całość w częściach",
"Zapłacono w części", "Brak zapłaty"
],
"CorrectionEffectType": [
"W dacie ujęcia faktury pierwotnej",
"W dacie wystawienia faktury korygującej",
"W dacie innej"
],
"ThirdPartyRole": [
"Rola inna", "Faktor", "Odbiorca", "Podmiot pierwotny",
"Dodatkowy nabywca", "Wystawca faktury", "Dokonujący płatności",
"JST – wystawca", "JST – odbiorca", "Członek GV – wystawca",
"Członek GV – odbiorca", "Pracownik"
],
"TransportType": [
"Transport morski", "Transport kolejowy", "Transport drogowy",
"Transport lotniczy", "Przesyłka pocztowa",
"Stałe instalacje przesyłowe", "Żegluga śródlądowa"
],
"CargoDescription": [
"Bańka", "Beczka", "Butla", "Karton", "Kanister", "Klatka",
"Kontener", "Kosz/koszyk", "Łubianka", "Opakowanie zbiorcze",
"Paczka", "Pakiet", "Paleta", "Pojemnik",
"Pojemnik do ładunków masowych stałych",
"Pojemnik do ładunków masowych w postaci płynnej",
"Pudełko", "Puszka", "Skrzynia", "Worek"
],
"OwnAccountBank": [
"Rachunek do rozliczeń wierzytelności nabytych",
"Rachunek do pobierania należności i przekazywania ich dostawcy",
"Rachunek gospodarki własnej, niebędący rozliczeniowym"
],
"TaxpayerStatus": [
"W stanie likwidacji",
"W postępowaniu restrukturyzacyjnym",
"W stanie upadłości",
"Przedsiębiorstwo w spadku"
],
"InvoicingMode": [
"online",
"offline"
]
}
}
PDF - generowanie obrazu faktury i UPO¶
Invoice - generowanie obrazu faktury¶
Metoda: POST
Query:
ksefNumber - numer KSeF faktury. Jeżeli numer KSeF zostanie podany to na fakturze zostanie wygenerowany QRCode z linkiem do faktury w systemie KSeF
Content-Type: multipart/form-data
Jako parametr należy podać plik XML zawierający dane faktury.
Po poprawnym wywołaniu metody serwis zwróci plik PDF z obrazem faktury. Jeżeli podamy dodatkowo numer KSeF faktury to na wizualizacji będzie umieszczony kod QR z numerem KSeF i linkiem do serwisu podatnika.
UPO - generowanie obrazu UPO¶
Metoda: POST
Content-Type: multipart/form-data
Jako parametr należy podać plik XML zawierający Urzędowe Potwierdzenie Odbioru.
Po poprawnym wywołaniu metody serwis zwróci plik PDF z obrazem potwierdzenia.
QrCode - generowanie kodów QR dla faktur offline¶
Offline - kod weryfikacji faktury (kod I)¶
Metoda: POST
Header:
NIP - numer NIP wystawcy
issueDate - data wystawienia faktury
invoiceHash - skrót pliku faktury. Jest to ciąg znaków wyliczany tzw. funkcją hash jednoznacznie identyfikujący zawartość pliku. W systemie Navigator365 skrót pliku jest dostępny jako jeden z elementów mentionsa dla atrybutu pliki
Po poprawnym wywołaniu metody serwis zwróci plik graficzny PNG zawierający QR kod.
Certificate - kod potwierdzenia autentyczności wystawcy (kod II)¶
Metoda: POST
Header:
NIP - numer NIP wystawcy faktury
invoiceHash - skrót pliku faktury. Jest to ciąg znaków wyliczany tzw. funkcją hash jednoznacznie identyfikujący zawartość pliku. W systemie Navigator365 skrót pliku jest dostępny jako jeden z elementów mentionsa dla atrybutu pliki
Po poprawnym wywołaniu metody serwis zwróci plik graficzny PNG zawierający QR kod.
Session - informacje o sesji KSeF¶
Invoices – pobranie informacji o fakturach wysłanych w sesji¶
Metoda: GET
Header:
NIP - numer NIP wystawcy faktury
apiKey – apiKey dla serwisu skojarzony z wystawcą faktury. Api key jest generowany podczas konfiguracji serwisu KSeF
sessionNumber - numer sesji, jest to parametr zwracany przez metody send i batch
Po poprawnym wywołaniu metody serwis zwróci json z danymi wysłanej faktury takimi jak numer KSeF czy datę przyjęcia. W pliku json znajduje się link, który służy do pobierania Urzędowego Potwierdzenia Odbioru.
status – pobranie informacji o statusie sesji¶
Metoda: GET
Header:
NIP - numer NIP wystawcy faktury
apiKey – apiKey dla serwisu skojarzony z wystawcą faktury. Api key jest generowany podczas konfiguracji serwisu KSeF
sessionNumber - numer sesji, jest to parametr zwracany przez metody send i batch
Po poprawnym wywołaniu metody serwis zwróci json z informacjami o statusie sesji.