🗂️ Mapowanie pól KSeF

Moduł Mapowanie pól KSeF umożliwia definiowanie własnych reguł mapowania pól z dokumentów Business Central do odpowiednich sekcji XML faktury KSeF. Dzięki temu możesz elastycznie kontrolować, jakie dane trafiają do faktur elektronicznych, bez konieczności modyfikacji kodu.

Najważniejsze możliwości

  • AI — tworzenie mapowań za pomocą opisów w języku naturalnym z wykorzystaniem AI (więcej).
  • Mapowanie pól z nagłówków i wierszy zaksięgowanych faktur sprzedaży oraz faktur serwisowych.
  • Obsługa wielu sekcji KSeF: DodatkowyOpis, DataZamowienia, NrZamowienia, DataUmowy, NrUmowy, Skonto – warunki, Skonto – wysokość, Indeks, NazwaTowaruLubUslugi, GTIN, CN oraz Numer partii towaru.
  • Pobieranie informacji z powiązanych danych – np. nazwy spedytora, numeru zamówienia czy oznaczenia zapasów
  • Jawne wyczyszczenie wartości pola w strukturze KSeF – np. usunięcie automatycznie generowanego indeksu lub kodu CN
  • Predefiniowane wartości – np. automatyczne dodanie numerów seryjnych z śledzenia jako DodatkowyOpis lub eksport wybranych wymiarów jako DodatkowyOpis
  • Filtrowanie danych źródłowych – ograniczenie mapowania do dokumentów spełniających określone kryteria.
  • Automatyczne filtrowanie po języku dokumentu – gdy tabela powiązana zawiera pole „Kod języka" lub pole z relacją do tabeli Język, system automatycznie filtruje rekordy według języka dokumentu źródłowego.
  • Formatowanie wartości pól – możliwość zastosowania formatu AL do wartości pola, np. wyświetlenie daty jako nazwy miesiąca lub sformatowanie liczby z określoną dokładnością. Formatowanie uwzględnia język dokumentu – np. nazwy miesięcy pojawiają się w języku faktury.
  • Priorytet mapowania – kontrola kolejności stosowania mapowań: gdy wiele konfiguracji dotyczy tej samej etykiety wyjściowej, stosowane jest mapowanie z wyższym priorytetem pasujące do danego rekordu (nagłówka lub wiersza). Niższy priorytet jest pomijany dla rekordów, dla których wyższy priorytet już pasował do filtra.
  • Obsługa zarówno faktur, jak i faktur korygujących (korekt).
  • Automatyczne sprawdzanie poprawności ustawień – system podpowie, jeśli coś jest skonfigurowane nieprawidłowo.

Obsługiwane obszary dokumentów

Obszar dokumentu Poziom zastosowania
Sprzedaż Nagłówek, Wiersz
Serwis Nagłówek, Wiersz

Obsługiwane sekcje KSeF

Sekcja Opis
DodatkowyOpis Dodatkowe opisy na fakturze – mapowane na poziomie nagłówka lub wierszy
DataZamowienia Data zamówienia powiązanego z fakturą
NrZamowienia Numer zamówienia powiązanego z fakturą
DataUmowy Data umowy powiązanej z fakturą
NrUmowy Numer umowy powiązanej z fakturą
Skonto – warunki Warunki skonta (rabatu gotówkowego) na fakturze
Skonto – wysokość Kwota lub procent skonta na fakturze
Indeks Indeks (kod wewnętrzny) przypisywany do wierszy faktury
NazwaTowaruLubUslugi Nazwa towaru lub usługi przypisywana do wierszy faktury
GTIN Kod GTIN przypisywany do wierszy faktury
CN Kod CN (Nomenklatura Scalona) przypisywany do wierszy faktury
Numer partii towaru Numer partii towaru – umożliwia wyczyszczenie automatycznie generowanej wartości

Jak to działa

Ogólny przepływ pracy

  1. Na stronie KSeF Helper - Mapowanie pól KSeF tworzysz nowe mapowanie ręcznie lub za pomocą AI, wybierając sekcję KSeF, obszar dokumentu i poziom zastosowania.
  1. Definiujesz kroki mapowania – wskazujesz, z którego pola (i ewentualnie z jakiej powiązanej tabeli) ma być pobrana wartość.
  2. Opcjonalnie konfigurujesz filtr rekordów, aby mapowanie działało tylko dla wybranych dokumentów.
  3. Włączasz mapowanie – od tego momentu system automatycznie uzupełnia dane w fakturach KSeF.

Wielokrokowe mapowanie

Każde mapowanie może składać się z jednego lub wielu kroków nawigacji:

  • Krok 1 – wskazuje pole w tabeli źródłowej (np. zaksięgowany nagłówek faktury sprzedaży).
  • Krok 2 i kolejne – nawigują do tabel powiązanych przez pole relacji. Przy wyborze tabeli w kroku 2+ system domyślnie pokazuje tylko tabele powiązane z bieżącą tabelą źródłową (na podstawie relacji pól). Zachowanie to można zmienić w ustawieniach — pole Filtruj powiązane tabele w wyszukiwaniu na stronie KSeF Helper - Ustawienia.

