KSeF i Dynamics 365 Business Central: jak to podłączyć

KSeF i Dynamics 365 Business Central — zdanie, które brzmi prosto. Podłączasz ERP do systemu państwowego, faktury idą, gotowe. W praktyce tak to nie działa.

Robiliśmy integrację fakturacji z KSeF w środowisku, gdzie Business Central był głównym systemem wystawiania faktur. Poniżej opisuję, co musisz rozwiązać i gdzie realnie zgrzyta. Jeśli szukasz kogoś do tego, robimy to.

Dlaczego BC + KSeF to nie jest tylko konfiguracja

Business Central to rozbudowany ERP z dopracowanym modułem fakturacji. KSeF to asynchroniczny, limitowany system państwowy z własnym stanem. Gdy je ze sobą połączysz, powstają tarcia, których żaden konfigurator z Marketplace nie rozwiąże do końca.

Trzy rzeczy, które to komplikują:

KSeF jest asynchroniczny. Wysyłasz fakturę, dostajesz numer referencyjny. Potwierdzenie (UPO) przychodzi później — minuty, czasem dłużej. Między wysłaniem a UPO musisz gdzieś przechowywać stan i go śledzić.

BC ma własny automat stanów faktur. Posted Invoice, Sent, Cancelled — te stany musisz synchronizować z tym, co mówi KSeF. Gdy stany są niesynchronizowane, księgowe nie wiedzą, co jest zafakturowane, a co nie.

Limity KSeF są realne. Przy wsadowym przetwarzaniu większej agendy trafisz na nie. Bez kontroli tempa zatrzymasz całą fakturację w połowie miesiąca.

Architektura integracji

Integracja, która nie padnie, stoi na kilku filarach. Opisuję je w kolejności, w jakiej na nie trafisz.

1. Mapowanie BC → format KSeF

Business Central przechowuje dane w innej strukturze niż KSeF FA(2) XML. Mapowanie nie jest trywialne.

Co musisz rozwiązać:

• Identyfikatory kontrahenta (NIP, NIP-UE) — BC może je mieć w kilku miejscach, KSeF akceptuje jeden konkretny format
• Serie numeracyjne faktur — KSeF ma własną logikę numerowania, BC ma swoją; musisz zdecydować, który system jest autorytatywny i jak poinformować drugi
• Typy faktur — sprzedażowe, korygujące, zaliczkowe; każdy ma inne obowiązkowe pola
• Zaokrąglenia i stawki VAT — BC liczy podatek po swojemu, KSeF wymaga wartości z określoną liczbą miejsc dziesiętnych

Mapowanie to źródłowy plik prawdy, nie jednorazowy skrypt. Zmienia się wraz z legislacją.

2. Durable submit z idempotency key

Największy błąd, jaki widzę w istniejących integracjach: żądanie HTTP wywołuje KSeF API bezpośrednio z event handlera w BC. Gdy żądanie się nie powiedzie (timeout, 503, restart serwera), faktura albo się nie zarejestruje, albo zarejestruje dwukrotnie.

Każde wysłanie faktury do KSeF musi być:

• Utrwalone — zapisane do kolejki przed wysłaniem, nie po
• Idempotentne — deterministyczny klucz wyprowadzony z numeru faktury w BC; KSeF odrzuci je, jeśli faktura z tym kluczem już istnieje
• Powtarzalne — gdy zawiedzie, retry spróbuje ponownie bez efektów ubocznych

W środowisku .NET rozwiązujemy to przez Hangfire lub podobny job scheduler — nie background service z kolejką in-memory, bo ta nie przeżyje restartu.

3. Polling statusu i UPO z powrotem do BC

Wysłałeś fakturę. KSeF zwrócił numer referencyjny. Teraz musisz śledzić status, aż przyjdzie UPO.

UPO (Urzędowe Poświadczenie Odbioru) to jedyny dowód, że państwo przyjęło fakturę. Bez UPO faktura nie jest gotowa — bez względu na to, co mówi BC.

Polling musi:

• Respektować limity KSeF (nie wywoływać co sekundę)
• Stosować exponential backoff przy błędach
• Po otrzymaniu UPO zaktualizować rekord w BC — numer KSeF, data przyjęcia, odnośnik do dokumentu UPO
• Alertować, gdy faktura utknie dłużej niż oczekiwane maksimum

UPO zapisujemy z powrotem do BC jako załącznik lub do własnej tabeli. Księgowe muszą mieć dowód dostępny bezpośrednio w ERP, nie w zewnętrznym systemie.

4. Reconciliacja

Ten krok pomija niemal każdy. Jest najważniejszy.

