Informacje wstępne #
Opis konfiguracji jest dla wersji KSeF 1.0.
W systemie Navigator365 nie mamy bezpośrednio narzędzi do wysyłania czy pobierania faktur z KSeF. Tak jak w przypadku innych integracji musimy sami zbudować proces, w ramach którego nastąpi wymiana informacji. Będziemy do tego używać standardowych akcji takich jak Wywołaj REST Api, Utwórz dokument czy Zmień wartość pola. Do komunikacji użyjemy serwis pośredniczący stworzony przez firmę Archman. Dokładny opis serwisu znajduje się w osobnym artykule tutaj.
Przygotowanie formularzy #
W systemie masz już przygotowany formularz dla faktur w aplikacji Zakupy lub CRM. Może się jednak okazać, że brakuje pól które są związane z KSeF takich jak numer KSeF albo po prostu wcześniej nie były potrzebne przy przetwarzaniu faktur papierowych. Dlatego pierwszą rzeczą, którą należy zrobić przy konfiguracji KSeF, jest przegląd istniejących formularzy pod kątem pól oraz ich rozbudowa lub utworzenie nowych formularzy.
Formularz konfiguracyjny #
W systemie powinno być miejsce gdzie przechowujemy dane konfiguracyjne KSeF. Mowa tu o takich danych jak token do autoryzacji w serwisie. Jeżeli nie masz jeszcze przygotowanego formularza konfiguracyjnego w aplikacji do przetwarzania faktur to dobrym pomysłem jest przygotowanie takiego formularza. Poniżej prezentujemy przykład takiego formularza
Jak widzimy mamy tu podstawowe dane naszej firmy, których możemy użyć do uzupełnienia danych podstawowych oraz dane specyficzne dla KSeF. Token KSeF będzie służył do autoryzacji zaś pole Data i czas pobrania faktury to pole techniczne, które wykorzystamy w procesie pobierania faktur.
Formularz faktury #
Formularz faktury z reguły wymaga tylko dodania pól, których brakuje. Na pewno takim polem będzie Numer KSeF.
Warto porównać zestaw danych, który jest przesyłany z KSeF (link) i wybrać pola, które nas interesują
Jeżeli mamy już przygotowane formularze to możemy przystąpić do tworzenia procesów. W przypadku faktur zakupowych trzeba będzie stworzyć proces pobierania faktury, w przypadku faktur sprzedażowych – przerobić istniejący proces obiegu faktury poprzez dodanie nowej ścieżki dystrybucji faktury poprzez KSeF. Popatrzmy w szczegółach, jak mogą wyglądać takie procesy.
Pobieranie faktur #
Do pobierania faktur użyjemy metody Get z serwisu pośredniczącego. Komunikacja z serwisem pośredniczącym odbywa się za pomocą REST Api dlatego użyjemy do tego akcji Wywołaj REST Api z odpowiednimi parametrami. Proces konfigurujemy tak, by nie był przypisany do żadnego formularza. Na etapie pobierania faktur nie potrzebujemy pracować na konkretnym dokumencie. Warto jednak tak skonfigurować proces, by był uruchamiany zgodnie z harmonogramem. Na pokazanym przykładzie proces uruchamia się co 30 minut można to jednak skonfigurować zgodnie z własnymi potrzebami.
Proces jest stosunkowo prosty, warto jednak zwrócić uwagę na kilka aspektów wywołania metody Get.
Jako parametry podajemy zakres czasowy z jakiego chcemy pobrać faktury. KSeF nie przechowuje informacji, czy dany dokument został już pobrany dlatego sami musimy pilnować by nie pobrać wielokrotnie tego samego dokumentu.
Propozycja rozwiązania tego problemu jest następująca:
Na początku procesu wykonujemy akcję Zmień wartość zmiennej procesowej, w której ustawiamy zmienną procesową Data pobrania na bieżącą datę. Warto pamiętać, by była to zmienna typu data i czas.
Jak pamiętamy, w formularzu konfiguracyjnym mieliśmy pole z zapisaną datą ostatniego pobrania faktur. Obie te daty, czyli Data pobrania i data ostatniego pobrania tworzą nam okno czasowe, z którego pobieramy dokumenty.
Konfigurację wywołania REST Api widać na poniższym zrzucie ekranu.
Do pełnego skonfigurowania akcji potrzebujemy jeszcze przekazać uwierzytelnienia. Robimy to poprzez zakładkę Nagłówki, w której definiujemy dwa pola: nip oraz token. Jak widzimy na poniższym zrzucie ekranu używamy tu wartości zapisanych na formularzu konfiguracyjnym. Dzięki temu przechowujemy te wartości w jednym miejscu. Mamy też większą pewność, że token nie dostanie się w niepowołane ręce.
Warto w tym miejscu zauważyć, że w odpowiedzi, którą dostajemy z KSeF faktury dostajemy w postaci listy dokumentów. Dlatego w procesie użyta jest akcja pętla. Pętlę wykonujemy po zmiennej procesowej nazwanej u nas Lista faktur.
Zmienną tę definiujemy jako json czyli strukturę do przechowywania złożonych obiektów. Przykładowe pliki oraz pełny opis struktury można znaleźć na stronie dokumentacji serwisu.
W pętli używamy dwóch standardowych akcji: Stwórz dokument oraz Zmień wartość pola. Użycie tych akcji jest standardowe, tworzymy nowy dokument i uzupełniamy pola na tym dokumencie. Jak widać na zrzucie, zmienna typu json, której używamy w pętli, pozwala na rozwinięcie całej struktury dokumentu i dostęp do każdego pola.
Jak wiemy, w obiekcie json mogą być zawarte tablice, tak też jest w tym przypadku. Tablicą są np. pozycje na fakturze. By łatwiej uzupełnić dokument używamy akcji Zmień wartość pola z opcją Dodaj kolekcję – po wskazaniu tablicy w strukturze json system uzupełnia całą listę pozycji danymi zgodnie z definicją kolumn wskazaną w akcji.
Po wykonaniu pętli mamy ostatnią akcję – zapisujemy w dokumencie konfiguracyjnym datę pobrania faktur. Data ta posłuży nam przy kolejnym wywołaniu procesu jako data Od.
W procesie pobierania faktur nie mamy zdefiniowanego obiegu faktur. Obieg ten jest zdefiniowany niezależnie. Dzięki takiemu podejściu oddzielamy zdarzenie pobrania dokumentów od jego procesowania w ramach organizacji. Mamy jeden proces obiegu, który używamy niezależnie od tego, czy faktura została pobrana z KSeF, wprowadzona ręcznie czy poprzez OCR. Proces ten uruchamiamy podczas tworzenia dokumentu faktury.
Pełny opis serwisu wraz z przekładowym plikiem json zawierającym wszystkie pola zwracane z serwisu KSeF znajduje się w dokumentacji serwisu.
Wysyłanie faktury #
Wysyłanie faktury może być sprowadzone do dwóch akcji – wysyłania faktury i zapisywania numeru sesji. Obok tego procesu istnieje oczywiście cały proces obiegu faktury którego jednym z elementów będzie wysyłka.
Dlatego najwygodniej proces wysyłki stworzyć jako osobny proces i uruchomić go w procesie głównym. Na dwóch kolejnych zrzutach ekranu widać taką konfigurację.
I sam proces wysyłki
Na tym procesie jest trochę więcej akcji, gdyż mamy tu również obsłużony proces pobierania UPO z mechanizmem oczekiwania na kolejną iterację. Ten fragment nie jest potrzebny, możemy pobierać UPO w inny sposób, np. uruchamiając proces w pętli.
Prześledźmy teraz akcje, które są użyte do wysyłania faktury. Szczegółowy opis metod użytych w akcji Wywołaj Rest API znajduje się w osobnym artykule.
Jak widać jest to standardowe wywołanie metody API poprzez akcję, jako parametr podajemy json zasilany danymi z formularza. Całą konfigurację jsona wykonujemy w jednej akcji
Pełny opis metody wraz z przykładowym plikiem json znajduje się w dokumentacji serwisu.
Warto zwrócić uwagę na dane zwracane przez metodę SEND, jest to numer sesji KSeF. Będzie nam on potrzebny do pobrania potwierdzenia wysłania dlatego zapisujemy go w zmiennej procesowej.
W kolejnej akcji zapisujemy otrzymany numer w polu na formularzu. Ustawiamy przy okazji zmienną pomocniczą, która mówi nam o sposobie wysłania faktury. Zmienna ta będzie służyła jedynie do filtrowania dokumentów. Używamy tu standardowej akcji Zmień wartość pola.
Nasza faktura została wysłana.
Potrzebujemy jednak jeszcze otrzymać potwierdzenie wysłania, numer faktury w systemie KSeF oraz datę przesłania, która jest potrzebna do zaksięgowania dokumentu. Do tego używamy kolejnej metody z serwisu KSeF. Opis tej metody wraz z przykładowym jsonem znajduje się w dokumentacji serwisu.
Tym razem jako rezultat otrzymujemy json z polami. Standardowo konfigurujemy ten json jako zmienną procesową:
Na koniec wystarczy zapisać otrzymane dane na naszym formularzu faktury:
Warto zauważyć, że zapisujemy tu zarówno plik potwierdzenia jak i dane proste takie jak daty czy ciągi znaków. Możemy do tego użyć jednej akcji – zmień wartość pola.
Na tej operacji możemy skończyć obieg faktury. Dane zostały wysłane, pobraliśmy potwierdzenie. Jedyne co zostało do zrobienia to ewentualnie przesłać informacje z KSeF do systemu ERP ale to temat na osobny artykuł.