+48 12 307 44 12
support@navigator365.com
View Categories

Przygotowanie do integracji z KSeF

Table of Contents

System KSeF #

KSeF czyli Krajowy System eFaktur to platforma stworzona przez ministerstwo finansów do wymiany faktur drogą elektroniczną. Docelowo system ma zastąpić prawie cała wymianę papierowych faktur. Wyjątki z systemem KSeF:

  • Faktury dotyczące transakcji wewnątrzwspólnotowych oraz sprzedaż na rzecz konsumentów nie podlegających obowiązki e-fakturowania
  • Faktury konsumenckie (B2C), bilety, faktury uproszczone których kwota nie przekracza 450 zł
  • Faktury dokumentujące czynności i rozliczenia w procedurach szczególnych (OSS, IOSS)

Platforma umożliwia wystawianie faktur, przekazywanie faktur z systemu ERP lub EZD za pośrednictwem interfejsu oraz pobieranie faktur. System działa na zasadzie centralnego repozytorium dokumentów, co oznacza, że wszystkie faktury trafiają w jedno miejsce i są z tego miejsca pobierane.

Kiedy zaczynamy #

Uruchomienie produkcyjne systemu KSeF oraz wymóg jego stosowania przez podmioty gospodarcze planowane jest na I kwartał 2026 roku. Do tego czasu firmy, które chcą używać innych narzędzi do przesyłania faktur niż te oferowane przez Ministerstwo Finansów powinny wdrożyć obsługę KSeF w systemach ERP lub EZD. System Navigator umożliwia integrację z KSeF zarówno jako niezależne rozwiązanie – pobieranie faktur i ich procesowanie w ramach obieg dokumentów jak i jako hub do komunikacji ERP <> KseF – pobieranie i przesyłanie plików XML bez procesu obiegu dokumentów.

Warto być na bieżąco i śledzić strony Ministerstwa Finansów:

Krajowy System e-Faktur (KSeF)

Pytania i odpowiedzi – KSeF

Co powinienem zrobić by uruchomić KSeF #

Po stronie KSeF #

Uwaga: Opis dotyczy aktualnej wersji KSeF czyli 1.0. Wersja ta będzie działała do 1 września 2025 roku. Po tym okresie należy przejść na wersję 2.0 co wiąże się ze zmianami np. w autoryzacji. Więcej w komunikacje na stronach Ministerstwa Finansów.

Kwestia dostępu do KSeF i wygenerowania tokenu do komunikacji jest indywidualną kwestią podmiotu, który chce wystawiać faktury poprzez KSeF. Dostawca oprogramowania księgowego, ERP lub EOD nie może w imieniu podmiotu wystąpić o konto w systemie czy wygenerować tokenu.

Proces uzyskania tokenu można opisać w kilku prostych krokach. Niestety, trudno powiedzieć ile czasu zajmie przejście całej procedury więc najlepiej nie zostawiać tego na ostatnią chwilę.

Co potrzebujemy zrobić aby uzyskać token:

  • 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.
  • Na tym etapie trzeba zweryfikować czy połączenie z KSeF działa prawidłowo dla wszystkich wskazanych osób. Uwaga: to jeszcze nie jest ten moment, gdy podpinamy oprogramowanie EOD czy ERP do KSeF
  • Token dostępowy należy wygenerować. Po zalogowaniu się w aplikacji MF (Aplikacja Podatnika KSeF i inne narzędzia (podatki.gov.pl)) należy odszukać opcję Tokeny -> Generuj token. Wygenerowany token należy przekazać firmie wdrażającej oprogramowanie lub samodzielnie dokonać konfiguracji systemu przez wprowadzenie tokenu.

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ącycm 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 #

/Invoice/Generate #

Metoda: POST

Content-Type: application/json

Jako parametr należy podać json zawierający opis faktury. Przykład jsona znajduje się poniżej:

