Samofakturowanie w KSeF - case study z branży najmu

Spis treści

1. Zakopane, kwiecień, 200 apartamentów i jeden problem
2. Dlaczego samofakturowanie to osobna historia
3. Jak to zbudowaliśmy
4. Największa pułapka: KSeF nie odpowiada od razu
5. Co zyskał klient
6. Kiedy warto rozważyć własną integrację
7. Podsumowanie
8. FAQ

Zakopane, kwiecień, 200 apartamentów i jeden problem {#wstep}

visitzakopane.pl zarządza rozliczeniami dla ponad 200 apartamentów na wynajem w Zakopanem i okolicach. Ferie, wakacje, Sylwester — w szczycie sezonu liczba faktur do wystawienia rośnie kilkukrotnie w ciągu kilku dni.

Kiedy KSeF stał się nieuchronny, pojawił się konkretny problem: jak to wszystko zautomatyzować, nie zmieniając codziennej pracy operacyjnej i nie dokładając kolejnej platformy do stosu?

Pracujemy z visitzakopane.pl od kilku lat. Podjęliśmy się integracji bezpośrednio — autorski CRM klienta połączyliśmy z API KSeF 2.0. Bez pośredników, bez abonamentów, z pełną kontrolą nad procesem.

Ten artykuł opisuje jak to zrobiliśmy, gdzie był największy problem i co z tego wynika dla firm w podobnej sytuacji.

Dlaczego samofakturowanie to osobna historia {#samofakturowanie}

Większość materiałów o KSeF opisuje standardowy scenariusz: firma wystawia fakturę swoim klientom, faktura trafia do KSeF. Prosto.

visitzakopane.pl działa inaczej. Firma wystawia faktury w imieniu właścicieli apartamentów — to model samofakturowania, w którym nabywca generuje dokument sprzedażowy sprzedawcy.

W praktyce oznacza to:

• faktura musi trafić do KSeF na konto NIP właściciela nieruchomości, nie firmy zarządzającej
• wymagane są odpowiednie uprawnienia po stronie właściciela
• proces musi działać powtarzalnie dla dziesiątek różnych podmiotów

To znacznie bardziej złożony scenariusz niż standardowe fakturowanie — i właśnie dlatego zdecydowaliśmy się go opisać. Rzadko pojawia się w artykułach o KSeF, a dotyczy całej branży zarządzania najmem.

Jak to zbudowaliśmy {#architektura}

Model integracji był prosty w założeniu:

CRM klienta ↔ API KSeF 2.0

Bez pośrednich platform. Cały proces przebiega automatycznie — od wygenerowania faktury po zapisanie potwierdzenia w systemie.

Cztery kroki procesu

Generowanie dokumentu
CRM generuje fakturę w formacie XML zgodnym z FA(2) — standardem KSeF. Już na tym etapie system waliduje dane: NIP kontrahenta, stawki VAT, strukturę dokumentu. Błędna faktura nie wychodzi poza CRM.

Autoryzacja
Połączenie z KSeF wymaga uwierzytelnienia. Używamy asymetrycznego szyfrowania RSA (OAEP) z kluczem publicznym pobieranym bezpośrednio z certyfikatów KSeF — zabezpieczenia są zawsze aktualne bez ręcznej interwencji.

Szyfrowanie i wysyłka
Każda sesja generuje unikalny klucz AES (CBC). Faktura jest szyfrowana przed wysyłką — treść dokumentu pozostaje poufna w trakcie transmisji.

Zapis potwierdzenia
Po przetworzeniu system automatycznie zapisuje w CRM numer referencyjny KSeF i Urzędowe Potwierdzenie Odbioru (UPO). Operatorzy nie muszą nic robić ręcznie.

Konsola systemu podczas testowego wysłania faktury — wszystkie 7 kroków zakończonych sukcesem. Od pobrania certyfikatów KSeF po otrzymanie numeru referencyjnego.

Największa pułapka: KSeF nie odpowiada od razu {#asynchronicznosc}

Gdyby zapytać programistę który to wdrożył, co było najtrudniejsze — odpowiedź jest jednoznaczna:

"Największym wyzwaniem nie był sam format XML, lecz asynchroniczność systemu KSeF. Sukcesem okazało się wdrożenie mechanizmu Session Status Polling, który potrafi inteligentnie oczekiwać na pełną gotowość środowiska procesowego Ministerstwa Finansów."

Co to znaczy w praktyce?

KSeF nie działa synchronicznie. Po wysłaniu dokumentu system MF przetwarza go w tle — w czasie który potrafi być nieprzewidywalny. Najprostsze podejście — wyślij i odbierz odpowiedź — kończy się błędami 404 i 415. To właśnie te błędy były przez długi czas głównym źródłem niepowodzeń przy integracjach KSeF.

Rozwiązaniem jest mechanizm statusowania sesji: system regularnie pyta API KSeF o stan przetwarzania, czeka na gotowość środowiska MF i pobiera potwierdzenie dopiero kiedy jest dostępne.

Bez tego — integracja działa w testach, ale nie wytrzymuje realnego obciążenia.

Co zyskał klient

Po wdrożeniu:

• Raportowanie faktury do KSeF poniżej 10 sekund — wliczając inicjalizację sesji i oczekiwanie na potwierdzenie MF
• Zero ręcznych operacji — proces przebiega automatycznie od momentu wystawienia faktury w CRM
• Walidacja przed wysyłką — błędne dokumenty są odrzucane po stronie CRM, zanim trafią do MF
• Pełna historia w systemie — każda faktura ma przypisany numer KSeF i UPO dostępny natychmiast
• Gotowość na sezon — architektura bez problemu obsłuży setki faktur dziennie przy szczycie rezerwacji

Faktura FV/20260428/80532 widoczna w Aplikacji Podatnika KSeF — środowisko testowe. Numer KSeF przyznany natychmiast po przetworzeniu dokumentu.

Kiedy warto rozważyć własną integrację

Nie każda firma potrzebuje bezpośredniej integracji z API KSeF. Dla wielu wystarczy eksport XML z systemu księgowego i ręczne wgranie do Aplikacji Podatnika.

Własna integracja zaczyna mieć sens gdy:

• wystawiasz dużą liczbę faktur miesięcznie i ręczna obsługa jest kosztowna czasowo
• korzystasz z autorskiego CRM lub ERP który nie ma gotowej integracji z KSeF
• działasz w modelu samofakturowania lub obsługujesz wiele podmiotów
• masz sezonowe skoki wolumenu które wykluczają procesy ręczne
• zależy Ci na pełnej kontroli i niezależności od zewnętrznych platform

Podsumowanie

KSeF to infrastruktura. Dobrze wdrożona jest niewidoczna. Źle wdrożona staje się problemem przy szczycie sezonu, kontroli skarbowej lub zmianie skali działalności.

To wdrożenie pokazało, że format XML to rozwiązany problem. Prawdziwe wyzwanie leży w obsłudze asynchroniczności systemu MF i zaprojektowaniu procesu który działa stabilnie — nie tylko w środowisku testowym, ale przy realnym obciążeniu biznesowym.

Jeśli prowadzisz firmę w podobnym modelu i stoisz przed tym samym pytaniem — zapraszamy do rozmowy.

→ Grupa Insight — Software House

Stack wdrożenia: #custom CRM; #secure API communication, #async queue logic, #XML validation, #logging & retry mechanisms

FAQ

Czy integracja z KSeF wymaga zmiany obecnego systemu?
Nie zawsze. W wielu przypadkach można podłączyć istniejący CRM lub ERP do API KSeF bez wymiany systemu. Zależy to od architektury i dostępności API po stronie klienta.

Czy samofakturowanie działa w KSeF?
Tak, ale wymaga odpowiednich uprawnień na koncie KSeF sprzedawcy i właściwej logiki po stronie integratora. To jeden z bardziej złożonych scenariuszy — środowisko testowe MF ma w tym obszarze ograniczenia, pełne testy wymagają produkcji.

Czy KSeF da się zautomatyzować przy dużej liczbie faktur?
Tak — pod warunkiem że integracja obsługuje asynchroniczność systemu MF. Bez tego działa w testach, nie działa przy obciążeniu.

Jaki format XML obsługuje KSeF?
Aktualnie obowiązujący standard to FA(2). Format FA(3) jest w fazie testowej w Aplikacji Podatnika 2.0.

Czy warto budować integrację bezpośrednio z API?
Przy dużym wolumenie, własnym CRM lub niestandardowych procesach — tak. Bezpośrednia integracja daje pełną kontrolę, skalowalność i niezależność od zewnętrznych platform.