Przejdź do treści

Konfiguracja Navigator365 do współpracy z KSeF

Informacje wstępne

Artykuł opisuje konfigurację integracji z KSeF 2.0. Navigator365 komunikuje się z KSeF przez serwis pośredniczący firmy Archman. Przygotowanie serwisu, uwierzytelnienia i opis metod znajdziesz w artykule o integracji z KSeF.

Integrację można uruchomić na dwa sposoby:

  • Opcja A — gotowa aplikacja KSEF (zalecana): import aplikacji przygotowanej przez Archman, zawierającej formularze, procesy i menu.
  • Opcja B — konfiguracja od podstaw: budowa formularzy i procesów przy użyciu standardowych akcji Navigator365.

W obu wariantach akcja Wywołaj REST API korzysta z połączenia do serwisu KSeF skonfigurowanego przez administratora. W procesie wybierasz usługę w polu Połączenie i podajesz Ścieżkę operacji. Adresu bazowego i klucza API nie wpisujesz w każdej akcji ani na formularzu konfiguracyjnym aplikacji.

Przygotowanie połączenia z serwisem

  1. Przygotuj serwis pośredniczący i dostęp do właściwego środowiska KSeF zgodnie z instrukcją integracji.
  2. Poproś administratora o skonfigurowanie połączenia w sekcji RestConnections. Połączenie określa nazwę usługi, adres bazowy i autoryzację ApiKey z nagłówkiem ApiKey.
  3. W akcji Wywołaj REST API wybierz to połączenie, np. KSeF. Nazwa na liście zależy od konfiguracji administratora.
  4. Wybierz metodę HTTP, podaj ścieżkę względną i parametry operacji. W parametrach użyj wzmianek (@mentions) wskazujących dane firmy lub zmienne procesowe.
  5. Wskaż zmienną procesową na odpowiedź. Dla kolekcji faktur i statusów sesji użyj typu JSON.

Autoryzacja jest pobierana z wybranego połączenia. Nie dodawaj ponownie nagłówka ApiKey w akcji. Klucz serwisu pośredniczącego służy do komunikacji Navigator365 z serwisem Archman; token lub certyfikat KSeF jest konfigurowany po stronie tego serwisu.

Jeśli firmy lub środowiska wymagają różnych adresów albo kluczy, administrator przygotowuje odpowiednie połączenia. W akcjach wybierz połączenie właściwe dla obsługiwanej firmy i środowiska.

Operacje używane w procesach

Poniższe ścieżki są względne wobec adresu bazowego wybranej usługi. Wartości w nawiasach klamrowych zastąp wzmiankami.

Operacja Metoda Ścieżka / dane Wynik
Pobranie faktur zakupu GET Invoice/export?nip={NIP}&from={DataOd}&to={DataDo}&subjectType=subject2 Tablica obiektów z invoiceSummary i invoiceXml
Przetworzenie XML faktury POST Invoice/process?calculateMissingFields=true; multipart/form-data, pole invoice z plikiem XML JSON z danymi faktury
Pobranie statusów faktur w sesji GET session/invoices?sessionNumber={NumerSesji}&nip={NIP} Tablica statusów i adresów UPO
Pobranie UPO XML GET Pełny adres z upoDownloadUrl, połączenie Własny adres, autoryzacja BRAK XML UPO
Wydruk UPO POST pdf/upo; multipart/form-data, pole upo z plikiem UPO XML PDF UPO

Generowanie XML, wysyłkę faktury i wydruk PDF skonfiguruj zgodnie z metodami Generate, Send i PDF. Dopasuj format danych do metody dostępnej w zainstalowanej wersji serwisu. W opisanej metodzie Send treścią żądania jest JSON faktury, a w metodzie generowania PDF — plik XML.

Opcja A — gotowa aplikacja KSEF

Gotową aplikację KSEF uzyskasz u partnera wdrożeniowego Archman. Po imporcie przypisz połączenia w akcjach REST API, uzupełnij konfiguracje firm i sprawdź powiązania z formularzami faktur zakupu (FZ) oraz faktur sprzedaży (FS).