{
  "general": {                               						// Ogólne dane faktury
    "invoiceType": "Podstawowa",             						// Rodzaj faktury: Podstawowa / Zaliczkowa / Rozliczeniowa / Korygująca...
    "priceType": "Netto",                    						// Rodzaj cen: Netto / Brutto
    "nextInvoiceNumber": "FV/2025/001",      						// Kolejny numer faktury
    "currencyCode": "PLN",                   						// Kod waluty (ISO 4217)
    "dateOfIssue": "2025-08-27",             						// Data wystawienia faktury
    "dateOfDelivery": "2025-08-26",          						// Data dostawy / wykonania usługi
    "periodStartDate": "2025-08-01",         						// Początek okresu rozliczeniowego
    "periodEndDate": "2025-08-31",           						// Koniec okresu rozliczeniowego
    "warehouseDocumentNumbers": [            						// Numery dokumentów magazynowych
      "WZ/2025/01",
      "MM/2025/02"
    ],
    "additionalDescription": [               						// Sekcja dodatkowych opisów
      {
        "invoiceItemNumber": 1,              					// Numer pozycji faktury, której dotyczy opis
        "typeOfInformation": "Opis",         						// Rodzaj informacji
        "informationContent": "Dodatkowy opis do pozycji" 			// Treść opisu
      }
    ],
    "correctCorrectionInvoiceNumber": "FV/2025/0009",  	 			// Poprawny numer faktury korygowanej
    "reasonForCorrection": "Pomylona cena",             			// Przyczyna korekty
    "correctionEffectType": "W dacie ujęcia faktury pierwotnej", 	// Typ skutku korekty
    "correctionInvoiceIdentificationData": [   						// Dane faktury korygowanej
      {
        "dateOfIssue": "2025-08-01",           						// Data wystawienia faktury korygowanej
        "correctionInvoiceNumber": "FV/2025/0005", 					// Numer
        "kSeFNumberOfCorrectionInvoice": "1234567890-KSEF-0005"		// Numer KSeF
      }
    ]
  },
  "seller": {                              							// Dane sprzedawcy
    "taxIdentificationNumber": "1111111111",						// NIP sprzedawcy
    "name": "Przykładowa Firma Sp. z o.o.",							// Nazwa sprzedawcy
    "address": {													// Dane adresowe
      "countryCode": "PL",                  						// Kod kraju
      "line1": "ul. Kwiatowa 10, 00-001 Warszawa",					// Adres
      "line2": "pok. 5"                     						// Dodatkowa linia adresu
    },
    "mailingAddress": {												// Adres do korespondencji
      "countryCode": "PL",											// Kod kraju
      "line1": "skrytka pocztowa 123",								// Adres
      "line2": null													// Dodatkowa linia adresu
    },
    "contactDetails": [												// Dane kontaktowe
      {
        "phoneNumber": "123456789",									// Numer telefonu
        "emailAddress": "kontakt@firma.pl"							// Adres email
      }
    ]
  },
  "buyer": {                               							// Dane nabywcy
    "taxIdentificationNumber": "2222222222",						// NIP nabywcy
    "name": "Jan Kowalski",											// Nazwa nabywcy
    "address": {													// Dane sprzedawcy
      "countryCode": "PL",											// Kod kraju
      "line1": "ul. Polna 5, 00-002 Warszawa",						// Adres
      "line2": null													// Dodatkowa linia adresu
    },
    "mailingAddress": null,											// Adres do korespondencji. Można go wypełnić tak samo jak przy adresie do korespondencji sprzedawcy
    "contactDetails": [												// Dane kontaktowe
      {
        "phoneNumber": "987654321",									// Numer telefonu
        "emailAddress": "jan.kowalski@example.com"					// Adres email
      }
    ]
  },
  "positionsBeforeRevision": [              						// Pozycje przed korektą (dla faktury korygującej)
    {
      "name": "Towar - stara cena",									// Nazwa towaru
      "measure": "sztuka",											// Jednostka miary
      "quantity": 1,												// Ilość
      "unitPrice": 100,												// Cena jednostkowa
      "taxRate": "23",												// Stawka VAT
      "exchangeRate": 1.0											// Kurs waluty
    }
  ],
  "positions": [                           							// Pozycje faktury
    {
      "name": "Towar A",											// Nazwa towaru
      "measure": "sztuka",											// Jednostka miary
      "quantity": 2,												// Ilość
      "unitPrice": 50,												// Cena jednostkowa
      "taxRate": "23",												// Stawka VAT
      "exchangeRate": 1.0											// Kurs waluty
    },
    {
      "name": "Usługa B",
      "measure": "godzina",
      "quantity": 5,
      "unitPrice": 100,
      "taxRate": "8",
      "exchangeRate": null
    }
  ],
  "payment": {                             							// Dane płatności
    "paymentInformation": "Brak zapłaty",   						// Zapłacono / Zapłata częściowa / Brak zapłaty
    "paymentDate": "2025-09-15",            						// Termin zapłaty
    "partialPayments": [											// Informacja o płatnościach częściowych
      {
        "partialPaymentDate": "2025-08-30",							// Data płatności
        "partialPaymentAmount": 500.0								// Wartość płatności częściowej
      }
    ],
    "paymentTermsAndDescriptions": [								// Płatności
      {
        "paymentTerm": "2025-09-30",        						// Termin płatności
        "paymentTermDescription": "30 dni od daty wystawienia"		// Opis terminu płatności
      }
    ],
    "paymentMethod": "Przelew",             						// Metoda płatności: Gotówka/Przelew/Karta/etc.
    "otherPaymentDescription": "Raty miesięczne",
    "bankAccountNumbers": [                 						// Rachunki sprzedawcy
      {
        "fullAccountNumber": "PL12123456789012345678901234",		// Numer rachunku
        "swift": "INGBPLPW",										// Kod SWIFT
        "ownAccountBank": "Rachunek gospodarki własnej, niebędący rozliczeniowym",	// 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": "ING Bank Śląski",								// Nazwa banku
        "accountDescription": "Rachunek główny"						// Opis rachunku
      }
    ],
    "faktorBankAccountNumbers": [            						// Rachunki faktora
      {
        "fullAccountNumber": "PL99998888777766665555444433",
        "swift": "PKOPPLPW",
        "ownAccountBank": "Rachunek do rozliczeń wierzytelności nabytych",
        "bankName": "PKO BP",
        "accountDescription": "Rachunek faktora"
      }
    ],
    "skonto": {														// Skonto
      "skontoConditions": "Przy płatności do 7 dni rabat 2%",
      "skontoAmount": "2%"
    }
  },
  "annotation": {                           						// Adnotacje podatkowe
    "checkoutMethod": false,										// Metoda kasowa
    "selfBilling": false,											// Samofakturowanie
    "reverseCharge": true,											// Odwrotne obciążenie
    "splitPaymentMechanism": true,									// Metoda podzielonej płatności
    "provisionOfActForTaxExemption": "Art. 43 ust. 1 pkt 10 ustawy o VAT",	// Przepis ustawy o zwolnieniu z podatku VAT
    "provisionOfDirectiveForTaxExemption": null,					// Przepis dyrektywy o zwolnieniu z podatku VAT
    "anotherLegalBasisForTaxExemption": null,						// Inna podstawa prawna do zwolnienia z podatku
    "newMeansOfTransport": false,									// Wewnątrzwspólnotowe dostawy nowych środków transportu
    "obligationToIssueVat22Document": false,						// Obowiązek wystawienia dokumentu VAT-22
    "simplifiedTripartiteProcedure": false,							// Procedura uproszczona
    "secondHandGoods": false,										// Towary używane
    "worksOfArt": false,											// Dzieła sztuki
    "travelAgencies": false,										// Biura podróży
    "collectorsAndAntiques": false									// Przedmioty kolekcjonerskie i antyki
  },
  "orderTerms": {                            						// Warunki transakcji
    "contracts": [													// Umowy
      {
        "agreementDate": "2025-07-01",								// Data umowy
        "contractNumber": "UM/07/2025/01"							// Numer umowy
      }
    ],
    "orders": [														// Zamówienia
      {
        "orderDate": "2025-07-15",									// Data zamówienia
        "orderNumber": "ZAM/07/2025/123"							// Numer zamówienia
      }
    ]
  }
}
Pokaż więcej
Pokaż mniej

