Nordlet

← Blog

Dezvoltarea unui API de contabilitate care supraviețuiește unui audit

Un ghid practic privind securitatea și controalele de audit de care are nevoie un API financiar înainte ca întreprinderile olandeze să îi încredințeze propriile registre contabile.

Nordlet Team · · 12 min de citire

Un API de contabilitate care returnează codul 200 OK la înregistrarea unei plăți nu v-a spus aproape nimic. Nu a confirmat că registrul a înregistrat intrarea, că actorul a fost autorizat să o efectueze, că suma a trecut de validare sau că o persoană cu autoritate a aprobat-o. Pentru companiile din Țările de Jos, unde autoritatea fiscală se așteaptă ca înregistrările să fie reconstructibile și păstrate timp de șapte ani, acea prăpastie dintre „cererea a reușit” și „registrele sunt corecte” reprezintă locul unde auditurile eșuează.

Pregătirea pentru audit (audit-ready) este un obiectiv de proiectare operațională, nu un certificat. Aceasta înseamnă că API-ul păstrează unlanț complet: de la actorul autentificat la acțiunea autorizată, modificarea validată a stării, aprobare, rezultatul din registru și până la dovezile rezistente la manipulare. Tot ce urmează se referă la construirea deliberată a acestui lanț, în loc să presupunem că autentificarea și protocolul TLS sunt suficiente.

Ce face ca un API de contabilitate să fie „pregătit pentru audit”

Un auditor care reconstruiește o tranzacție trebuie să răspundă unei secvențe specifice de întrebări. Cine a inițiat-o? Aveau permisiunea de a o face? A trecut modificare de validarea contabilă? Cine a aprobat-o? Ce a înregistrat registrul? Poate fi acea înregistrare alterată retroactiv fără a lăsa vreo urmă?

Dacă API-ul dumneavoastră nu poate răspunde la toate cele șase întrebări pe baza propriilor jurnale și modele de date, atunci el nu este pregătit pentru audit, indiferent cât de curat arată codul. Majoritatea API-urilor gestionează bine prima întrebare și slab pe celelalte.

Controalele care reduc această discrepanță se împart în câteva categorii: starea contabilă explicită, autorizarea stratificată, autentificarea cu domeniu de aplicare delimitat (scoped), scrierile Idempotente (idempotent writes), validarea pe partea de server, separarea atribuțiilor și jurnalele rezistente la manipulare (tamper-evident logging). Acestea se susțin reciproc. O autorizare slabă subminează un jurnal de audit puternic, deoarece nu mai puteți avea încredere că actorul înregistrat avea vreo treabă să efectueze acțiunea respectivă.

Modelați stările contabile înainte de a modela punctele finale (endpoints)

Cea mai frecventă greșeală de proiectare este tratarea fiecărei înregistrări financiare ca pe un obiect ușor de editat cu ajutorul operațiunilor create, read, update, delete. Contabilitatea nu funcționează așa, iar un auditor va observa imediat dacă o înregistrare jurnalistică postată poate fi suprascrisă în tăcere.

Fiecare resursă materială din punct de vedere financiar are nevoie de o mașină de stări explicită (state machine). O înregistrare în jurnal sau o plată parcurge de obicei etapele:

draft → submitted → approved → posted → settled

Corecțiile nu derulează această cale înapoi. O înregistrare postată care este greșită primește o stornare asociată sau o ajustare compensatorie. Originalul rămâne intact.

Un set viabil de reguli:

  • Ciornele (drafts) pot fi editate de utilizatorii autorizați.
  • Înregistrările trimise pot fi editate doar de rolurile permise sau pot fi returnate la stadiul de ciornă.
  • Înregistrările aprobate necesită o modificare controlată și o nouă aprobare.
  • Înregistrările postate nu pot fi suprascrise sau șterse, ci doar stornate sau ajustate.
  • Modificările pentru perioadele închise necesită o autorizare superioară, un motiv specificat și un eveniment de audit.

O încercare de tranziție ilegală, cum ar fi editarea unei înregistrări postate, ar trebui să returneze o eroare stabilă și să scrie totuși o înregistrare de audit. Tentativa eșuată reprezintă, de asemenea, o dovadă.

