Ce definește un API pentru un registru contabil dublu imuabil

Un registru contabil (ledger) pentru o piață online nu se definește prin simplul fapt că stochează mișcări de bani, deoarece majoritatea sistemelor fac acest lucru. El se definește prin ceea ce se întâmplă atunci când un furnizor de plăți trimite același webhook de două ori, când o rambursare sosește după ce un vânzător a fost deja plătit sau când un auditor întreabă cum a ajuns soldul unui vânzător la valoarea actuală. Aceste momente scot la iveală dacă aveți un registru contabil în partidă dublă imuabil sau un câmp modificabil cu un nume promițător.

Pentru o platformă de tip marketplace, răspunsul pe scurt este următorul: un API de registru contabil în partidă dublă imuabil înregistrează fiecare eveniment cu impact financiar sub forma unei tranzacții de jurnal echilibrate, o postează în mod atomic, nu o suprascrie niciodată și vă permite să deduceți soldurile, să faceți reconcilierea cu sistemele externe și să exportați istoricul în mod programatic. Orice altceva reprezintă doar detalii adiacente acestei structuri de bază.

Înregistrări de jurnal echilibrate, nu un câmp de sold cumulat

Cel mai clar indicator este modul în care API-ul reprezintă soldul unui vânzător. Dacă soldul este un număr pe care aplicația dumneavoastră îl incrementează direct, nu este un registru în partidă dublă. Dacă soldul este o vizualizare derivată din liniile de jurnal postate, atunci ar putea fi.

Fiecare tranzacție trebuie să conțină debituri și credite egale. Atunci când un cumpărător plătește 100 EUR pentru o comandă în care platforma reține un comision de 15 EUR, registrul înregistrează contul de încasări debitat cu 100 EUR, contul creditor al vânzătorului creditat cu 85 EUR și veniturile din comisioane creditate cu 15 EUR. Cele două părți însumează întotdeauna aceeași valoare. Această regulă structurală elimină o categorie largă de erori înainte ca acestea să ajungă într-un raport.

O tranzacție de jurnal trebuie să expună, cel puțin:

• Un ID de tranzacție unic și imuabil
• Linii de debit și credit, fiecare având un cont, o sumă și o monedă
• O dată efectivă și o marcă temporală de postare
• Un tip de eveniment de afaceri (vânzare, rambursare, plată către vânzător, refuz de plată sau chargeback)
• O cheie de idempotență
• O referință sursă către comandă, plată sau evenimentul furnizorului
• O stare (în așteptare, postat, inversat)
• Serviciul sau acreditarea care l-a creat

Fondurile disponibile ale unui vânzător devin astfel o interogare asupra acelor linii, nu o valoare actualizată de cineva în codul aplicației. Acest lucru contează deoarece un sold modificat direct șterge motivul fiecărei mișcări. Modelul Nordlet tratează registrul contabil în partidă dublă drept calea oficială de scriere (authoritative write path): fiecare document postează înregistrări de jurnal echilibrate, iar baza de date însăși refuză înregistrările neechilibrate. Aceasta este setarea implicită corectă pentru oricine integrează contabilitatea într-o piață online.

Postare exclusiv prin adăugare (append-only) cu corecții compensatorii

Termenul „imuabil” trebuie să însemne că un jurnal postat nu poate fi editat direct. Eșecurile sunt remediate prin adăugarea unor operațiuni ulterioare, nu prin ștergere. O înregistrare greșită a unui comision primește o inversare care anulează valoarea inițială, urmată de o înregistrare corectată care reflectă rezultatul dorit. Ambele fac trimitere la cea inițială, iar istoricul de audit arată cine a inițiat modificarea și când.

API-ul trebuie să respingă comenzile simple de tip UPDATE și DELETE aplicate înregistrărilor contabile postate. El poate permite atașarea de metadate fără impact financiar, cum ar fi o referință la un tichet de suport, cu condiția ca sumele, conturile și marcajele temporale să rămână neschimbate.

