Przejdź do treści

Integracja z KSeF

Integracja z Krajowym Systemem e-Faktur (KSeF) w Navigatorze opiera się na akcjach systemowych, które ustawiasz w krokach procedur obiegu dokumentów (patrz Akcje systemowe). Akcje pozwalają wygenerować i wysłać fakturę sprzedaży, sprawdzić jej status i pobrać Urzędowe Poświadczenie Odbioru (UPO), a w drugą stronę pobrać faktury zakupu i przepisać ich dane na formularz.

Zanim zaczniesz

Navigator komunikuje się z KSeF poprzez serwis pośredniczący dostarczany przez firmę Archman. Certyfikaty, serwis, kody stawek VAT i mapowanie form płatności opisuje artykuł Przygotowanie systemu pod KSeF. Od tej konfiguracji zależy działanie akcji:

  • NIP firmy: akcje identyfikują firmę po NIP-ie kontrahenta przypisanego do firmy. Jeżeli firma nie ma kontrahenta albo NIP jest niepoprawny, akcja kończy się błędem.
  • Stawki VAT: kod stawki musi być jednym z kodów KSeF: 23, 22, 8, 7, 5, 4, 3, 0 KR, 0 WDT, 0 EX, zw, oo, np I, np II. Pozycja ze stawką o innym kodzie trafi do faktury bez stawki VAT.
  • Formy płatności: każda forma płatności powinna mieć przypisaną formę KSeF: Gotówka, Karta, Bon, Czek, Kredyt, Przelew, Płatność mobilna lub Płatność inna. Forma bez przypisania nie trafi do wysyłanej faktury, a przy imporcie pole zostanie puste.
  • Waluty: przy imporcie waluta jest wyszukiwana po symbolu, dlatego symbol waluty musi być kodem ISO (np. PLN, EUR). Faktura w walucie, której nie ma w systemie, zostanie zaimportowana bez waluty.

Przegląd akcji

Akcja Do czego służy Gdzie się ją uruchamia
Wygeneruj fakturę KSeF Tworzy plik XML faktury z danych formularza Faktura sprzedaży
Wyślij fakturę interaktywnie Wysyła do KSeF jeden plik XML Faktura sprzedaży
Wyślij faktury wsadowo Wysyła do KSeF paczkę plików XML Paczka faktur
Pobierz informacje o fakturach wysłanych w sesji Zapisuje na fakturach numer KSeF, status i adres UPO Faktura sprzedaży lub paczka faktur
Pobierz status sesji Zapisuje status całej sesji wysyłki Faktura sprzedaży lub paczka faktur
Pobierz UPO Pobiera plik XML z UPO Faktura sprzedaży
Wygeneruj podgląd UPO w PDF Tworzy PDF z pliku XML UPO Faktura sprzedaży
Pobierz faktury interaktywnie Pobiera faktury z KSeF i tworzy z nich dokumenty Obieg w trybie akcji (np. pozycja menu)
Pobierz faktury wsadowo Jak wyżej, z użyciem eksportu paczki faktur Obieg w trybie akcji (np. pozycja menu)
Pobierz fakturę po numerze KSeF Pobiera jeden plik XML faktury Dowolny dokument
Przetwórz fakturę KSeF Przepisuje dane z pliku XML na formularz Faktura zakupu
Wygeneruj podgląd faktury w PDF Tworzy wizualizację faktury w PDF z kodami QR Faktura sprzedaży lub zakupu
Wygeneruj kod QR do weryfikacji faktury (Kod I) Tworzy obraz kodu QR z napisem OFFLINE Faktura sprzedaży
Wygeneruj kod QR do potwierdzenia autentyczności wystawcy (Kod II) Tworzy obraz kodu QR z napisem CERTYFIKAT Faktura sprzedaży
Pobierz status działania KSeF Sprawdza, czy KSeF jest dostępny Dowolny dokument

Parametr Użytkownik występuje w prawie każdej akcji. Wskazuje osobę, która zostanie zapisana jako autor zmian. Domyślnie wstawiane jest pole systemowe Id użytkownika. Jeżeli parametr jest pusty, zmiany zostaną zapisane jako zmiany użytkownika o ID 1 (administratora systemu).

Parametr Firma wskazuje firmę, w imieniu której działa akcja. W systemie z jedną firmą wystarczy zmienna systemowa ID firmy. Przy wielofirmowości lepiej użyć pola wbudowanego Firma z formularza dokumentu. Zmienna ID firmy to firma wybrana w przełączniku firm w nagłówku: przy wyborze Wszystkie firmy i w procedurach uruchamianych według harmonogramu jest pusta, a akcja kończy się błędem. W takich procedurach wpisz ID firmy jako stałą.

Wysyłanie faktur sprzedaży

Proces wysyłki faktury składa się z następujących kroków:

  1. Wygenerowanie pliku XML z danych formularza: akcja Wygeneruj fakturę KSeF.
  2. Wysłanie pliku do KSeF:
    • interaktywnie: jedną akcją na dokumencie faktury,
    • wsadowo: przez dokument techniczny Paczka faktur, do którego przypisane są pliki XML faktur.
  3. Pobranie informacji o fakturach wysłanych w sesji: na fakturze zapisywany jest m.in. numer KSeF i adres do pobrania UPO.
  4. Pobranie UPO, zawsze na dokumencie faktury.
  5. Opcjonalnie: wygenerowanie podglądu UPO i faktury w PDF.

Wygeneruj fakturę KSeF

Akcja tworzy plik XML faktury ustrukturyzowanej na podstawie danych z formularza i zapisuje go we wskazanym miejscu. Plik otrzymuje nazwę zgodną z numerem własnym dokumentu, dlatego numer własny musi być nadany przed uruchomieniem akcji. Razem z plikiem zapisywany jest jego skrót SHA-256. Po tym skrócie kolejne akcje rozpoznają fakturę w odpowiedziach z KSeF.