Przykład: aby pobrać nazwę spedytora z faktury sprzedaży, krok 1 wskazuje pole Kod spedytora w nagłówku faktury, a krok 2 nawiguje do tabeli Spedytor i odczytuje pole Nazwa.

Łączenie wielu pól w jedną wartość

Gdy potrzebujesz złożyć wartość z kilku pól tej samej tabeli, utwórz wiele kroków wskazujących na kolejne pola i włącz opcję Połącz wiele wartości. System połączy wyniki poszczególnych kroków, rozdzielając je zdefiniowanym separatorem.

Przykład: aby przekazać pełny adres odbiorcy dostawy z faktury serwisowej jako DodatkowyOpis, każdy krok pobiera kolejne pole adresowe (nazwa, ulica, miasto, kod pocztowy, kraj), a separator „ - " łączy je w jedną wartość.

Pobieranie danych z tabeli powiązanej (tekst dodatkowy zapasu)

Możesz pobierać dane z dowolnej tabeli powiązanej z dokumentem. Poniższy przykład pokazuje mapowanie, które dla każdego wiersza faktury sprzedaży pobiera tekst dodatkowy zapasu z tabeli Wiersz tekstu dodatkowego — krok 1 wskazuje pole Nr w wierszu faktury, a krok 2 nawiguje do tabeli tekstu dodatkowego i odczytuje pole Tekst.

Eksport wymiarów jako DodatkowyOpis

Konfiguracja predefiniowana z typem Wymiary automatycznie eksportuje zaznaczone wymiary skrótów do faktur KSeF. Na karcie mapowania widoczna jest sekcja Wymiary do uwzględnienia, w której zaznaczasz interesujące wymiary.

Wskazówki

  • Dla sekcji DataZamowienia, NrZamowienia, DataUmowy, NrUmowy, Skonto – warunki, Skonto – wysokość, Indeks, NazwaTowaruLubUslugi, GTIN, CN i Numer partii towaru poziom zastosowania jest ustawiany automatycznie i nie można go modyfikować.
  • Dla sekcji NazwaTowaruLubUslugi dostępne jest dodatkowe pole Separator pola, pozwalające na łączenie wartości z wielu mapowań w jedną nazwę.
  • Wyłączenie mapowania (pole Włączone = fałsz) powoduje, że nie jest ono brane pod uwagę podczas generowania XML.
  • Priorytet: mapowania są przetwarzane w kolejności malejącej według priorytetu. Gdy mapowanie pasuje do rekordu (filtr zwróci wynik), kolejne mapowania z niższym priorytetem dla tej samej etykiety wyjściowej są pomijane dla tego rekordu. Mapowania o równym priorytecie są uruchamiane wszystkie. Domyślna wartość priorytetu to 0.

Szczegółowy opis pól i stron konfiguracyjnych znajdziesz w sekcji Ustawienia.

Formatowanie wartości pól

Pole Format w krokach mapowania pozwala zmienić sposób wyświetlania wartości pola. Używa standardowych ciągów formatu AL (FormatString). Możesz formatować daty, liczby i tekst, a także dodawać stały tekst przed lub po wartości pola.

Stały tekst w formacie

Ciąg formatu może zawierać dowolny tekst poza znacznikami w nawiasach < >. Dzięki temu możesz dodać etykietę, prefiks lub sufiks do wartości pola.

Format Przykładowy wynik (dla daty 16.05.2026)
Warunki: <Day,2>.<Month,2>.<Year4> Warunki: 16.05.2026
Data dostawy: <Day,2> <Month Text> <Year4> Data dostawy: 16 maj 2026

Przykłady formatowania dat

Format Przykładowy wynik (dla daty 16.03.2026)
<Day,2>.<Month,2>.<Year4> 16.03.2026
<Year4>-<Month,2>-<Day,2> 2026-03-16
<Month Text> <Year4> marzec 2026
<Day>. <Month Text> <Year4> 16. marzec 2026
<Year4>/<Month,2> 2026/03
<Day,2>-<Month,2>-<Year> 16-03-26
Informacja

Nazwy miesięcy są wyświetlane w języku dokumentu. Jeśli faktura ma ustawiony język polski, wynikiem będzie „marzec". Dla języka angielskiego — „March".

Przykłady formatowania liczb

Format Przykładowy wynik (dla wartości 1234.5)
<Precision,2:2><Standard Format,0> 1 234,50
<Precision,4:4><Standard Format,0> 1 234,5000
<Precision,0:0><Standard Format,0> 1 235
<Sign><Integer><Decimals> 1234.5
<Sign><Integer Thousand><Decimals,3> 1 234,500

Jak ustawić formatowanie

  1. Otwórz kartę mapowania pól KSeF.
  2. W sekcji Kroki mapowania znajdź krok, którego wartość chcesz sformatować.
  3. W kolumnie Format wpisz odpowiedni ciąg formatu AL.
  4. Zapisz ustawienia — od teraz wartość pola będzie formatowana zgodnie z podanym wzorcem.