Nordlet

← Blogg

Að smíða bókhalds-API sem stenst úttekt

Hagnýt handbók um það öryggis- og úttektareftirlit sem fjármála-API þarf á að halda áður en hollensk fyrirtæki treysta því fyrir bókhaldi sínu.

Nordlet Team · · 10 mín lesun

Bókhalds-API sem skilar 200 OK á greiðsluskrif segir þér nákvæmlega ekkert. Það hefur hvorki staðfest að höfuðbókið hafi bókað færsluna, að notandinn hafi haft heimild til þess, að upphæðin hafi staðist staðfestingu né að einhver með tilskilin réttindi hafi samþykkt hana. Fyrir fyrirtæki í Hollandi, þar sem skattyfirvöld krefjast þess að hægt sé að endurgera gögn og varðveita þau í sjö ár, er bilið á milli „beiðnin tókst“ og „bókhald er rétt“ staðurinn þar sem úttektir fara úrskeiðis.

Að vera úttektarvænt (audit-ready) er rekstrarlegt hönnunarmarkmið, ekki vottorð. Það þýðir að API-ið viðheldur órofinni keðju: auðkenndur aðili til heimilaðrar aðgerðar, yfirfarið ástandsbreytingar til samþykkis yfir í niðurstöðu höfuðbókar yfir í sönnunargögn sem verja gegn áttum. Allt hér að neðan snýst um að smíða þessa keðju meðvitað í stað þess að gera ráð fyrir að auðkenning og TLS dugi til.

Hvað gerir bókhalds-API „úttektarvænt“

Endurskoðandi sem endurgerir færslu þarf að geta svarað ákveðinni röð spurninga. Hver átti frumkvæðið að henni? Höfðu þeir leyfi til þess? Stóð breytinginstjórnuninst þáttum bókhaldslegri staðfestingu? Hver samþykkti hana? Hvað skráði höfuðbókin? Er hægt að breyta þeirri færslu eftirá án þess að það skilji eftir sig ummerki?

Ef API-ið þitt getur ekki svarað öllum sex spurningum út frá eigin annálum og gagnamódeli, er það ekki úttektarvænt, óháð því hversu hreinn kóðinn lítur út. Flest API ráða vel við fyrstu spurninguna en illa við afganginn.

Eftirlitsaðgerðirnar sem brúa þetta bil skiptast í nokkra hópa: skýrt bókhaldslegt ástand, stigskiptar heimildir, afmarkaða auðkenningu, einskriftarþolna skrif (idempotent writes), staðfestingu meginhluta (server-side validation), aðgreiningu starfa og tamper-evident annála (tamper-evident logging). Þær styrkja hver aðra. Veikar heimildir grafa undan sterkum úttektarannál, þar sem þú getur ekki lengur treyst því að skráði aðili hafi haft eitthvað erindi með að framkvæma aðgerðina.

Módeleraðu bókhaldslegt ástand áður en þarft að módelera endapunkta

Algengasta hönnunarváin er að meðhöndla öll fjárhagsleg gögn sem frjálslega breytanlega hluti (objects) með create, read, update, delete. Bókhald virkar ekki þannig, og endurskoðandi tekur eftir því samstundis ef hægt er að skrifa þegjandi yfir bókaða færslu í dagbók.

Hvert fjárhagslega mikilvægt tilfang (resource) þarf skýra ástandsvél (state machine). Dagbókarfærsla eða greiðsla fer yfirleitt í gegnum eftirfarandi:

draft → submitted → approved → posted → settled

Leiðréttingar spóla ekki þessa leið til baka. Bókuð færsla sem er röng fær tengda endurhvarfsfærslu (reversal) eða jöfnunarfærslu. Upprunalega færslan heldur sér óbreyttri.

Gagnlegar reglur:

  • Drögum (drafts) mábreyta af notendum með heimildir.
  • Færslum sem hefur verið skilað inn má eingöngu breyta af hlutverkum með tilskilin leyfi, eða færa aftur í drög.
  • Samþykktar færslur krefjast stýrðra breytinga og nýrra samþykkis.
  • Ekki er hægt að skrifa yfir eða eyða bókuðum færslum, einungis snúa þeim við eða leiðrétta.
  • Breytingar á lokuðum tímabilum krefjast hærri heimilda, tilgreindrar ástæðu og úttektaratburðar.

Tilraun til ólöglegrar breytingar, svo sem að breyta bókaðri færslu, ætti að skila stöðugri villu og samt skrá úttektaratburð. Mistöku tilraunin er líka sönnunargagn.