Este util să separăm trei concepte pe care oamenii le confundă adesea:

• Imuabilitate operațională: utilizatorii aplicației nu pot modifica sau șterge rândurile postate.
• Imuabilitate de audit: sistemul poate demonstra că istoricul nu a fost modificat.
• Păstrare legală: înregistrările sunt păstrate pe perioada impusă de legislația aplicabilă.

O bază de date relațională cu adăugare exclusivă (append-only), bazată pe permisiuni stricte, copii de rezervă și fluxuri de lucru riguroase de inversare, oferă un registru cu adevărat imuabil. Tehnologia blockchain nu este o cerință în acest caz, iar pentru datele contabile din UE introduce de obicei probleme de confidențialitate și corectare care depășesc avantajele legate de detectarea modificărilor neautorizate.

Atomicitate și idempotență

Un eveniment dintr-o piață online trebuie să fie postat în mod atomic: fie se înregistrează toate liniile de jurnal, fie niciuna. Înregistrarea încasării de 100 EUR fără a înregistra comisionul de 15 EUR generează un rezultat neechilibrat și înșelător, pe care cineva va trebui să îl descurce ulterior. Nordlet aplică această regulă dedesubtul stratului de aplicație: un declanșator (trigger) amânat al bazei de date verifică dacă fiecare postare este echilibrată în momentul confirmării (commit), astfel încât o tranzacție neechilibrată să nu poată fi niciodată salvată.

Idempotența este zona în care majoritatea integrărilor se blochează discret. Sistemele de plată reîncearcă operațiunile în caz de erori de rețea, iar fișierele de decontare sunt rulate din nou. Fără o cheie de idempotență asociată chiriașului (tenant) sau contului, o singură solicitare reîncercată creează înregistrări contabile duplicate. O solicitare repetată cu aceeași cheie ar trebui să returneze tranzacția originală, nu una nouă.

Cheia trebuie să fie legată de evenimentul generator, tipul evenimentului, ID-ul evenimentului furnizorului, entitatea legală și un hash al conținutului (payload) solicitării. Dacă aceeași cheie sosește cu o sumă sau o monedă diferită, API-ul trebuie să trateze acest lucru ca pe o coliziune și să o respingă, în loc să accepte în tăcere noul conținut. Acceptarea tăcută duce la compromiterea traseului de audit. Antetul Idempotency-Key din Nordlet funcționează astfel: o reîncercare cu aceeași cheie și același conținut redă răspunsul stocat, în timp ce aceeași cheie cu un conținut diferit este respinsă cu eroarea idempotency_key_reuse. Este o funcționalitate minoră cu un impact uriaș asupra reconcilierii.

Contabilitate de împărțire multi-parte (Multi-party split accounting)

O comandă plasată pe o piață online nu reprezintă o singură mișcare de fonduri. O singură vânzare poate implica fondurile cumpărătorului, încasările vânzătorului, comisionul platformei, comisioanele de procesare a plăților, TVA-ul aferent comisionului, costurile de expediție și rezervele. Registrul necesită structuri de conturi care să mențină aceste elemente separate, în loc să le comaseze într-o singură valoare netă.

Există o presupunere comună pe care merită să o combatem: funcția de „plată divizată” (split payout) a unui furnizor de plăți nu este același lucru cu contabilitatea unei piețe online. Împărțirea banilor între mai mulți beneficiari direcționează doar numerarul. Aceasta nu vă oferă o înregistrare completă și imuabilă a comisionului câștigat, a TVA-ului colectat, a rambursărilor datorate sau a rezervelor reținute. Tot aveți nevoie de propriul registru contabil și trebuie să îl reconciliați cu furnizorul.

De asemenea, un registru pentru marketplace trebuie să distingă mai multe tipuri de solduri pentru un vânzător:

