TaxLayer
Technika2026-11-138 min Čas čítaniaod TaxLayer Team

E-faktúra cez API: automatická konverzia a kontrola CSV a XML na ZUGFeRD, XRechnung a PEPPOL

Povinnosť e-faktúry zasiahne najviac firmy s veľkým počtom faktúr. Kto mesačne vystavuje stovky alebo tisíce faktúr, nemôže ich nahrávať, kontrolovať a sťahovať po jednej. Zároveň nie každé ERP má modul pre e-faktúry a vlastný softvér by musel ZUGFeRD, XRechnung a PEPPOL vytvárať sám, udržiavať ich aktuálne a overovať podľa oficiálnych pravidiel. API túto medzeru zapĺňa: Váš softvér dodá dáta, rozhranie dodá overené e-faktúry. Tento sprievodca ukazuje, ako to funguje a na čo dbať pri výbere.

> Stručná odpoveď: API pre e-faktúry prijíma údaje faktúr z Vášho systému a vracia hotové súbory ZUGFeRD, XRechnung alebo PEPPOL. Najspoľahlivejšie sú štruktúrované vstupy (CSV alebo XML), pretože sa nič neodhaduje. Rozhodujúce je, aby sa každý súbor pred výstupom overil podľa EN 16931 a pravidiel KoSIT. API TaxLayer na to ponúka štyri endpointy (stav, konverzia CSV, konverzia XML, kontrola) a je súčasťou Enterprise.

Prečo API namiesto ručnej práce

E-faktúra je štruktúrovaný súbor dát podľa EN 16931. Ručné vytvorenie zaberie na jednu faktúru len niekoľko minút, pri veľkých objemoch však dni v mesiaci. K tomu pribúdajú zdroje chýb: nesprávne kódy jednotiek, chýbajúce povinné údaje pre XRechnung, zaokrúhľovacie rozdiely v prehľade dane. API automatizuje celú cestu:

  • Váš systém exportuje údaje faktúr, napríklad v noci ako súbor CSV.
  • Malý skript odošle súbor na rozhranie.
  • API vytvorí pre každú faktúru PDF ZUGFeRD, XRechnung alebo súbor PEPPOL.
  • Každý súbor sa overí, kým sa vráti. Chybné faktúry sa vrátia s odôvodnením namiesto neplatného súboru.

Váš fakturačný proces tak zostane taký, aký je, len na konci vznikne platná e-faktúra.

Ktorý vstup: CSV, XML alebo PDF

Najdôležitejšou otázkou pri automatizácii je, v akej forme dáta existujú.

VstupTypický zdrojSpoľahlivosť
CSVexport z ERP, skladový systém, tabuľkaveľmi vysoká, hodnoty sa preberú presne
XML (UBL, CII)existujúce e-faktúry, moderné systémyveľmi vysoká, čítanie podľa pravidiel
PDFtlač faktúr z ľubovoľných systémovdobrá, ale len s kontrolou človekom

CSV je najjednoduchšia cesta pre systémy bez modulu e-faktúry. Takmer každé ERP vie vydať faktúry ako tabuľku. V šablóne TaxLayer je každá položka v jednom riadku, hlavičkové údaje (predávajúci, kupujúci, platba) sa opakujú v každom riadku. Jeden súbor môže obsahovať mnoho faktúr zoskupených podľa čísla faktúry.

XML sa oplatí, ak už e-faktúry existujú a má sa zmeniť len formát. Typickým prípadom je XRechnung pre úrad, ktorý zákazník chce navyše ako čitateľné PDF ZUGFeRD, alebo faktúra ZUGFeRD, ktorá sa má odoslať cez sieť PEPPOL. UBL (XRechnung, PEPPOL BIS) a CII (ZUGFeRD, Factur-X) sa čítajú podľa pravidiel, bez AI.

PDF je vstup, ktorý sľubuje najviac pohodlia a ponúka najmenej istoty. Moderná AI číta údaje faktúr z PDF veľmi dobre, ale nie bezchybne. Zamenená číslica v sume alebo nesprávne rozpoznaná sadzba dane by sa inak dostala bez kontroly do právne záväznej faktúry. TaxLayer preto PDF zámerne ponúka iba vo webovej aplikácii, s krokom kontroly pred výstupom a v dávke až 50 faktúr (Enterprise Plus: 70). Prečo samotné PDF nie je e-faktúra, vysvetľuje článok Excel a PDF nie sú e-faktúra.

Kontrola: časť, na ktorú mnohí zabúdajú

E-faktúra je e-faktúrou až vtedy, keď vyhovuje pravidlám. Pre Nemecko ide o EN 16931 a pre XRechnung navyše o nemecké obchodné pravidlá (BR-DE), napríklad telefónne číslo a e-mailovú adresu predávajúceho. Tieto pravidlá kontroluje Koordinierungsstelle für IT-Standards (KoSIT) oficiálnou sadou pravidiel, ktorú používajú aj verejní príjemcovia faktúr.

Pri API dbajte na tri body:

  • Kontrola pred výstupom: Každý vytvorený súbor by mal prejsť úplnou sadou pravidiel, nielen schémou XML.
  • Automaticky znamená automaticky: Aj najlepšia kontrola potvrdzuje len formu. V TaxLayer prebiehajú všetky kontroly strojovo, nie je tu žiadna manuálna kontrola; za obsah (sumy, sadzby dane, príjemcu) zodpovedáte ako doteraz sami.
  • Fail-closed: Ak kontrolná služba nie je dostupná, API nesmie vydať nekontrolovaný súbor. API TaxLayer vtedy odpovie kódom 503 a nič neúčtuje; Váš skript požiadavku jednoducho odošle znova.
  • Zrozumiteľné chyby: Namiesto „neplatné“ potrebujete kód pravidla a hlásenie, napríklad BR-DE-6 pri chýbajúcom telefónnom čísle. Kódy si môžete vyhľadať v zozname kódov chýb XRechnung.