Þetta er staðurinn þar sem óbreytanlegt tvíþætt höfuðbók (double-entry ledger) skilar sínu gildi. Höfuðbók Nordlet er hönnuð þannig að hver færsla lendir sem jafnvægi, varanleg færsla, þar sem gagnagrunnsgildra (database trigger) tryggir jafnvægi við vistun (commit), og leiðréttingar eiga sér stað með endurhvarfi frekar en endurskrifum. Sú þvingun finnst takmarkandi í þróun en verður að því sem endurskoðandinn þinn treystir á við úttekt.

Veittu heimildir fyrir hverri beiðni, ekki bara auðkenningu

Auðkenning sýnir hver er að hringja. Hún segir ekkert til um hvort sá sem hringir megi snerta tiltekinn reikning, dagbók eða lögaðila. OWASP API Security Project setur biluð aðgangsheimindi á hlutum (object-level authorization) efst á lista sinn yfir áhættuþætti einmitt vegna þess að API afhjúpa auðkenni hluta sem gera aðgang þvert á leigjendur auðveldan þegar eftirliti er ábótavant.

Hver beiðni til fjárhags-API ætti að hafa tilheyrandi heimildir sem byggjast á samsetningu þátta, en ekki eingöngu á einum auðkenni:

  • auðkenndum aðila
  • viðskiptaforriti eða þjónustureikningi
  • leigjanda (tenant)
  • lögaðila
  • auðkenni tilfangs (resource ID)
  • umbeðinni aðgerð
  • núverandi ástandi tilfangs
  • upphæð eða færsluþröskuldi

Tvær hagnýtar reglur skipta meira máli en aðrar. Í fyrsta lagi skaltu leiða leigjanda- og notendasamhengi út frá auðkenndu kenni og hafna öllum leigjenda- eða hlutverkakröfum sem viðskiptavinur sendir og stangast á við það. Kallaður ætti aldrei að geta fullyrt fyrir hvaða fyrirtæki hann kemur fram. Í öðru lagi skaltu nota neitun að sjálfgefnu (deny-by-default). Ef engin stefna heimilar aðgerð skýrlega, mistekst hún.

Prófaðu báðar áttir. Láréttur aðgangur, þar sem einn leigjandi nær í gögn annars leigjanda, og lóðréttur aðgangur, þar sem venjulegur notandi nær í samþykktar-, bókunar- eða útflutningsaðgerðir. Báðir eru algengir og báðir eru hrikalegir í bókhaldsgögnum.

Hlutverkakerfi Nordlet, með hlutverkum eiganda, stjórnanda (admin), endurskoðanda, framkvæmdastjóra, þróunaraðila og áhorfanda yfir mörg fyrirtæki undir einum reikningi, er til staðar til að gera þessa aðgreiningu framkvæmanlega í stað þess að vera eingöngu von. Þróunarhlutverk sem getur búið til drög að reikningum ætti ekki að geta leyst úr læðingi greiðslur.

Afmarkaðu auðkenni (tokens) við viðskiptaþætti, en ekki CRUD sögn

Fyrir umboðsaðgang skal nota gildandi öryggisleiðbeiningar fyrir OAuth 2.0 í stað endurnýtanlegra lykilorða eða víðtækra kyrrstæðra API-lykla. RFC 9700 er núverandi besta starfsvenja (Best Current Practice) og setur skýrar kröfur fyrir viðskiptavini og auðkenningarþjóna: staðfestar endursendislóðir (redirect URIs), PKCE þar sem við á, athuganir á útgefanda og áhorfendum (issuer/audience checks), stuttan líftíma aðgangskenni (access-tokens) og endurnýjun auðkenna (refresh-token rotation) ásamt afturköllun.

Ákvörðun um afmörkun (scoping) er þar sem bókhaldssértæk hugsun birtist. Almenn afmörk eins og read og write eru nánast gagnslaus til að aðgreina störf. Afmörk ættu að samræmast getu:

  • journal:create og journal:approve eru aðskilin afmörk.
  • Að búa til greiðslufyrirmæli veitir ekki leyfi til að leysa þau úr læðingi.
  • Útflutningsleyfi er aðskilið frá lestrarleyfi, þar sem fjöldaútflutningur er leið til gagnaleka.

Vertu nákvæmur um hvar tiltekin vara stendur á þeim kvarða. API-lyklar Nordlet hafa afmörk eftir einingum eins og sales:read og sales:write, sem eru yfirfarnar við hverja aðgerð, sem aðskilur einingar og les frá skrifum en ekki búna til frá samþykki; þar sem þú þarft þá nákvæmari skiptingu í dag skaltu framfylgja henni í þinni eigin þjónustu á undan kallinu.