Sekcja Zawartość
Pulpit Skróty akcji, ostatnie faktury zakupu i sprzedaży oraz dokumenty oczekujące na działanie użytkownika
Powiązane faktury → Faktury zakupu Lista FZ z filtrem Źródło = KSeF
Powiązane faktury → Faktury sprzedaży Lista FS z filtrem Źródło = KSeF, sortowana malejąco po dacie dokumentu
Administracja → Konfiguracja ogólna Ustawienia aplikacji i konfiguracje poszczególnych firm

Na pulpicie dostępne są przyciski:

  • Pobierz faktury zakupu — uruchamia pobieranie asynchronicznie. Komunikat o rozpoczęciu informuje, że operacja może potrwać kilka minut.
  • Wystaw fakturę sprzedaży — otwiera nowy dokument sprzedaży z domyślnym typem Faktura.

Przygotowanie formularzy

Poniższe pola opisują gotową aplikację i stanowią wzorzec dla konfiguracji od podstaw. Kody odnoszą się do dostarczonego przykładu; w istniejących formularzach dopasuj mapowanie do własnych kodów.

Formularz konfiguracyjny

Pole Kod Przeznaczenie
Czy tworzyć pozycje faktur CzyPobieracPozycjeFaktur Określa, czy import FZ tworzy pozycje dokumentu
Konfiguracje KSEF dla firm KonfiguracjeFirm Lista subdokumentów z konfiguracją dla każdej firmy
Firma Zależny od formularza Powiązanie z podmiotem, z którego pobierany jest m.in. NIP
Data i czas ostatniego pobrania faktur DataICzasOstatniegoPobraniaFaktur Początek kolejnego okna pobierania faktur dla firmy

Dane firmy powinny umożliwiać uzupełnienie faktury: NIP, nazwa, adres, e-mail oraz odpowiednio KRS, REGON i BDO. Przed pierwszym pobraniem ustaw datę początkową importu dla każdej firmy.

W starszej konfiguracji występowały pola Adres serwisu KSEF (PoleTekstowe) i Klucz API KSeF (KluczApi). Przy korzystaniu z predefiniowanego połączenia ich rolę przejmuje konfiguracja RestConnections. Po imporcie starszej aplikacji zmień wywołania procesów tak, aby wybierały połączenie zamiast odczytywać adres i klucz z formularza.

Formularz faktury i Dokument KSeF

Formularz Dokument KSeF (Dokument - KSEF) przechowuje dane integracji powiązane z fakturą. Przy konfiguracji od podstaw dodaj odpowiednie pola do FZ i FS lub do powiązanego formularza.

Sekcja Pole Kod w przykładzie Typ / zawartość
Nagłówek Numer KSeF NumerKsef Tekst
Nagłówek Data przesłania do KSeF DataPrzeslania Data i czas
Nagłówek Data trwałego zapisu w KSeF DataRejestracji Data i czas, permanentStorageDate
e-Faktura Faktura XML FakturaXml Załącznik z oryginalnym XML
e-Faktura Faktura JSON FakturaJson2 Tekst wieloliniowy z danymi przetworzonymi z XML
UPO Numer sesji NumerSesji Tekst zwracany po wysyłce
UPO Status UPO StatusUpo Tekst z status.description
UPO UPO URL UpoUrl Tekst z upoDownloadUrl
UPO UPO XML UpoXml1 Załącznik
UPO UPO PDF Zależny od formularza Załącznik z wydrukiem UPO

Na fakturze przygotuj także pole Źródło z wartością KSeF, załącznik na wydruk faktury PDF i powiązania z kontrahentem, umowami, zamówieniami oraz płatnościami.

Sekcja Adnotacje obejmuje dane wymagane przez używany schemat faktury, np. metodę kasową, samofakturowanie, odwrotne obciążenie, podzieloną płatność, zwolnienie z VAT wraz z podstawą prawną, procedurę marży i dane transportu. Sekcja Umowy i zamówienia zawiera listy powiązanych dokumentów z numerami i datami.

