Mi az a könyvelési API? Gyakorlati útmutató platformfejlesztőknek

A könyvelési API közérthető definíciója, mi különbözteti meg az adózási vagy fizetési API-tól, és mit érdemes ellenőrizni, mielőtt integrálnánk egybe.

A könyvelési API egy olyan interfész, amely lehetővé teszi, hogy az egyik program vezesse egy másik program könyveit. Az Ön szoftvere HTTP-n keresztül küld egy pénzügyi eseményt. Az API ezt az eseményt a számlatükörhöz kapcsolódó, egyensúlyban lévő kettős könyvviteli tételekké alakítja, úgy tárolja őket, hogy azokat ne lehessen észrevétlenül módosítani, alkalmazza az adózási szabályokat, és ugyanezen az interfészen keresztül riportokat, dokumentumokat, valamint exportokat ad vissza.

Ez a definíció elvégzi a munka nagy részét. A cikkben szereplő minden más dolog ennek a következménye.

Az egyverziós változat

A könyvelési API elfogadja az alkalmazásból érkező pénzügyi eseményeket, mindegyiket egyensúlyban lévő könyvelési tétellé alakítja, változatlan formában (immutably) tárolja az adókezeléssel és a háttérdokumentumokkal együtt, valamint a kapott főkönyvet, a dokumentumokat és a riportokat programozható végpontokként teszi elérhetővé.

Ha egy termék könyvelési API-nak nevezi magát, de nem készít könyvelési tételeket, akkor az valami más egy szép névvel. Ez nem feltétlenül baj. Csak azt jelenti, hogy nem fogja elvégezni azt a feladatot, amire kérni fogja.

Mi nem egy könyvelési API

Négy rokon termékkategóriát szokás összetéveszteni a könyvelési API-kkal, általában egy projekt későbbi szakaszában.

Kategória	Mit csinál	Mit nem csinál
Adószámítási API	Megadja a helyes adókulcsot vagy adóössveget egy tranzakcióhoz	Nem vezeti a könyveket, és nem őrzi meg a döntés alapjául szolgáló dokumentumokat az előírt őrzési ideig
Fizetési API	Pénzt mozgat a felek között, és riportot készít ezekről a mozgásokról	Nem rögzíti az elért jutalékot, a fizetendő ÁFÁ-t, vagy az eladóval szembeni tartozást a fizetés és a kifizetés között
Egységesítő vagy aggregátor API	Adatokat olvas és ír az ügyfél meglévő könyvelőprogramjában	Nem működik nyilvántartási rendszerként; a könyvei abban az eszközben vannak, amelyet az egyes ügyfelek már eleve használnak
Riporting vagy BI API	Adatokat olvas ki egy meglévő főkönyvből, és vizualizálja azokat	Nem hozza létre azokat a tételeket, amelyekből az adatok származnak

Ezek mindegyikének megvan a valós felhasználási területe. Egy olyan platformnak azonban, amelynek nyilvántartási rendszerként kell működnie, a könyvelési API-ra van szüksége a motorháztető alatt, nem pedig helyette.

Öt dolog, amit egy könyvelési API-nak tudnia kell

1. Egyensúlyban lévő tételek rögzítése. Minden eseményből olyan tartozik és követel tétel lesz, amelyek összege megegyezik. Amikor egy vevő 100 eurót fizet egy olyan piactéren, amely 15 euró jutalékot számít fel, a tétel 100 euróval terhel egy elszámolási számlát (tartozik), 85 euróval jóváír egy eladóval szembeni kötelezettséget (követel), 15 eurót pedig jutalékbevételként könyvel le (követel). Ez nem könyvelési formalitás. Ez egy strukturális ellenőrzés, amely még azelőtt kiszűri az integrációs hibák egész sorát, hogy azok eljutnának egy riportig.

2. Előzmények megőrzése. A könyvelt tételt nem szerkesztjük át. A hibát sztornózással, valamint egy helyesbített tétellel korrigáljuk, amelyek mindkettője az eredetihez van kapcsolva. A lezárt hónapok le vannak zárva, így azokba már nem lehet új dátumú tételt rögzíteni.

3. Adószámítás és -kezelés. Az uniós kereskedelemben ez a teljesítés helyét, az adófizetési kötelezettség átszárítását (reverse charge), a hivatalos nyilvántartásban ellenőrzött adószámokat és a döntést indokoló bizonyítékokat jelenti, amelyeket a tranzakció mellett tárol a rendszer, ahelyett, hogy a számítás után eldobná őket.

