E-račun putem API-ja: automatska pretvorba i provjera CSV-a i XML-a u ZUGFeRD, XRechnung i PEPPOL
Obveza e-računa najviše pogađa tvrtke s mnogo računa. Tko mjesečno piše stotine ili tisuće računa, ne može ih pojedinačno učitavati, provjeravati i preuzimati. Istodobno nema svaki ERP modul za e-račune, a vlastiti bi softver morao sam generirati ZUGFeRD, XRechnung i PEPPOL, održavati ih ažurnima i provjeravati prema službenim pravilima. API popunjava tu prazninu: vaš softver šalje podatke, sučelje vraća provjerene e-račune. Ovaj vodič pokazuje kako to funkcionira i na što paziti pri odabiru.
> Kratki odgovor: API za e-račune preuzima podatke računa iz vašeg sustava i vraća gotove datoteke u formatu ZUGFeRD, XRechnung ili PEPPOL. Najpouzdaniji su strukturirani ulazi (CSV ili XML) jer se vrijednosti ne pogađaju. Ključno je da se svaka datoteka prije izdavanja provjeri prema EN 16931 i KoSIT pravilima. TaxLayer API za to nudi četiri endpointa (status, pretvorba CSV-a, pretvorba XML-a, provjera) i uključen je u Enterprise.
Zašto API umjesto ručnog rada
E-račun je strukturirani skup podataka prema EN 16931. Ručna izrada oduzima po računu samo nekoliko minuta, ali kod velikih količina to su dani mjesečno. K tome dolaze izvori pogrešaka: pogrešne šifre mjernih jedinica, nedostajući obvezni podaci za XRechnung, razlike u zaokruživanju u poreznom obračunu. API automatizira cijeli put:
- Vaš sustav izvozi podatke računa, primjerice noću kao CSV datoteku.
- Mala skripta šalje datoteku sučelju.
- API generira po računu ZUGFeRD PDF, XRechnung ili PEPPOL datoteku.
- Svaka se datoteka provjerava prije nego što se vrati. Neispravni računi vraćaju se s obrazloženjem umjesto kao nevaljana datoteka.
Tako vaš proces izdavanja računa ostaje kakav jest, samo na kraju stoji valjani e-račun.
Koji ulaz: CSV, XML ili PDF
Najvažnije pitanje pri automatizaciji je u kojem obliku podaci postoje.
| Ulaz | Tipičan izvor | Pouzdanost |
|---|---|---|
| CSV | ERP izvoz, robno poslovanje, tablica | vrlo visoka, vrijednosti se preuzimaju točno |
| XML (UBL, CII) | postojeći e-računi, moderni sustavi | vrlo visoka, čita se prema pravilima |
| ispis računa iz bilo kojeg sustava | dobra, ali samo uz ljudsku provjeru |
CSV je najjednostavniji put za sustave bez modula za e-račune. Gotovo svaki ERP može izdati račune kao tablicu. U TaxLayerovom predlošku svaka stavka stoji u jednom retku, a podaci zaglavlja (prodavatelj, kupac, plaćanje) ponavljaju se u svakom retku. Jedna datoteka smije sadržavati mnogo računa, grupiranih prema broju računa.
XML se isplati kada e-računi već postoje i treba samo promijeniti format. Tipično je XRechnung za tijelo javne vlasti koji kupac dodatno želi kao čitljiv ZUGFeRD PDF, ili ZUGFeRD račun koji treba poslati preko PEPPOL mreže. UBL (XRechnung, PEPPOL BIS) i CII (ZUGFeRD, Factur-X) čitaju se prema pravilima, bez umjetne inteligencije.
PDF je ulaz koji obećava najviše udobnosti, a nudi najmanje sigurnosti. Moderna umjetna inteligencija vrlo dobro čita podatke računa iz PDF-ova, ali ne bez pogrešaka. Zamijenjena znamenka u iznosu ili krivo prepoznata porezna stopa inače bi nepreispitana završila u pravno obvezujućem računu. TaxLayer stoga PDF namjerno nudi samo u web aplikaciji, s korakom provjere prije izdavanja i skupno do 50 računa (Enterprise Plus: 70). Zašto sam PDF nije e-račun, objašnjava članak Excel i PDF nisu e-račun.
Provjera: dio koji mnogi zaborave
E-račun je e-račun tek kada udovoljava pravilima. Za Njemačku su to EN 16931 i za XRechnung dodatno njemačka poslovna pravila (BR-DE), primjerice telefonski broj i adresa e-pošte prodavatelja. Ta pravila provjerava Koordinierungsstelle für IT-Standards (KoSIT) službenim skupom pravila koji koriste i javni primatelji računa.
Kod API-ja pazite na tri točke:
- Provjera prije izdavanja: svaka generirana datoteka treba proći cjelovit skup pravila, a ne samo XML shemu.
- Automatski znači automatski: čak i najbolja provjera potvrđuje samo oblik. U TaxLayeru sve provjere rade strojno, nema ručne kontrole; za sadržaj (iznose, porezne stope, primatelja) odgovarate sami kao i dosad.
- Fail-closed: ako usluga provjere nije dostupna, API ne smije izdati neprovjerenu datoteku. TaxLayer API tada odgovara s 503 i ništa ne naplaćuje; vaša skripta jednostavno ponovno šalje zahtjev.
- Razumljive pogreške: umjesto „nevaljano“ trebate kod pravila i poruku, primjerice BR-DE-6 za nedostajući telefonski broj. Kodove možete potražiti u imeniku XRechnung kodovi pogrešaka.
Endpoint za provjeru koristan je i za ulazne račune: prije nego što račun dobavljača ode u knjigovodstvo, pokazuje udovoljava li pravilima. Za pojedinačne datoteke postoji i besplatni validator u pregledniku.
Sigurnost i zaštita podataka
API za račune obrađuje osjetljive podatke. Pitajte za:
- Upravljanje ključevima: API ključevi trebaju se pohranjivati samo kao hash i biti opozivi u svakom trenutku. U TaxLayeru ključ vidite jednom pri izradi; opozvani ključ odmah postaje nevaljan.
- Bez pristupa iz preglednika: ključevi pripadaju na poslužitelj. TaxLayer API ne šalje CORS zaglavlja, pa pozivi s web stranica nisu mogući.
- Pohrana: datoteke računa ne bi trebalo pohranjivati. Zapisnik pristupa trebao bi sadržavati samo tehničke podatke.
- Lokacija: obrada u EU, kod TaxLayera u Frankfurtu.
Kako izgleda poziv
Poziv je jednostavan HTTP zahtjev: CSV datoteku šaljete metodom POST na /v1/convert/csv?format=xrechnung i svoj ključ stavljate u zaglavlje Authorization: Bearer tlk_…. S curl-om je to jedna naredba, u Pythonu ili Node.js-u oko deset redaka.
Odgovor je JSON: po računu gotova datoteka (XML kao tekst ili ZUGFeRD PDF kao Base64) i popis računa koji se nisu mogli izraditi, s razlogom. U vaš kontingent ulaze samo uspješno izrađeni računi. Svi endpointi, parametri, kodovi pogrešaka i primjeri u Node.js-u i Pythonu nalaze se u API dokumentaciji.
Kontrolni popis za početak
- Provjerite može li vaš sustav izvoziti račune kao CSV ili XML.
- Preuzmite CSV predložak iz dokumentacije i preslikajte svoje stupce na njega.
- Za XRechnung dopunite Leitweg-ID odnosno referencu kupca, telefon, e-poštu, poštanski broj i mjesto prodavatelja te poštanski broj, mjesto i adresu e-pošte ili PDV identifikacijski broj (USt-IdNr.) kupca.
- U računu pod „API (Beta)“ izradite ključ i testirajte pozivom statusa.
- Pošaljite prvu datoteku i obradite polje errors prije nego što prijeđete na noćno pokretanje.
---
E-račun ne mora biti projekt s vlastitim razvojem. Uz TaxLayer API vaš sustav isporučuje podatke, a vi dobivate natrag provjerene ZUGFeRD, XRechnung i PEPPOL datoteke. API je uključen u Enterprise i Enterprise Plus i trenutačno je dostupan kao beta. Pitanja na info@taxlayer.de.
Često postavljana pitanja
Što je API za e-račune?
Programsko sučelje kojem vaš softver šalje podatke računa i koje vraća gotove e-račune u željenom formatu, primjerice ZUGFeRD, XRechnung ili PEPPOL. Ušteđujete vlastiti generator, održavanje verzija formata i pogon validatora.
Koji je ulaz najprikladniji za automatizaciju?
Strukturirani podaci, dakle CSV ili XML. Vrijednosti se preuzimaju točno, ništa se ne mora pogađati. Iz PDF-ova se podaci doduše mogu očitati umjetnom inteligencijom, ali to nije bez pogrešaka i zahtijeva korak ljudske provjere.
Kako osigurati da je generirani e-račun valjan?
Svaku datoteku treba prije izdavanja provjeriti službenim pravilima, dakle EN 16931 i za XRechnung dodatno njemačkim BR-DE pravilima. TaxLayer API provjerava svaku datoteku KoSIT pravilima provjere i izdaje samo datoteke koje su prošle provjeru.
Mogu li API-jem provjeravati i račune dobavljača?
Da. Endpoint za provjeru prima XML (UBL ili CII) i ZUGFeRD PDF-ove i vraća rezultat s kodovima pravila, primjerice BR-CO-15 za pogrešan ukupni iznos. Tako se neispravni ulazni računi uoče prije knjiženja.
Koliko košta TaxLayer API?
Uključen je u pakete Enterprise i Enterprise Plus. Pretvorbe se računaju u isti mjesečni kontingent kao i web aplikacija, a provjere imaju zasebno dnevno ograničenje.
Trebam li znanje programiranja?
Malo. Poziv je jednostavan HTTP zahtjev koji se može poslati pomoću curl-a, kratke skripte u Pythonu ili Node.js-u ili iz mnogih ERP sustava. Dokumentacija sadrži primjere koje možete kopirati.
Besplatni alati
Povezani članci
Pretvorite PDF račune odmah
Isprobajte TaxLayer besplatno, 2 konverzije mjesečno, bez kreditne kartice.
Započnite odmah