Starea soldului	Ce reprezintă
În așteptare (Pending)	Fonduri legate de un eveniment, dar care nu sunt încă eligibile pentru retragere
Disponibile (Available)	Fonduri care respectă regulile de eliberare, rezerve, rambursare și dispute
Reținute / rezervate (Held / reserved)	Sume oprite pentru refuzuri de plată (chargebacks), retururi sau controale antifraudă
Plătite (Paid out)	Sume transferate către vânzător
Negative / recuperabile (Negative / recoverable)	Sume pe care vânzătorul le datorează după ce rambursările sau comisioanele depășesc fondurile disponibile

Trecerea banilor din starea „în așteptare” în cea „disponibilă” trebuie să fie la rândul ei o tranzacție de jurnal echilibrată, nu doar un câmp redenumit.

Inversări, rambursări și solduri negative

Fluxurile financiare dintr-un marketplace se deplasează în ambele direcții, adesea într-o ordine imprevizibilă. Situațiile dificile apar în cazul rambursărilor efectuate după ce plata a fost deja trimisă către vânzător sau al refuzurilor de plată (chargebacks) care sosește săptămâni mai târziu. Un registru serios definește ce se întâmplă atunci când soldul disponibil al unui vânzător nu poate acoperi o rambursare: se creează un sold negativ, suma este trecută în categoria creanțelor față de vânzător, se utilizează o rezervă sau sunt blocate plățile viitoare.

Fiecare dintre aceste evenimente trebuie să facă trimitere la tranzacția originală și să o păstreze intactă. Registrul înregistrează consecința contabilă a unei rambursări, fără a stabili însă politica de rambursare a platformei sau răspunderea sa juridică. Menținerea clară a acestei granițe previne numeroase discuții confuze de design.

Valute și precizie

Piețele online transfrontaliere necesită o gestionare explicită a banilor. Sumele trebuie să folosească codurile valutare ISO 4217 și o reprezentare exactă, fie prin unități subordonate sub formă de numere întregi (minor units), fie prin șiruri zecimale cu precizie fixă, evitând complet tipurile de date cu virgulă mobilă (floats). Fără rotunjiri tăcute. În momentul conversiei, registrul trebuie să păstreze suma originală, cursul valutar, sursa cursului, marcajul temporal și suma rezultată, diferențele de rotunjire fiind postate într-un cont definit.

O singură tranzacție echilibrată nu trebuie să amestece valutele fără un mecanism valutar explicit. Dacă faceți acest lucru, rapoartele dumneavoastră vor contrazice realitatea în moduri greu de urmărit la sfârșitul lunii.

Reconcilierea cu sistemele externe

Un registru echilibrat intern nu este suficient prin sine însuși; el trebuie să corespundă cu lumea exterioară: tranzacțiile furnizorilor de plăți, comisioanele acestora, rapoartele de decontare, extrasele bancare, fișierele de plată și rapoartele de refuz de plată.

Un API matur acceptă evenimente externe importate și stări de potrivire precum: „potrivit” (matched), „potrivit parțial” (partially matched), „nepotrivit” (unmatched), „duplicat”, „neconcordanță de sumă” și „necesită revizuire”. Diferențele de reconciliere trebuie să genereze înregistrări explicite de excepție sau intrări contabile. Ele nu trebuie niciodată să modifice în tăcere istoricul registrului. Abordarea Nordlet privind reconcilierea bancară și potrivirea plăților se bazează tocmai pe acest principiu: extrasele importate și exporturile Stripe omit orice a fost deja importat, sugestiile de plată sunt punctate în funcție de sumă, referință, partener și IBAN, potrivirea printr-un singur clic gestionează cazurile de rutină, iar excepțiile sunt evidențiate în loc să fie ascunse.

Limitele impuse de UE pe care API-ul trebuie să le respecte (și cele pe care nu le poate controla)

