Integracja KSeF w aplikacji firmowej — jak to wygląda od środka
O KSeF napisano setki poradników w stylu „przygotuj firmę na e-faktury”. My napiszemy o czymś, o czym pisze mało kto, bo mało kto to zrobił: jak wygląda podłączenie własnej aplikacji do KSeF od strony technicznej — z pułapkami, na które sami wpadliśmy, integrując z bramką Ministerstwa Finansów systemy dla firm serwisowych.
Co naprawdę znaczy „mamy KSeF w systemie”
Za tym jednym zdaniem kryje się łańcuch: zbudowanie faktury w strukturze logicznej FA(3) (XML o kilkuset polach, walidowany wobec oficjalnego schematu), uwierzytelnienie w bramce (wyzwanie–odpowiedź z tokenem, z szyfrowaniem po drodze), otwarcie sesji, wysyłka, odpytywanie o status i odebranie UPO — urzędowego poświadczenia, które jest jedynym dowodem, że faktura istnieje w obiegu. Każde ogniwo ma własne tryby awarii. Wykonawca, który mówi „dorobimy KSeF w tydzień”, zwykle widział tylko pierwsze ogniwo.
Pułapki, na które wpadliśmy za Ciebie
- adresy środowisk: dokumentacja i poradniki w sieci mieszają KSeF 1.0 i 2.0 — stare adresy bramek odpowiadają, ale zwracają HTML zamiast API; godziny debugowania gwarantowane
- trzy środowiska (testowe, demo, produkcyjne) różnią się zachowaniem — testy wyłącznie na produkcyjnym to proszenie się o wpadkę przy pierwszej realnej fakturze
- adres nabywcy to nie jeden tekst, tylko struktura pól — kopiowanie „ulica, miasto” jednym ciągiem kończy się odrzuceniem
- błąd tokena (HTTP 450) NIE może oznaczać w systemie „faktura odrzucona przez urząd” — to błąd techniczny; myląc te stany, księgowość zacznie ręcznie prostować rzeczy, które wystarczyło ponowić
- token trzeba przechowywać zaszyfrowany i odnawiać — wpisany na sztywno w konfigurację to incydent bezpieczeństwa czekający na termin
Co to zmienia w codziennej pracy firmy serwisowej
Dobrze zintegrowany KSeF jest niewidzialny: technik zamyka zlecenie protokołem, biuro klika „wystaw”, faktura buduje się z pozycji zlecenia, leci do bramki, a system pilnuje statusu i archiwizuje UPO przy fakturze. Nikt nie loguje się do rządowej aplikacji i nie przepisuje pozycji. Źle zintegrowany — mnoży pracę: podwójne wystawianie, ręczne sprawdzanie statusów, niejasne stany „wysłana? przyjęta?”. Obowiązek jest ten sam; różnica jest w godzinach.
Pytania kontrolne do wykonawcy integracji
- na którym środowisku KSeF testował i czy pokaże wysyłkę na bramkę testową na żywo
- jak system rozróżnia błąd techniczny od odrzucenia merytorycznego
- gdzie i jak przechowywany jest token (odpowiedź musi zawierać słowo „zaszyfrowany”)
- co się dzieje z fakturą, gdy bramka nie odpowiada — kolejka i ponowienia czy komunikat błędu na użytkownika
- gdzie ląduje UPO i jak księgowość je znajdzie za trzy lata
Najczęstsze pytania
Ile kosztuje integracja KSeF w aplikacji firmowej?
W naszym kalkulatorze wyceniamy ją na 8–14 tys. zł netto jako moduł istniejącej aplikacji — z budową struktury FA(3), obsługą sesji, statusami i archiwizacją UPO. Widełki rosną, gdy dochodzi wiele podmiotów wystawiających albo nietypowe rodzaje dokumentów.
Czy nie wystarczy program księgowy z KSeF, po co to w aplikacji firmowej?
Wystarczy — jeśli akceptujesz przepisywanie danych ze zleceń do programu księgowego. Integracja w aplikacji usuwa właśnie to ogniwo: faktura powstaje z zamkniętego zlecenia, bez przepisywania i błędów przepisywania. Księgowość dalej używa swojego programu, ale dostaje komplet zamiast strzępów.
Nasza aplikacja już istnieje — da się dołożyć KSeF bez przebudowy?
Zwykle tak, o ile aplikacja ma sensownie ustrukturyzowane dane faktur (pozycje, stawki VAT, dane stron jako pola, nie jeden tekst). Audyt tej struktury to pierwszy krok — czasem godzina, czasem sygnał, że najpierw trzeba uporządkować model danych.