4. Egyeztetés a külső pénzmozgásokkal. Az olyan könyvek, amelyek soha nem találkoznak a bankkivonattal, csak találgatások. Az API-nak be kell fogadnia a bankkivonatokat vagy a szolgáltatói elszámolásokat, és egyeztetnie kell azokat a rögzítettekkel.

5. Exportálás. Riportok, dokumentumok és auditfájlok olyan formátumban, amelyet egy hús-vér könyvelő és az adóhatóság is elfogad.

Az a termék, amely az első hármat tudja, de az utolsó kettőt nem, továbbra is arra kényszerít valakit, hogy minden hónapban táblázatokkal dolgozzon.

Hogy néz ki a valóságban egy API-hívás?

A mechanika egyszerűbb, mint a könyvelés. A Nordlet API-jában minden művelet egy RPC-stílusú POST kérés kiszámítható szerkezettel:

POST /v1/{module}/{resource}/{action}
Authorization: Bearer <api key>
Idempotency-Key: <your event id>

Létrehoz egy kimenő számlát, majd kiállítja azt. A kiállítás az a pillanat, amikor a könyvelés megtörténik: a dokumentum megkapja a hézagmentes sorszámát, az egyensúlyban lévő könyvelési tétel lekönyvelődik, és az ÁFA-sorok is rögzítésre kerülnek vele együtt. Az Ön platformjának soha nem kell kézzel összepakolnia a tartozik és követel tételeket.

A fenti kódrészletben három olyan részlet van, amely fontosabb a végpont nevénél:

A kulcs hatóköre (scope). Egy kulcs olyan jogosultságokat hordoz, mint a sales:write, így az integráció csak ahhoz fér hozzá, amihez feltétlenül szükséges.
Az idempotencia-kulcs (idempotency key). Ha ugyanazt a kérést ugyanazzal a hasznos teherrel (payload) újra megpróbálja, a tárolt választ kapja vissza a második számla helyett. Ha ugyanezt a kulcsot küldi el egy másik tartalommal, a kérés idempotency_key_reuse hibával elutasításra kerül a csendes elfogadás helyett.
Pénzösszegek sztringként. Az összegek decimális sztringek, nem lebegőpontos számok (float), mivel a lebegőpontos számok olyan módon veszítenek el centeket, amelyek az év végén csúnyán visszaütnek.

Hol helyezkedik el az architekúrában?

Az Ön alkalmazása marad a front-end és az üzleti események forrása. A könyvelési API pedig az mögötte lévő pénzügyi nyilvántartási rendszer (system of record). A folyamat általában így néz ki:

Valami történik a termékében: egy rendelés, egy visszatérítés, egy kifizetés vagy egy előfizetés megújítása.
A háttérrendszere meghívja a könyvelési API-t az eseménnyel és egy idempotencia-kulccsal.
Az API lekönyveli a tételt, alkalmazza az ÁFÁ-t, és visszaadja azokat az azonosítókat, amelyeket a saját nyilvántartásában tárol.
Egy webhook – például a sale_invoice.paid – értesíti a rendszert az állapotváltozásról, így Ön az eseményekre reagál ahelyett, hogy folyamatosan kérdezné (polling) az állapotot.
A banki tranzakciók banki adatáfolyamon (bank feed) vagy kivonatimportáláson keresztül érkeznek meg, és a rendszer egyezteti őket a rögzített dokumentumokkal.
Az időszak végén a riportok és az adóbevallások ugyanezekből az adatokból generálódnak, a lezárt hónap pedig lezárásra kerül.

Ezen a listán semmi sem igényli, hogy egy ember megnyisson egy könyvelőprogramot. Ez a kategória lényege.

Hogyan viszonyul az alternatívákhoz?

Megközelítés	Bevezetési erőfeszítés	Auditpozíció	Skálázhatóság a tranzakciós volumen növekedésével
Táblázatok és kézi rögzítés	Legkisebb	Gyenge; az előzmények szerkeszthetők	Nem
Könyvelőapp plusz CSV-exportok	Alacsony	Teljes mértékben a fegyelmen múlik	Rosszul; valakinek fájlokat kell importálnia
Aggregátor API az egyes ügyfelek saját könyveibe	Közepes	Azt örökli, amit az ügyfél eszköze tud	Igen, de a nyilvántartás soha nincs az Ön tulajdonában
Beágyazott könyvelési API	Közepes	Erős, ha a főkönyv immutálható és az időszakok zárhatók	Igen
Saját főkönyv építése	Legmagasabb	Csak akkor erős, ha a vezérléseket is Ön építi ki	Igen, és örökre karbantartja