Acesta este segmentul în care pretențiile de marketing tind să depășească realitatea. Un registru contabil ajută la respectarea obligațiilor în UE, dar nu le îndeplinește singur.

TVA. Registrul trebuie să păstreze dimensiunile relevante pentru taxe: jurisdicția, cota, categoria fiscală și modul în care a fost determinată cota respectivă. El trebuie să distingă vânzarea efectuată de vânzător către cumpărător de comisionul platformei și să separe TVA-ul aferent comisioanelor de sumele aflate în tranzit. Nordlet gestionează calculele de TVA pentru fiecare țară, validarea VIES și generarea registrelor i.SAF, alături de scenariile OSS și IOSS cu care se confruntă piețele online din UE. Tratați registrul ca pe o dovadă și un motor fiscal, nu ca pe o consultanță fiscală.

DAC7. Regulile de raportare pentru platforme impun legături fiabile între identitatea vânzătorului, jurisdicție, totalurile tranzacțiilor, comisioane, rambursări și plăți. Un registru echilibrat produce dovezile tranzacțiilor, dar nu stabilește dacă un vânzător este supus raportării și nici nu înlocuiește procesul de cunoaștere a clientelei (KYC), integrarea (onboarding) sau fluxul de raportare. Păstrați contabilitatea tranzacțiilor și raportarea de reglementare ca domenii separate.

PSD2 și custodia fondurilor. Înregistrarea mișcărilor de bani nu este echivalentul obținerii unei licențe de servicii de plată sau a salvgardării fondurilor. Registrul trebuie să facă explicite fluxul de bani și părțile implicate. El nu poate oferi, prin propriile mijloace, autorizația pentru servicii de plată și nici nu poate dovedi că numerarul este deținut într-un anumit cont. Aceasta rămâne o chestiune legată de rolul dumneavoastră de reglementare și de furnizorii de servicii de plată (PSP).

GDPR. Imuabilitatea creează o tensiune reală cu principiile de protecție a datelor. Cea mai sigură arhitectură păstrează datele monetare în nucleul imuabil și datele cu caracter personal în afara acestuia. Utilizați referințe pseudonimizate stabile pentru vânzători și clienți în liniile de jurnal. Stocați detaliile personale modificabile într-un sistem separat, cu acces controlat, care dispune de propriul flux de lucru pentru păstrare și ștergere. „Imuabil” nu înseamnă o autorizație de a păstra pentru totdeauna orice conținut de plată.

O listă de verificare pentru evaluarea unui API de registru contabil

Etichetele funcționalităților sunt ieftine. Testați comportamentul într-un mediu de test (sandbox) în schimb. Rulați aceste scenarii și verificați rezultatele:

• Posați o comandă de 100 EUR împărțită între vânzător și platformă și confirmați existența unui jurnal echilibrat cu conturi explicite.
• Trimiteți aceeași solicitare de două ori și confirmați generarea unei singure tranzacții, fără duplicate.
• Încercați să editați o înregistrare postată și confirmați că aceasta este respinsă sau limitată la metadate fără impact financiar.
• Corectați un comision greșit și confirmați existența unei inversări asociate și a unei înregistrări corectate.
• Emiteți o rambursare parțială după efectuarea plății către vânzător și confirmați existența unei rambursări trasabile, cu o creanță asupra vânzătorului sau un sold negativ, după caz.
• Re Transmiteți un webhook al furnizorului și confirmați detectarea duplicatelor.
• Procesați o decontare în mai multe valute și confirmați detaliile valutare și contabilitatea conversiei.
• Interogați soldul unui vânzător la sfârșitul unei perioade și confirmați un rezultat revalidat cu o dată de închidere documentată.
• Importați o decontare de la furnizor și confirmați potrivirea cu o stare de excepție care lasă istoricul neatins.
• Exportați activitatea pe o lună și confirmați un extras complet, paginat și repetabil.

