Ce este un API de registratură în partidă dublă pentru marketplace-uri?
Un API de registratură în partidă dublă înregistrează fluxul de bani dintr-un marketplace sub formă de note contabile echilibrate și imutabile, astfel încât să știi mereu cine, cui și de ce trebuie să plătească.
Un marketplace poate părea sănătos în tabelul său cu orders și totuși să dea date greșite despre banii săi. Comanda are statusul „plătit“. Tabloul de bord al vânzătorului afișează un sold. Totuși, nimic din acel tabel nu dovedește câți bani deține efectiv platforma, cât datorează fiecărui vânzător, ce parte din încasare reprezintă venit din comision sau ce TVA a devenit exigibil. Un API de registratură în partidă dublă (double-entry ledger API) există tocmai pentru a înregistra corect aceste consecințe financiare, câte o tranzacție echilibrată pe rând.
Spus pe scurt: un API de registratură în partidă dublă este un sistem contabil programabil. Aplicația ta îi trimite un eveniment financiar, cum ar fi o plată încasată sau o plată aprobată către un partener (payout), iar registrul consemnează acel eveniment ca pe un jurnal cu debite și credite egale în conturi cu denumiri specifice. El nu mută bani. El înregistrează adevărul despre banii care s-au mutat în altă parte.
Ce înseamnă „registratură în partidă dublă“ în acest context
Un registru este istoricul modificărilor aduse conturilor, nu un simplu tabel care reține cel mai recent sold. Un registru funcțional se bazează pe trei concepte interconectate:
- Cont (Account): o poziție financiară denumită, cum ar fi creanțe de la procesatorul de plăți, datorii față de vânzători, venituri din comisioane sau TVA de plată.
- Tranzacție (jurnal / transaction): un singur eveniment financiar atomic care conține mai multe linii echilibrate.
- Înregistrare (notă contabilă / entry sau posting): o singură linie de debit sau de credit din cadrul acelei tranzacții.
Invarianta care menține întregul ansamblu coerent este simplă: totalul debitelor este egal cu totalul creditelor, pentru fiecare tranzacție și fiecare monedă în parte. De regulă, API-urile de registratură resping o scriere neechilibrată înainte ca aceasta să ajungă în stocaj. Documentația Modern Treasury definește o tranzacție din registru ca implicând două sau măcar două conturi, cu cel puțin un debit și un credit de sume egale, și tratează o tranzacție înregistrată ca fiind imutabilă.
Partida dublă nu înseamnă exact două rânduri. O singură vânzare pe marketplace necesită adesea un debit și mai multe credite. Aceasta este partea pe care oamenii o interpretează greșit cel mai des.
De ce au marketplace-urile nevoie de un registru și nu doar de un tabel de plăți
Un marketplace gestionează mai multe relații financiare în același timp. Un cumpărător plătește. Un procesator decontază fondurile. Platforma poate controla temporar banii. Vânzătorul își câștigă partea sa. Platforma își oprește comisionul. Taxele devin exigibile. Se poate reține o sumă drept garanție (reserve). Ulterior, un transfer (payout) scoate banii din sistem, iar rambursările (refunds) sau refuzurile de plată (chargebacks) anulează parțial aceste operațiuni.
Un tabel de tip payments îți poate indica statusul comercial al unei comenzi. Dar nu îți poate spune cu precizie:
- valoarea creanțelor de la procesator sau a numerarului disponibil
- suma datorată fiecărui vânzător
- valoarea veniturilor care revin platformei
- valoarea TVA-ului de plată și țara în care este datorat
- suma reținută drept garanție pentru eventuale rambursări sau litigii
- dacă un transfer a redus corect datoria către vânzător
- dacă decontările procesatorului corespund așteptărilor platformei
Ghidul Nordlet despre API-urile de registratură în partidă dublă pentru contabilitatea marketplace-urilor trasează o linie clară: tabelele aplicației descriu starea produsului, în timp ce registrul consemnează consecințele financiare ale acelei stări. De asemenea, subliniază un aspect care merită repetat: rapoartele procesatorilor de plăți reprezintă inputuri pentru reconciliere, nu o evidență contabilă completă în partidă dublă.
O vânzare tipică pe marketplace, pas cu pas
Să presupunem că un cumpărător plătește 100 EUR, vânzătorului i se cuvin 85 EUR, iar comisionul platformei este de 15 EUR. Pentru claritate, ignorăm TVA-ul și comisioanele procesatorului.
| Cont | Debit | Credit | Motiv |
|---|---|---|---|
| Creanțe procesator de plăți | 100 EUR | Procesatorul datorează platformei plata încasată | |
| Datorii față de vânzători | 85 EUR | Platforma datorează banii vânzătorului | |
| Venituri din comisioane | 15 EUR | Platforma și-a câștigat comisionul | |
| Total | 100 EUR | 100 EUR | Echilibrat |
Clasificarea importantă aici este că suma de 85 EUR datorată vânzătorului reprezintă o datorie (pasiv), nu un venit al platformei. Conform cadrului conceptual IFRS, o datorie este o obligație prezentă de a transfera o resursă economică. Un marketplace nu trebuie să înregistreze încasările integrale ale vânzătorului drept venit propriu doar pentru că plata s-a făcut prin intermediul său. Indiferent dacă acționezi ca agent, principal sau contribuabil considerat (deemed supplier), tratamentul contabil se poate schimba, însă mecanismul registrului rămâne același.
Atunci când vânzătorul devine eligibil pentru încasare, nu se recunoaște niciun venit nou. Practic, stingi datoria:
| Cont | Debit | Credit |
|---|---|---|
| Datorii față de vânzători | 85 EUR | |
| Bancă sau cont de decontare (payout clearing) | 85 EUR | |
| Total | 85 EUR | 85 EUR |
Dacă procesatorul reține un comision de 3 EUR înainte de decontare, fluxul de numerar devine un jurnal cu trei linii: 97 EUR în numerar la bancă, 3 EUR cheltuieli cu procesarea, 100 EUR descărcare din creanțele procesatorului. Orice modificare de poziție are o sursă și o destinație.
Cum funcționează API-ul, pas cu pas
1. Aplicația ta detectează un eveniment de business. O plată este încasată, o comandă este livrată, un transfer este aprobat, o rambursare este emisă, se deschide un litigiu sau sosește o decontare. Baza ta de date își păstrează în continuare starea operațională. Registrul consemnează efectul monetar.
2. Trimiți o cerere structurată. Aceasta conține de obicei tipul evenimentului, suma și moneda, ID-ul comenzii sau al plății, identificatorii cumpărătorului și ai vânzătorului, comisionul, datele fiscale, conturile implicate, datele efective și de înregistrare, o cheie de idempotență (idempotency key) și metadate care fac trimitere la înregistrările procesatorului și ale produsului. Exemplul de API public al Nordlet prezintă o cerere conceptuală de vânzare care include ID-ul vânzătorului, tipul vânzării, suma, moneda, precum și țara și cota de TVA.
3. API-ul validează datele. Se verifică dacă debitele și creditele sunt echilibrate, dacă conturile există și permit înregistrări, dacă moneda este acceptată, dacă suma folosește o reprezentare precisă în unități monetare subunitare (minor-unit), dacă cheia de idempotență nu a fost reutilizată pentru un alt rezultat, dacă perioada contabilă este deschisă și dacă metadatele obligatorii sunt prezente. O verificare eșuată nu lasă în urmă nicio înregistrare parțială.
4. Înregistrarea se face atomic. Întreaga tranzacție se scrie ca o singură unitate. Nu trebuie să fie posibil niciodată să înregistrezi debitul în timp ce creditul coerent eșuează. În cazul unui marketplace, o divizare parțială ar putea crea un sold fictiv de vânzător fără numerarul corespondent sau ar putea contabiliza comisionul fără a înregistra obligația față de vânzător.
5. Soldurile și rapoartele sunt derivate din registru. După înregistrare, poți citi soldurile conturilor, soldurile în așteptare și disponibile ale vânzătorilor, balanța de verificare, activitatea din registrul-jurnal, sumarele de TVA și istoricul la o dată din trecut. Soldul vânzătorului trebuie să poată fi reconstruit din înregistrări, nu bazat pe un câmp modificabil.
6. Webhook-urile notifică produsul tău. Evenimente precum sale_invoice.paid, un jurnal înregistrat, un transfer disponibil sau o excepție de reconciliere îți sunt trimise automat. Procesează-le în mod idempotent. Un webhook este o notificare, nu o permisiune de a aplica evenimentul financiar a doua oară. Convențiile API detaliază domeniile de aplicare (scopes), cheile de idempotență, formatele erorilor și semnarea webhook-urilor.
Soldurile vânzătorilor nu se rezumă la o singură cifră
Cele mai multe marketplace-uri întâmpină probleme tratând soldul unui vânzător ca pe o singură valoare numerică. Banii trebuie să treacă prin mai multe stări:
| Stare | Semnificație |
|---|---|
| În așteptare (Pending) | Vânzătorul poate avea dreptul la bani, dar condițiile de eliberare nu sunt îndeplinite |
| Disponibil (Available) | Eligibil pentru transfer (payout) |
| Rezervat (Reserved) | Reținut pentru acoperirea eventualelor rambursări, retururi sau litigii |
| Plătit (Paid out) | Obligație achitată printr-un transfer |
| Negativ (Negative) | Rambursările, refuzurile de plată sau comisioanele depășesc fondurile disponibile |
Modelele procesatorilor reflectă această structură. Fluxul de plăți și transferuri separate de la Stripe permite unei platforme să își încaseze propriul cont, apoi să transfere porțiuni către conturile conectate, comisioanele, rambursările și refuzurile de plată afectând soldul platformei. Modelul de marketplace Adyen face o distincție între conturile de sold ale utilizatorilor (care păstrează fondurile până la transfer) și un cont de sold pasibil (liable balance account) care poate absorbi soldurile negative rezultate din rambursări sau litigii. Acestea sunt surse utile de date pentru registrul tău, dar nu reprezintă modelul tău contabil complet.
Transferurile și veniturile vânzătorilor se produc la momente diferite
Un vânzător poate realiza venituri luni și își poate primi banii lunea viitoare. Între aceste momente, o comandă este livrată, se reține o garanție, se generează un lot de plăți, procesatorul efectuează decontarea scăzând comisioanele, iar un depozit bancar ajunge în cont. Un registru trebuie să păstreze fiecare etapă în parte, în loc să suprascrie comanda cu un status final de tip „plătit“. Tocmai acest lucru îți permite să justifici diferențele de timp dintre activitatea comenzilor, drepturile vânzătorului, decontare, inițierea transferului și încasarea bancară.
Rambursările și refuzurile de plată: anulează prin reversare, nu rescrie
Rambursările și refuzurile de plată sunt evenimente noi legate de plata originală. Într-un registru imutabil, corecțiile se fac printr-o înregistrare de reversare (storno) urmată de o înregistrare corectă, astfel încât tranzacția inițială rămâne vizibilă în scopuri de audit. Modern Treasury tratează tranzacțiile înregistrate ca fiind imutabile și acceptă chei de idempotență pentru a preveni dublarea obiectelor în caz de reîncercare a cererii.
O rambursare tipică reduce numerarul sau creanțele de la cumpărător, anulează datoria față de vânzător, poate anula o parte din comision în funcție de politică, ajustează taxele și poate consuma o rezervă pentru rambursări. Un refuz de plată reduce numerarul sau creanțele de la procesator, poate redeschide o sumă datorată de vânzător sau de platformă, înregistrează o cheltuială cu litigiul și un comision al procesatorului și mută fondurile printr-un cont de rezerve.
Reconcilierea: conectarea registrului la banii reali
Un registru poate fi echilibrat la nivel intern și totuși să ofere date greșite cu privire la lumea exterioară. Reconcilierea compară înregistrările interne cu dovezile externe: rapoartele de decontare ale procesatorilor, extrasele bancare, fișierele de plăți, înregistrările privind rambursările și litigii.
Un flux de lucru viabil arată astfel:
- Importă lotul de decontare sau extrasul bancar.
- Potrivește fiecare linie cu o comandă, plată, rambursare, comision, transfer sau litigiu.
- Compară brutul estimat, deducerile, rezervele și valoarea netă.
- Înregistrează în registru mișcările confirmate.
- Trimite elementele nepotrivite într-un cont tranzitoriu (suspense account) dedicat.
- Investighează excepțiile.
- Blochează perioada contabilă.
Materialul de reconciliere al Nordlet descrie exact acest proces: importul loturilor de decontare, potrivirea liniilor de încasare și rambursare și direcționarea încasărilor nepotrivite către contul tranzitoriu în loc să se ghicească o factură. Două verificări sunt esențiale și niciuna nu o înlocuiește pe cealaltă: validarea în partidă dublă întreabă dacă fiecare jurnal este echilibrat, în timp ce reconcilierea verifică dacă acesta corespunde datelor de la procesator, bancă și evenimentului de business.
Detalii de design care decid succesul implementării
Idempotența (Idempotency). Asociază cheia cu un eveniment stabil, cum ar fi payment_captured:pi_123. O reîncercare a cererii va returna rezultatul inițial, nu va crea un al doilea jurnal.
Atomicitatea (Atomicity). Toate liniile unui eveniment se înregistrează împreună sau niciuna.
Imutabilitatea și reversările (Immutability and reversals). Istoricul înregistrat nu poate fi editat prin actualizări obișnuite. Corecțiile creează înregistrări asociate care păstrează valoarea inițială, data, clasificarea, motivul și autorul.
Precizia monetară (Precise money). Fără numere în virgulă mobilă binare (binary floating point). Folosește unități subunitare sub formă de numere întregi sau zecimale exacte, o monedă explicită și o regulă de rotunjire deterministă pentru divizări. Dacă divizezi 100 EUR între vânzători și comisioane fără o astfel de regulă, un singur cent rătăcit îți va strica soldul.
Data efectivă versus data înregistrării (Effective vs posting dates). Momentul în care cumpărătorul a plătit, momentul în care vânzătorul și-a câștigat banii, momentul în care banca a făcut decontarea și momentul în care s-a operat înregistrarea sunt date diferite. Confundarea lor face ca raportarea pe perioade și stabilirea momentului fiscal să fie nesigure.
Multimonedă (Multi-currency). Debitul și creditul trebuie să fie echilibrate în cadrul aceleiași monede. Conversia necesită un eveniment de curs valutar explicit, cu conturi pentru comision, rotunjire și orice câștig sau pierdere valutară (FX). Acceptarea unui câmp de currency nu transformă un registru într-un motor de schimb valutar.
Ce nu va face un API de registratură în locul tău
Nu îți va stabili planul de conturi. Tot trebuie să determini dacă acționezi ca principal sau ca agent, când este câștigat comisionul, ce parte suportă comisioanele procesatorului, cum afectează rambursările comisionul și cum se calculează și se raportează TVA-ul. Ghidul propriu al Nordlet recomandă să mapezi mai întâi fluxurile de numerar, să schițezi planul de conturi, să soliciți unui contabil să îl revizuiască, iar apoi să implementezi un flux complet, de la comandă până la transfer și reconciliere, înainte de a scala.
Nu va rezolva chestiunile legate de taxe. TVA-ul depinde de locația cumpărătorului și a vânzătorului, de tipul produsului, de statutul în scopuri de TVA și de regulile privind contribuabilul considerat (deemed supplier); ghidul pentru TVA în UE explică ce calculează motorul și ce semnalează pentru a fi verificat de un operator uman. Acoperirea TVA oferită de Nordlet este axată pe UE și SEE, prin urmare nu se extinde la taxele de vânzări din SUA (US sales tax) sau la e-facturarea din America Latină. De asemenea, nu va rezolva ambiguitățile operaționale: dacă fereastra de retur a expirat, dacă un transfer trebuie blocat sau dacă o plată este frauduloasă. Acestea sunt deciziile tale. Registrul înregistrează rezultatul lor financiar.
Unde se poziționează Nordlet
Nordlet este un API de contabilitate creat pentru platforme și marketplace-uri, care oferă un registru imutabil în partidă dublă, gestionarea plăților (payouts), tratarea TVA-ului în UE, endpoint-uri REST, SDK-uri tipizate și webhook-uri accesibile printr-o singură interfață. Caracteristica sa distinctivă este integrarea funcțiilor contabile direct în propriul tău produs, în loc să folosești un checkout terț. La momentul scrierii acestui articol, produsul se află în stadiul de acces timpuriu, cu un mediu de testare (sandbox) pentru partenerii de design, așa că trebuie privit ca un exemplu puternic al categoriei. Este recomandat să evaluezi maturitatea pentru producție, timpul de funcționare (uptime) și acoperirea jurisdicțională pentru propria ta speță înainte de a lua un angajament.
Pentru dezvoltatorii de marketplace-uri și platforme, modelul mental util constă în separarea dintre mișcarea banilor și adevărul financiar. Procesatorul tău mută banii. Un API de registratură în partidă dublă înregistrează cine și ce sume are de primit, ce ai câștigat, ce taxe și rezerve deții și dacă lumea exterioară se reconciliază corect cu evidențele tale contabile.
FAQ
Este un API de registratură în partidă dublă același lucru cu un procesator de plăți?
Nu. Un procesator autorizează, încasează, decontatează și, uneori, efectuează plăți către beneficiari. Un API de registratură înregistrează consecințele contabile ale acelor evenimente. Cele mai multe marketplace-uri le folosesc pe ambele: un procesator precum Stripe sau Adyen pentru mișcarea banilor și un registru pentru evidența contabilă.
Pot folosi pur și simplu tabloul de bord al procesatorului meu drept registrul-jurnal general?
Poți încerca, dar în cele din urmă va eșua la un audit. Raportarea procesatorului arată încasări, comisioane, transferuri și decontări, dar de obicei nu reflectă totalitatea obligațiilor tale față de vânzători, pasivele fiscale, cheltuielile non-procesator sau ajustările contabile. Tratează-l drept un input pentru reconciliere.
Înseamnă un registru echilibrat că evidența mea contabilă este corectă?
Înseamnă doar că înregistrările tale respectă regula debit-credit. O tranzacție perfect echilibrată poate fi totuși înregistrată în contul greșit, pentru vânzătorul greșit sau cu tratamentul fiscal eronat. Echilibrul este necesar, dar nu și suficient. Reconcilierea este cea care prinde restul erorilor.
Dacă registrul este imutabil, cum corectez greșelile?
Introduci o înregistrare de reversare (storno), urmată de una corectă. Înregistrarea originală rămâne vizibilă, ceea ce și constituie scopul principal. Imutabilitatea protejează pista de audit, nu îți blochează erorile.
Un API de contabilitate mă face automat conform din punct de vedere legal?
Nu. El impune o structură contabilă și generează înregistrări utilizabile. Conformitatea legală depinde în continuare de jurisdicția ta, de rolul contractual, de tratamentul fiscal, de reglementările privind plățile, de procesele KYC și AML, precum și de obligațiile de raportare.