Po poprawnym wywołaniu metody serwis zwróci plik XML w standardzie schemy KSeF.

Send – wysyłka faktury KSeF #

Metoda: POST

Header:

nip – string zawierający NIP podmiotu wysyłającego fakturę

token – token KSeF podmiotu wysyłającego fakturę

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).

UPO – pobranie urzędowago poświadczenia odbioru #

Metoda: GET

Parametry: numer sesji przekazywany w ścieżce wywołania metody

Po poprawnym wywołaniu metody serwis zwróci json z danymi wysłanej faktury takimi jak numer KSeF czy datę przyjęcia oraz plikiem PDF z potwierdzeniem zakodowanym w base64. Poniżej prezentowany jest przykładowy json

{
  "documents": [
    {
      "ksefNumber": "6050056477-20240226-B1D364A8B83A-AB",					//numer KSeF wysłanej faktury
      "nextInvoiceNumber": "FV/2024/1",										//numer faktury
      "submissionDate": "2024-02-26T12:31:53.731+01:00",					//data wysłania do KSeF
      "receivedDate": "2024-02-26T12:31:53.941+01:00",						//data przyjęcia w KSeF
      "documentHash": "L0pUda24bdAIjWYtE70XylbpMXXPtS+KveQMrHKdXxI="
    }
  ],																		//plik UPO w formacie pdf zakodowany w base64 
  "upoFile":																"PD94bWwgdmVyc2lvbj0iMS4wIiBlbmNvZGluZz0iVVRGLTgiPz48UG90d2llcmR6ZW5pZSB4bWxucz0iaHR0cDovL3Vwby5zY2hlbWF0e=="
}
Pokaż więcej
Pokaż mniej

