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.

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:

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