Parametr Opis
Dokument Dokument, z którego pochodzą dane, zwykle pole systemowe Id dokumentu.
Użytkownik Autor zmian.
Typ faktury KSeF Rodzaj faktury: Faktura podstawowa, Korygująca fakturę podstawową, Faktura zaliczkowa, Faktura rozliczeniowa, Faktura uproszczona, Faktura korygująca fakturę zaliczkową lub Faktura korygująca fakturę rozliczeniową. Wybierz pozycję z listy albo, gdy jeden typ dokumentu obsługuje kilka rodzajów faktur, pole formularza.
Faktura wystawiona w cenach Netto lub Brutto. Od tego zależy, czy w pozycjach faktury zostaną przekazane ceny i wartości netto, czy brutto.
Dodatkowe pola Mapowanie atrybutów formularza na pola faktury, których nie obsługują pola wbudowane (adnotacje, rachunki bankowe, warunki transakcji itd.). Opis w akapicie Pola dodatkowe KSeF.
Zapisz plik w Miejsce zapisu pliku XML: systemowy kontener Pliki albo atrybut typu Panel plików. Najlepiej użyć osobnego atrybutu tylko na plik XML faktury. Akcje wysyłki biorą z niego pierwszy plik, więc inne załączniki mogłyby zostać wysłane zamiast faktury.

Większość danych faktury pochodzi z pól wbudowanych:

Dane w XML faktury Źródło w Navigatorze
Sprzedawca (Podmiot1): nazwa, NIP, numer EORI, adres, e-mail, telefon Kontrahent przypisany do firmy z dokumentu
Nabywca (Podmiot2): nazwa, NIP, numer EORI, adres, e-mail, telefon Kontrahent i adres kontrahenta z dokumentu. Dla kontrahentów zagranicznych zamiast NIP-u przekazywany jest numer VAT UE albo inny identyfikator, zależnie od prefiksu kraju
Numer faktury (P_2) Numer własny
Data wystawienia (P_1) Data dokumentu
Data dostawy lub wykonania usługi (P_6) Data zdarzenia gospodarczego
Kod waluty Waluta (domyślnie PLN)
Pozycje faktury Elementy dokumentu: nazwa asortymentu z opisem, jednostka miary, ilość, cena i wartość netto lub brutto, rabat, stawka VAT, kurs waluty. Dla faktury zaliczkowej i jej korekty elementy dokumentu trafiają do sekcji zamówienia (Zamowienie), a nie do pozycji
Podsumowanie stawek VAT Tabela VAT dokumentu
Kwota należności ogółem (P_15) Kwota brutto. Dla faktury korygującej różnica między kwotą brutto korekty i faktury korygowanej. Dla faktur zaliczkowych i rozliczeniowych pole dodatkowe Kwota zapłaty/pozostała do zapłaty
Forma płatności Forma płatności z przypisaną formą KSeF
Termin płatności Data płatności, jeżeli w polach dodatkowych nie wskazano terminów płatności
Faktura korygowana Dokument korygowany oraz metoda korekty. Przy korygowaniu przez stan przed korektą do XML trafiają też pozycje faktury korygowanej

Rachunek bankowy na fakturze sprzedaży

Numer rachunku, na który nabywca ma zapłacić, nie jest pobierany z pól wbudowanych. Przekaż go w polach dodatkowych Płatność: Numery rachunku bankowego: ….

Wyślij fakturę interaktywnie

Akcja wysyła do KSeF jeden wcześniej wygenerowany plik XML. Dla każdej faktury otwierana jest osobna sesja interaktywna. Po wysłaniu akcja czeka na przetworzenie faktury przez KSeF, najdłużej około 2 minut, i zamyka sesję. Jeżeli w tym czasie KSeF odrzuci fakturę, akcja kończy się błędem z kodem i opisem przyczyny, np. błędem weryfikacji pliku albo duplikatem faktury. Jeżeli przetwarzanie potrwa dłużej, akcja kończy się bez błędu, a wynik trzeba sprawdzić akcją Pobierz informacje o fakturach wysłanych w sesji. Jeżeli pliku nie ma albo nie jest to plik XML, akcja również kończy się błędem.

Parametr Opis
Firma Firma, która wysyła fakturę. Musi to być ta sama firma, która jest wskazana na formularzu faktury, z którego wygenerowano plik XML. Najwygodniej użyć pola Firma z formularza faktury.
Plik Atrybut typu Panel plików albo systemowy kontener Pliki, w którym jest plik XML. Jeżeli plików jest więcej, brany jest pierwszy z nich. Można też wskazać ID pliku wyliczone zapytaniem SQL.
Użytkownik Autor zmian.
Zapisz numer referencyjny sesji w Atrybut, w którym zapisany zostanie numer referencyjny sesji KSeF. Jest on potrzebny do pobrania informacji o fakturze i statusu sesji.

Wyślij faktury wsadowo

Akcja pakuje wiele plików XML do jednego archiwum, szyfruje je i wysyła do KSeF w jednej sesji wsadowej. Pomijane są pliki, które nie są plikami XML wygenerowanymi akcją Wygeneruj fakturę KSeF. Jeżeli nie zostanie żaden plik, akcja kończy się błędem. W odróżnieniu od wysyłki interaktywnej akcja nie czeka na przetworzenie faktur. Wynik trzeba sprawdzić akcjami Pobierz status sesji i Pobierz informacje o fakturach wysłanych w sesji.

Parametr Opis
Firma Firma, która wysyła faktury. W paczce mogą być tylko faktury jednej firmy, zgodnej z firmą na formularzach faktur.
Pliki Atrybut wielokrotnego wyboru (np. Autowyszukiwanie z możliwością wyboru wielu wartości), w którym przechowywane są ID plików XML do wysłania.
Użytkownik Autor zmian.
Zapisz numer referencyjny sesji w Atrybut, w którym zapisany zostanie numer sesji. Wszystkie faktury z paczki mają wspólny numer sesji, dlatego najlepiej zapisać go na dokumencie paczki faktur.

Dokument Paczka faktur

