Fakturowanie — Faktury wystawione i zakupu, KSeF, tryby pre-fill

Kompletny przewodnik po module fakturowania w SerwisRun. Dokument opisuje wystawianie faktur w 4 trybach (konserwacja / interwencja / harmonogram umowy / recznie), import faktur zakupu z KSeF, automatyczne tworzenie PZ oraz oznaczanie zrodlowych dokumentow jako zafakturowanych.

Zmiana 2026-03-20: Faktury w menu bocznym to teraz grupa z dwoma pozycjami: Faktury wystawione (/invoices/issued) i Faktury zakupu (/invoices/purchase). Importer KSeF dla faktur zakupu + auto-PZ (wykrywanie nr zamowienia PO z opisu).

1 Architektura modulu fakturowania

Kluczowe tabele

Kluczowy podzial: direction

2 Faktury wystawione (outgoing)

Lista faktur wystawionych dane zanonimizowane.

U Uprawnienie: invoices / VIEW + EDIT (wystawianie)

Przycisk „Nowa faktura"

W module /invoices/issued przycisk otwiera kreator faktury (/invoices/issued/wizard) — 3-fazowy wizard z pionowym sidebarem.

3 Kreator faktury — 3 fazy, 4 tryby

Faza 1 — Wybor zrodla (tryb)

Faza 2 — Dane i pozycje