Aici își câștigă meritul un registru imuabil în partidă dublă. Registrul Nordlet (/en/features/) este conceput astfel încât fiecare tranzacție să ajungă ca o înregistrare echilibrată și permanentă, echilibrul fiind impus de un declanșator al bazei de date (database trigger) în momentul confirmării (commit), iar corecțiile realizându-se prin stornări, nu prin rescrieri. Această constrângere pare restrictivă în timpul dezvoltării și se transformă în aspectul în care contabilul dumneavoastră are încredere în timpul unui audit.

Autorizați fiecare cerere, nu doar o autentificați

Autentificarea dovedește cine efectuează apelul. Nu spune nimic despre posibilitatea ca acel apelant să acceseze o anumită factură, un anumit jurnal sau o entitate juridică anume. Proiectul de securitate API OWASP (OWASP API Security Project) plasează autorizarea deficitară la nivel de obiect în fruntea listei sale de riscuri tocmai pentru că API-urile expun identificatori de obiecte care facilitează accesul între chiriași (cross-tenant) atunci când lipsesc verificările.

Fiecare cerere către un API financiar ar trebui să fie autorizată pe baza unei combinații de factori, nu doar a unui token:

  • actorul autentificat
  • aplicația client sau contul de servicii
  • chiriașul (tenant)
  • entitatea juridică
  • ID-ul resursei
  • operațiunea solicitată
  • starea curentă a resursei
  • suma sau pragul tranzacției

Două reguli practice contează mai mult decât restul. În primul rând, deduceți contextul chiriașului și al utilizatorului din identitatea autentificată și respingeți orice revendicare (claim) de rol sau chiriaș furnizată de client care intră în conflict cu aceasta. Un apelant nu ar trebui să poată susține niciodată în numele cărei companii acționează. În al doilea rând, aplicați principiul refuzului implicit (deny-by-default). Dacă nicio politică nu acordă în mod explicit o acțiune, aceasta eșuează.

Testați ambele direcții. Accesul orizontal, în care un chiriaș accesează datele altui chiriaș, și accesul vertical, în care un utilizator obișnuit accesează funcții de aprobare, postare sau export. Ambele sunt frecvente și ambele sunt catastrofale în datele contabile.

Modelul de roluri al Nordlet, care include rolurile de proprietar (owner), administrator (admin), contabil (accountant), manager, dezvoltator (developer) și vizualizator (viewer) în mai multe companii sub un singur cont, există pentru a face această separație aplicabilă, mai degrabă decât dezirabilă la nivel teoretic. Un rol de dezvoltator care poate crea ciorne de facturi nu ar trebui să poată elibera plăți.

Delimitați tokenurile la capabilități de business, nu la verbe CRUD

Pentru accesul delegat, utilizați recomandările actuale de securitate OAuth 2.0, în loc de parole reutilizabile sau chei API statice extinse. RFC 9700 reprezintă standardul actual privind cele mai bune practici (Best Current Practice) și stabilește cerințe clare pentru clienți și servere de autorizare: URI-uri de redirecționare validate, PKCE acolo unde este cazul, verificări ale emitentului și ale destinatarului, durate de viață scurte pentru tokenurile de acces și rotirea tokenurilor de reîmprospătare (refresh-token) cu revocare.

Decizia de delimitare (scoping) este momentul în care gândirea specifică domeniului contabil iese în evidență. Domeniile de aplicare generice, cum ar fi read și write, sunt aproape inutile pentru separarea atribuțiilor. Domeniile de aplicare ar trebui să corespundă capabilităților:

  • journal:create și journal:approve sunt domenii separate.
  • Crearea unei instrucțiuni de plată nu acordă permisiunea de a o elibera.
  • Permisiunea de export este distinctă de permisiunea de citire, deoarece exportul în masă reprezintă o cale de scurgere a datelor.

Fiți preciși cu privire la locul în care un anumit produs se situează pe acea scară. Cheile API ale Nordlet conțin domenii de aplicare per modul, cum ar fi sales:read și sales:write, verificate la fiecare acțiune, ceea ce separă modulele și operațiunile de citire de cele de scriere, dar nu și crearea de aprobare; acolo unde aveți nevoie de această diviziune mai fină în prezent, aplicați-o în propriul serviciu înainte de apel.

Pentru operațiunile de valoare mare, merită să evaluați dacă Profilul de securitate FAPI 2.0 (FAPI 2.0 Security Profile) se aplică. Acesta a fost conceput pentru API-uri care protejează date financiare sensibile și oferă garanții mai puternice decât OAuth de bază. Majoritatea integrărilor contabile pentru IMM-uri nu vor avea nevoie de profilul complet, dar fluxurile de eliberare a plăților și de conectare bancară sunt locurile unde trebuie luat în considerare.