Procesy integracyjne

Proces 1: Pobieranie faktur kosztowych z KSeF

Proces Pobieranie faktur kosztowych działa asynchronicznie. Uruchamia go przycisk Pobierz faktury zakupu lub harmonogram. Proces iteruje po konfiguracjach firm i nie wymaga rozpoczęcia na konkretnej fakturze.

Start: przycisk lub harmonogram
  └─► Pętla: konfiguracje firm
        ├─► Pobierz konfigurację firmy i NIP
        ├─► Ustaw zmienne: Data od, Data do
        ├─► Pobierz faktury [Wywołaj REST API]
        │     Połączenie: KSeF
        │     GET Invoice/export?nip={NIP}&from={DataOd}&to={DataDo}&subjectType=subject2
        └─► Bramka: status HTTP 200?
              ├─► Nie → obsłuż błąd, zachowaj poprzednią datę pobrania
              └─► Tak
                    ├─► Pętla: pobrane faktury
                    │     └─► Podproces: Tworzenie faktury kosztowej
                    │           Parametry: JSON faktury, kontekst firmy
                    └─► Po pomyślnym przetworzeniu całego zakresu:
                          zapisz datę ostatniego pobrania = Data do
  1. Pobierz konfigurację firmy i jej NIP.
  2. Ustaw zmienne Data od na ostatnią datę pobrania oraz Data do na bieżący czas. Zachowaj tę samą wartość Data do przez cały import. Daty przekaż w ISO 8601 z informacją o strefie czasowej.
  3. W akcji Wywołaj REST API wybierz połączenie KSeF, metodę GET i ścieżkę Invoice/export?nip={NIP}&from={DataOd}&to={DataDo}&subjectType=subject2.
  4. Zapisz odpowiedź jako zmienną JSON Kolekcja faktur i sprawdź status HTTP. Dla odpowiedzi 200 przejdź do pętli po elementach kolekcji.
  5. Dla każdego elementu uruchom synchronicznie podproces Tworzenie faktury kosztowej, przekazując JSON bieżącej faktury i kontekst firmy.
  6. Po pomyślnym przetworzeniu całego zakresu zapisz Data do jako datę ostatniego pobrania tej firmy.

Ponowienie importu po błędzie

W dostarczonym przykładzie data ostatniego pobrania jest aktualizowana przed wywołaniem API. Taka kolejność wymaga przywrócenia poprzedniej daty lub ponownego pobrania tego samego zakresu po błędzie. Przy budowaniu procesu od podstaw zapisuj datę po zakończeniu importu, aby kolejna próba nie pominęła nieprzetworzonych faktur. Przed duplikatami chroni wyszukiwanie istniejącego dokumentu przed jego utworzeniem.

Proces 2: Tworzenie faktury kosztowej

Podproces Tworzenie faktury kosztowej przyjmuje jeden element odpowiedzi z eksportu. Tworzy lub aktualizuje dokument FZ i uruchamia jego obieg.