Po wyborze zrodla system automatycznie wypelnia (zobacz sekcja „Pre-fill" ponizej):

• Dane klienta (nabywca): nazwa, NIP, adres z fakturowania
• Dane sprzedawcy: z company_settings
• Termin platnosci: z hierarchii (umowa → klient → firma)
• Pozycje: z kosztorysu (gdy jest) lub z protokolu (czas pracy + materialy)

Uzytkownik moze skorygowac dowolne pole przed zapisem. System weryfikuje VAT, sumy netto/brutto.

Faza 3 — Podsumowanie

• Przeglad wszystkich danych
• Podglad PDF
• Wybor: „Zapisz jako wersja robocza" / „Wystaw i zablokuj numer"
• Opcja: wyslanie do KSeF od razu po wystawieniu

Kreator faktury dane zanonimizowane — pionowy sidebar z 3 fazami.

4 Mechanizm pre-fill (auto-wypelnianie)

Tryb A — Z konserwacji

Backend endpoint POST /invoices/from-maintenance/:id robi:

1. Pobiera konserwacje z JOIN contracts ON maintenances.contract_id = contracts.id
2. Pobiera klienta (nabywce) z JOIN clients
3. Jesli konserwacja ma kosztorys powykonawczy (status=approved) — uzywa pozycji z kosztorysu
4. Jesli brak kosztorysu — generuje pozycje z czasu pracy (godziny × stawka umowna) + materialy z protokolu
5. Oblicza VAT per pozycja (domyslnie 23%)
6. Ustawia termin platnosci: issueDate + contract.paymentTermDays

Tryb B — Z interwencji (naprawy)

Analogicznie, ale zrodlem jest repair_protocols. Dodatkowo sprawdza is_warranty — jesli true, faktura NIE jest tworzona (gwarancja nie fakturowana).

Tryb C — Harmonogram umowy

Dla umow z platnosciami ryczaltowymi (np. 1000 PLN/miesiac). Pozycja harmonogramu: {period: 'month', amount: 1000, dueDate: '2026-04-10', isIssued: false}. Po wystawieniu faktury → isIssued=true, issuedAt.

Tryb D — Recznie

Brak pre-fill. Uzytkownik wypelnia wszystko od zera — kreator pokazuje tylko walidacje i podpowiedzi (NIP lookup z MF, obliczanie sum).

5 Oznaczanie zrodlowych dokumentow

Po wystawieniu faktury system automatycznie oznacza zrodlo jako zafakturowane, aby zapobiec podwojnemu fakturowaniu:

Gwarancja: Jesli is_warranty = true w interwencji, status zmienia sie na warranty (bez faktury). System nie pozwala utworzyc faktury z interwencji gwarancyjnej.

6 Faktury zakupu (incoming)

Lista faktur zakupu dane zanonimizowane — import z KSeF.

Szczegoly faktury zakupu dane zanonimizowane — dostawca, pozycje, VAT, link do PZ.

U Uprawnienie: invoices / EDIT

Moduł /invoices/purchase (PurchaseInvoicesPage) wyswietla faktury z direction = 'incoming'. Dwa zrodla dodawania:

1. Recznie — przycisk „Nowa faktura zakupu" otwiera formularz (wybor dostawcy, numer, daty, pozycje)
2. Import z KSeF — przycisk „Pobierz z KSeF" (patrz sekcja ponizej)

Powiazanie z dostawca

invoices.supplier_id → FK do suppliers. System weryfikuje NIP przez API MF (Biala Lista):

• Zielony badge „Podatnik VAT aktywny" — jesli NIP jest na biale liscie
• Czerwony badge „Nieaktywny VAT" — ostrzezenie przed zaplata
• Wyswietlany numer konta bankowego dostawcy z Bialej Listy (weryfikacja anty-fraudu)

7 Import z KSeF (XML FA_VAT)

Wymagania

• Konfiguracja w Ustawienia → Integracje → KSeF:
  • Token autoryzacyjny KSeF (generowany z konta podatnika w MF)
  • Numer NIP firmy
  • Srodowisko: Produkcja / Test
• Rola uzytkownika z uprawnieniem invoices/EDIT

Przebieg importu

1. Klik „Pobierz z KSeF" → POST /invoices/purchase/fetch-ksef (zapytanie do API KSeF z filtrem po dacie)
2. System wyswietla liste niezaimportowanych faktur (porownanie z invoices.ksef_uid)
3. Uzytkownik zaznacza faktury do importu → klik „Importuj"
4. Backend: POST /invoices/purchase/import-ksef → dla kazdej faktury:
   • Pobiera XML (ksef.service.downloadInvoice(uid))
   • Parsuje FA_VAT (parseFaVatXml) — wyciaga naglowek, pozycje, dane dostawcy
   • Dopasowuje dostawce po NIP (lub tworzy nowy)
   • Tworzy rekord invoices z direction=incoming, ksef_uid
   • Tworzy invoice_items 1:1 z pozycjami XML
5. Toast: „Zaimportowano N faktur"

8 Auto-tworzenie PZ z faktury zakupu

Po zaimportowaniu faktury zakupu system moze automatycznie wygenerowac dokument PZ (przyjecie zewnetrzne) — dzieki temu material od razu trafia na stan magazynu.

Endpoint

POST /invoices/purchase/:id/create-pz — tworzy PZ z nastepujacymi krokami:

1. Matchowanie materialow — dla kazdej pozycji faktury system szuka w materials:
   • Priorytet 1: ean (kod kreskowy z pozycji faktury)
   • Priorytet 2: manufacturer + partNumber
   • Priorytet 3: manufacturer + type
   • Priorytet 4: nazwa (case-insensitive)
2. Wykrywanie oddzialu — z opisu faktury (np. „Dostawa do POZ-01") lub z supplier.branch_id
3. Wykrywanie nr zamowienia — regex PO-YYYY-NNNNNN w opisie (powiazanie z parts_orders)
4. Utworzenie PZ:
   • warehouse_documents z type=PZ, supplier_invoice_number, supplier_id
   • warehouse_document_items 1:1 z faktury, z cena zakupu
5. Status: draft — magazynier musi potwierdzic przed aktualizacja stanu

Co sie dzieje przy potwierdzeniu PZ?

1. Dla kazdej pozycji PZ tworzona jest nowa partia materialu (material_batches) z:
   • purchase_date — data dokumentu
   • unit_price — z faktury
   • remaining_quantity — pelna ilosc z PZ
   • Powiazanie z supplier_id, purchase_invoice_id, warehouse_document_id
2. warehouse_stock.quantity += qty w magazynie docelowym
3. Walidacja: porownanie ceny z ostatnia partia tego materialu (alert gdy odchylenie > 10%)
4. Status PZ: draft → confirmed

9 Statusy faktur i platnosci

10 Termin platnosci — hierarchia

Priorytet (najwyzszy → najnizszy):
umowa (contracts.payment_term_days) → klient (clients.payment_days_due) → firma (company_settings.default_payment_term_days) → 14 dni (hardcoded fallback)

Wyliczanie terminu: dueDate = issueDate + termDays.

Gdzie ustawiac?

11 Wysylka do KSeF (e-faktury)

Od 2026-07 KSeF jest obowiazkowy dla duzych podatnikow. System wspiera:

• Wysylke pojedynczej faktury — przycisk „Wyslij do KSeF" w widoku faktury
• Wysylke wsadowa — cron job wysyla co godzine faktury z status=issued AND ksef_sent=false
• Sledzenie statusu — invoices.ksef_status (pending / accepted / rejected), ksef_uid, ksef_rejection_reason
• Pobieranie UPO — dokument potwierdzajacy odbior (XML podpisany)

Konfiguracja KSeF

1. Panel Administracyjny → Integracje → KSeF
2. Wybor srodowiska: „Test" (dev) / „Produkcja"
3. Upload certyfikatu lub wklejenie tokenu autoryzacyjnego
4. Klik „Testuj polaczenie" — weryfikacja tokenem
5. Zaznacz „Automatyczna wysylka po wystawieniu" (opcjonalne)

12 Raporty i eksport

Raporty w module Raporty

• Obroty miesieczne — suma netto/brutto per miesiac, trend YoY
• Top klientow — ranking po sumie faktur
• Przeterminowane — lista z dniami opoznienia, kwotami
• Struktura VAT — rozbicie po stawkach (23% / 8% / 0%)

Eksport do Excela

W module /invoices/issued lista faktur moze byc eksportowana do Excel z kolumnami: numer, data, klient, NIP, kwota netto, VAT, brutto, termin, status. Export respektuje filtry tabeli.

Eksport do ksiegowosci

Format JPK_FA (XML) — eksport zgodny z wymaganiami MF dla kontroli skarbowych. Dostepny w Raporty → JPK.