Kontrolný endpoint je užitočný aj pri prijatých faktúrach: Skôr než faktúra dodávateľa pôjde do účtovníctva, ukáže, či vyhovuje pravidlám. Pre jednotlivé súbory existuje navyše bezplatný validátor v prehliadači.

Bezpečnosť a ochrana údajov

API pre faktúry spracúva citlivé údaje. Pýtajte sa na:

  • Správu kľúčov: API kľúče by sa mali ukladať iba ako hash a mali by byť kedykoľvek odvolateľné. V TaxLayer kľúč uvidíte raz pri vytvorení; odvolaný kľúč je okamžite neplatný.
  • Žiadny prístup z prehliadača: Kľúče patria na server. API TaxLayer neodosiela hlavičky CORS, volania z webových stránok preto nie sú možné.
  • Ukladanie: Súbory faktúr by sa nemali ukladať. Prístupový protokol by mal obsahovať iba technické údaje.
  • Umiestnenie: Spracovanie v EÚ, v TaxLayer vo Frankfurte.

Ako vyzerá volanie

Volanie je jednoduchá požiadavka HTTP: súbor CSV odošlete metódou POST na /v1/convert/csv?format=xrechnung a svoj kľúč vložíte do hlavičky Authorization: Bearer tlk_…. S curl je to jeden riadok, v Pythone alebo Node.js približne desať riadkov.

Odpoveď je JSON: pre každú faktúru hotový súbor (XML ako text alebo PDF ZUGFeRD ako Base64) a zoznam faktúr, ktoré sa nepodarilo vytvoriť, s dôvodom. Do Vášho limitu sa počítajú len úspešne vytvorené faktúry. Všetky endpointy, parametre, kódy chýb a príklady v Node.js a Pythone nájdete v dokumentácii API.

Kontrolný zoznam pre štart

  1. Overte, či Váš systém vie exportovať faktúry ako CSV alebo XML.
  2. Stiahnite si šablónu CSV z dokumentácie a namapujte na ňu svoje stĺpce.
  3. Pre XRechnung doplňte Leitweg-ID, resp. referenciu kupujúceho, telefón, e-mail, PSČ a mesto predávajúceho, ako aj PSČ, mesto a e-mailovú adresu alebo IČ DPH kupujúceho.
  4. V účte vytvorte v časti „API (Beta)“ kľúč a vyskúšajte ho volaním stavu.
  5. Odošlite prvý súbor a vyhodnoťte pole errors, skôr než prejdete na nočný beh.

---

E-faktúra nemusí byť projekt s vlastným vývojom. S API TaxLayer Váš systém dodá dáta a Vy dostanete späť overené súbory ZUGFeRD, XRechnung a PEPPOL. API je súčasťou Enterprise a Enterprise Plus a momentálne je dostupné ako beta. Otázky na info@taxlayer.de.

Často kladené otázky

Čo je API pre e-faktúry?

Programové rozhranie, na ktoré Váš softvér odošle údaje faktúr a ktoré vráti hotové e-faktúry v požadovanom formáte, napríklad ZUGFeRD, XRechnung alebo PEPPOL. Ušetríte si vlastný generátor, údržbu verzií formátov a prevádzku validátora.

Ktorý vstup sa najlepšie hodí na automatizáciu?

Štruktúrované dáta, teda CSV alebo XML. Hodnoty sa preberú presne, nič sa nemusí odhadovať. Dáta z PDF sa síce dajú načítať pomocou AI, no nie bezchybne a vyžaduje to kontrolný krok človeka.

Ako zabezpečím, že vytvorená e-faktúra je platná?

Každý súbor by sa mal pred výstupom overiť podľa oficiálnej sady pravidiel, teda EN 16931 a pre XRechnung navyše nemeckých pravidiel BR-DE. API TaxLayer kontroluje každý súbor kontrolnými pravidlami KoSIT a vydá iba súbory, ktoré prešli.

Môžem pomocou API kontrolovať aj faktúry dodávateľov?

Áno. Kontrolný endpoint prijíma XML (UBL alebo CII) a PDF ZUGFeRD a vracia výsledok s kódmi pravidiel, napríklad BR-CO-15 pri nesprávnom celkovom súčte. Chybné prijaté faktúry tak vyjdú najavo ešte pred zaúčtovaním.

Koľko stojí API TaxLayer?

Je súčasťou tarifov Enterprise a Enterprise Plus. Konverzie sa započítavajú do rovnakého mesačného limitu ako webová aplikácia, kontroly majú vlastný denný limit.

Potrebujem znalosti programovania?

Trochu. Volanie je jednoduchá požiadavka HTTP, ktorú možno odoslať pomocou curl, krátkeho skriptu v Pythone alebo Node.js, alebo z mnohých ERP systémov. Dokumentácia obsahuje príklady na skopírovanie.

Konvertujte PDF faktúry hneď teraz

Vyskúšajte TaxLayer zadarmo, 2 konverzie mesačne, bez kreditnej karty.

Začať teraz