Olyan számviteli API építése, amely túléli a pénzügyi ellenőrzést

Egy számviteli API, amely egy fizetési műveletre 200 OK választ ad, szinte semmit sem mond önnek. Nem erősítette meg, hogy a főkönyv rögzítette a tételt, hogy a végrehajtó jogosult volt rá, hogy az összeg megfelelt a validációnak, vagy hogy bárki illetékes jóváhagyta volna. A hollandiai vállalkozások esetében, ahol az adóhatóság elvárja a nyilvántartások visszakövethetőségét és hét évig történő megőrzését, a „kérés sikeres volt” és „a könyvek helyesek” közötti rés az a pont, ahol az ellenőrzések félresiklanak.

Az ellenőrzésre kész (audit-ready) állapot operatív tervezési cél, nem pedig tanúsítvány. Azt jelenti, hogy az API fenntart egy teljes láncot: hitelesített szereplő -> felhatalmazott művelet -> validált állapottanúsítvány -> jóváhagyás -> főkönyvi eredmény -> hamisíthatatlan bizonyíték. Az alábbiakban mindezeknek a láncszemeknek a szándékos felépítéséről lesz szó, ahelyett, hogy feltételeznénk, a hitelesítés és a TLS magától megoldja ezeket.

Mitől lesz egy számviteli API „ellenőrzésre kész”?

Egy tranzakciót visszakövető könyvvizsgálónak egy adott kérdéssorra kell válaszolnia. Ki kezdeményezte? Jogosult volt rá? Átment a változás a számviteli validáción? Ki hagyta jóvá? Mit rögzített a főkönyv? Módosítható-e az a rekord utólag anélkül, hogy nyomot hagyna?

Ha az API a saját naplóiból és adatmodelljéből nem tud mind a hat kérdésre válaszolni, akkor nem ellenőrzésre kész, függetlenül attól, hogy a kód milyen tiszta. A legtöbb API az első kérdést jól kezeli, a többit viszont gyengén.

A hézagot betömő vezérlők néhány csoportba sorolhatók: explicit számviteli állapotok, rétegzett felhatalmazás, hatáskörhöz kötött hitelesítés, idempotens írások, szerver oldali validáció, a feladatok szétválasztása (segregation of duties), valamint hamisíthatatlan naplózás. Ezek erősítik egymást. A gyenge felhatalmazás aláásza az erős auditnaplót, mivel többé nem bízhat abban, hogy a naplózott szereplőnek bármi keresnivalója volt a művelet elvégzésében.

Számviteli állapotok modellezése az végpontok modellezése előtt

A leggyakoribb tervezési hiba az, ha minden pénzügyi rekordot szabadon szerkeszthető objektumként kezelnek create, read, update, delete műveletekkel. A számvitel nem így működik, és egy könyvvizsgáló azonnal észreveszi, ha egy könyvelt vegyes bizonylat (journal entry) csendben felülírható.

Minden pénzügyileg lényeges erőforrásnak explicit állapotszámmal (state machine) kell rendelkeznie. Egy vegyes bizonylat vagy kifizetés tipikusan a következő utat járja be:

draft → submitted → approved → posted → settled

A helyesbítések nem tekerik vissza ezt az utat. A rosszul rögzített bejegyzés egy kapcsolódó sztornót vagy kompenzáló kiigazítást kap. Az eredeti sértetlen marad.

Egy működőképes szabállykészlet:

• A tervezeteket (draft) a jogosult felhasználók szerkeszthetik.
• A benyújtott rekordokat csak a megengedett szerepkörök szerkeszthetik, vagy visszaküldhetik tervezetbe.
• A jóváhagyott rekordok ellenőrzött módosítást és újbóli jóváhagyást igényelnek.
• A könyvelt rekordok nem írhatók felül és nem törölhetők, csak sztornírozhatók vagy kiigazíthatók.
• A lezárt időszaki módosítások emelt szintű felhatalmazást, megindokolt okot és audit eseményt igényelnek.

