Wystawianie faktur dla NFZ przez API Fakturowni - dostosowanie pod KSeF

FAQ: Wystawianie faktur dla NFZ przez API Fakturowni – KSeF

Opis problemu

Firmy świadczące usługi medyczne dla NFZ, korzystające z API Fakturowni do wystawiania faktur i ich wysyłki do KSeF, zobowiązane są od 1 kwietnia 2026 r. do wystawiania faktur ustrukturyzowanych zgodnych ze specyfikacją NFZ (format FA(2)/FA(3)).

Poniżej znajdziesz odpowiedzi na najczęstsze pytania dotyczące mapowania wymaganych przez NFZ pól na parametry API Fakturowni.

1. Okres rozliczeniowy (OkresFa – pola P_6_Od i P_6_Do)

Pytanie: Czy API obsługuje przekazanie zakresu dat okresu rozliczeniowego (P_6_Od / P_6_Do)? Jakich pól JSON użyć?

Odpowiedź:

Pola P_6_Od i P_6_Do nie są jeszcze dostępne w API – termin ich wdrożenia nie jest na ten moment znany.

W obecnym stanie API do wysyłki do KSeF wymagana jest data w formacie yyyy-mm-dd, przekazywana przez parametr sell_date.

Rozwiązanie tymczasowe: Jeśli faktura dotyczy całego miesiąca, można w polu sell_date podać ostatni dzień tego miesiąca (np. 2026-03-31). Jest to rozwiązanie prawidłowe podatkowo.

Planowane jest dodanie dedykowanych pól P_6_Od i P_6_Do umożliwiających precyzyjne wskazanie okresu rozliczeniowego.

2. Numer umowy (WarunkiTransakcji/Umowy/NrUmowy)

Pytanie: Czy API obsługuje przekazanie numeru umowy z NFZ w sekcji WarunkiTransakcji? Jaka jest nazwa pola JSON?

Odpowiedź:

Tak. Numer umowy należy przekazać przez parametr oid (odpowiednik pola „Nr zamówienia” w formularzu faktury).

Aby numer ten był prawidłowo przesyłany do KSeF, w ustawieniach konta musi być aktywna opcja „Wstaw numer zamówienia”:

1. Przejdź do Ustawienia → Ustawienia konta → Wydruki
2. Włącz opcję „Wstaw numer zamówienia”

Więcej informacji: Numer zamówienia na fakturze – instrukcja

3. Indeks pozycji faktury (FaWiersz/Indeks)

Pytanie: Czy pole code w pozycjach faktury (positions[].code) jest mapowane na element Indeks w strukturze FaWiersz FA(3)?

Odpowiedź:

Tak. Parametr code w sekcji positions jest mapowany do KSeF jako Indeks (FaWiersz/Indeks).

4. DodatkowyOpis na poziomie dokumentu (descriptions)

Pytanie: Czy poniższy zapis w tablicy descriptions jest prawidłowy i zostanie poprawnie przeniesiony do sekcji Faktura/Fa/DodatkowyOpis w XML KSeF?

Odpowiedź:

Tak, poniższy zapis jest prawidłowy:

"descriptions": [
  {
    "kind": "identyfikator-szablonu",
    "content": "87654321",
    "position_index": null
  },
  {
    "kind": "identyfikator-swiadczeniodawcy",
    "content": "123456",
    "position_index": null
  }
]

• Pole kind → mapowane na Klucz w KSeF
• Pole content → mapowane na Wartosc w KSeF
• Wartość position_index: null → oznacza poziom dokumentu (bez NrWiersza)

5. Podmiot3 – odbiorca (OW NFZ) przez tablicę recipients

Pytanie: Czy użycie tablicy recipients z tax_no_kind: “nip_with_id” spowoduje prawidłowe wypełnienie sekcji Podmiot3 z IDWew w XML KSeF?

Odpowiedź:

Tak, poniższy zapis jest prawidłowy:

"recipients": [{
  "name": "Warszawski Oddział Wojewódzki NFZ",
  "tax_no": "9451842593-00011",
  "tax_no_kind": "nip_with_id",
  "company": true,
  "country": "PL",
  "city": "Warszawa",
  "street": "ul. Szpitalna 12",
  "post_code": "00-310",
  "role": "Odbiorca"
}]

Zasady wypełniania:

• tax_no_kind → należy podać wartość “nip_with_id”
• tax_no → format: NIP myślnik wewnętrzne ID (5 cyfr), np. 1234567890-12345
• Nabywca (buyer_tax_no) → główny NIP NFZ, np. 1070001057

Więcej informacji w dokumentacji API: Nabywca z NIP i wewnętrznym ID (np. oddział firmy)