Get – pobranie faktur z KSeF #

Metoda: GET

Parametry:

Header:

nip – string zawierający NIP podmiotu wysyłającego fakturę

token – token KSeF podmiotu wysyłającego fakturę

Ścieżka:

from – data od której chcemy pobierać faktury (data kluczowa aby nie pobierać wszystkich historycznych faktur)

to – data do kiedy chcemy pobierać faktury

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

{
  "ksefNumber": "1234567890-20250829-ABC123DEF456-78",
  "schemaVersion": "2",
  "taxSummary": [
    {
      "taxRate": "23",
      "netAmount": 1000.0,
      "taxAmount": 230.0,
      "grossAmount": 1230.0
    },
    {
      "taxRate": "8",
      "netAmount": 500.0,
      "taxAmount": 40.0,
      "grossAmount": 540.0
    }
  ],
  "invoiceXml": "PD94bWwgdmVyc2lvbj0iMS4wIiBlbmNvZGluZz0iVVRGLTgi=",
  "invoiceHtml": "PCFET0NUWVBFIGh0bWw+CjxodG1sPgo8aGVhZD4KICA8dGl0bGU+RmFrdHVyY=",
  "general": {
    "invoiceType": "Podstawowa",
    "priceType": "Netto",
    "nextInvoiceNumber": "FV/2025/001",
    "currencyCode": "PLN",
    "dateOfIssue": "2025-08-29",
    "dateOfDelivery": "2025-08-28",
    "periodStartDate": "2025-08-01",
    "periodEndDate": "2025-08-31",
    "warehouseDocumentNumbers": [
      "WZ/2025/001",
      "WZ/2025/002"
    ],
    "additionalDescription": [
      {
        "invoiceItemNumber": 1,
        "typeOfInformation": "Uwagi dodatkowe",
        "informationContent": "Towar zgodny z zamówieniem nr ZAM/2025/001"
      },
      {
        "invoiceItemNumber": 2,
        "typeOfInformation": "Informacja o gwarancji",
        "informationContent": "Gwarancja 24 miesiące od daty zakupu"
      }
    ],
    "correctCorrectionInvoiceNumber": null,
    "reasonForCorrection": null,
    "correctionEffectType": null,
    "correctionInvoiceIdentificationData": null
  },
  "seller": {
    "taxIdentificationNumber": "1234567890",
    "name": "Example Company Sp. z o.o.",
    "address": {
      "countryCode": "PL",
      "line1": "ul. Przykładowa 123, 00-001 Warszawa",
      "line2": "Budynek A, piętro 2"
    },
    "mailingAddress": {
      "countryCode": "PL",
      "line1": "ul. Korespondencyjna 456, 00-002 Warszawa",
      "line2": null
    },
    "contactDetails": [
      {
        "phoneNumber": "+48 22 123 45 67",
        "emailAddress": "kontakt@example.com"
      },
      {
        "phoneNumber": "+48 22 765 43 21",
        "emailAddress": "sprzedaz@example.com"
      }
    ]
  },
  "buyer": {
    "taxIdentificationNumber": "0987654321",
    "name": "Client Company Sp. z o.o.",
    "address": {
      "countryCode": "PL",
      "line1": "ul. Kliencka 789, 00-003 Kraków",
      "line2": "Budynek B"
    },
    "mailingAddress": {
      "countryCode": "PL",
      "line1": "ul. Pocztowa 321, 00-004 Kraków",
      "line2": "Skrytka pocztowa 123"
    },
    "contactDetails": [
      {
        "phoneNumber": "+48 12 987 65 43",
        "emailAddress": "zamowienia@client.com"
      }
    ]
  },
  "positionsBeforeRevision": null,
  "positions": [
    {
      "name": "Laptop Dell Inspiron 15",
      "measure": "sztuka",
      "quantity": 2.0,
      "unitPrice": 2500.0,
      "taxRate": "23",
      "exchangeRate": null
    },
    {
      "name": "Mysz optyczna Logitech",
      "measure": "sztuka",
      "quantity": 5.0,
      "unitPrice": 50.0,
      "taxRate": "23",
      "exchangeRate": null
    },
    {
      "name": "Książka techniczna",
      "measure": "sztuka",
      "quantity": 10.0,
      "unitPrice": 50.0,
      "taxRate": "8",
      "exchangeRate": null
    }
  ],
  "payment": {
    "paymentInformation": "Brak zapłaty",
    "paymentDate": null,
    "partialPayments": [
      {
        "partialPaymentDate": "2025-09-15",
        "partialPaymentAmount": 500.0
      },
      {
        "partialPaymentDate": "2025-09-30",
        "partialPaymentAmount": 1270.0
      }
    ],
    "paymentTermsAndDescriptions": [
      {
        "paymentTerm": "2025-09-28",
        "paymentTermDescription": "Płatność przelewem na rachunek bankowy"
      },
      {
        "paymentTerm": "2025-10-15",
        "paymentTermDescription": "Płatność za pozostałą część faktury"
      }
    ],
    "paymentMethod": "Przelew",
    "otherPaymentDescription": "Płatność w dwóch ratach zgodnie z umową",
    "bankAccountNumbers": [
      {
        "fullAccountNumber": "12 1234 5678 9012 3456 7890 1234",
        "swift": "PKOPPLPW",
        "ownAccountBank": "Rachunek gospodarki własnej, niebędący rozliczeniowym",
        "bankName": "PKO Bank Polski S.A.",
        "accountDescription": "Rachunek główny firmy"
      },
      {
        "fullAccountNumber": "98 9876 5432 1098 7654 3210 9876",
        "swift": "INGBPLPW",
        "ownAccountBank": null,
        "bankName": "ING Bank Śląski S.A.",
        "accountDescription": "Rachunek pomocniczy"
      }
    ],
    "faktorBankAccountNumbers": [
      {
        "fullAccountNumber": "11 1111 2222 3333 4444 5555 6666",
        "swift": "BPKOPLPW",
        "ownAccountBank": "Rachunek do rozliczeń wierzytelności nabytych",
        "bankName": "Bank Pekao S.A.",
        "accountDescription": "Rachunek faktora"
      }
    ],
    "skonto": {
      "skontoConditions": "2% przy płatności w ciągu 10 dni",
      "skontoAmount": "35.40"
    }
  },
  "annotation": {
    "checkoutMethod": false,
    "selfBilling": false,
    "reverseCharge": false,
    "splitPaymentMechanism": true,
    "provisionOfActForTaxExemption": "Art. 43 ust. 1 pkt 1 ustawy o VAT",
    "provisionOfDirectiveForTaxExemption": "Art. 132 ust. 1 lit. a Dyrektywy 2006/112/WE",
    "anotherLegalBasisForTaxExemption": "Rozporządzenie Ministra Finansów z dnia...",
    "newMeansOfTransport": false,
    "obligationToIssueVat22Document": false,
    "simplifiedTripartiteProcedure": false,
    "secondHandGoods": false,
    "worksOfArt": false,
    "travelAgencies": false,
    "collectorsAndAntiques": false
  },
  "orderTerms": {
    "contracts": [
      {
        "agreementDate": "2025-08-15",
        "contractNumber": "UMW/2025/001"
      },
      {
        "agreementDate": "2025-07-20",
        "contractNumber": "UMW/2025/002"
      }
    ],
    "orders": [
      {
        "orderDate": "2025-08-20",
        "orderNumber": "ZAM/2025/001"
      },
      {
        "orderDate": "2025-08-22",
        "orderNumber": "ZAM/2025/002"
      }
    ]
  }
}
Pokaż więcej
Pokaż mniej

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 dpokumencie.

What are your Feelings

Kontakt

Telefon

+48 12 307 44 12

Adres email

support@navigator365.com

Become a partner