Egy jogellenes átmenet megkísérlésének, például egy könyvelt tétel szerkesztésének, stabil hibát kell visszaadnia, miközben naplóbejegyzést is ír. A sikertelen kísérlet ugyancsak bizonyíték.

Itt érdemli ki a helyét a megmásíthatatlan kettős könyvvitelű főkönyv. A Nordlet főkönyve úgy van felépítve, hogy minden tranzakció kiegyensúlyozott, állandó tételként érkezik be, az egyenleget pedig a véglegesítés pillanatában egy adatbázis-trigger kényszeríti ki, a helyesbítések pedig átírás helyett sztornírozással történnek. Ez a megkötés a fejlesztés során korlátozónak tűnik, az audit alatt viszont azzá válik, amiben a könyvelője bízni fog.

Minden kérés engedélyezése, ne csak a hitelesítése

A hitelesítés azt bizonyítja, hogy ki hívja a rendszert. Azt viszont nem mondja meg, hogy az illető nyúlhat-e egy adott számlához, naplóhoz vagy jogi személyhez. Az OWASP API Security Project azért helyezi a törött objektumszintű felhatalmazást a kockázati listája élére, mert az API-k olyan objektumazonosítókat tesznek közzé, amelyek hiányzó ellenőrzések esetén megkönnyítik a bérlők közötti (cross-tenant) hozzáférést.

A pénzügyi API-ra érkező minden kérést tényezők kombinációja alapján kell felhatalmazni, nem csupán egy token alapján:

• hitelesített szereplő
• kliensalkalmazás vagy szolgáltatásfiók
• bérlő (tenant)
• jogi személy
• erőforrás-azonosító
• kért művelet
• aktuális erőforrás-állapot
• összeg vagy tranzakciós küszöbérték

Két gyakorlati szabály fontosabb, mint a többi. Először is, a bérlő és a felhasználó kontextusát a hitelesített identitásból kell levezetni, és el kell utasítani minden olyan, a kliens által megadott bérlőre vagy szerepkörre vonatkozó állítást (claim), amely ellentmond ennek. A hívó soha nem állapíthatja meg saját maga, hogy melyik cég nevében jár el. Másodszor, alkalmazza az alapértelmezett tiltás (deny-by-default) elvét. Ha egyetlen szabályzat sem engedélyezi explicit módon a műveletet, akkor az meghiúsul.

Tesztelje mindkét irányt. A horizontális hozzáférést, amikor az egyik bérlő eléri a másik bérlő adatait, és a vertikális hozzáférést, amikor egy átlagos felhasználó eléri a jóváhagyási, könyvelési vagy exportálási funkciókat. Mindkét eset gyakori, és mindkettő katasztrofális a számviteli adatok szempontjából.

A Nordlet szerepkör-modellje – amely a tulajdonos, adminisztrátor, könyvelő, menedzser, fejlesztő és olvasó szerepköröket biztosítja egy fiókon belüli több cég számára – azért létezik, hogy ez a szétválasztás kikényszeríthető legyen ahelyett, hogy csak elméleti vágy maradna. Egy olyan fejlesztői szerepkör, amely tervezet számlákat hozhat létre, nem engedélyezheti a kifizetések kiadását.

Hatáskörökön alapuló tokenek használata CRUD igék helyett

Delegált hozzáférés esetén a többször felhasználható jelszavak vagy a széles körű statikus API-kulcsok helyett az aktuális OAuth 2.0 biztonsági útmutatást kell követni. Az RFC 9700 az aktuális iparági legjobb gyakorlat (Best Current Practice), amely egyértelmű követelményeket támaszt a kliensekkel és az engedélyezési szerverekkel szemben: érvényesített átirányítási URI-k, PKCE alkalmazása ahol szükséges, kibocsátó és közönség (audience) ellenőrzése, rövid hozzáférési token-élettartam, valamint a frissítési tokenek (refresh token) rotációja visszavonással.