Saját rendszer építése bizonyos csapatok számára teljesen racionális döntés. Ezt részletesebben is tárgyaljuk a piactereknek szóló build-versus-buy útmutatónkban.

Mit érdemes ellenőrizni, mielőtt integrálnánk egybe?

Származtatott vagy tárolt az egyenleg? Kérdezze meg, hogy az eladói egyenleg a könyvelési sorok lekérdezése-e, vagy egy olyan oszlop, amelyet valaki frissít. Csak az egyik éli túl a NAV-ellenőrzést.
Mi történik egy újrapróbálkozás (retry) során? Küldje el ugyanazt a kérést kétszer, és számolja meg a tételeket.
Módosítható-e egy már lekönyvelt tétel? A válasz határozott nem kell, hogy legyen, egy dokumentált helyesbítési útvonallal kiegészítve.
A lezárt időszak valóban elutasítja a könyvelést? Tesztelje le egy tesztkörnyezetben (sandbox). A Nordlet a lezárt időszakra eső könyvelési kérésre 409-es hibakódot ad vissza.
Hogyan vannak ábrázolva a pénzösszegek? Decimális sztringekként vagy egész számként a legkisebb egységben (pl. cent). Soha ne lebegőpontos számként (float).
Mi szerepel az auditnaplóban? A végrehajtó (actor), a művelet, az entitás és magának a változásnak a részletei lekérdezhető formában, ahelyett, hogy naplófájlokba lennének temetve.
Mik a rate limit korlátok? A Nordlet percenként 300 kérést engedélyez API-kulcsonként, és a válaszfejlécekben jelzi a fennmaradó keretet. Bármi legyen is ez a szám, ismerje meg, mielőtt megtervezi a szinkronizációt.
Hogyan tudja kinyerni az adatait? Riportok, dokumentumok és naplók olyan formátumban, amelyet átadhat egy könyvelőnek.

Ezek mindegyike letesztelhető egy délután alatt egy tesztcéggel (sandbox company). A gyártói funkciólisták nem bizonyítékok; a reprodukálható teszt az.

FAQ

Ugyanaz a könyvelési API, mint a könyvelőprogram?

Ez egy olyan könyvelőprogram, amelynek az interfésze máshol van. A hagyományos könyvelőprogram egy embert ültet a főkönyv elé; a könyvelési API az Ön kódját ülteti oda. Az alapvető kötelezettségek, a kettős könyvviteli struktúra és a riportok ugyanazok.

Szükségem van még könyvelőre, ha ilyet használok?

Igen. Az API automatizálja a rögzítést, a számítást és a riportkészítést. Nem hoz szakmai döntéseket a besorolásról, a céltartalékokról vagy arról, hogy egy adott szerződést hogyan kell kezelni, és a legtöbb országban nem írja alá vagy küldi be az Ön törvényi előírás szerinti beszámolóját.

Használhatok könyvelési API-t anélkül, hogyérteném a kettős könyvitelt?

Részben. Egy jó API egy olyan üzleti dokumentumból, mint például egy számla, összeállítja Önnek a könyvelési tételeket. Attól függetlenül még értenie kell, hogy mit jelentenek a számlák, amikor elolvas egy riportot, vagy elmagyaráz egy egyenleget egy könyvvizsgálónak.

Mi a különbség a könyvelési API és a főkönyvi API (ledger API) között?

A főkönyvi API egyensúlyban lévő mozgásokat rögzít a számlák között. A könyvelési API ugyanezt teszi, de hozzáadja a jogszabályi réteget is: jogi sorszámozással ellátott dokumentumokat, ÁFA-kezelést, adónyilvántartásokat, tárgyi eszközöket, időszaki zárást és azokat a riportokat, amelyeket egy adott joghatóság elvár. Minden könyvelési API tartalmaz egy főkönyvet, de nem minden főkönyv számít könyvelési rendszernek.

Mennyi ideig tart egy ilyen integráció?

Egy első működő folyamathoz – ügyfél létrehozása, számla kiállítása, fizetés fogadása, a könyvelési tétel megtekintése – egy tipizált SDK-val és egy tesztkörnyezettel számoljon inkább napokkal, mint hetekkel. A visszatérítéseket, helyesbítéseket, többvalutás kezelést, egyeztetést és időszaki zárást lefedő éles integráció már nagyobb feladat, és az őszinte becslés attól függ, hogy a terméke a valóságban hány ilyen esetet generál.