Wysyłkę wsadową uruchamia się na dokumencie technicznym, który zbiera faktury do wysłania. Typ dokumentu i formularz paczki przygotowujesz sam. Formularz paczki powinien zawierać:

  • pole wbudowane Firma: paczka obejmuje faktury jednej firmy,
  • atrybut wielokrotnego wyboru z ID plików XML faktur, wygenerowanych akcją Wygeneruj fakturę KSeF; wskazujesz go w parametrze Pliki akcji wysyłki i akcji pobierania informacji o fakturach,
  • atrybut na numer referencyjny sesji.

Pliki XML pozostają przypisane do dokumentów faktur. Dzięki temu akcja Pobierz informacje o fakturach wysłanych w sesji, uruchomiona na paczce, zapisze numer KSeF i status na każdej fakturze z osobna. Sposób dodawania faktur do paczki (np. wybór paczki na formularzu faktury i dopisanie pliku zapytaniem SQL albo lista plików na formularzu paczki) zależy od konfiguracji wdrożenia.

Wysyłka interaktywna a wsadowa

KSeF ogranicza liczbę zapytań do API, m.in. liczbę otwieranych sesji i wysyłanych faktur w ciągu sekundy, minuty i godziny. Akcja Wyślij fakturę interaktywnie otwiera osobną sesję dla każdej faktury, więc limit otwierania sesji interaktywnych jest jednocześnie limitem liczby faktur, które można wysłać interaktywnie. Jedna sesja wsadowa może zawierać wiele faktur, dlatego przy większej liczbie faktur korzystaj z paczek.

Serwis pośredniczący pilnuje limitów. Wstrzymuje kolejne zapytania i ponawia je, gdy KSeF zwróci błąd przekroczenia limitu (HTTP 429). Przekroczenie limitu wydłuża więc działanie akcji, a nie kończy jej od razu błędem.

Aktualne wartości podaje dokumentacja KSeF: limity API oraz limity techniczne (m.in. maksymalna liczba faktur w sesji).

Pobierz informacje o fakturach wysłanych w sesji

Akcja odpytuje KSeF o wszystkie faktury z sesji, dopasowuje je do wskazanych plików XML po skrócie pliku i zapisuje dane na dokumentach faktur, do których te pliki należą. Działa tak samo dla wysyłki interaktywnej i wsadowej. Przy paczce dane trafiają na każdą fakturę z paczki, a nie na dokument paczki.

Parametr Opis
Numer referencyjny sesji Numer zapisany przez akcję wysyłki, na fakturze albo na paczce faktur.
Firma Firma, do której należą wysłane faktury. Musi być taka sama jak w akcji wysyłki.
Pliki/Plik Pliki XML wysłanych faktur. Przy wysyłce interaktywnej jest to atrybut z plikiem XML faktury, przy paczce atrybut z ID plików XML na paczce.
Użytkownik Autor zmian.
Typ dokumentów wysłanych w sesji Typy dokumentów faktur. Wskazanie typów pozwala wybrać atrybuty z ich formularzy w parametrze Dodatkowe pola.
Dodatkowe pola Atrybuty na fakturze, w których akcja zapisze pobrane dane (patrz tabela niżej).
Zapisz plik w Miejsce zapisu pliku JSON z pełną odpowiedzią KSeF.

Pola, które możesz zapisać w parametrze Dodatkowe pola:

Pole Opis
Numer KSeF Numer nadany fakturze przez KSeF. Potrzebny m.in. do wizualizacji faktury i powiązania korekty z fakturą korygowaną
Adres do pobrania UPO Adres pliku XML z UPO faktury, używany w akcji Pobierz UPO. Adres jest ważny tylko przez określony czas, dlatego UPO trzeba pobrać możliwie szybko
Status: Kod Kod statusu faktury w KSeF (tabela niżej). Pozwala sterować obiegiem
Status: Opis Opis statusu
Status: Szczegóły Dodatkowe informacje o statusie, np. przyczyna błędu
Data nadania numeru KSeF Data nadania fakturze numeru KSeF
Data przyjęcia faktury Data przyjęcia faktury w KSeF do dalszego przetwarzania
Data trwałego zapisu faktury Data trwałego zapisu faktury w repozytorium KSeF. Wartość pojawia się z opóźnieniem i tuż po wysyłce może być jeszcze pusta

Najważniejsze kody statusu faktury:

Kod Opis
100 Faktura przyjęta do dalszego przetwarzania
150 Trwa przetwarzanie
200 Sukces
405 Przetwarzanie anulowane z powodu błędu sesji
410 Nieprawidłowy zakres uprawnień
430 Błąd weryfikacji pliku faktury
440 Duplikat faktury
450 Błąd weryfikacji semantyki dokumentu faktury

Pełną listę kodów zawiera dokumentacja API KSeF.

Przy wysyłce interaktywnej faktura jest zwykle przetworzona, zanim zakończy się akcja wysyłki, więc akcję można uruchomić zaraz po niej. Przy wysyłce wsadowej faktury mogą być jeszcze przetwarzane (kod 100 lub 150). Wtedy akcję trzeba uruchomić ponownie później.

Adres do pobrania UPO jest generowany od nowa przy każdym odpytaniu KSeF. Jeżeli adres wygasł, wystarczy ponownie uruchomić tę akcję.

Pobierz status sesji

Akcja sprawdza status całej sesji wysyłki. Przydaje się zwłaszcza przy paczkach faktur, gdy chcesz wiedzieć, ile faktur zostało przyjętych, a ile odrzuconych.

Parametr Opis
Numer referencyjny sesji Numer zapisany przez akcję wysyłki.
Firma Firma, która wysłała faktury.
Dokument Dokument, na którym akcja zapisze wynik, np. paczka faktur.
Użytkownik Autor zmian.
Dodatkowe pola Atrybuty, w których akcja zapisze dane sesji (patrz lista niżej).
Zapisz plik w Miejsce zapisu pliku JSON z odpowiedzią KSeF.

Dane sesji, które możesz zapisać:

  • Status: Kod, Status: Opis, Status: Szczegóły: status sesji, np. 200 (sesja przetworzona pomyślnie) albo 445 (brak poprawnych faktur),
  • Adres do pobrania UPO: adres zbiorczego UPO dla całej sesji, dostępny po zamknięciu sesji i wygenerowaniu UPO,
  • Liczba przyjętych faktur w ramach sesji,
  • Liczba faktur przeprocesowanych w ramach sesji z sukcesem,
  • Liczba faktur przeprocesowanych w ramach sesji z błędem.