Autentificarea fără parolă a Nordlet prin linkuri unice trimise pe e-mail elimină problema parolei reutilizabile pentru utilizatorii umani, reprezentând o credențială în plus care nu mai trebuie rotită, scursă sau compromisă prin phishing.

Faceți scrierile financiare idempotente

Rețelele cad în mijlocul unei cereri. Un client trimite o instrucțiune de plată, conexiunea se întrerupe înainte ca răspunsul să arrive, iar clientul reîncearcă. Fără protecție, aveți acum două plăți.

Cheile de idempotendă (idempotency keys) rezolvă această problemă. Clientul trimite o cheie unică la fiecare scriere; serverul înregistrează cheia și rezultatul acesteia. O reîncercare cu aceeași cheie returnează rezultatul original în loc să creeze o a doua înregistrare. Nordlet acceptă un antet Idempotency-Key la fiecare apel care modifică date starea, redând răspunsul stocat la o reîncercare cu același conținut (payload) și respingând aceeași cheie cu un conținut modificat. Orice API de contabilitate care omite această funcție va produce în cele din urmă înregistrări duplicate în registru pe care cineva va trebui să le descurce manual.

Asociați acest lucru cu validarea pe partea de server. Nu aveți niciodată încredere că clientul verifică dacă debitele sunt egale cu creditele, dacă o cotă de TVA este valabilă pentru țară și perioadă sau dacă un cont există. Validarea rulează pe server, înainte de tranziția stării, iar o scriere respinsă produce o eroare stabilă și o înregistrare de audit.

Jurnale de audit rezistente la manipulare și păstrarea datelor conform legislației olandeze

Jurnalul de audit reprezintă stratul de dovezi și are cerințe diferite față de datele obișnuite de business. Acesta ar trebui să înregistreze decizia de autorizare, versiunea politicii, actorul, obiectul, operațiunea, starea anterioară și cea nouă, precum și codul motivului, fără a înregistra vreodată secrete sau credențiale de plată complete.

Proprietatea critică este rezistența la manipulare (tamper-evident). Dacă un administrator poate edita sau șterge în liniște înregistrările de audit, jurnalul nu dovedește nimic. Stocarea exclusiv append-only (doar adăugare), înlănțuirea criptografică sau păstrarea de tip scriere unică (write-once) rezolvă toate aceste aspecte. Ideea este că o modificare trebuie să poată fi detectată.

Perioada de păstrare merită propria politică, separată de ștergerea înregistrărilor de business. În Țările de Jos, perioada generală de păstrare a înregistrărilor administrative este de șapte ani, iar pentru înregistrările referitoare la bunuri imobile ajunge la zece ani. Fluxurile dumneavoastră obișnuite de ștergere a datelor și de conformitate cu GDPR nu trebuie să poată distruge înregistrări sau dovezi de audit pe care o regulă legală de păstrare încă le acoperă. Definiți regulile de reținere legală (legal hold), arhivare și ștergere pentru dovezile de audit în mod independent și mapați-le la jurisdicțiile în care operați.

Blocarea perioadelor (period locking) sprijină acest lucru la nivelul contabilității. Odată ce o lună este închisă, înregistrările din aceasta nu se pot schimba fără o autorizare superioară și un motiv înregistrat. Nordlet aplică blocarea perioadelor, astfel încât lunile închise să rămână închise, respingând orice postare datată în interiorul unei perioade blocate, chiar și prin intermediul API-ului, acesta fiind unul dintre primele lucruri pe care le verifică un auditor olandez.

Securizați marginile: webhook-uri, exporturi și integrări

API-ul principal este, de obicei, partea cea mai bine apărată a sistemului. Marginile prezintă scurgeri.

Webhook-urile reprezintă un risc de cerere falsificată. Un eveniment precum sale_invoice.paid ar trebui semnat astfel încât destinatarul să poată verifica dacă provine de la dumneavoastră, iar receptorii ar trebui să trateze livrarea ca fiind de tipul cel puțin o dată (at-least-once) și să utilizeze ID-ul evenimentului pentru deduplicare. Nordlet semnează fiecare livrare de webhook cu o semnătură HMAC asupra corpului brut (raw body) și reîncearcă livrările eșuate cu backoff exponențial, astfel încât un receptor trebuie să verifice semnătura și să dedupliceze după ID-ul evenimentului în loc să presupună livrarea exact o dată (exactly-once).

