Przykład: Faktura sprzedaży (OINV)

Ten rozdział przeprowadza krok po kroku przez profil OINV_FA3_SERVICE_LAYER_FULL — referencyjny profil mapowania dla standardowej faktury sprzedaży SAP B1 (tabela OINV) do formatu FA(3) KSeF.

Źródła danych profilu

Profil wykorzystuje 12 źródeł danych, wykonywanych w kolejności:

1. invoice (sort_order: 1)

Główne dane nagłówka faktury z Service Layer:

Invoices({DocEntry})?$select=DocEntry,DocNum,DocDate,DocDueDate,TaxDate,
  CardCode,CardName,DocTotal,DocTotalFC,VatSum,VatSumFC,
  DocCurrency,Comments,PaymentMethod,...

Zwraca: numer dokumentu, daty, kwoty, walutę, kontrahenta.

2. invoice_fc (sort_order: 2)

Dane walutowe — używane gdy faktura jest w walucie obcej:

Invoices({DocEntry})?$select=DocTotalFC,VatSumFC,DocRate

3. seller (sort_order: 3)

Dane sprzedawcy z endpointu CompanyInfo:

CompanyInfo?$select=CompanyName,TaxIdNumber,AddressLine1,City,ZipCode,Country

Zwraca: NIP firmy, nazwę, adres.

4. buyer (sort_order: 4)

Dane nabywcy z BusinessPartners:

BusinessPartners('{invoice.CardCode}')?$select=CardCode,CardName,
  FederalTaxID,BPAddresses,Country,...

Zwraca: NIP kontrahenta, nazwę, adres.

5. country_info (sort_order: 5)

Sprawdzenie czy kraj nabywcy jest w UE:

Countries('{buyer.Country}')?$select=Code,EU

Zwraca: EU = "tYES" lub "tNO".

6. buyer_eu (sort_order: 6)

Rozszerzone dane nabywcy UE — numer VAT UE:

BusinessPartners('{invoice.CardCode}')?$select=UnifiedFederalTaxID

7. payment (sort_order: 7)

Warunki płatności:

PaymentTermsTypes({invoice.PaymentGroupCode})?$select=PaymentTermsGroupName,NumberOfAdditionalDays

8. payment_terms (sort_order: 8)

Rozszerzone informacje o płatności (termin, metoda).

9. bank (sort_order: 9)

Konto bankowe sprzedawcy:

CompanyInfo?$select=DefaultBankAccount,IBAN

10. bank_info (sort_order: 10)

Szczegóły banku — kod SWIFT, nazwa banku.

11. lines (sort_order: 11, is_array: true)

Pozycje faktury:

Invoices({DocEntry})/DocumentLines?$select=VisualOrder,ItemDescription,
  Quantity,Price,GrossTotal,LineTotal,VatGroup,VatPercent,MeasureUnit,...

Tablica — każdy wiersz generuje element FaWiersz w XML.

12. vat_summary (sort_order: 12, is_array: true)

Podsumowanie VAT pogrupowane po stawce:

Invoices({DocEntry})/DocumentLines?$select=VatPercent,
  &$apply=groupby((VatPercent),aggregate(LineTotal with sum as NetTotal, ...))

Tablica — każdy wiersz generuje sekcję podsumowania P_13/P_14.

Kluczowe mapowania pól

Nagłówek

Ścieżka XML	Źródło	Transformacja	Wynik
Faktura.Naglowek.KodFormularza	—	CONST("FA")	FA
Faktura.Naglowek.WariantFormularza	—	CONST("3")	3
Faktura.Naglowek.DataWytworzeniaFa	invoice	TaxDate	2026-03-15
Faktura.Naglowek.SystemInfo	—	CONST("BizFlowNH")	BizFlowNH

Daty i numer faktury

Ścieżka XML	Źródło	Pole	Opis
Faktura.Fa.KodWaluty	invoice	DocCurrency	Waluta (PLN, EUR…)
Faktura.Fa.P_1	invoice	TaxDate	Data wystawienia
Faktura.Fa.P_2	invoice	DocDate	Data sprzedaży
Faktura.Fa.P_6	invoice	DocNum|PREFIX("FV/")	Numer faktury

Sprzedawca (Podmiot1)

Ścieżka XML	Źródło	Pole
Faktura.Podmiot1.DaneIdentyfikacyjne.NIP	seller	TaxIdNumber|REGEX("[^0-9]","")
Faktura.Podmiot1.DaneIdentyfikacyjne.Nazwa	seller	CompanyName|TRIM
Faktura.Podmiot1.Adres.KodKraju	seller	CONST("PL")
Faktura.Podmiot1.Adres.AdresL1	seller	AddressLine1|TRIM
Faktura.Podmiot1.Adres.MiejscowoscL	seller	City|TRIM
Faktura.Podmiot1.Adres.KodPocztowyL	seller	ZipCode|TRIM

Nabywca (Podmiot2)