Pobierz UPO

Akcja pobiera Urzędowe Poświadczenie Odbioru (UPO) w postaci pliku XML spod adresu zapisanego przez akcję Pobierz informacje o fakturach wysłanych w sesji (UPO faktury) lub Pobierz status sesji (UPO zbiorcze sesji).

Parametr Opis
Adres do pobrania UPO Atrybut z adresem UPO. Adres wygasa po pewnym czasie. Jeżeli pobranie się nie powiedzie, uruchom ponownie akcję, która zapisała adres.
Użytkownik Autor zmian.
Zapisz plik w Miejsce zapisu pliku XML z UPO: systemowy kontener Pliki albo atrybut typu Panel plików.

Wygeneruj podgląd UPO w PDF

Akcja tworzy czytelny dla człowieka plik PDF na podstawie pliku XML z UPO.

Parametr Opis
Plik Plik XML z UPO pobrany akcją Pobierz UPO. Gdy atrybut ma kilka plików, akcja bierze pierwszy.
Użytkownik Autor zmian.
Nazwa wygenerowanego pliku Nazwa pliku PDF bez rozszerzenia. Domyślnie „Upo”.
Zapisz plik w Miejsce zapisu pliku PDF: systemowy kontener Pliki albo atrybut typu Panel plików.

Odbieranie faktur zakupu

Odbieranie faktur odbywa się w dwóch etapach:

  1. Akcja Pobierz faktury pobiera z KSeF pliki XML i dla każdej faktury tworzy nowy dokument w Navigatorze.
  2. Na każdym nowym dokumencie automatycznie startuje obieg, a jego pierwszym krokiem powinna być akcja Przetwórz fakturę KSeF, która przepisuje dane z pliku XML na formularz.

Pobierz faktury interaktywnie i wsadowo

Obie akcje mają tę samą konfigurację i tworzą dokumenty w ten sam sposób. W obu przypadkach faktury są wyszukiwane według daty trwałego zapisu w KSeF. Różnią się sposobem pobierania:

  • Pobierz faktury interaktywnie: najpierw pobiera listę faktur, a potem każdą fakturę osobnym zapytaniem. Pobieranie faktur po numerze ma niski limit zapytań, dlatego ta akcja nadaje się do niewielkiej liczby faktur.
  • Pobierz faktury wsadowo: zleca w KSeF eksport faktur, czeka na przygotowanie zaszyfrowanej paczki, a następnie ją pobiera i rozpakowuje. Jeżeli KSeF nie przygotuje paczki w ciągu około 2 minut, pobieranie kończy się błędem zapisanym w logu firmy. Jedna paczka może zawierać wiele faktur, dlatego ta akcja jest zalecana przy większej liczbie faktur.

Akcja działa w tle. Po uruchomieniu użytkownik od razu dostaje komunikat o rozpoczęciu pobierania, a dokumenty pojawiają się w systemie stopniowo. Rozpoczęcie i zakończenie pobierania oraz ewentualne błędy są zapisywane w logu firmy. Dla jednej firmy i jednego typu podmiotu w danej chwili może trwać tylko jedno pobieranie.

Dla każdej pobranej faktury akcja:

  1. Pomija fakturę, jeżeli w systemie jest już dokument o tym samym numerze KSeF.
  2. Szuka kontrahenta po NIP-ie sprzedawcy. Jeżeli kontrahent ma dokument wzorcowy, nowy dokument jest tworzony na jego podstawie. W przeciwnym razie tworzony jest pusty dokument wskazanego typu i kategorii.
  3. Zapisuje plik XML faktury, numer KSeF i typ faktury KSeF we wskazanych polach.
  4. Uzupełnia formularz na podstawie rekomendacji AI z treści pliku XML.
  5. Ustawia wartości domyślne, nadaje uprawnienia i uruchamia obieg dokumentu.
Parametr Opis
Firma Firma, dla której pobierasz faktury. Procedura może działać bez formularza, dlatego zwykle wskazuje się pole systemowe Id firmy, a w procedurze uruchamianej według harmonogramu ID firmy wpisane jako stała (patrz Przegląd akcji).
Użytkownik Autor zmian.
Typ podmiotu Rola firmy na pobieranych fakturach: Podmiot 1 (sprzedawca, czyli własne faktury sprzedaży), Podmiot 2 (nabywca, czyli faktury zakupu), Podmiot 3 (strona trzecia) albo Podmiot upoważniony.
Tryb pobierania Przyrostowo pobiera faktury od ostatniego pobrania. Datę ostatniego pobrania Navigator zapamiętuje osobno dla każdej firmy i typu podmiotu. Przy pierwszym uruchomieniu pobiera faktury z ostatnich 730 dni, chyba że w parametrze Od podasz późniejszą datę. Zakres dat pobiera faktury z okresu Od–Do (oba są wtedy wymagane) i nie zmienia zapamiętanej daty. Przydaje się do uzupełnienia brakujących faktur.
Od, Do Początek i koniec okresu pobierania w czasie UTC, w formacie RRRR-MM-DD GG:mm:ss.SSS.
Ustawienia Mapowanie rodzajów faktur KSeF na dokumenty Navigatora (patrz niżej).

Duża liczba faktur

Jedno zapytanie do KSeF zwraca ograniczoną liczbę faktur (limit podaje dokumentacja API KSeF). Jeżeli w okresie jest ich więcej, nadmiarowe faktury nie zostaną pobrane. Przy pierwszym uruchomieniu na środowisku z dużą liczbą faktur podaj w parametrze Od niedawną datę albo pobierz zaległe faktury w kilku krótszych zakresach dat.

W parametrze Ustawienia dodajesz wiersz dla każdego rodzaju faktury KSeF:

Kolumna Opis
Typ faktury KSeF Rodzaj faktury. Wymagany. Faktury rodzaju bez wiersza są pomijane, dlatego warto zmapować wszystkie siedem rodzajów.
Typ dokumentu Typ dokumentu w Navigatorze. Wymagany. Kilka rodzajów faktur może trafiać do jednego typu, np. wszystkie korekty do typu Faktura korygująca.
Kategoria dokumentu Kategoria dokumentu. Wymagana.
Zapisz plik w Systemowy kontener Pliki albo atrybut typu Panel plików na plik XML. Wymagany. Bez zapisanego pliku nie da się później przetworzyć faktury.
Zapisz numer KSeF w Atrybut tekstowy na numer KSeF faktury. Opcjonalny.
Zapisz typ faktury KSeF w Atrybut na rodzaj faktury KSeF. Opcjonalny.

Pobierz fakturę po numerze KSeF

Akcja pobiera z KSeF jeden plik XML faktury o wskazanym numerze KSeF. Nie tworzy dokumentu ani nie przetwarza danych. Można ją wykorzystać np. do ręcznego uzupełnienia brakującej faktury, a następnie uruchomić akcję Przetwórz fakturę KSeF.

Parametr Opis
Firma Firma, która ma dostęp do faktury w KSeF.
Użytkownik Autor zmian.
Numer KSeF Numer faktury w KSeF.
Zapisz plik w Miejsce zapisu pliku XML: systemowy kontener Pliki albo atrybut typu Panel plików.

Przetwórz fakturę KSeF

Akcja odczytuje plik XML faktury i przepisuje dane na formularz dokumentu: pola wbudowane, elementy dokumentu, tabelę VAT i zmapowane atrybuty. Powinna być pierwszym krokiem obiegu faktury zakupu, bo bez niej dokument pozostanie pusty. Po zapisaniu danych przeliczane są pola wyliczane formularza.

Parametr Opis
Plik Atrybut z plikiem XML faktury pobranym z KSeF.
Dokument Dokument, na który akcja przepisze dane, zwykle pole systemowe Id dokumentu.
Użytkownik Autor zmian.
Uzupełnij brakujące wartości Wystawca nie musi podawać na fakturze wszystkich kwot. Tak wylicza brakujące wartości z pozostałych danych (patrz niżej).
Uwzględnij elementy dokumentu Czy uzupełniać elementy dokumentu. Domyślnie Tak. Nie pomija pozycje faktury, ale nadal uzupełnia tabelę VAT i dane nagłówka.
Dodatkowe pola Mapowanie pól faktury na atrybuty formularza (patrz Pola dodatkowe KSeF).

Parametr Uzupełnij brakujące wartości wylicza:

  • w pozycjach i zamówieniach: cenę netto z ceny brutto (i odwrotnie) na podstawie stawki VAT, wartość netto i brutto z ceny, ilości i rabatu, kwotę VAT, a gdy brakuje ilości, ilość z wartości i ceny,
  • w podsumowaniu faktury: kwoty netto i VAT dla poszczególnych stawek, wyliczone z pozycji.

Pola wbudowane uzupełniane z KSeF

Poniższe tabele pokazują, które dane z pliku XML zapisywane są w polach wbudowanych. W kolumnie środkowej podana jest nazwa kolumny w bazie danych.