Cea mai solidă dovadă constă în documentație însoțită de un test reproductibil. Termeni precum „în timp real”, „pregătit pentru audit” și „imuabil” nu înseamnă nimic fără modelul de date, semantica erorilor și comportamentul de păstrare din spatele acestora.

Ce am verifica mai întâi

Dacă am evalua mâine un API de registru contabil pentru o piață online, am începe cu două aspecte înainte de orice altceva. În primul rând, am demonstra că soldul unui vânzător este derivat din liniile de jurnal și nu dintr-un câmp modificabil, deoarece tot ceea ce depinde de acesta în aval se bazează pe el. În al doilea rând, am retransmite același webhook și am confirma că rezultă exact o singură înregistrare contabilă. Aceste două teste spun mai multe despre calitatea designului subiacent decât orice listă de funcționalități.

După aceea, considerentele centrate pe API contează pentru viteza cu care echipa dumneavoastră livrează: SDK-uri tipizate, webhookuri pentru evenimente precum sale_invoice.paid, un mediu de test functional și blocarea perioadelor pentru a proteja lunile închise. Nordlet a fost conceput în jurul acestui model, având același set de funcționalități expus prin API ca și în aplicație, ceea ce îi permite unei platforme să ruleze registre pregătite pentru audit în propriul produs, fără a adăuga o soluție externă de finalizare a comenzilor. Pentru o perspectivă mai amplă asupra modului în care un astfel de registru se integrează în arhitectura unei piețe online, consultați ghidul nostru despre API-urile pentru registre contabile în partidă dublă destinate contabilității marketplace-urilor.

FAQ

Garantează partida dublă corectitudinea contabilității mele?

Nu. Un registru poate fi perfect echilibrat, în timp ce postează în conturile greșite, aplică un tratament TVA incorect sau atribuie fonduri altui vânzător. Echilibrul este un control structural care detectează erorile aritmetice și părțile lipsă dintr-o tranzacție, dar nu oferă nicio garanție că logica de afaceri a mapat corect evenimentul. De aceea, testarea în sandbox pe baza unor scenarii reale contează mai mult decât simpla verificare a soldului.

Este suficient registrul unui furnizor de plăți pentru o piață online?

De obicei, nu. Un furnizor de servicii de plată (PSP) urmărește fondurile în propriul sistem, ceea ce este util pentru mișcare și decontare. Piața dumneavoastră online are totuși nevoie de propriile înregistrări pentru veniturile din comisioane, datoriile față de vânzători, TVA-ul aferent comisioanelor, rambursări, rezerve, dispute și rapoarte de management. Cele două sisteme trebuie reconciliate, iar tratarea perspectivei furnizorului drept propria contabilitate lasă lacune care ies la iveală în timpul unui audit.

Am nevoie de blockchain pentru a face un registru imuabil?

Nu. O bază de date relațională cu adăugare exclusivă (append-only), cu permisiuni stricte de scriere, fluxuri controlate de corectare, jurnale de audit (audit logs) și copii de rezervă fiabile, vă oferă imuabilitate operațională și de audit. Tehnologia blockchain adaugă o probă distribuită împotriva modificărilor, dar aduce dificultăți legate de confidențialitate, performanță și corectare care contravin cerințelor contabile din UE și normelor GDPR. Pentru majoritatea piețelor online, aceasta rezolvă o problemă pe care nu o au.

Poate un registru imuabil să păstreze datele pentru totdeauna în conformitate cu GDPR?

Păstrarea înregistrărilor contabile pe perioada impusă de lege este în regulă. Păstrarea pe termen nedefinit a datelor cu caracter personal complete sau a conținuturilor de plată doar pentru că registrul este imuabil nu este permisă. Păstrați faptele monetare și referințele pseudonimizate în nucleul imuabil și țineți detaliile personale într-un sistem separat, cu politici adecvate de păstrare și ștergere. Imuabilitatea se aplică evenimentului financiar, nu fiecărei bucăți de date atașate acestuia.