Exporturile reprezintă o cale de scurgere a datelor în masă. Exporturile de rapoarte în format XLSX, PDF sau JSON extrag volume mari de date financiare într-o singură operațiune, motiv pentru care au nevoie de propria permisiune, limite de viteză (rate limits) și jurnale de audit. Integrările terțe pe care le consumați ar trebui tratate ca intrări de încredere, fiind validate în același mod în care validați cererile directe ale clienților.

Lista de verificare pentru pregătirea de audit a unui API de contabilitate olandez

Utilizați aceste elemente înainte de a susține că o integrare este pregătită pentru audit:

  • Mașină de stări explicită pe fiecare resursă financiară; intrările postate nu pot fi suprascrise
  • Autorizare la nivel de obiect și de entitate juridică pentru fiecare cerere, cu refuz implicit (deny-by-default)
  • Context pentru chiriaș și rol derivat din token, nu din cererile clientului
  • OAuth 2.0 conform RFC 9700; domenii bazate pe capabilități; separarea creării de aprobare
  • Separarea atribuțiilor aplicată prin roluri, nu doar documentată
  • Chei de idempotendă pentru toate scrierile financiare
  • Validare contabilă și de TVA pe partea de server înainte de tranzițiile de stare
  • Jurnal de audit append-only, rezistent la manipulare, cu coduri de motiv
  • Reguli de păstrare și de reținere legală mapate la perioadele olandeze (șapte ani, zece pentru proprietăți)
  • Blocarea perioadelor pentru lunile închise
  • Webhook-uri semnate cu deduplicare; exporturi delimitate (scoped), cu limită de rată și înregistrate în jurnal

Ce am construi mai întâi

Dacă am integra contabilitatea într-o platformă olandeză mâine, am începe cu modelul de stare și autorizarea la nivel de obiect, înainte de a scrie un singur punct final de business. Aceste două decizii constrâng tot ceea ce urmează, iar retroadaptarea lor într-un sistem care a tratat înregistrările din registru ca rânduri editabile este cu adevărat dificilă. Idempotendă și jurnalul de audit urmează imediat după aceea, deoarece sunt ieftin de adăugat devreme și costisitoare de adăugat după ce datele încep să circule.

Restul – tokenurile delimitate, webhook-urile semnate, blocarea perioadelor – urmează mai ușor odată ce fundația este solidă. Toate acestea pot fi testate pe o companie sandbox (/en/get-started/) înainte ca vreuna să atingă datele de producție.

FAQ

Un API pregătit pentru audit înseamnă că afacerea este conformă?

Nu, și merită să fim preciși în această privință. Pregătirea pentru audit este o proprietate de proiectare a sistemului: registrul, controalele și lanțul de dovezi sunt construite astfel încât un audit să poată reuși. Conformitatea cu un cadru fiscal, contabil sau de securitate specific este o evaluare separată care mapează acele controale la un standard numit. Un API bine construit facilitează munca de conformitate; nu o înlocuiește.

Cât timp trebuie păstrate înregistrările contabile în Țările de Jos?

Obligația generală este de șapte ani pentru înregistrările administrative, extinzându-se la zece ani pentru înregistrările legate de bunuri imobile. Construiți reguli de păstrare și reținere legală pe care fluxurile dumneavoastră obișnuite de ștergere să nu le poată suprascrie.

Este suficientă o cheie API statică pentru o integrare financiară?

Pentru automatizarea de la server la server cu o sferă restrânsă poate funcționa, dar cheile statice reutilizabile sunt greu de rotit și periculoase dacă sunt divulgate. Pentru accesul delegat și orice flux orientat spre utilizatorul uman, OAuth 2.0 cu tokenuri cu durată scurtă de viață și domenii delimitate reprezintă opțiunea mai sigură.

De ce contează atât de mult idempotendă în special pentru contabilitate?

Deoarece o scriere duplicată în majoritatea sistemelor reprezintă un neajuns, în timp ce o scriere duplicată în contabilitate înseamnă un număr greșit în registre pe care cineva trebuie să îl găsească și să îl storneze. Cheile de idempotendă fac ca reîncercările să fie sigure în loc să fie riscante.

Lecturi suplimentare