Ścieżka XML	Źródło	Pole
Faktura.Podmiot2.DaneIdentyfikacyjne.NIP	buyer	FederalTaxID|REGEX("[^0-9]","")
Faktura.Podmiot2.DaneIdentyfikacyjne.Nazwa	buyer	CardName|TRIM
Faktura.Podmiot2.Adres.KodKraju	buyer	Country
Faktura.Podmiot2.Adres.AdresL1	buyer	Street|TRIM

Pozycje faktury (FaWiersz)

Generowane z tablicowego źródła lines:

Ścieżka XML	Pole	Opis
Faktura.Fa.FaWiersz.NrWierszaFa	EXPR("[VisualOrder] + 1")	Numer wiersza
Faktura.Fa.FaWiersz.P_7	ItemDescription|TRIM	Nazwa towaru/usługi
Faktura.Fa.FaWiersz.P_8B	Quantity	Ilość
Faktura.Fa.FaWiersz.P_8A	MeasureUnit|TRIM	Jednostka miary
Faktura.Fa.FaWiersz.P_9A	Price	Cena jednostkowa netto
Faktura.Fa.FaWiersz.P_11	LineTotal	Wartość netto wiersza
Faktura.Fa.FaWiersz.P_11A	GrossTotal	Wartość brutto wiersza
Faktura.Fa.FaWiersz.P_12	VatGroup|VATMAP	Stawka VAT (kategoria KSeF)

Logika warunkowa

PLN vs waluta obca

Faktura w PLN używa pól DocTotal, VatSum. Faktura walutowa (np. EUR) używa pól DocTotalFC, VatSumFC:

// Kwota brutto — PLN
Faktura.Fa.P_15 → DocTotal|IF_FIELD_EQ("DocCurrency","PLN")

// Kwota brutto — waluta obca
Faktura.Fa.P_15 → DocTotalFC|IF_FIELD_NEQ("DocCurrency","PLN")

System generuje oba mapowania — ale transformacja warunkowa powoduje, że tylko jedno daje wynik.

Nabywca UE vs poza UE

Dla nabywców z UE dodawane są dodatkowe pola:

// Tylko dla nabywców UE
Faktura.Podmiot2.DaneIdentyfikacyjne.NrVatUE →
  UnifiedFederalTaxID|IF_FIELD_EQ("country_info.EU","tYES")|TRIM

BrakID — brak NIPu

Gdy kontrahent nie ma NIPu (np. osoba fizyczna):

// Jeśli NIP jest pusty, ustaw BrakID na 1
Faktura.Podmiot2.DaneIdentyfikacyjne.BrakID →
  FederalTaxID|IF_EMPTY|CONST("1")

Pole BrakID = 1 informuje KSeF, że nabywca nie ma numeru identyfikacji podatkowej.

Podsumowanie VAT

Sekcje P_13/P_14 generowane z tablicowego źródła vat_summary:

// Netto VAT 23%
Faktura.Fa.P_13_1 → NetTotal|VATFILTER("23")|SUM

// Kwota VAT 23%
Faktura.Fa.P_14_1 → VATAmount|VATFILTER("23")|SUM

// Netto VAT 8%
Faktura.Fa.P_13_3 → NetTotal|VATFILTER("8")|SUM

// Kwota VAT 8%
Faktura.Fa.P_14_3 → VATAmount|VATFILTER("8")|SUM

Import i eksport profilu

Profil OINV_FA3_SERVICE_LAYER_FULL można eksportować jako JSON i importować u innego klienta:

• Eksport: otwórz profil — menu — Eksportuj JSON
• Import: w liście profili — Importuj — wybierz plik JSON

Eksportowany JSON zawiera pełną definicję profilu: źródła danych, mapowania pól i mapowania VAT. Po imporcie należy zweryfikować, że kody VAT i zapytania SQL odpowiadają konfiguracji docelowego SAP.

Standaryzacja między klientami

Jeśli wdrażasz BizFlow NH u wielu klientów z podobną strukturą SAP, utrzymuj bazowy profil JSON jako szablon. Importuj go jako punkt wyjścia i dostosowuj tylko to, co się różni (kody VAT, niestandardowe pola).

Modyfikacja profilu

Profil OINV_FA3_SERVICE_LAYER_FULL jest punktem wyjścia. Dla konkretnego klienta można go dostosować:

• Zmienić zapytania SQL — jeśli klient używa niestandardowych pól SAP
• Dodać transformacje — np. REPLACE na nazwie ulicy
• Zmienić stałe — np. numer wersji formularza
• Dodać źródła — np. dodatkowe dane z UDF

Zalecany workflow:

1. Zaimportuj profil bazowy
2. Uruchom podgląd na istniejącej fakturze
3. Porównaj z oczekiwanym XML
4. Dostosuj mapowania tam, gdzie dane się różnią
5. Przetestuj na kilku fakturach przed włączeniem na produkcji