Integracja z KSeF
Zanim zaczniemy konfigurować formularze czy procesy pod integrację z KSeF warto przeczytać artykuł o przygotowaniu systemu do integracji.
Akcje¶
Aktualna wersja implementacji KSeF znacząco różni się sposobem działania od implementacji wersji 1.0. Akcje wyglądają podobnie ale zmienił się cały schemat działania. Ogólnie proces wysyłania faktur do KSeF wymaga następujących kroków:
- Przygotowanie pliku XML na podstawie danych formularza
- Przygotowanie do wysłania faktury
- Interaktywnie – jedną akcją na dokumencie faktury
- Wsadowo – poprzez dokument techniczny Paczka faktur do którego przypisane są faktury
- Pobranie informacji o sesji KSeF. W tej akcji uzupełniane są pola na dokumentach faktur niezależnie od sposobu wysłania
- W przypadku wysłania interaktywnego – na dokumencie faktury
- W przypadku wysłania wsadowego – na dokumencie paczki faktury
- Pobranie UPO – zawsze na dokumencie faktury
- Wizualizacja UPO w postaci pliku PDF – zawsze na dokumencie faktury
Pobieranie faktur nie zmieniło się znacząco. Logika działania jest identyczne, doszła tylko możliwość pobierania paczki faktur.
Wygeneruj fakturę KSeF¶
Akcja tworzy plik XML z danymi z faktury. Plik taki może zostać przesłany do innego systemu lub ręcznie przekazany do systemu KSeF. Plik XML jest wymagany do wysłania faktury wię tak akcja msi się znaleźć w procesie obiegu faktury jeżeli wysyłamy ją do KSeF.
Parametry:
Większość pól wbudowanych jest przypisana do odpowiednich pól faktury ustrukturyzowanej dlatego nie trzeba ich konfigurować w akcji.
Dokument – Wskazanie dokumentu, na podstawie którego zostanie wygenerowana faktura KSeF. Z reguły jest to dokument na którym uruchomiono procedurę obiegu. Domyślnie jest tu wstawiana zmienna systemowa Id Dokumentu
Użytkownik – osoba, która zostanie wskazana jako modyfikująca dokument. Domyślnie jest tu wstawiana zmienna systemowa ID zalogowanego użytkownika
Typ faktury w KSeF – pole słownikowe, pozwala na wybór typu faktury.
Faktura wystawiona w cenach – pole słownikowe, wybór rodzaju cen na fakturze.
Dodatkowe pola – pole typu lista atrybutów. Pozwala na zmapowanie pól formularza na pola faktury. Lista dostępnych pól znajduje się na końcu artykułu.
Zapisz plik w (return) – w tym polu wskazujemy atrybut plików, w którym przechowujemy plik XML. Dobrym pomysłem jest dodanie do formularza osobnego atrybutu na przechowywanie pliku XML faktury, będzie łatwiej wskazać takie pole w innych akcjach, np. wyślij fakturę.
Wyślij fakturę interaktywnie¶
Akcja wysyła wcześniej utworzony plik XML do systemu KSeF. Uwaga: jeżeli plik nie został wcześniej utworzony to akcja zakończy się błędem.
Parametry:
Firma – Wskazanie firmy, w imieniu której będzie wysyłana faktura. Z reguły wystarczy zostawić w tym polu wartość Pole systemowe: Id firmy
Plik – Wskazanie atrybutu, w którym przechowywany jest plik XML. Można użyć wartości systemowej Pliki lub wskazać własny atrybut. Jeżeli w atrybucie przechowywane jest więcej plików to po wskazaniu atrybutu brany jest pierwszy plik. W tym parametrze można też wskazać bezpośrednio ID pliku, np. wyliczone przy pomocy zapytania SQL.
Użytkownik – osoba, która zostanie wskazana jako modyfikująca dokument. Domyślnie jest tu wstawiana zmienna systemowa ID zalogowanego użytkownika
Zapisz numer referencyjny sesji w (return) – w tym miejscu można wskazać atrybut na formularzu, w którym zapisany zostanie numer sesji KSEF. Numer ten jest potrzebny by pobrać Urzędowe Potwierdzenie Odbioru. Obecność tego numeru jest również znakiem, że faktura została prawidłowo przesłana.
Wyślij fakturę wsadowo¶
Akcja przygotowuje i wysyła paczkę faktur na podstawie wcześniej utworzonych plików XML do systemu KSeF. Pack tworzona jest ze wszystkich dokumentów w polu Dokumenty ktore zawierają XML wygenerowany przez akcję Wygeneruj fakturę KSeF
Parametry:
Firma – Wskazanie firmy, w imieniu której będzie wysyłana faktura. Z reguły wystarczy zostawić w tym polu wartość Pole systemowe: Id firmy
Pliki – Wskazanie atrybutu, w którym przechowywane są ID plików XML do wysłania. Można użyć wartości systemowej Pliki lub wskazać własny atrybut. W tym parametrze można też wskazać bezpośrednio ID pliku, np. wyliczone przy pomocy zapytania SQL.
Użytkownik – osoba, która zostanie wskazana jako modyfikująca dokument. Domyślnie jest tu wstawiana zmienna systemowa ID zalogowanego użytkownika
Zapisz numer referencyjny sesji w (return) – w tym miejscu można wskazać atrybut na formularzu, w którym zapisany zostanie numer sesji KSEF. Numer ten jest potrzebny by pobrać Urzędowe Potwierdzenie Odbioru. Obecność tego numeru jest również znakiem, że faktura została prawidłowo przesłana.
W tym miejscu warto wspomnieć o dokumencie technicznym – Paczka faktur. Jeżeli wysyłamy wsadowo faktury należy przygotować taki dokument który będzie zbierał informacje o fakturach przypisanych doo paczki. Proces wysyłania faktur będzie uruchamiany na tym technicznym dokumencie a nie na oryginalnym dokumencie faktury. Jak widzimy w konfiguracji do wysłania faktur potrzebujemy dwóch parametrów: Firmy i Plików. Firma to oczywiście pole systemowe Firma, należy tylko zwrócić uwagę by firma z faktury zgadzała się z firmą z paczki faktur. Jeżeli nie mamy wdrożonej wielofirmowości to w ogóle nie mamy takiego problemu, możemy użyć zmiennej systemowej ID firmy. Pole pliki powinno zawierać ID plików XML z fakturami wygenerowanymi akcją Wygeneruj fakturę KSeF. Może to być zwykłe pole Auto wyszukiwanie wielokrotnego wyboru z podpiętą listą plików lub zwykłym zapytaniem SQL do tabeli Fi.
W procesie obiegu faktury należy dodać ścieżkę – Wysłanie paczki faktur – w ramach tej ścieżki dodać bieżącą fakturę do pola Faktury w paczce na paczce faktur. Niestety nie ma prostej akcji która potrafi to zrobić, należy albo napisać rozszerzenie albo przygotować akcje Zmień wartość pola w których zapytaniami SQL dodamy odpowiednie wartości do tabeli FlVa. Ponieważ to zapytanie nie dodaje się do bezpośredniego wklejenia do akcji nie będziemy go podawać, należy przygotować swoje własne zapytanie. Ogólny schemat obiegu mógłby wyglądać następująco:
Dodatkowo na formularzu faktury zostało dodane pole Paczka faktur w którym wybieramy do jakiej paczki mamy dodać fakturę. Jest to zwykłe pole Auto wyszukiwanie z podpiętą listą dokumentów typu Paczka faktur. Warto tu zastosować zapytanie SQL w którym ograniczymy wybór paczki do konkretnej firmy czy statusu paczy (tylko niewysłane). Pola tego używamy w akcji do wskazania dokumentu na którym modyfikujemy pole Faktury w paczce.
Różnica między wysyłaniem interaktywny a wsadowym¶
KSeF w wersji 2.0 wprowadził limity w ilości wysyłanych i odbieranych faktur. Dla faktur sprzedażowych, które wysyłamy do KSeF wygląda to tak:
| Rodzaj wysyłki | Na sekundę | Na minutę | Na godzinę |
| Wysyłka interaktywna | 10 faktur | 30 faktur | 180 faktur |
| Wysyłka wsadowa | 10 paczek | 20 paczek | 120 paczek |
O ile limity sekundowe czy minutowe nie powinny nikogo ograniczać to limit godzinowy dla wysyłki interaktywnej może być problemem. Dlatego należy policzyć, ile faktur będzie wysyłane i dostosować do tego konfigurację systemu. Gdy generujemy więcej niż 100 faktur na godzinę to należy poważnie zastanowić się nad implementacją paczki faktur od razu a nie czekać aż system zacznie odrzucać faktury z powodu przekroczenia limitu.
Limit ilości paczek jest praktycznie nie do przekroczenia ponieważ w jednej paczce może być nawet kilka tysięcy faktur.
Pobierz informacje o fakturach wysłanych w sesji¶
Kiedy już udało nam się wysłać fakturę i mamy numer sesji to kolejnym krokiem jest sprawdzenie, co się z naszymi fakturami dzieje. Potrzebujemy też pobrać informacje z KSeF o numerze faktury czy datach rejestracji. Do tego właśnie służy akcja Pobierz informacje o fakturach wysłanych w sesji. Warto zauważyć, że o ile mamy dwie akcje na wysyłanie faktur – interaktywnie i wsadowo – to mamy tylko jedną akcję do pobierania informacji. Tą akcją obsłużymy obie metody wysyłania
Parametry:
Numer referencyjny sesji – Numer, który zapisaliśmy przy wysyłaniu faktur. Po tym parametrze sprawdzamy paczkę faktur wysłanych do KSeF. Uwaga: jeżeli wysyłamy interaktywnie to paczka faktur zawiera po prostu jeden dokument.
Firma – Wskazanie firmy, która odpowiada za wysłanie dokumentów. Jeżeli mamy jedną firmę w systemie to wystarczy pole systemowe ID Firmy ale jeżeli mamy wielowirmowość to lepiej użyć pola Firma na dokumencie. Jeżeli Numer referencyjny sesji nie będzie się zgadzał z NIP-em firmy to dostaniemy błąd o braku sesji.
Typ dokumentów wysłanych w sesji – typ dokumentu Navigatora które zostały wysłane. Z reguły będzie to Faktura zakupu.
Plik / pliki – odnośnik do plików wysłanych w sesji. Dla wysyłki interaktywnej może to być po prostu ID atrybutu z fakturą w XML. Jeżeli wysyłamy paczkę faktur to mamy na polu dokumentu Paczka faktur pole wskazujące pliki w paczce. To pole należy podać jako parametr tej akcji.
Użytkownik – osoba, która zostanie wskazana jako modyfikująca dokument. Domyślnie jest tu wstawiana zmienna systemowa ID zalogowanego użytkownika
Dodatkowe pola – Tu możemy określić jakie pola zostaną zapisane na dokumencie. Uwaga: są to pola dotyczące dokumentów wskazanych w parametrze Dokumenty wysłane w sesji więc w przypadku paczki faktur zmiany będą nanoszone na każdym dokumencie wskazanym w paczce.
Dostępne pola:
Adres do pobrania UPO: Adres URL, pod którym dostępny jest plik XML z UPO. Służy jako parametr do kolejnej akcji
Data nadania numeru KSeF: Data nadania numeru KSeF. Należy ją interpretować jako datę dostarczenia faktury do kontrahenta
Data przyjęcia faktury: Data przyjęcia faktury do systemu KSeF, należy ją interpretować jako datę wystawienia faktury
Data trwałego zapisu faktury: Data trwałego zapisu faktury. Od tego czasu faktury nie można zmienić ani usunąć z systemu.
Status: Kod: Kod statusu faktury w KSeF. Mając kod możemy sterować procesem, np. wychwytując faktury które zostały ponownie wysłane lub faktury które nadal są przetwarzane
Status: Opis: Opis statusu. To jest informacja o stanie faktury przedstawiona w czytelny dla człowieka sposób.
Status: Szczegóły: Dodatkowe informacje, np. informacja w której sesji została wysłana faktura jeżeli system uzna naszą fakturę za duplikat.
Numer KSeF: Najważniejsza informacja. Po numerze KSeF zidentyfikujemy płatność czy możemy soę komunikować z kontrahentem w sprawie wyjaśnienia wątpliwości dotyczących faktury.
Zapisz plik w (return) – Należy wskazać pole do którego zostanie zapisany plik json ze wszystkimi danymi pobranymi w akcji. Uwaga: to nie jest zapisanie Urzędowego Potwierdzenia Odbioru (UPO) faktury, do tego służy kolejna akcja.
Akcja Pobierz UPO¶
Akcja pozwala na pobranie Urzędowego Potwierdzenia Odbioru (UPO). Dokument ten jest tożsamy z potwierdzeniem dostarczenia faktury do kontrahenta. Dokument UPO pobierany jest w formie XML i zapisywany w panelu załączników.
Parametry:
Adres do pobrania: Adres, który dostaliśmy w akcji Pobierz informacje o statusie faktur wysłanych w sesji. W przeciwieństwie do tej tamtej akcji Pobierz UPO działa na dokumencie faktury. W panelu załączników zapisywany jest plik XML z UPO.
Dokument – Wskazanie dokumentu, na podstawie którego zostanie wygenerowana faktura KSeF. Z reguły jest to dokument na którym uruchomiono procedurę obiegu. Domyślnie jest tu wstawiana zmienna systemowa Id Dokumentu
Użytkownik – osoba, która zostanie wskazana jako modyfikująca dokument. Domyślnie jest tu wstawiana zmienna systemowa ID zalogowanego użytkownika
Generuj podgląd UPO w PDF¶
Ostatnią akcją związaną z wysyłaniem faktur jest generowanie podglądu UPO w PDF. Do jej wywołania potrzebujemy plik XML z UPO który pobieramy akcją Pobierz UPO. Po wywołaniu akcji plik PDF trafia do panelu załączników.
Parametry:
Plik:Wskazanie na ID pliku z którego ma zostać wygenerowany PDF. Jeżeli wskażemy panel plików to zostanie pobrany pierwszy załącznik.
Dokument – Wskazanie dokumentu, na podstawie którego zostanie wygenerowana faktura KSeF. Z reguły jest to dokument na którym uruchomiono procedurę obiegu. Domyślnie jest tu wstawiana zmienna systemowa Id Dokumentu
Użytkownik – osoba, która zostanie wskazana jako modyfikująca dokument. Domyślnie jest tu wstawiana zmienna systemowa ID zalogowanego użytkownika
Wynik działania akcji wygląda tak:
Akcja Pobierz faktury¶
Akcja pozwala na pobranie faktur wystawionych na firmę z systemu KSeF. W aktualnej wersji akcja ta jedynie pobiera pliki XML i zapisuje je w polu na formularzu. Dla każdego pobranego pliku XML tworzony jest jeden dokument w Navigatorze. Akcja nie przetwarza pliku XML i nie uzupełnia pól na formularzu.
System KSeF obsługuje siedem typów faktur. W konfiguracji akcji możemy zmapować typy faktur KSeF na typy dokumentów w Navigatorze. Warto w konfiguracji uwzględnić wszystkie typu faktur KSeF gdyż brak jakiegoś typu może skutkować zagubieniem faktury. System pamięta ostatnio pobraną fakturę i pobiera wszystkie starsze ale jeżeli nie ma zmapowanego typu faktury to faktury tego typu będą pomijane.
Konfiguracja pobierania wsadowego wygląda identycznie.
Parametry akcji Pobierz fakturę
Firma – ID firmy dla której pobieramy faktury. Ponieważ proces może być uruchamiany bez formularza możemy tu wstawić zmienną systemową ID firmy
Użytkownik – osoba, która zostanie wskazana jako modyfikująca dokument. Domyślnie jest tu wstawiana zmienna systemowa ID zalogowanego użytkownika
Pobierz faktury z okresu (dni) – parametr opcjonalny. Jeżeli zostanie ustawiony system pobierze faktury które nie są starsze niż X dni. Parametr warto ustawić przy pierwszym uruchomieniu na nowym środowisku gdy wiemy, że możemy pobrać setki lub tysiące starych faktury. W pozostałych przypadkach sugerowałbym pozostawienie tego pola pustego.
Ustawienia – w tym miejscu mapujemy typy faktur KSeF na typy dokumentów w Navigatorze. Do wyboru mamy takie opcje:
Typ faktury KSeF – tu wskazujemy typ faktury KSeF który chcemy zmapować. Typ może pojawić się tylko raz, jeżeli ustawimy dwa różne mapowania dla tego samego typu to system potraktuje to jako błąd
Typ dokumentu – typ dokumentu z Navigatora. Ty możemy przypisać jeden typ dokumenty do wielu typów faktur, np. wszystkie faktury korygujące KSeF trafiają do jednego typu dokumentu – Faktura korygująca.
Kategoria dokumentu – kategoria dokumentu w Navigatorze
Zapisz plik w – atrybut, w którym będzie przechowywany dokument XML. Musi to być atrybut typu Pliki. Możemy wskazać systemowy kontener plików ale wygodniej jest przygotować dedykowany atrybut do przechowywania plików XML faktury. Będzie nam łatwiej potem wskazać plik w akcji przetwarzania faktury. Jeżeli nie zapiszemy pliku na formularzu to nie będziemy mogli potem przenieść informacji z pliku faktury do pól na formularzu.
Zapisz numer KSeF w – pole tekstowe w którym zapiszemy numer KSeF otrzymanej faktury
Akcja Przetwórz fakturę KSeF¶
Akcja przetwarza plik XML i odczytuje z niego dane. Pola z faktury ustrukturyzowanej są przepisywane na odpowiednie pola formularza zgodnie z mapowaniem w konfiguracji akcji. Część pól jest już zmapowana na pola wbudowane więc nie trzeba ich podawać w konfiguracji akcji. Akcja powinna być uruchomiona na samym początku procedury obiegu faktury bo bez niej użytkownik dostanie pusty dokument. Proces obiegu faktury mógłby wyglądać następująco:
¶
Na rysunku widzimy dwie akcje: Przetwarzanie faktury i Generowanie obrazu faktury. Ta drug akcja opisana jest niżej¶
Konfiguracja akcji wygląda następująco:
Obie wersje akcji mają identyczną konfigurację.
Parametry akcji pobierania faktur
Plik – atrybut, w którym przechowywany jest XML pobrany z KSeF
Dokument – ID dokumentu który modyfikujemy. Z reguły będzie to pole systemowe ID Dokumentu
Użytkownik – osoba, która zostanie wskazana jako modyfikująca dokument. Domyślnie jest tu wstawiana zmienna systemowa ID zalogowanego użytkownika
Dodatkowe pola – pole typu lista atrybutów. Większość pól wbudowanych jest przypisana do odpowiednich pól faktury ustrukturyzowanej dlatego nie trzeba ich konfigurować w akcji, w tym miejscu wskazujemy mapowanie wszystkich pól dodatkowych które będą przechowywane na formularzu jako atrybuty.
Generuj podgląd faktury w PDF¶
Pobranie faktury akcją Pobierz faktury jedynie uzupełni pola na formularzu, nie otrzymamy graficznego obrazu faktury np. w pliku PDF. Jeżeli chcemy otrzymać taki obraz to powinniśmy skorzystać z akcji Generuj podgląd faktury w PDF. Akcja działa podobnie jak akcja Generuj podgląd UPO w PDF
Parametry:
Plik:Wskazanie na ID pliku z którego ma zostać wygenerowany PDF. Jeżeli wskażemy panel plików to zostanie pobrany pierwszy załącznik.
Użytkownik – osoba, która zostanie wskazana jako modyfikująca dokument. Domyślnie jest tu wstawiana zmienna systemowa ID zalogowanego użytkownika
Zapisz plik w (return) – w tym miejscu wskazujemy miejsce – atrybut załącznik lub pole załączników na formularzu – gdzie będzie zapisany obraz faktury.
Kody QR na fakturze¶
Co to są kody QR i do czego będziemy ich potrzebować? Najlepiej oddać głos Ministerstwu Finansów które w najczęściej zadawanych pytaniach odpowiada:
Kod QR to specjalny znak graficzny umieszczany na wizualizacji faktury. Pozwala w prosty sposób sprawdzić czy dokument znajduje się w systemie, a po wpisaniu dodatkowych danych pobrać go z KSeF.
Faktury wystawione online i faktury wystawione w trybie offline (już dosłane do KSeF) mają kod QR z napisem w postaci numeru KSeF.
Faktury wystawione offline, ale jeszcze nie dosłane do KSeF, mają dwa kody QR. Pierwszy z napisem „OFFLINE” zapewnia dostęp do tej faktury i weryfikację danych z faktury, a drugi kod QR z napisem „CERTYFIKAT”, umożliwia weryfikację tożsamości wystawcy.
Całość Pytań i odpowiedzi znajduje się pod tym adresem: https://ksef.podatki.gov.pl/pytania-i-odpowiedzi-ksef-20
W systemie Navigator mamy dwie akcje służące do generowania kodów QR
Wygeneruj kod QR do weryfikacji faktury (Kod I)¶
Akcja pozwala na wygenerowanie kodu I czyli kodu OFFLINE opisanego wyżej
Parametry:
Firma – Wskazanie firmy, która odpowiada za wysłanie dokumentów. Jeżeli mamy jedną firmę w systemie to wystarczy pole systemowe ID Firmy ale jeżeli mamy wielowirmowość to lepiej użyć pola Firma na dokumencie.
Pliki – Wskazanie pola, w którym jest wygenerowany plik XML z fakturą. Na przykładzie powyżej jest to dedykowany atrybut
Użytkownik – osoba, która zostanie wskazana jako modyfikująca dokument. Domyślnie jest tu wstawiana zmienna systemowa ID zalogowanego użytkownika
Zapisz plik w (return) – wskazanie atrybutu lub plików gdzie zostanie zapisany plik z obrazem kodu QR. Uwaga, w przypadku faktur offline należy wygenerować wydruk faktury po wygenerowaniu kodu QR i umieścić ten kod na wydruku.
Wygeneruj kod QR do potwierdzenia autentyczności wystawcy (Kod II)¶
Akcja pozwala na wygenerowanie kodu II czyli kodu CERTYFIKAT opisanego wyżej
Parametry:
Firma – Wskazanie firmy, która odpowiada za wysłanie dokumentów. Jeżeli mamy jedną firmę w systemie to wystarczy pole systemowe ID Firmy ale jeżeli mamy wielowirmowość to lepiej użyć pola Firma na dokumencie.
Pliki – Wskazanie pola, w którym jest wygenerowany plik XML z fakturą. Na przykładzie powyżej jest to dedykowany atrybut
Użytkownik – osoba, która zostanie wskazana jako modyfikująca dokument. Domyślnie jest tu wstawiana zmienna systemowa ID zalogowanego użytkownika
Zapisz plik w (return) – wskazanie atrybutu lub plików gdzie zostanie zapisany plik z obrazem kodu QR. Uwaga, w przypadku faktur offline należy wygenerować wydruk faktury po wygenerowaniu kodu QR i umieścić ten kod na wydruku.
Przykłady procedur obiegu¶
Wysłanie faktury¶
Wysyłanie faktur najwygodniej zrealizować w ramach procedury obiegu faktury. Po kroku zatwierdzenia dokumentu można dodać kroki, które będą odpowiadały za wysyłkę faktury.
Na poniższym diagramie przedstawiony jest przykład obsłużenia trzech form wysyłki faktury: poprzez KSeF, poprzez e-mail oraz tradycyjnie, pocztą. Wykorzystane są tu akcje do wysyłki e-maili oraz akcje integracji z KSeF
Warto zauważyć, że akcja wysyłki przez KSeF jest wykonywana automatycznie zaś akcja pobierania UPO jest zwykłym działaniem użytkownika. Taka konfiguracja jest niezbędna, gdyż dokument wysłany do KSeF musi być przetworzony. Powoduje to, że bywają opóźnienia w generowaniu UPO. Dlatego użytkownik musi ręcznie, po jakimś czasie pobrać UPO.
Pobranie faktur¶
Pobieranie faktu można zrealizować poprzez prosty obieg składający się z jednej akcji. Ważne, by skonfigurować ten obieg w trybie akcji.
Dzięki temu będzie można podpiąć taki obieg pod pozycję w menu dokumentów. Użytkownik, wybierając opcję Pobierz z KSeF, zainicjuje pobieranie faktur.
Pola używane do komunikacji z KSeF¶
Akcje, służące do integracji z systemem KSeF wykorzystują pola systemowe do pobierania informacji z formularza i przesyłania ich do systemu KSeF. Oznacza to, że na formularzu muszą być takie pola jak netto, brutto, VAT czy asortyment by prawidłowo przygotować plik XML do wymiany. Tych pól nie można skonfigurować poprzez wskazanie mapowania z dowolnym atrybutem na formularzu. Akcje integracyjne nie będą prawidłowo bez tych pól.
Jednak nie wszystkie pola używane do wymiany z KSeF są obsługiwane jako pola systemowe. W tym przypadku możemy użyć atrybutów jednak do prawidłowej pracy należy wskazać mapowanie atrybutu na pole w XML KSeF. Dostępna lista pól:
Data umowy – pole typu data, służy do wskazania daty umowy na podstawie której została wystawiona faktura; pole nieobowiązkowe
Data zamówienia – pole typu data, służy do wskazania daty zamówienia, na podstawie którego została wystawiona faktura; pole nieobowiązkowe
Data zapłaty – Pole typu data; zawiera datę zapłaty w przypadku gdy faktura została opłacona; pole nieobowiązkowe
Data zapłaty częściowej – Pole typu data, zawiera datę zapłaty częściowej w przypadku gdy faktura została częściowo opłacona; pole nieobowiązkowe
Kwota zapłaty częściowej – Pole typu liczba zmiennoprzecinkowa, zawiera kwotę częściowej zapłaty; pole nieobowiązkowe
Numer umowy – Pole tekstowe, zawiera numer umowy, na podstawie której wystawiono fakturę; pole nieobowiązkowe
Numer zamówienia – Pole tekstowe; zawiera numer zamówienia, na podstawie którego wystawiono fakturę; pole nieobowiązkowe
P_16 Metoda kasowa – Pole jednokrotnego wyboru, W przypadku faktur zawierających adnotację „metoda kasowa”, dokumentujących dostawę towarów lub świadczenie usług, w odniesieniu do których obowiązek 61 podatkowy powstaje zgodnie z art. 19a ust. 5 pkt 1 lub art. 21 ust. 1 ustawy, należy podać wartość „1″; w przeciwnym przypadku należy podać wartość „2″; Pole obowiązkowe
P_17 Samofakturowanie – Pole jednokrotnego wyboru, W przypadku faktur, o których mowa w art. 106d ust. 1 ustawy, zawierających adnotację „samofakturowanie”, należy podać wartość „1″; w przeciwnym przypadku należy podać wartość „2″. ; Pole obowiązkowe
P_18 Odwrotne obciążenie – Pole jednokrotnego wyboru, W przypadku faktur zawierających adnotację „odwrotne obciążenie”, dokumentujących dostawę towarów lub wykonanie usługi, dla których obowiązanym do rozliczenia podatku od wartości dodanej lub podatku o podobnym charakterze jest nabywca towaru lub usługi – należy podać wartość „1″; w przeciwnym przypadku należy podać wartość „2″. ; Pole obowiązkowe
P18A Mechanizm podzielonej płatności – Pole jednokrotnego wyboru, W przypadku faktur zawierających adnotację „mechanizm podzielonej płatności”, w których kwota należności ogółem przekracza kwotę 15.000 zł lub jej równowartość wyrażoną w walucie obcej, obejmujących dokonaną na rzecz podatnika dostawę towarów lub świadczenie usług wymienionych w załączniku nr 15 do ustawy, należy podać wartość „1″; w przeciwnym przypadku należy podać wartość „2”.; Pole obowiązkowe
P_19 Czy zwolnienie z VAT – Pole jednokrotnego wyboru, W przypadku faktur dokumentujących dostawę towarów lub świadczenie usług zwolnionych od podatku na podstawie art. 43 ust. 1 ustawy, art. 113 ust. 1 i 9 albo przepisów wydanych na podstawie art. 82 ust. 3 ustawy lub na podstawie innych przepisów, należy podać 62 wartość „1″; w przeciwnym przypadku należy podać wartość „2″. W przypadku, gdy pole P_19 równa się „1”, należy wypełnić dodatkowo jedno z pól: P_19A, P_19B lub P_19C.; Pole obowiązkowe
P_19A Przepis ustawy uprawniającej do zwolnienia – Pole tekstowe, Jeśli pole P_19 równa się „1″ – należy wskazać przepis ustawy albo aktu wydanego na podstawie ustawy, na podstawie którego podatnik stosuje zwolnienie od podatku. Przykład: „Art. 43 ust. 1 pkt 37 ustawy o podatku od towarów i usług (Dz. U. 2021 poz. 685 ze zm.)”
P_19B Przepis dyrektywy 2006/112/WE – Pole tekstowe, Jeśli pole P_19 równa się „1″ – należy wskazać przepis dyrektywy 2006/112/WE, który zwalnia od podatku taką dostawę towarów lub takie świadczenie usług.
P_19C Inna podstawa prawna – Pole tekstowe, Jeśli pole P_19 równa się „1″ – należy wskazać inną podstawę prawną wskazującą na to, że dostawa towarów lub świadczenie usług korzysta ze zwolnienia.
UWAGA: jeżeli pole P_19 jest ustawione na 1 to należy wypełnić jedno z pól P_19A, P_19B, P_19C
P_PMarzy Procedura marży – Pole jednokrotnego wyboru, W przypadku wystąpienia procedur marży, o których mowa w art. 119 lub 120 ustawy, należy podać wartość „1”; w przeciwnym przypadku należy podać wartość „2”. W przypadku, gdy pole P_PMarzy równa się „1”, należy wypełnić dodatkowo jedno z pól: P_PMarzy_2, P_PMarzy_3_1, P_PMarzy_3_2, P_PMarzy_3_3.
P_PMarzy_2 Procedura marży dla biur podróży – Pole logiczne (checkbox), W przypadku świadczenia usług turystyki, dla których podstawę opodatkowania stanowi marża, zgodnie z art. 119 ust. 1 ustawy, a faktura dokumentująca świadczenie zawiera wyrazy „procedura marży dla biur podróży”, należy podać wartość „1”.
P_PMarzy_3_1 Procedura marży – towary używane – Pole logiczne (checkbox), W przypadku dostawy towarów używanych, dla których podstawę opodatkowania stanowi marża, zgodnie z art. 120 ustawy, a faktura dokumentująca dostawę zawiera wyrazy „procedura marży – towary używane”, należy podać wartość „1”.
P_PMarzy_3_2 Procedura marży – dzieła sztuki – Pole logiczne (checkbox), W przypadku dostawy dzieł sztuki, dla których podstawę opodatkowania stanowi marża, zgodnie z art. 120 ustawy, a faktura dokumentująca dostawę zawiera wyrazy „procedura marży – dzieła sztuki”, należy podać wartość „1”.
P_PMarzy_3_1 Procedura marży – Przedmioty kolekcjonerskie i antyki – Pole logiczne (checkbox), W przypadku dostawy przedmiotów kolekcjonerskich i antyków, dla których podstawę opodatkowania stanowi marża, zgodnie z art. 120 ustawy, a faktura dokumentująca dostawę zawiera wyrazy „procedura marży – przedmioty kolekcjonerskie i antyki”, należy podać wartość „1”.
Zapłacono – Pole logiczne, Podaje się „1” w przypadku, gdy kwota należności wynikająca z faktury, do momentu jej wystawienia, została zapłacona w całości.
Zapłata częściowa – Pole logiczne, Podaje się „1” w przypadku, gdy kwota należności wynikająca z faktury, do momentu jej wystawienia, została zapłacona w części.
Dodatkowo warto na formularzu faktury umieści techniczne pole tekstowe Numer KSeF. Jeśli działanie akcji Wyślij do KSeF zakończy się sukcesem to system KSeF zwróci unikatowy numer który należy zapamiętać. Ten numer posłuży do komunikacji z KSeF i wskazania konkretnego dokumentu np. do pobrania UPO (Urzędowe Potwierdzenie Odbioru) lub do wystawienia faktury korygującej.
Warto również dodać dwa kolejne pola techniczne:
Data przesłania do KSeF – Pole typu data i czas
Data przyjęcia w KSeF – pole typu Data i czas
Używając dodatkowych akcji Pobierz z UPO datę przesłania oraz Pobierz z UPO datę przyjęcia można zapisać te daty w polach technicznych. Daty te są bardzo istotne gdyż są używane do określenia daty dostarczenia faktury do kontrahenta oraz są brane pod uwagę przy rozliczeniach VAT-owskich.
Pola wbudowane importowane z KSeF¶
| KSeF (XML) | Tabela Documnet ([Do]) | Dokumenty |
| Fa.P_2 | ForgeinNumber | Numer obcy |
| Fa.P_1 | DocumentDate | Data dokumentu |
| Fa.P_6 | FactDate | Data zdarzenia gospodarczego |
| Fa.Platnosc.TerminPlatnosci.Termin | PayDate | Data płatności |
| Fa.Platnosc.FormaPlatnosci | PaymentTypeID | Typ płatności |
| Podmiot1.DaneIdentyfikacyjne.NIP | ContractorID | ID kontrahenta |
| Fa.KodWaluty | CurrencyID | ID waluty |
| Fa.Platnosc.RachunekBankowy.NrRB | AccountID | ID konta bankowego |
| pole wyliczane | Net | Kwota netto |
| pole wyliczane | Vat | Kwota VAT |
| pole wyliczane | Gross | Kwota Brutto |
| pole wyliczane | NetMain | Kwota netto w walucie głównej |
| pole wyliczane | VatMain | Kwota VAT w walucie głównej |
| pole wyliczane | GrossMain | Kwota Brutto w walucie głównej |
| KSeF (XML) | Tabela ContractorAccount ([CoCa]) | Konta bankowe kontrahentów |
| Podmiot1.DaneIdentyfikacyjne.NIP | ContractorId | ID kontrahenta |
| Fa.Platnosc.RachunekBankowy.NrRB | AccountNumber | Numer rachunku bankowego |
| Fa.Platnosc.RachunekBankowy.NrRB | CurrencyId | ID waluty |
| KSeF (XML) | Tabela DocumentElements ([DoEl]) | Elementy na fakturze |
| pole wyliczane | DocumentID | ID dokumentu |
| Fa.FaWiersz.P_7 | AssortmentID | ID asortymentu |
| Fa.FaWiersz.P_7 | AssortmentName | Nazwa asortymentu |
| Fa.FaWiersz.P_8A | UnitID | ID jednostki miary |
| Fa.FaWiersz.P_7 | Name | Nazwa |
| Fa.FaWiersz.P_8B | Amount | Ilość |
| Fa.FaWiersz.P_9A lub Fa.FaWiersz.P_9B | PriceNet | Cena netto |
| Fa.FaWiersz.P_9A lub Fa.FaWiersz.P_9B | PriceNetBeforeDiscount | Cena netto przed rabatem |
| pole wyliczane | ValueNet | Wartość netto |
| Fa.FaWiersz.P_12 | VatID | ID stawki VAT |
| pole wyliczane | PriceNet | Cena netto |
| pole wyliczane | PriceGross | Cena Brutto |
| pole wyliczane | PriceGrossBeforeDiscount | Cena Brutto przed rabatem |
| pole wyliczane | ValueVat | Wartość VAT |
| pole wyliczane | ValueGross | Wartość Brutto |
| KSeF (XML) | Tabela DocumentVat ([DoVa]) | Tabela VAT |
| pole wyliczane | DocumentId | ID dokumentu |
| pole wyliczane | VatId | ID stawki VAT |
| pole wyliczane | VatRate | Stawka VAT |
| pole wyliczane | VatName | Nazwa stawki VAT |
| pole wyliczane | NetValue | Wartość netto |
| pole wyliczane | VatValue | Wartość VAT |
| pole wyliczane | GrossValue | Wartość Brutto |
| pole wyliczane | NetValueMain | Wartość netto w walucie głównej |
| pole wyliczane | VatValueMain | Wartość VAT w walucie głównej |
| pole wyliczane | GrossValueMain | Wartość Brutto w walucie głównej |
Warto zwrócić uwagę na kilka aspektów związanych z polawmi wbudowanymi
- Adnotacja pole wyliczane oznacza, że wartość jest wyliczana z innych pól tak jak np. tabela VAT jest wyliczana z pozycji na fakturze (Fa.Wiersz) lub z operacji w trakcie dodawania jak np. Element.DocumentID jest ustawiane na podstawie ID dokumentu utworzonego przy imporcie
- System stara się dodać do bazy niektóre dane jeżeli nie ma ich jeszcze w bazie. Dotyczy to kontrahenta czy numeru rachunku bankowego. W trakcie dodawania może być uruchomiona cała procedura związana z nowym rekordem jak np. odwołanie do bazy GUS przy dodawaniu nowego kontrahenta.
- Nie wszystkie elementy są dodawane. Jeżeli system znajdzie na fakturze wartość której nie ma w bazie to zostanie ona pominięta. Dotyczy to:
- Metod płatności. Należy najpierw dodać nowe metody i zmapować je ze słownikiem KSeF. Dodawanie metod płatności odbywa się poprzez Ustawienia > Kartoteki > Formy płatności.Należy przypilnować, by wszystkie formy płatności z KSeF miały swoje odpowiedniki w Navigatorze
- Waluty. Należy dodać nową walutę jeżeli spodziewamy się faktury w tej walucie. Dodawanie waluty odbywa się poprzez Ustawienia > Kartoteki > Waluty. Jako symbol należy podać kod ISO waluty
Mapowanie atrybutów do pól KSeF¶
Poniżej znajduje się tabela zawierająca mapowanie pól konfigurowalnych, opisanych w akapicie Pola używane do komunikacji z KSeF, do pól z XML KSeF
| KSeF (XML) | Atrybut (akcja) |
| P_16 | P_16 metoda kasowa |
| P_17 | P_17 samofakturowanie |
| P_18 | P_18 odwrotne obciążenie |
| P_18A | P_18A mechanizm podzielonej płatności |
| P_19 | P_19 czy zwolnienie z vat |
| P_19A | P_19A przepis ustawy uprawniający do zwolnienia |
| P_19B | P_19B przepis dyrektywy 2006/112/WE |
| P_19C | P_19C inna podstawa prawna |
| P_23 | P_23 faktura WE uproszczona |
| P_PMarzy | P_PMarzy procedura marży |
| P_PMarzy_2 | P_PMarzy_2 procedura marży dla biur podróży |
| P_PMarzy_3_1 | P_PMarzy_3_1 procedura marży-towary używane. |
| P_PMarzy_3_2 | P_PMarzy_3_2 procedura marży-dzieła sztuki |
| P_PMarzy_3_3 | P_PMarzy_3_3 procedura marży-przedmioty kolekcjonerskie i antyki |
| DataUmowy | Data umowy |
| NrUmowy | Numer umowy |
| DataZamowienia | Data zamówienia |
| NrZamowienia | Numer zamówienia |
| Zaplacono | Zapłacono |
| DataZaplaty | Data zapłaty |
| ZaplataCzesciowa | Zapłata częściowa |
| DataZaplatyCzesciowej | Data zapłaty częściowej |
| KwotaZaplatyCzesciowej | Kwota zapłaty częściowej |
| NrRBPL | Numer rachunku bankowego PL |