A hatáskörök (scopes) meghatározása az a pont, ahol a számvitel-specifikus gondolkodás megmutatkozik. Az olyan általános hatáskörök, mint a read és a write, gyakorlatilag haszontalanok a feladatok szétválasztásához. A hatásköröknek képességekhez kell igazodniuk:

• A journal:create és a journal:approve külön hatáskörök.
• A fizetési utasítás létrehozása nem ad felhatalmazást annak kiutalására.
• Az exportálási engedély eltér az olvasási engedélytől, mivel a tömeges exportálás adat-kiszivárgási útvonal.

Legyen pontos abban, hogy egy adott termék hol helyezkedik el ezen a skálán. A Nordlet API-kulcsai olyan modulonkénti hatásköröket hordoznak, mint a sales:read és a sales:write, amelyeket minden műveletnél ellenőriz a rendszer; ez elválasztja a modulokat, valamint az olvasást az írástól, de nem választja el a létrehozást a jóváhagyástól – ahol ma erre a finomabb megosztásra van szüksége, azt a hívás előtt a saját szolgáltatásában kell kikényszerítenie.

Nagy értékű műveletek esetén érdemes felmérni, hogy a FAPI 2.0 Security Profile alkalmazható-e. Ezt kifejezetten az érzékeny pénzügyi adatokat védő API-k számára tervezték, és az alapszintű OAuth-nál erősebb garanciákat nyújt. A legtöbb KKV számviteli integrációnak nem lesz szüksége a teljes profilra, de a kifizetés-kiutalási és a bankkapcsolati folyamatok azok a területek, ahol érdemes megfontolni.

A Nordlet jelszómentes bejelentkezése egyszer használatos e-mailes linkeken keresztül megszünteti a humán felhasználók számára fennálló újra felhasználható jelszó problémáját, ami egyel kevesebb hitelesítő adatot jelent, amelyet forgatni, kiszivárogtatni vagy adathalászattal megszerezni lehetne.

Pénzügyi írások idempotenssé tétele

A hálózatok a kérés közben is meghibásodhatnak. A kliens elküld egy fizetési utasítást, a kapcsolat megszakad a válasz megérkezése előtt, a kliens pedig újrapróbálkozik. Védelem nélkül most már két kifizetése van.

Az idempotencia-kulcsok (idempotency keys) ezt oldják meg. A kliens minden írási művelettel egyedi kulcsot küld; a szerver rögzíti a kulcsot és annak eredményét. Az azonos kulcsú újrapróbálkozás az eredeti eredményt adja vissza a második bejegyzés létrehozása helyett. A Nordlet minden módosító hívásnál elfogadja az Idempotency-Key fejezetet (header), azonos hasznos teherrel (payload) történő újrapróbálkozáskor visszajátssza a tárolt választ, míg a megváltozott hasznos teherrel érkező azonos kulcsot elutasítja – és bármely számviteli API, amely kihagyja ezt a funkciót, előbb-utóbb olyan duplikált főkönyvi tételeket fog előállítani, amelyeket valakinek kézzel kell bogarásznia.

Párosítsa ezt a szerver oldali validációval. Soha ne bízza a kliensre annak ellenőrzését, hogy a tartozik egyenlő-e a követellel, hogy az ÁFA-kulcs érvényes-e az országra és az időszakra, vagy hogy létezik-e a számlaszám. A validáció a szerveren fut, az állapotváltás előtt, az elutasított írás pedig stabil hibát és audit rekordot eredményez.

Hamisíthatatlan auditnaplók és holland megőrzési szabályok

Az auditnapló a bizonyítékok rétege, és más követelményeket támaszt, mint a szokásos üzleti adatok. Rögzítenie kell a felhatalmazási döntést, a szabályzat verzióját, a szereplőt, az objektumot, a műveletet, az előző és az új állapotot, valamint az okkódot (reason code), anélkül hogy titkos adatokat vagy teljes fizetési hitelesítő adatokat rögzítene.