Raz dziennie (lub częściej) uruchamiasz job, który porównuje:

• Faktury w BC o statusie „wysłane do KSeF"
• Faktury, dla których mamy UPO
• Faktury, dla których UPO brakuje lub status jest nieznany

Jeśli znajdziesz rozbieżność, chcesz wiedzieć o tym wcześniej niż klient lub kontroler. Job reconciliacji to zabezpieczenie, które sprawia, że błędy fire-and-forget nie zakopują się cicho w danych.

5. Obsługa awarii i środowisko testowe

KSeF ma środowisko testowe i produkcyjne. Przełączanie między nimi musi być konfigurowalne bez przepisywania kodu.

Środowisko testowe KSeF zachowuje się inaczej niż produkcja — inne limity, inne czasy odpowiedzi, czasem inne kody błędów. Architektura musi absorbować te różnice, nie wystawiać ich do logiki biznesowej.

Produkcyjne awarie KSeF są realne. Integracja musi:

• Wykryć awarię (odróżnić „KSeF niedostępny" od „moja faktura ma błąd")
• Fakturacja w BC działa normalnie — faktury gromadzą się w kolejce
• Po przywróceniu dostępności kolejka wysyła się automatycznie, w porządku, bez duplikatów

Gdzie realnie zgrzyta

Z doświadczenia: najwięcej czasu spędzisz w tych miejscach.

Serie numeracyjne. BC ma własną serię numeracyjną faktur. KSeF nadaje własne numery. Zaprojektowanie przejściowego mapowania obu serii, żeby księgowe się nie pogubili, wymaga starannego projektu.

Dokumenty korygujące. Korekty i noty mają w KSeF inny format i inne obowiązkowe pola. Musisz mapować odniesienie do faktury pierwotnej — nawet gdy faktura pierwotna była w systemie przed uruchomieniem integracji.

Retry bez duplikatów. Logika retry musi być poprawnie skonfigurowana po stronie BC i po stronie KSeF. Prosty retry bez idempotency key stworzy duplikatowe faktury w systemie państwowym — a ich anulowanie to dodatkowa robota.

Monitoring dla księgowych. Techniczny log nie wystarczy. Księgowa musi widzieć stan każdej faktury w terminologii, którą rozumie: wysłana, czeka na potwierdzenie, potwierdzona, odrzucona. To musisz zbudować ponad technicznym automatem stanów.

Liczby z produkcji

W systemach, gdzie budowaliśmy integrację, przetworzyliśmy ponad 40 000 dokumentów na produkcji. 100% dostarczonych z UPO. Żadnej zgubionej faktury, żadnego duplikatu.

To nie jest liczba ze slajdów presalowych. To wynik architektury, która zakłada, że KSeF bywa powolny, bywa niedostępny i że sieć nie jest niezawodna.

Jak pomagamy

Integrację KSeF z Business Central robię jako custom integracja. Efektem jest:

• Mapowanie BC → format KSeF dla twoich typów faktur
• Pipeline submitowy z idempotency key i retry
• Polling statusu z UPO z powrotem do BC
• Job reconciliacji
• Dashboard stanu faktur dla księgowych
• Przełączanie środowiska testowego i produkcyjnego

Jeśli masz istniejącą integrację i chcesz audytu — zrobię to. Jeśli budujesz nową — zacznij porządnie.

Napisz do nas — powiemy ci, czego wymaga twoja konkretna konfiguracja BC.

---

FAQ

Czy integracja KSeF działa jako standardowe rozszerzenie BC z Marketplace?

Rozszerzenie z Marketplace może pokryć podstawowy scenariusz, jeśli masz standardowe faktury i nie spodziewasz się awarii. Gdy przybywa wolumenu, niestandardowych typów faktur lub potrzebujesz reconciliacji, okazuje się, że rozszerzenie ma twarde ograniczenia. Custom integracja daje pełną kontrolę nad każdym krokiem.

Jak długo trwa implementacja?

Zależy od zakresu procesu fakturacji. Podstawowe podłączenie (submit + UPO) to kwestia tygodni. Z reconciliacją, dashboardem i obsługą przypadków brzegowych licz 6–10 tygodni. Dokładniejszy szacunek podam po analizie twojej konfiguracji BC.

Czy musimy mieć własną infrastrukturę .NET, czy można inaczej?

Integracja działa jako osobna usługa poza BC. Nie musisz zmieniać kodu BC. Potrzebujesz środowiska, w którym może działać .NET background service i job scheduler — chmura (Azure, AWS) lub on-premise. Jeśli masz BC w chmurze u Microsoftu, rozwiązujemy to jako osobny mikroserwis z podłączeniem API do BC.