Start: JSON jednej faktury, kontekst firmy
  ├─► Utwórz lub zaktualizuj FZ (numer faktury + NIP sprzedawcy)
  ├─► Zapisz XML i pobierz dokument do dalszych akcji
  ├─► Przetwórz XML na JSON [Wywołaj REST API]
  │     Połączenie: KSeF
  │     POST Invoice/process?calculateMissingFields=true
  │     multipart/form-data: invoice = plik XML faktury
  ├─► Wygeneruj wydruk faktury
  ├─► Odszukaj kontrahenta po NIP sprzedawcy
  │     ├─► Istnieje → zapamiętaj ID kontrahenta
  │     └─► Nie istnieje → uzupełnij NIP, pobierz dane z GUS, zapamiętaj ID
  ├─► Bramka: czy korekta?
  │     ├─► Tak → przetwórz pozycje korekty
  │     │          └─► Pętla: faktury korygowane → odszukaj i powiąż z FZ
  │     └─► Nie → przejdź dalej
  ├─► Bramka: czy tworzyć pozycje faktur?
  │     ├─► Tak → pętla: general.positions → utwórz pozycje FZ
  │     └─► Nie → pomiń tworzenie pozycji
  ├─► Uzupełnij dane faktury i sekcję KSeF
  ├─► Pętla: zamówienia → odszukaj i powiąż
  ├─► Pętla: umowy → odszukaj i powiąż
  ├─► Podproces: Tworzenie płatności
  └─► Uruchom obieg faktury zakupowej
  1. Użyj akcji Utwórz lub zaktualizuj dokument. Wyszukaj FZ po numerze faktury i NIP sprzedawcy. Uzupełnij typ dokumentu, numer z invoiceSummary.invoiceNumber, numer KSeF z invoiceSummary.ksefNumber oraz źródło KSeF.
  2. Zapisz invoiceXml jako załącznik XML. Jeżeli zapis pliku wymaga base64, zakoduj tekst XML w UTF-8. Datę wystawienia mapuj z invoiceSummary.issueDate; invoicingDate jest osobnym polem odpowiedzi.
  3. Pobierz utworzony lub zaktualizowany dokument akcją Pobierz dokument, aby udostępnić jego pola jako wzmianki.
  4. Wywołaj POST Invoice/process?calculateMissingFields=true przez połączenie KSeF. W treści multipart/form-data przekaż plik XML w polu invoice. Zapisz wynik jako JSON faktury.
  5. Wygeneruj wydruk faktury z szablonu KSeF i zapisz PDF w załącznikach.
  6. Odszukaj kontrahenta po NIP sprzedawcy (seller.taxIdentificationNumber w przetworzonym JSON). Jeśli nie istnieje, uzupełnij NIP i pobierz dane z GUS. Nabywcę (buyer) powiąż z właściwą firmą.
  7. Sprawdź typ faktury i general.correctionInvoiceIdentificationData. Dla korekty przetwórz pozycje oznaczone beforeRevision=true zgodnie z mapowaniem korekt w aplikacji; w opisanym przykładzie są usuwane z kolekcji importowanych pozycji. Odszukaj faktury korygowane po numerze, dacie wystawienia i kontrahencie, a następnie dodaj powiązania.
  8. Jeśli Czy tworzyć pozycje faktur jest włączone, wykonaj pętlę po general.positions. Uzupełnij nazwę, ilość, miarę, cenę netto, wartości netto i brutto, kwotę VAT, stawkę VAT oraz powiązanie pozycji z FZ.
  9. Uzupełnij dane faktury, typ, kontrahenta, nabywcę oraz sekcję KSeF: numer, daty, XML i JSON.
  10. Powiąż zamówienia z general.orderTerms.orders oraz umowy z general.orderTerms.contracts, wyszukując je po numerach.
  11. Uruchom podproces Tworzenie płatności, przekazując rachunki bankowe, termin, kwotę i metodę płatności z general.payment.
  12. Uruchom standardowy obieg faktury zakupowej.

Mechanizm aktualizacji może uzupełnić lub nadpisać fakturę wprowadzoną wcześniej z maila albo dokumentu papierowego. Przy ponownym imporcie uwzględnij istniejące pozycje i powiązania, aby ich nie powielać. Obieg akceptacji i dekretacji pozostaje osobnym procesem, wspólnym dla różnych źródeł faktur.

Proces 3: Przygotowanie i wysyłanie faktury sprzedaży

Proces Wysłanie do KSeF jest wywoływany synchronicznie z obiegu faktury sprzedaży w aplikacji Sprzedaż. W dostarczonym przykładzie przygotowuje XML i wydruk; właściwa wysyłka następuje w obiegu FS po jego zakończeniu.