Fyrir verðmætar aðgerðir er þess virði að meta hvort FAPI 2.0 Security Profile eigi við. Hún var hönnuð fyrir API sem vernda viðkvæm fjárhagsgögn og býður upp á sterkari tryggingar en grunnur OAuth. Flestar samþættingar fyrir lítil og meðalstór fyrirtæki þurfa ekki alla prófílinn, en greiðsluflæði og bankatengingar eru staðirnir til að íhuga hann.

Lykilorðalaus innskráning Nordlet í gegnum einnota tölvupósttengla fjarlægir vandamálið með endurnýtanleg lykilorð fyrir mannlega notendur, sem er einu skilríki færri til að snúa, leka eða verða fyrir veiðum.

Gerðu fjárhagsleg skrif einskriftarþoln (idempotent)

Netkerfi bregðast miðri beiðni. Viðskiptavinur sendir greiðslufyrirmæli, tengingin rofnar áður en svarið berst og viðskiptavinurinn reynir aftur. Án verndar ertu núna með tvær greiðslur.

Einskriftarlyklar (idempotency keys) leysa þetta. Viðskiptavinurinn sendir einstakan lykil með hverju skrift; netþjónninn skráir lykilinn og niðurstöðu hans. Endurtekning með sama lykli skilar upprunalegu niðurstöðunni í stað þess að búa til aðra færslu. Nordlet samþykkir Idempotency-Key haus á öllum breytingaköllum, spilar geymda svarið aftur við endurtekningu með sama nytgögnum (payload) og synjar sama lykli með breyttum nytgögnum, og öll bókhalds-API sem sleppa þessu atriði munu á endanum framleiða tvíteknar höfuðbókarfærslur sem einhver þarf að flækja úr í höndunum.

Paraðu þetta við staðfestingu meginhluta. Treystu aldrei viðskiptavininum til að athuga að debet jafni kredet, að VSK-hlutfall sé gilt fyrir landið og tímabilið, eða að reikningur sé til. Staðfesting fer fram á netþjóninum, áður en ástandinu er breytt, og hafnað skrif skilar stöðugri villu og úttektaratburði.

Úttektarvænir og viðvarandi annálar og hollensk varðveisla

Úttektarannállinn er sönnunargagnalagið og hann hefur aðrar kröfur en venjuleg viðskiptagögn. Hann ætti að skrá ákvörðun um heimildir, útgáfu stefnu, aðila, hlut, aðgerð, fyrri og nýja stöðu og ástæðukóða, án þess nokkurn tíma að skrá leyniorð eða fullar greiðsluskilríki.

Gagnlegi eiginleikinn er vernd gegn áttum (tamper-evidence). Ef stjórnandi getur hljótt breytt eða eytt úttektarskrám sannar annállinn ekkert. Viðbætingarsafn (append-only storage), dulkóðuð keðja (cryptographic chaining) eða geymsla sem skrifast einu sinni (write-once retention) taka öll á þessu. Málið er að breyting ætti að vera greinanleg.

Varðveisla á skilið sína eigin stefnu, aðskilda frá eyðingu viðskiptagagna. Í Hollandi er almennur varðslutími stjórnsýslugagna sjö ár, og fyrir gögn sem tengjast fasteignum nær hann upp í tíu ár. Venjuleg gagnatæmingar- og GDPR-eyðingarferlar þínir mega ekki geta eyðilagt gögn eða úttektarsönnun sem lagaleg varðslut regla nær enn yfir. Skilgreindu lögmætan geymslustað, skjalageymslu og eyðingarreglur fyrir úttektarsönnun sjálfstætt og kortleggðu þær í þau lögsagnarumdæmi sem þú starfar í.

Tímabilalæsing (period locking) styður þetta á bókhaldslaginu. Þegar mánuði er lokað er ekki hægt að breyta færslum í honum án hækkaðra heimilda og skráðrar ástæðu. Nordlet framfylgir tímabilalæsingu þannig að lokaðir mánuðir haldist lokaðir, og hafnar öllum bókunum sem dagsettar eru innan lokaðs tímabils jafnvel í gegnum API, sem er einn af fyrstu hlutum sem hollenskur endurskoðandi skoðar.

Tryggðu brúnirnar: vefboð (webhooks), útflutning og samþættingar

Kjarna-API-ið er venjulega best verndaði hluti kerfisins. Brúnirnar leka.

Vefboð eru áhætta vegna fölsuðra beiðna. Atburður eins og sale_invoice.paid ætti að vera undirritaður þannig að viðtakandinn geti staðfest að hann kom frá þér, og móttakendur ættu að meðhöndla afhendingu sem amk-einu-sinni (at-least-once) og nota atburðarauðkennið til afritunar (deduplication). Nordlet undirritar hverja vefboðsafhendingu með HMAC-undirritun yfir hráan meginhluta og reynir aftur mistakta afhendingu með vaxandi biðtíma (exponential backoff), þannig að móttakandi þarf að staðfesta undirritunina og útrýma tvíteknum eftir atburðarauðkenni í stað þess að gera ráð fyrir nákvæmlega-einni-afhendingu.