A kritikus tulajdonság a hamisíthatatlanság. Ha egy adminisztrátor csendben szerkesztheti vagy törölheti az auditnaplókat, akkor a napló semmit sem bizonyít. A csak hozzáfűzhető (append-only) tárolás, a kriptográfiai láncolás vagy a egyszer írható megőrzés (WORM) mind ezt a célt szolgálják. A lényeg az, hogy a módosításnak észlelhetőnek kell lennie.

A megőrzés külön szabályzatot érdemel, elválasztva az üzleti adatok törlésétől. Hollandiában a közigazgatási és számviteli nyilvántartások általános megőrzési ideje hét év, az ingatlanokhoz kapcsolódó nyilvántartások esetében pedig tíz év. A szokásos adatkezelési és GDPR-törlési munkafolyamatok nem tehetik lehetővé olyan rekordok vagy auditbizonyítékok megsemmisítését, amelyekre még kiterjed a jogi megőrzési szabály. Határozza meg függetlenül a jogi zárolási (legal hold), archiválási és törlési szabályokat az auditbizonyítékokra vonatkozóan, és képezze le ezeket azokra a joghatóságokra, amelyekben működik.

Az időszaki zárolás (period locking) ezt a számviteli rétegen támogatja. Amint egy hónap lezárul, az abban lévő tételek nem változtathatók meg emelt szintű felhatalmazás és naplózott indoklás nélkül. A Nordlet érvényesíti az időszaki zárolást, így a lezárt hónapok lezárva maradnak, elutasítva a zárolt időszakon belüli dátummal ellátott könyveléseket még az API-n keresztül is, ami az egyik első dolog, amit egy holland könyvvizsgáló ellenőrzéskor megnéz.

A szélek védelme: webhookok, exportok és integrációk

Az alap-API általában a rendszer legjobban védett része. A szélek szivárognak.

A webhookok hamisított kérések kockázatát hordozzák. Az olyan eseményeket, mint a sale_invoice.paid, alá kell írni, hogy a címzett ellenőrizhesse, hogy valóban öntől származik-e, a címzetteknek pedig a kézbesítést legalább egyszeri alkalomként (at-least-once) kell kezelniük, és az eseményazonosítót kell használniuk a duplikációk kiszűrésére. A Nordlet minden webhook-kézbesítést HMAC-aláírással lát el a nyers törzs (raw body) felett, és exponenciális hátralékkal (exponential backoff) próbálja újra a sikertelen kézbesítéseket, így a címzettnek ellenőriznie kell az aláírást és az eseményazonosító alapján deduplikálnia kell ahelyett, hogy pontosan egyszeri kézbesítést (exactly-once) feltételezne.

Az exportálások tömeges adat-kiszivárgási útvonalat jelentenek. A XLSX, PDF vagy JSON formátumú jelentésexportok egyetlen művelettel nagy mennyiségű pénzügyi adatot töltenek le, ezért saját engedélyt, sebességkorlátozást (rate limit) és auditnaplózást igényelnek. Az Ön által felhasznált harmadik féltől származó integrációkat megbízratlan bemenetként kell kezelni, és ugyanúgy kell validálni, mint a közvetlen klienskéréseket.

Ellenőrzés-készségi ellenőrzőlista holland számviteli API-hoz

Használja ezt mielőtt kijelenti, hogy egy integráció ellenőrzésre kész:

• Explicit állapotszám minden pénzügyi erőforráson; a könyvelt tételek nem írhatók felül
• Objektumszintű és jogi személy szerinti felhatalmazás minden kérésnél, alapértelmezett tiltással
• Bérlő és szerepkör kontextus levezetése a tokenből, nem a kliens állításaiból
• OAuth 2.0 az RFC 9700 szerint; képességalapú hatáskörök; külön létrehozás és jóváhagyás
• A feladatok szétválasztásának kikényszerítése a szerepkörökben, nem csupán dokumentációban
• Idempotencia-kulcsok minden pénzügyi íráson
• Szerver oldali számviteli és ÁFA validáció az állapotváltások előtt
• Csak hozzáfűzhető, hamisíthatatlan auditnapló okkódokkal
• Megőrzési és jogi zárolási szabályok leképezve a holland időszakokra (hét év, ingatlanoknál tíz)
• Időszaki zárolás a lezárt hónapokra
• Aláírt webhookok deduplikációval; hatáskörhöz kötött, sebességkorlátozott, naplózott exportok

Mit építenénk meg először?

Ha holnap építenénk be a számvitelt egy holland platformba, az állapotmodellel és az objektumszintű felhatalmazással kezdenénk, mielőtt egyetlen üzleti végpontot is megírnánk. Ez a két döntés korlátozza minden lefelé irányuló folyamatot, és utólag visszamenőleg beépíteni őket egy olyan rendszerbe, amely a főkönyvi tételeket szerkeszthető sorokként kezelte, őszintén szólva fájdalmas. Az idempotencia és az auditnapló következik ezután, mivel ezeket olcsó korán hozzáadni és drága az adatok áramlása után beépíteni.

A többi – a hatáskörhöz kötött tokenek, az aláírt webhookok, az időszaki zárolás – könnyebben következik, miután az alapok szilárdan állnak. Mindez tesztelhető egy sandbox céggel, mielőtt bármi éles adathoz érne.

FAQ

Jelenti-e egy ellenőrzésre kész API, hogy a vállalkozás megfelel a jogszabályoknak?

Nem, és érdemes ebben pontosnak lenni. Az ellenőrzésre készség a rendszer tervezési tulajdonsága: a főkönyv, a vezérlők és a bizonyítéklánc úgy van felépítve, hogy a vizsgálat sikeres lehessen. Az adóügyi, számviteli vagy biztonsági keretrendszernek való megfelelés egy külön értékelés, amely ezeket a vezérlőket egy nevesített szabványhoz képezi le. A jól felépített API megkönnyíti a megfelelést, de nem helyettesíti azt.

Mennyi ideig kell megőrizni a számviteli bizonylatokat Hollandiában?

Az általános kötelezettség hét év a közigazgatási nyilvántartások esetében, ami tíz évre terjed ki az ingatlanokhoz kötődő nyilvántartásoknál. Olyan megőrzési és jogi zárolási szabályokat építsen ki, amelyeket a szokásos törlési munkafolyamatok nem tudnak felülírni.

Elegendő-e egy statikus API-kulcs a pénzügyi integrációhoz?

Szűk körű szerver-szerver automatizáláshoz működhet, de az újra felhasználható statikus kulcsokat nehéz forgatni, és kiszivárgásuk veszélyes. Delegált hozzáféréshez és bármilyen humán interakciót igénylő folyamathoz a rövid élettartamú, hatáskörhöz kötött tokeneket használó OAuth 2.0 a jobb választás.

Miért olyan fontos az idempotencia kifejezetten a számvitelben?

Mivel a duplikált írás a legtöbb rendszerben kellemetlenség, a számvitelben viszont egy hibás összeg a könyvekben, amelyet valakinek meg kell találnia és helyesbítenie kell. Az idempotencia-kulcsok kockázatmentessé teszik az újrapróbálkozásokat.

További olvasnivalók

• OWASP API Security Project az aktuális API kockázati kategóriákhoz
• RFC 9700: OAuth 2.0 Security Best Current Practice a delegált hozzáférési követelményekhez
• Valós idejű uniós ÁFA fejlesztőknek Hollandiában a holland adózási környezetről a gyakorlatban
• API konvenciók a hatáskörökről, az idempotenciáról, a hibákról és a webhook-aláírásról