Start: obieg faktury sprzedaży
  ├─► Podproces: Wysłanie do KSeF (przygotowanie XML i wydruku)
  │     ├─► Pobierz konfigurację firmy
  │     ├─► Zbuduj JSON faktury
  │     ├─► Pętla: dokumenty powiązane
  │     │     ├─► Zamówienie → dodaj do general.orderTerms.orders
  │     │     └─► Umowa → dodaj do general.orderTerms.contracts
  │     ├─► Bramka: czy korekta?
  │     │     ├─► Tak → dodaj dane faktur korygowanych i pozycje korekty
  │     │     └─► Nie → przejdź dalej
  │     ├─► Usuń puste elementy JSON
  │     ├─► Przygotuj XML i zastąp poprzedni plik na FS
  │     └─► Wygeneruj PDF i zapisz w załącznikach FS
  ├─► Powrót do obiegu FS: wyślij fakturę [Wywołaj REST API]
  │     Połączenie: KSeF, metoda Send
  │     Dane: JSON faktury i NIP wystawcy
  └─► Zapisz numer sesji na FS i oznacz źródło = KSeF
  1. Pobierz konfigurację firmy wystawiającej fakturę.
  2. Zbuduj JSON faktury z danych formularza: seller, buyer, thirdParties, general i footer. W general uwzględnij walutę, datę wystawienia, typ faktury, pozycje, sumy VAT, adnotacje i payment.
  3. Dodaj umowy i zamówienia do general.orderTerms. Dla korekty dodaj dane faktur korygowanych i pozycje korekty.
  4. Usuń puste elementy, które nie powinny trafić do danych wysyłanych do serwisu.
  5. Przygotuj XML zgodny ze schematem obsługiwanym przez wybraną wersję serwisu (FA(2) lub FA(3), zależnie od dokumentu i operacji). Strukturę danych dla generatora opisuje metoda Generate.
  6. Wyczyść poprzedni plik w polu Faktura XML, a następnie zapisz nowy XML jako załącznik.
  7. Wygeneruj PDF faktury i zapisz go w załącznikach FS. Możesz użyć szablonu wydruku lub metody PDF serwisu, która przyjmuje XML.
  8. W obiegu FS wywołaj metodę wysyłki przez połączenie KSeF. Dla opisanej metody Send przekaż JSON faktury i NIP wystawcy zgodnie z jej kontraktem.
  9. Zapisz zwrócony numer sesji w polu Numer sesji na FS i oznacz źródło KSeF.

Numer sesji służy do późniejszego sprawdzenia statusu. Samo przygotowanie XML i PDF nie oznacza wysłania faktury, a zwrócenie numeru sesji nie zastępuje pobrania wyniku jej przetwarzania.

Proces 4: Pobranie UPO dla dokumentów sesji

Proces Pobranie UPO dla dokumentów sesji otrzymuje parametry Numer sesji i ID firmy. Można go uruchomić ręcznie lub z procesu pobierania brakujących UPO.

Start: Numer sesji, ID firmy
  ├─► Pobierz konfigurację firmy
  ├─► Pobierz statusy faktur [Wywołaj REST API]
  │     Połączenie: KSeF
  │     GET session/invoices?sessionNumber={NumerSesji}&nip={NIP}
  └─► Pętla: faktury z odpowiedzi
        ├─► Odszukaj FS (numer faktury, firma, sesja)
        ├─► Zapisz numer KSeF, daty, status i URL UPO
        └─► Bramka: czy dostępny jest adres UPO?
              ├─► Nie → przejdź do kolejnej faktury
              └─► Tak
                    ├─► Pobierz XML UPO [Wywołaj REST API]
                    │     Połączenie: Własny adres
                    │     GET {upoDownloadUrl}, autoryzacja: BRAK
                    ├─► Zapisz UPO.xml na FS
                    ├─► Wygeneruj PDF UPO [Wywołaj REST API]
                    │     Połączenie: KSeF
                    │     POST pdf/upo
                    │     multipart/form-data: upo = plik UPO XML
                    └─► Zapisz PDF UPO na FS
  1. Pobierz konfigurację firmy.
  2. Przez połączenie KSeF wywołaj GET session/invoices?sessionNumber={NumerSesji}&nip={NIP} i zapisz odpowiedź jako JSON.
  3. Wykonaj pętlę po elementach odpowiedzi. Odszukaj FS po invoiceNumber, uwzględniając firmę i sesję, aby uniknąć dopasowania faktury innego podmiotu.
  4. Zapisz dane z odpowiedzi zgodnie z tabelą poniżej.
  5. Jeśli odpowiedź zawiera adres UPO, pobierz XML: w osobnej akcji Wywołaj REST API wybierz Własny adres, metodę GET, Adres URL z upoDownloadUrl i autoryzację BRAK. Tymczasowy adres zawiera dane dostępu; nie dodawaj klucza serwisu KSeF.
  6. Zapisz XML w polu UpoXml1 jako plik UPO.xml. Gdy odpowiedź jest tekstem, a zapis załącznika wymaga base64, użyj kodowania UTF-8, np. encode(convert_to({UPO TXT}, 'UTF8'), 'base64'), zastępując {UPO TXT} wzmianką zmiennej.
  7. Przez połączenie KSeF wywołaj POST pdf/upo. Przekaż zapisany plik XML w polu upo treści multipart/form-data.
  8. Zapisz otrzymany PDF w polu UPO PDF na FS.
