KSeF a Dynamics 365 Business Central: jak to napojit

KSeF a Dynamics 365 Business Central — věta, která vypadá jednoduše. Napojíte ERP na státní systém, faktury odcházejí, hotovo. V praxi to takhle nefunguje.

Dělali jsme napojení fakturace na KSeF v prostředí, kde Business Central byl primární systém pro vystavování faktur. Níže popisuji, co musíte vyřešit a kde to reálně drhne. Jestli na tohle hledáte dodavatele, děláme to.

Proč BC + KSeF není jen konfigurace

Business Central je mohutný ERP s propracovaným modulem fakturace. KSeF je asynchronní, rate-limited státní systém s vlastním stavem. Když je dáte dohromady, vzniknou třecí plochy, které žádný konfigurátor z Marketplace nevyřeší beze zbytku.

Tři věci, které to komplikují:

KSeF je asynchronní. Odešlete fakturu, dostanete referenční číslo. Potvrzení (UPO) přijde později — minutes, občas déle. Mezi odesláním a UPO musíte stav někde držet a sledovat.

BC má vlastní stavový automat faktur. Posted Invoice, Sent, Cancelled — tyhle stavy musíte synchronizovat s tím, co říká KSeF. Když jsou stavy nesynchronizované, účetní nevědí, co je fakturováno a co ne.

Rate limity KSeF jsou reálné. Při dávkovém zpracování větší agendy na ně narazíte. Bez řízení tempa zastavíte celou fakturaci v půlce měsíce.

Architektura napojení

Napojení, které nespadne, stojí na několika pilířích. Popisuji je v pořadí, v jakém na ně narazíte.

1. Mapování BC → KSeF formát

Business Central drží data v jiné struktuře než KSeF FA(2) XML. Mapping není triviální.

Co musíte vyřešit:

• Identifikátory protistrany (NIP, DIČ) — BC je může mít na více místech, KSeF akceptuje jeden konkrétní formát
• Číselné řady faktur — KSeF má vlastní číslovací logiku, BC má svoji; musíte rozhodnout, která je autoritativní a jak druhý systém informovat
• Typy faktur — prodejní, opravné, zálohové; každý má jiné povinné pole
• Zaokrouhlení a DPH sazby — BC počítá daň svým způsobem, KSeF požaduje hodnoty na konkrétní počet desetinných míst

Mapping je zdrojový soubor pravdy, ne jednorázový skript. Mění se s legislativou.

2. Durable submit s idempotency key

Největší chyba, kterou vidím v existujících integracích: HTTP request zavolá KSeF API přímo z BC event handleru. Když request selže (timeout, 503, restart serveru), faktura se buď nezaregistruje, nebo se zaregistruje dvakrát.

Každé odeslání faktury do KSeF musí být:

• Persistované — zapsáno do fronty před odesláním, ne až po
• Idempotentní — deterministický klíč odvozený z čísla faktury v BC; KSeF ho odmítne, pokud faktura s tímto klíčem už existuje
• Opakovatelné — když selže, retry to zkusí znovu bez vedlejšího efektu

V .NET prostředí to řešíme přes Hangfire nebo podobný job scheduler — ne background service s in-memory frontou, protože ta nepřežije restart.

3. Status polling a UPO zpět do BC

Odeslali jste fakturu. KSeF vrátil referenční číslo. Teď musíte sledovat stav, dokud nepřijde UPO.

UPO (Urzędowe Poświadczenie Odbioru) je jediný důkaz, že stát fakturu přijal. Bez UPO faktura není hotová, bez ohledu na to, co říká BC.

Polling musí:

• Respektovat rate limity KSeF (nevolat každou sekundu)
• Mít exponenciální backoff při chybách
• Po přijetí UPO aktualizovat záznam v BC — číslo KSeF, datum přijetí, odkaz na UPO dokument
• Alertovat, když faktura uvízne déle než je očekávané maximum

UPO ukládáme zpět do BC jako přílohu nebo do vlastní tabulky. Účetní musí mít důkaz dostupný přímo v ERP, ne v externím systému.

4. Reconciliation

Tenhle krok vynechá skoro každý. Je nejdůležitější.

Jednou denně (nebo vícekrát) spustíte job, který porovná:

• Faktury v BC ve stavu "odesláno do KSeF"
• Faktury, pro které máme UPO
• Faktury, pro které UPO chybí nebo je stav neznámý

Pokud najdete nesrovnalost, chcete vědět dřív než zákazník nebo kontrolor. Reconciliation job je pojistka, která zajistí, že fire-and-forget chyby se nezakopou tiše v datech.

5. Ošetření výpadků a testovací prostředí

KSeF má testovací a produkční prostředí. Přepínání mezi nimi musí být konfigurovatelné bez přepisování kódu.

Testovací prostředí KSeF se chová jinak než produkce — jiné limity, jiné responsetimes, občas jiné chybové kódy. Architektura musí tyto rozdíly absorbovat, ne je vystavovat do business logiky.

Produkční výpadky KSeF jsou reálné. Integrace musí:

• Detekovat výpadek (rozlišit "KSeF nedostupný" od "moje faktura má chybu")
• Fakturace v BC pokračuje normálně — faktury se hromadí ve frontě
• Po obnovení dostupnosti fronta se odešle automaticky, v pořádku, bez duplicit

Kde to reálně drhne

Ze zkušenosti: nejvíc času strávíte na těchto místech.

Číselné řady. BC má vlastní číselnou řadu faktur. KSeF přiděluje vlastní čísla. Přechodné mapování obou číselných řad, aby se účetní nezbláznil, vyžaduje pečlivý design.

Opravné doklady. Dobropisy a opravné faktury mají v KSeF jiný formát a jiná povinná pole. Musíte mapovat referenci na původní fakturu, a to i v případě, kdy původní faktura byla v systému před spuštěním integrace.

Retry bez duplicit. Retry logic musí být v BC i na KSeF straně správně nastavena. Jednoduchý retry bez idempotency key vytvoří duplicitní faktury ve státním systému — a zrušit je je pak práce navíc.

Monitoring pro účetní. Technický log nestačí. Účetní potřebuje vidět stav každé faktury v terminologii, které rozumí: odesláno, čeká na potvrzení, potvrzeno, zamítnuto. Tohle musíte postavit nad technickým stavovým automatem.

Čísla z produkce

V systémech, kde jsme napojení budovali, zpracovaly přes 40 000 dokumentů v produkci. 100 % doručeno s UPO. Žádná ztracená faktura, žádná duplicita.

To není číslo z presale slidů. Je to výsledek architektury, která počítá s tím, že KSeF bude občas pomalý, občas nedostupný a že síť není spolehlivá.

Jak s tím pomáháme

Napojení KSeF na Business Central dělám jako custom integrace. Výstupem je:

• Mapping BC → KSeF formát pro váš typ faktur
• Submit pipeline s idempotency key a retry
• Status polling s UPO zpět do BC
• Reconciliation job
• Dashboard stavu faktur pro účetní
• Přepínání testovací / produkční prostředí

Pokud máte existující integraci a chcete audit, udělám to. Pokud stavíte novou, začněte správně.

Napište nám — řekneme vám, co vaše konkrétní BC nastavení vyžaduje.

---

FAQ

Funguje napojení KSeF jako standardní BC extension z Marketplace?

Marketplace extension může pokrýt základní scénář, pokud máte standardní faktury a neočekáváte výpadky. Jakmile přibude objem, nestandardní typy faktur nebo potřeba reconciliation, zjistíte, že extension má pevně daná omezení. Custom integrace dává plnou kontrolu nad každým krokem.

Jak dlouho trvá implementace?

Záleží na rozsahu fakturačního procesu. Základní napojení (submit + UPO) je otázka týdnů. S reconciliation, dashboardem a ošetřením edge cases počítejte s 6–10 týdny. Víc přesný odhad dám po analýze vašeho BC nastavení.

Musíme mít vlastní .NET infrastrukturu, nebo to funguje i jinak?

Integrace běží jako samostatná služba mimo BC. Nepotřebujete měnit BC kód. Potřebujete prostředí, kde může běžet .NET background service a job scheduler — cloud (Azure, AWS) nebo on-premise. Pokud máte BC v cloudu u Microsoftu, řešíme to jako oddělený mikroservis s API napojením na BC.