KSeF (XML) Tabela Document ([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 (pierwszy poprawny termin)
Fa.Platnosc.FormaPlatnosci DoPyTyID Forma płatności
Podmiot1.DaneIdentyfikacyjne.NIP CoID Kontrahent (sprzedawca)
pole wyliczane AdID Adres kontrahenta
Fa.KodWaluty CuID Waluta
Fa.FaWiersz.KursWaluty CurrencyValue Kurs waluty (gdy jest jednakowy dla wszystkich pozycji)
Fa.Platnosc.RachunekBankowy.NrRB CoAcID Konto bankowe kontrahenta (tylko gdy na fakturze jest dokładnie jeden rachunek, szczegóły niżej)
Fa.DaneFaKorygowanej.NrKSeFFaKorygowanej CorrectDoID Dokument korygowany (tylko dla faktur korygujących, jeżeli faktura korygowana jest w systemie)
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 DocumentElements ([DoEl]) Elementy na fakturze
pole wyliczane DoID ID dokumentu
Fa.FaWiersz.P_7 AsID ID asortymentu
Fa.FaWiersz.P_7 AsName Nazwa asortymentu
Fa.FaWiersz.P_8A UnID 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
Fa.FaWiersz.P_12 VaID ID stawki VAT
pole wyliczane ValueNet Wartość 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 DoID ID dokumentu
pole wyliczane VaID ID stawki VAT
pole wyliczane VaRate Stawka VAT
pole wyliczane VaName Nazwa stawki VAT
pole wyliczane Net Wartość netto
pole wyliczane Vat Wartość VAT
pole wyliczane Gross Wartość brutto
pole wyliczane NetMain Wartość netto w walucie głównej
pole wyliczane VatMain Wartość VAT w walucie głównej
pole wyliczane GrossMain Wartość brutto w walucie głównej

Zasady:

  • Adnotacja pole wyliczane oznacza, że wartość jest wyliczana z innych pól, np. tabela VAT z pozycji faktury (Fa.FaWiersz), albo ustalana w trakcie importu, np. DoEl.DoID na podstawie ID przetwarzanego dokumentu.
  • Kontrahent jest wyszukiwany w kartotece po NIP-ie sprzedawcy (Podmiot1). Jeżeli nie zostanie znaleziony, system dodaje nowego kontrahenta i pobiera jego dane z bazy GUS, chyba że w ustawieniach typu dokumentu wyłączono uzupełnianie kontrahenta z GUS.
  • Forma płatności i waluta są ustawiane tylko wtedy, gdy mają odpowiedniki w systemie (zob. Zanim zaczniesz). W przeciwnym razie pole pozostaje puste.

Rachunki bankowe z faktury

Faktura może zawierać kilka rachunków bankowych (Fa.Platnosc.RachunekBankowy). Sposób ich zapisania zależy od konfiguracji parametru Dodatkowe pola.

Wariant 1: lista atrybutów na formularzu

Jeżeli zmapujesz pola rachunku bankowego na kolumny jednej listy atrybutów, każdy rachunek z faktury zostanie zapisany jako osobny wiersz tej listy.

KSeF (XML) Pole w akcji (Dodatkowe pola)
Fa.Platnosc.RachunekBankowy.NrRB Płatność: Numery rachunku bankowego: Pełny numer rachunku
Fa.Platnosc.RachunekBankowy.SWIFT Płatność: Numery rachunku bankowego: Kod SWIFT
Fa.Platnosc.RachunekBankowy.RachunekWlasnyBanku Płatność: Numery rachunku bankowego: Rachunek własny banku
Fa.Platnosc.RachunekBankowy.NazwaBanku Płatność: Numery rachunku bankowego: Nazwa banku
Fa.Platnosc.RachunekBankowy.OpisRachunku Płatność: Numery rachunku bankowego: Opis rachunku

Uwaga

W tym wariancie rachunki nie są dopisywane do kartoteki kontrahenta, a pole wbudowane konta bankowego na dokumencie (Do.CoAcID) nie jest uzupełniane. Wszystkie zmapowane atrybuty muszą należeć do tej samej listy atrybutów. Jeżeli należą do różnych list, rachunki nie zostaną zapisane w żadnej z nich.

Analogicznie można zapisać rachunki faktora (Fa.Platnosc.RachunekBankowyFaktora), używając pól Płatność: Numery rachunku bankowego faktora: ….

Wariant 2: kartoteka kontrahenta

Jeżeli pola rachunku bankowego nie są zmapowane na listę atrybutów, system dopisuje rachunki z faktury do kont bankowych kontrahenta (tabela ContractorAccount, [CoAc]):

KSeF (XML) Tabela ContractorAccount ([CoAc]) Konta bankowe kontrahentów
Podmiot1.DaneIdentyfikacyjne.NIP CoID Kontrahent ustalony na dokumencie (Do.CoID)
Fa.KodWaluty CuID Waluta dokumentu, a jeżeli nie jest ustawiona, waluta główna
Fa.Platnosc.RachunekBankowy.NrRB AccountNumber Numer rachunku bankowego
Fa.Platnosc.RachunekBankowy.SWIFT SWIFTCode Kod SWIFT
Fa.Platnosc.RachunekBankowy.NazwaBanku BankName Nazwa banku
Fa.Platnosc.RachunekBankowy.OpisRachunku AccountDescription Opis rachunku
Fa.Platnosc.RachunekBankowy.RachunekWlasnyBanku OwnBankAccountApDiElID Rachunek własny banku
pole wyliczane IsExternallyAdded Znacznik, że rachunek został dodany automatycznie (z KSeF)

Zasady działania:

  • Rachunki są dopisywane tylko wtedy, gdy na dokumencie udało się ustalić kontrahenta (Do.CoID).
  • Rachunek, który już istnieje u kontrahenta, nie jest dodawany ponownie. Numery są porównywane po samych cyfrach, bez spacji i prefiksów.
  • Jeżeli na fakturze jest dokładnie jeden rachunek, zostaje on dodatkowo ustawiony jako konto bankowe dokumentu (Do.CoAcID). Przy kilku rachunkach pole to pozostaje puste i użytkownik wybiera rachunek ręcznie.

Wizualizacja faktury i kody QR

Wygeneruj podgląd faktury w PDF

Plik XML nie nadaje się do czytania przez człowieka. Akcja tworzy na jego podstawie wizualizację faktury w PDF z warstwą tekstową. Działa zarówno dla faktur wysyłanych, jak i pobranych z KSeF.

Na wizualizacji zawsze umieszczany jest kod QR do weryfikacji faktury (Kod I), wyliczony z NIP-u sprzedawcy, daty wystawienia i skrótu pliku XML. Osobne akcje generujące kody QR nie są więc potrzebne, jeżeli doręczasz fakturę jako PDF z tej akcji.

Parametr Opis
Plik Plik XML faktury. Gdy atrybut ma kilka plików, akcja bierze pierwszy.
Numer KSeF Numer KSeF faktury. Jeżeli zostanie podany, jest drukowany na górze każdej strony PDF. Dla faktury, która nie ma jeszcze numeru KSeF, zostaw parametr pusty.
Użytkownik Autor zmian.
Nazwa wygenerowanego pliku Nazwa pliku PDF bez rozszerzenia. Domyślnie „Invoice”.
Dołącz QR kod II Czy umieścić na wizualizacji także kod QR potwierdzający autentyczność wystawcy (Kod II), wymagany dla faktur wystawionych w trybie offline. Wymaga certyfikatu KSeF typu Offline.
Zapisz plik w Miejsce zapisu pliku PDF: systemowy kontener Pliki albo atrybut typu Panel plików.

Kody QR na fakturze

Kody QR pozwalają odbiorcy, który dostał fakturę poza KSeF (np. jako PDF, wydruk czy załącznik e-mail), sprawdzić, czy faktura jest w KSeF i nie została zmieniona, pobrać jej plik XML, a przy fakturach offline potwierdzić tożsamość wystawcy. Zgodnie z dokumentacją API KSeF:

  • faktura wystawiona online ma jeden kod QR: Kod I,
  • faktura wystawiona offline ma dwa kody QR: Kod I do weryfikacji faktury i Kod II do potwierdzenia autentyczności wystawcy.

Pod Kodem I umieszcza się numer KSeF faktury, a jeżeli faktura nie ma jeszcze numeru, napis OFFLINE. Pod Kodem II umieszcza się napis CERTYFIKAT.

Akcje opisane niżej tworzą obrazy kodów (pliki PNG) do samodzielnego umieszczenia na wydruku, np. gdy faktura offline jest drukowana z innego szablonu niż wizualizacja z akcji Wygeneruj podgląd faktury w PDF.

Wygeneruj kod QR do weryfikacji faktury (Kod I)

Akcja tworzy obraz Kodu I z napisem OFFLINE, przeznaczony dla faktury, która nie ma jeszcze numeru KSeF.

Parametr Opis
Firma Firma, która wystawia fakturę. Najczęściej pole Firma z formularza faktury.
Plik Plik XML faktury wygenerowany akcją Wygeneruj fakturę KSeF.
Użytkownik Autor zmian.
Zapisz plik w Systemowy kontener Pliki albo atrybut typu Panel plików, w którym zostanie zapisany obraz kodu.

Wygeneruj kod QR do potwierdzenia autentyczności wystawcy (Kod II)

Akcja tworzy obraz Kodu II z napisem CERTYFIKAT. Kod jest podpisywany certyfikatem KSeF typu Offline, który musi być skonfigurowany w serwisie pośredniczącym (patrz Przygotowanie systemu pod KSeF). Certyfikat uwierzytelniający nie może być do tego użyty.

Parametry są takie same jak w akcji Kod I: Firma, Plik, Użytkownik i Zapisz plik w.

Pobierz status działania KSeF

Akcja nie ma parametrów. Sprawdza, czy KSeF jest dostępny, i wyświetla użytkownikowi komunikat. Jeżeli KSeF nie działa, komunikat jest błędem i zawiera szczegóły podane przez KSeF. Akcję można dodać np. jako przycisk na formularzu faktury, żeby przed wysyłką sprawdzić, czy KSeF działa.

Przykładowe obiegi

Wysyłka faktury sprzedaży

Wysyłkę najwygodniej umieścić w obiegu faktury, po kroku zatwierdzenia dokumentu. Przykładowa kolejność akcji automatycznych:

  1. Wygeneruj fakturę KSeF.
  2. Wyślij fakturę interaktywnie. Jeżeli KSeF odrzuci fakturę, akcja zakończy się błędem.
  3. Pobierz informacje o fakturach wysłanych w sesji: zapisuje numer KSeF i adres UPO.
  4. Pobierz UPO.
  5. Wygeneruj podgląd faktury w PDF z numerem KSeF, np. do wysłania nabywcy e-mailem.

Przy wysyłce wsadowej krok 1 i dodanie faktury do paczki ustawiasz w obiegu faktury, a wysyłkę, pobranie statusu sesji i informacji o fakturach w obiegu paczki faktur. Pobranie UPO i podglądu PDF można potem wykonać na każdej fakturze, gdy pojawi się na niej numer KSeF.

Pobieranie faktur zakupu

  1. Obieg w trybie akcji z jedną akcją Pobierz faktury wsadowo (lub interaktywnie), podpięty pod pozycję w menu dokumentów, np. „Pobierz z KSeF”. Użytkownik, wybierając tę pozycję, uruchamia pobieranie.
  2. W obiegu typu dokumentu wskazanego w Ustawieniach: pierwsze kroki z akcjami Przetwórz fakturę KSeF i Wygeneruj podgląd faktury w PDF (każda akcja w osobnym kroku), a dalej zwykła ścieżka akceptacji faktury.

Pola dodatkowe KSeF

Akcje Wygeneruj fakturę KSeF i Przetwórz fakturę KSeF korzystają z tego samego słownika pól KSeF. W parametrze Dodatkowe pola dodajesz wiersze, w których wskazujesz Pole KSeF i Atrybut na formularzu. Przy generowaniu wartość atrybutu trafia do pliku XML, a przy przetwarzaniu wartość z pliku XML jest zapisywana w atrybucie. Pole KSeF może wystąpić w konfiguracji tylko raz.

Rodzaj atrybutu zależy od struktury pola:

  • Pojedyncza wartość: zwykły atrybut na formularzu dokumentu. Pola logiczne (np. adnotacje) najlepiej mapować na atrybut typu checkbox.
  • Lista: pola, które na fakturze mogą wystąpić wielokrotnie (np. rachunki bankowe, terminy płatności, umowy). Mapujesz je na kolumny listy atrybutów. Pola należące do jednej grupy (np. wszystkie pola Płatność: Numery rachunku bankowego: …) muszą być kolumnami tej samej listy. Każdy wiersz listy to jedno wystąpienie na fakturze.
  • Pozycja: pola pozycji faktury (Pozycje: … i Zamówienia: …). Mapujesz je na atrybuty elementów dokumentu, a wartość jest zapisywana osobno dla każdej pozycji.

Pola, których wartość pochodzi ze słownika KSeF (np. informacja o płatności, rola strony trzeciej, typ skutku korekty), muszą zawierać dokładnie jedną z dopuszczalnych wartości, np. dla Płatność: Informacja o płatności: „Zapłacono”, „Zapłacono całość w częściach”, „Zapłacono w części” lub „Brak zapłaty”.

Pole KSeF Struktura
Adnotacje: Metoda kasowa Pojedyncza wartość (logiczna)
Adnotacje: Samofakturowanie Pojedyncza wartość (logiczna)
Adnotacje: Odwrotne obciążenie Pojedyncza wartość (logiczna)
Adnotacje: Mechanizm podzielonej płatności Pojedyncza wartość (logiczna)
Adnotacje: Przepis ustawy o zwolnieniu z podatku Pojedyncza wartość
Adnotacje: Przepis dyrektywy o zwolnieniu z podatku Pojedyncza wartość
Adnotacje: Inna podstawa prawna do zwolnienia z podatku Pojedyncza wartość
Adnotacje: Procedura uproszczona Pojedyncza wartość (logiczna)
Adnotacje: Biura podróży Pojedyncza wartość (logiczna)
Adnotacje: Towary używane Pojedyncza wartość (logiczna)
Adnotacje: Dzieła sztuki Pojedyncza wartość (logiczna)
Adnotacje: Przedmioty kolekcjonerskie i antyki Pojedyncza wartość (logiczna)
Kupujący: Jednostka samorządu terytorialnego (JST) Pojedyncza wartość (logiczna)
Kupujący: Członek grupy VAT (GV) Pojedyncza wartość (logiczna)
Miejsce wystawienia faktury Pojedyncza wartość
Data początkowa okresu Pojedyncza wartość
Data końcowa okresu Pojedyncza wartość
Kwota zapłaty/pozostała do zapłaty Pojedyncza wartość
Kwota zapłaty/pozostała do zapłaty przed korektą Pojedyncza wartość
Ogólne: Dane identyfikacyjne dla faktury korygowanej: Numer KSeF faktury korygowanej Pojedyncza wartość
Poprawny numer faktury korygowanej Pojedyncza wartość
Przyczyna korekty Pojedyncza wartość
Typ skutku korekty Pojedyncza wartość (słownik: W dacie ujęcia faktury pierwotnej, W dacie wystawienia faktury korygującej, W dacie innej)
Numery dokumentów magazynowych Lista
Faktury zaliczkowe: Numer faktury zaliczkowej wystawionej poza KSeF Lista
Faktury zaliczkowe: Numer identyfikujący fakturę zaliczkową w KSeF Lista
Dodatkowy opis: Numer pozycji faktury Lista
Dodatkowy opis: Rodzaj informacji Lista
Dodatkowy opis: Treść informacji Lista
Płatność: Informacja o płatności Pojedyncza wartość (słownik)
Płatność: Data zapłaty Pojedyncza wartość (dla informacji „Zapłacono”)
Płatność: Opis płatności innej Pojedyncza wartość (dla formy „Płatność inna”)
Płatność: Zapłaty częściowe: Data zapłaty częściowej Lista
Płatność: Zapłaty częściowe: Kwota zapłaty częściowej Lista
Płatność: Terminy płatności: Termin płatności Lista
Płatność: Terminy płatności: Opis terminu płatności: Ilość Lista
Płatność: Terminy płatności: Opis terminu płatności: Jednostka Lista
Płatność: Terminy płatności: Opis terminu płatności: Zdarzenie początkowe Lista
Płatność: Numery rachunku bankowego: Pełny numer rachunku Lista
Płatność: Numery rachunku bankowego: Kod SWIFT Lista
Płatność: Numery rachunku bankowego: Rachunek własny banku Lista
Płatność: Numery rachunku bankowego: Nazwa banku Lista
Płatność: Numery rachunku bankowego: Opis rachunku Lista
Płatność: Numery rachunku bankowego faktora: Pełny numer rachunku Lista
Płatność: Numery rachunku bankowego faktora: Kod SWIFT Lista
Płatność: Numery rachunku bankowego faktora: Rachunek własny banku Lista
Płatność: Numery rachunku bankowego faktora: Nazwa banku Lista
Płatność: Numery rachunku bankowego faktora: Opis rachunku Lista
Warunki transakcji: Umowy: Data umowy Lista
Warunki transakcji: Umowy: Numer umowy Lista
Warunki transakcji: Zamówienia: Data zamówienia Lista
Warunki transakcji: Zamówienia: Numer zamówienia Lista
Warunki transakcji: Numery partii towaru Lista
Warunki transakcji: Warunki dostawy Pojedyncza wartość
Warunki transakcji: Kurs umowny Pojedyncza wartość
Warunki transakcji: Waluta umowna Pojedyncza wartość
Warunki transakcji: Transport: Rodzaj transportu Lista
Warunki transakcji: Transport: Opis Ładunku Lista
Warunki transakcji: Transport: Jednostka opakowania Lista
Warunki transakcji: Transport: Wysyłka do: Kod kraju Lista
Warunki transakcji: Transport: Linia 1 adresu Lista
Warunki transakcji: Transport: Linia 2 adresu Lista
Strony trzecie: Kontrahent Lista (atrybut wskazujący kontrahenta)
Strony trzecie: Nazwa Lista
Strony trzecie: Role: Role strony trzeciej Lista (słownik, np. Faktor, Odbiorca, Dokonujący płatności, Rola inna)
Strony trzecie: Role: Opis roli Lista (dla roli „Rola inna”)
Stopka: Informacje: Stopka faktury Lista
Stopka: Rejestry: Pełna nazwa Lista
Stopka: Rejestry: KRS Lista
Stopka: Rejestry: REGON Lista
Stopka: Rejestry: BDO Lista
Pozycje: Data dostawy/wykonania usługi Pozycja
Pozycje: Uniwersalny unikalny numer wiersza faktury (UU_ID) Pozycja
Pozycje: Indeks Pozycja
Pozycje: GTIN Pozycja
Pozycje: PKWiU Pozycja
Pozycje: Symbol Nomenklatury Scalonej Pozycja
Pozycje: Symbol Polskiej Klasyfikacji Obiektów Budowlanych Pozycja
Pozycje: Znacznik dla towaru lub usług wymienionych w załączniku nr 15 do ustawy Pozycja (logiczna)
Pozycje: Symbol GTU Pozycja
Pozycje: Oznaczenie procedury Pozycja
Pozycje: Kwota podatku akcyzowego zawarta w cenie towaru Pozycja
Zamówienia: Uniwersalny unikalny numer wiersza zamówienia lub umowy (UU_IDZ) Pozycja (faktura zaliczkowa i jej korekta)
Zamówienia: Indeks Pozycja (faktura zaliczkowa i jej korekta)
Zamówienia: GTIN Pozycja (faktura zaliczkowa i jej korekta)
Zamówienia: PKWiU Pozycja (faktura zaliczkowa i jej korekta)
Zamówienia: Symbol Nomenklatury Scalonej Pozycja (faktura zaliczkowa i jej korekta)
Zamówienia: Symbol Polskiej Klasyfikacji Obiektów Budowlanych Pozycja (faktura zaliczkowa i jej korekta)
Zamówienia: Znacznik dla towaru lub usług wymienionych w załączniku nr 15 do ustawy Pozycja (faktura zaliczkowa i jej korekta, logiczna)
Zamówienia: Symbol GTU Pozycja (faktura zaliczkowa i jej korekta)
Zamówienia: Oznaczenie procedury Pozycja (faktura zaliczkowa i jej korekta)
Zamówienia: Kwota podatku akcyzowego zawarta w cenie towaru Pozycja (faktura zaliczkowa i jej korekta)

Znaczenie poszczególnych pól i warunki ich wypełniania opisuje broszura informacyjna Ministerstwa Finansów dotycząca struktury logicznej e-Faktury FA(3).