Pole na FS Pole odpowiedzi
NumerKsef ksefNumber
DataPrzeslania acquisitionDate
DataRejestracji permanentStorageDate
StatusUpo status.description
UpoUrl upoDownloadUrl

Status zapisuj również wtedy, gdy UPO nie jest jeszcze dostępne. Jeśli tymczasowy adres wygasł (upoDownloadUrlExpirationDate), ponownie pobierz informacje o sesji przed pobraniem XML.

Proces 5: Pobieranie brakujących UPO

Proces Pobieranie brakujących UPO działa według harmonogramu. W dostarczonym przykładzie uruchamia się co 3 godziny, a retencja instancji wynosi 3 dni przy zachowaniu minimum jednej instancji. Datę rozpoczęcia harmonogramu dopasuj do wdrożenia.

Start: harmonogram co 3 godziny
  └─► Pętla: konfiguracje firm
        └─► Pętla: sesje z dokumentów FS bez UPO
              └─► Podproces: Pobranie UPO dla dokumentów sesji
                    Numer sesji = numer z bieżącej sesji
                    ID firmy = ID z pętli zewnętrznej
  1. Wykonaj pętlę po konfiguracjach firm.
  2. Dla każdej firmy zbierz numery sesji z dokumentów FS, dla których brakuje UPO.
  3. Dla każdej sesji uruchom proces Pobranie UPO dla dokumentów sesji, przekazując numer sesji i ID firmy.

Opcja B — budowanie integracji od podstaw

  1. Przygotuj połączenie KSeF — administrator konfiguruje usługę w RestConnections, a projektant wybiera ją w akcjach REST API.
  2. Przygotuj formularz konfiguracyjny — dodaj konfiguracje firm, datę ostatniego pobrania oraz przełącznik tworzenia pozycji.
  3. Rozbuduj formularze FZ i FS — dodaj pola opisane w sekcji Przygotowanie formularzy, powiązania i załączniki.
  4. Zbuduj pobieranie FZ — połącz proces 1 z synchronicznym procesem 2. Uruchamiaj pobieranie ręcznie lub według harmonogramu.
  5. Rozbuduj obieg FS — dodaj przygotowanie danych i wysyłkę z procesu 3, a po wysyłce zapisz numer sesji.
  6. Zbuduj pobieranie UPO — przygotuj proces 4 oraz harmonogram procesu 5.
  7. Skonfiguruj menu — dodaj pulpit, listy FZ i FS z filtrem Źródło = KSeF oraz formularz konfiguracji ogólnej.

Przed uruchomieniem harmonogramów sprawdź konfigurację na docelowym środowisku testowym: pobranie faktury, ponowienie importu tego samego zakresu, obsługę korekty, wysyłkę FS i zapis UPO. Szczegółowe struktury danych oraz metody serwisu opisano w dokumentacji integracji.