Útflutningur er leið til magnleka á gögnum. Skýrsluútflutningur í XLSX, PDF eða JSON sækir mikið magn fjárhagsgagna í einni aðgerð, þannig að hann þarf sínar eigin heimildir, taxtatakmarkanir (rate limits) og úttektarskráningu. Samþættingar þriðju aðila sem þú notar ætti að meðhöndla sem ótreyst inntak, staðfestar á sama hátt og þú staðfestir beinar beiðnir viðskiptavina.

Gátlisti fyrir úttektarvæni hollensks bókhalds-API

Notaðu þetta áður en þú heldur því fram að samþætting sé úttektarvænt:

  • Skýr ástandsvél á hverju fjárhagslegu tilfangi; ekki er hægt að skrifa yfir bókfærðar færslur
  • Heimildir á hlut- og lögaðilastigi við hverja beiðni, neitun að sjálfgefnu
  • Leigjanda- og hlutverkasamhengi leitt af skilríkjum, ekki kröfum viðskiptavinar
  • OAuth 2.0 samkvæmt RFC 9700; getumiðaðir afmörk; aðskilinn stofn og samþykki
  • Aðgreining starfa framfylgt í hlutverkum, ekki bara skjalfest
  • Einskriftarlyklar á öllum fjárhagslegum skrifum
  • Bókhalds- og VSK-staðfesting meginhluta áður en ástandi er breytt
  • Aðeins-viðbætingar, úttektarannáll sem ver gegn áttum með ástæðukóðum
  • Varðveislu- og lögbannstreglur kortlagðar á hollensk tímabil (sjö ár, tíu fyrir fasteignir)
  • Tímabilalæsing á lokuðum mánuðum
  • Undirrituð vefboð með afritunarhreinsun; afmörkuð, taxtatakmörkuð, skráð útflutningur

Hvað við myndum byggja fyrst

Ef við værum að samþætta bókhald í hollenskan vettvang á morgun, myndum við byrja á ástandslíkaninu og heimildum á hlutastigi, áður en við skrifuðum einn einasta viðskiptaendapunkt. Þær tvær ákvarðanir þvinga allt annað sem á eftir kemur, og að setja þetta inn afturvirkt í kerfi sem meðhöndlaði höfuðbókarfærslur sem breytanlegar raðir er sannarlega sárt. Einskrift og úttektarannáll koma næst, því þær eru ódýrar í upphafi og dýrar eftir að gögnin eru farin að flæða.

Afgangurinn – afmörkuð skilríki, undirrituð vefboð, tímabilalæsing – fylgir auðveldara þegar grunnurinn heldur. Allt þetta er hægt að prófa gegn sandkassafyrirtæki áður en eitthvað af því snertir framleiðslugögn.

FAQ

Þýðir úttektarvænt API að fyrirtækið sé í samræmi við lög?

Nei, og það er þess virði að vera nákvæmur um þetta. Úttektarvæni er hönnunareiginleiki kerfisins: höfuðbókin, eftirlit og sönnunargagnakeðjan eru smíðuð þannig að úttekt geti heppnast. Samræmi við tiltekið skatta-, bókhalds- eða öryggiskerfi er sérstakt mat sem kortleggur þetta eftirlit við nefndan staðal. Vel hannað API gerir samræmisvinnu auðveldari; það kemur ekki í staðinn fyrir hana.

Hve lengi þarf að varðveita bókhaldsgögn í Hollandi?

Almenna skyldan er sjö ár fyrir stjórnsýslugögn, og nær til tíu ára fyrir gögn sem tengjast fasteignum. Byggðu upp varðveislu- og lögbannsreglur sem venjuleg eyðingarferli þín geta ekki hnekkt.

Er kyrrstæður API-lykill nóg fyrir fjárhagslega samþættingar?

Fyrir sjálfvirkni milli netþjóna með þröngt afmörk getur það virkað, en endurnýtanlegir kyrrstæðir lyklar eru erfiðir í snúningi og hættulegum þegar þeir leka. Fyrir umboðsaðgang og hvers kyns flæði sem snýr að mönnum er OAuth 2.0 með stuttum, getumiðuðum skilríkjum sterkari kosturinn.

Af hverju skiptir einskrift svo miklu máli fyrir bókhald sérstaklega?

Vegna þess að tvítekið skrif í flestum kerfum er óþægindi, og tvítekið skrif í bókhaldi er röng tala í bókum sem einhver þarf að finna og snúa við. Einskriftarlyklar gera endurtekningar öruggar í stað þess að vera áhættusamar.

Frekari lestur