Ce este un API de contabilitate? Un ghid pe înțelesul tuturor pentru dezvoltatorii de platforme

O definiție pe înțelesul tuturor a unui API de contabilitate, ce îl separă de un API de taxe sau de plăți și ce trebuie să verifici înainte de a te integra cu unul.

Un API de contabilitate este o interfață care permite unui program să țină evidența contabilă a altui program. Software-ul tău trimite un eveniment financiar prin HTTP. API-ul transformă acel eveniment în note contabile în partidă dublă (double-entry) echilibrate pe un plan de conturi, le stochează astfel încât să nu poată fi modificate pe furiș, aplică tratamentul fiscal și îți returnează rapoarte, documente și exporturi prin aceeași interfață.

Această definiție face cea mai mare parte a treabei. Tot ce urmează în acest articol este o consecință a ei.

Versiunea dintr-o singură propoziție

Un API de contabilitate acceptă evenimente financiare din aplicația ta, le convertește pe fiecare într-o notă contabilă echilibrată, le stochează în mod imutabil împreună cu tratamentul fiscal și dovezile justificative, și expune registrul (ledger), documentele și rapoartele rezultate ca puncte finale (endpoints) programabile.

Dacă un produs își spune API de contabilitate, dar nu generează note contabile, atunci este altceva cu un nume frumos. Asta nu înseamnă neapărat că este un produs rău. Înseamnă doar că nu va face treaba pe care urmează să i-o ceri.

Ce nu este un API de contabilitate

Patru categorii de produse conexe sunt confunde cu API-urile de contabilitate, de obicei într-un stadiu avansat al unui proiect.

Categorie	Ce face	Ce nu face
API de calcul al taxelor	Returnează cota corectă sau valoarea taxei pentru o tranzacție	Nu ține contabilitatea și nu stochează dovezile din spatele deciziei pe perioada de arhivare
API de plăți	Transferă bani între părți și raportează despre acele mișcări	Nu înregistrează comisionul câștigat, TVA-ul datorat sau datoria față de un vânzător între momentul plății și cel al decontării
API unificat sau de tip agregator	Citește și scrie date în software-ul contabil existent al clientului tău	Nu acționează ca sistem de evidență principal (system of record); contabilitatea ta se află în unealta pe care fiecare client o folosește deja
API de raportare sau BI	Citește cifre dintr-un registru existent și le vizualizează	Nu creează înregistrările din care derivă acele cifre

Fiecare dintre acestea are utilizări reale. O platformă care trebuie să fie sistemul de evidență principal are nevoie de API-ul de contabilitate la bază, nu în locul acestuia.

Cele cinci lucruri pe care trebuie să le facă un API de contabilitate

1. Înregistrează intrări echilibrate. Fiecare eveniment devine debite și credite care însumează aceeași valoare. Când un cumpărător plătește 100 € pe o piață online (marketplace) care percepe un comision de 15 €, înregistrarea debitează un cont de trecere (clearing) cu 100 €, creditează datoria către vânzător cu 85 € și creditează veniturile din comisioane cu 15 €. Aceasta nu este birocrație contabilă. Este o verificare structurală care depistează categorii întregi de erori de integrare înainte ca acestea să ajungă într-un raport.

2. Păstrează istoricul. O înregistrare publicată (posted) nu se editează. O greșeală se corectează printr-o stornare urmată de o înregistrare corectă, ambele legate de cea originală. Lunile închise sunt blocate astfel încât să nu se poată data nicio înregistrare nouă în ele.

3. Gestionează taxele. Pentru comerțul din UE, aceasta înseamnă locul prestării/livrării, taxarea inversă (reverse charge), codurile de TVA verificate înregistratul oficial VIES și dovezile care au justificat decizia, toate stocate alături de tranzacție în loc să fie aruncate după calcul.

4. Face reconcilierea cu banii din exterior. Niște registre contabile care nu se întâlnesc niciodată cu un extras de cont sunt doar o presupunere. API-ul trebuie să preia extrasele bancare sau deconturile furnizorilor de plăți și să le potrivească cu ceea ce s-a înregistrat.

5. Exportă. Rapoarte, documente și fișiere de audit, în formate acceptate de un contabil uman și de o autoritate fiscală.

Un produs care le face pe primele trei, dar nu le face pe ultimele două, va lăsa în continuare o persoană să lucreze în foi de calcul (spreadsheets) în fiecare lună.

Cum arată de fapt un apel

Mecanica este mai simplă decât contabilitatea. În API-ul Nordlet, fiecare operațiune este de tip RPC prin POST, având o formă previzibilă:

POST /v1/{module}/{resource}/{action}
Authorization: Bearer <api key>
Idempotency-Key: <your event id>

Creezi o factură de vânzare, apoi o emiți. Emiterea este momentul în care se produce contabilitatea: documentul primește numărul său secvențial fără întreruperi, nota contabilă echilibrată este înregistrată, iar liniile de TVA sunt salvate odată cu aceasta. Platforma ta nu asamblează niciodată manual debite și credite.

Trei detalii din acest fragment contează mai mult decât numele endpoint-ului:

Domeniul de aplicare (scope) al cheii. O cheie poartă permisiuni precum sales:write, astfel încât o integrare să primească doar accesul de care are nevoie.
Cheia de idempotență (idempotency key). Redă aceeași cerere cu același conținut (payload) și vei primi înapoi răspunsul stocat, nu o a doua factură. Trimite aceeași cheie cu un conținut diferit, iar cererea va fi respinsă cu eroarea idempotency_key_reuse, în loc să fie acceptată în tăcere.
Banii sub formă de șiruri de caractere (strings). Sumele sunt șiruri zecimale, nu numere cu virgulă mobilă (floating-point), deoarece numerele cu virgulă mobilă pierd cenți în moduri care devin vizibile la sfârșitul anului.

Unde se situează în arhitectura ta

Aplicația ta rămâne interfața cu utilizatorul (front end) și sursa evenimentelor de business. API-ul de contabilitate devine sistemul financiar de evidență din spatele acesteia. Fluxul este de obicei următorul:

Se întâmplă ceva în produsul tău: o comandă, o rambursare, o plată către un partener (payout), o reînnoire de abonament.
Backend-ul tău apelează API-ul de contabilitate cu evenimentul și o cheie de idempotență.
API-ul înregistrează nota contabilă, aplică TVA-ul și returnează identificatori pe care îi stochezi alături de propriile înregistrări.
Un webhook precum sale_invoice.paid informează sistemul tău când se schimbă starea, astfel încât să reacționezi la evenimente în loc să le cauți prin interogări periodice (polling).
Tranzacțiile bancare sosesc printr-un flux bancar (bank feed) sau prin importul unui extras și sunt comparate cu documentele înregistrate.
La sfârșitul perioadei, rapoartele și jurnalele de taxe sunt generate din aceleași date, iar luna închisă este blocată.

Nimic din această listă nu necesită ca un om să deschidă o aplicație de contabilitate. Acesta este scopul acestei categorii.

Cum se compară cu alternativele

Abarcare	Efort de pornire	Poziție în fața auditului	Scalare odată cu volumul de tranzacții
Foi de calcul și introducere manuală	Cel mai scăzut	Slabs istoricul este edictabil	Nu
Aplicație contabilă plus exporturi CSV	Scăzut	Depinde în întregime de disciplină	Slab; cineva trebuie să importe fișiere
API de agregare în contabilitatea fiecărui client	Mediu	Moștenește ce poate unealta clientului	Da, dar nu deții niciodată înregistrarea
API de contabilitate încorporat (embedded)	Mediu	Puternic dacă registrul este imutabil și perioadele se blochează	Da
Construirea propriului registru	Cel mai ridicat	Puternic doar dacă construiești și controalele	Da, și îl menții pentru totdeauna

Construirea propriei soluții este o alegere legitimă pentru unele echipe. Este tratată mai detaliat în ghidul nostru despre construirea versus achiziționarea unei soluții pentru piețe online (marketplaces).

Ce să verifici înainte de a te integra cu un API

Soldul este derivat sau stocat? Întreabă dacă soldul unui vânzător este rezultatul unei interogări pe liniile contabile sau o coloană pe care o actualizează cineva. Doar una dintre variante supraviețuiește unui audit.
Ce se întâmplă în cazul unei reîncercări (retry)? Trimite aceeași cerere de două ori și numără înregistrările.
Poți edita o înregistrare publicată? Răspunsul ar trebui să fie nu, însoțit de o metodă documentată de corectare.
O perioadă blocată respinge efectiv o înregistrare? Testează acest lucru într-un mediu de test (sandbox). Nordlet returnează 409 pentru o înregistrare datată într-o perioadă blocată.
Cum sunt reprezentați banii? Prin șiruri zecimale sau unități monetare subunitare întregi (minor units). Niciodată prin numere cu virgulă mobilă (floats).
Ce conține înregistrarea de audit (audit record)? Actorul, acțiunea, entitatea și modificarea însăși, care să poată fi interogate în loc să fie îngropate în fișiere jurnal (log files).
Care sunt limitele de apel (rate limits)? Nordlet permite 300 de cereri pe minut per cheie API și raportează bugetul rămas în antetele de răspuns (response headers). Indiferent care este numărul, află-l înainte de a-ți proiecta sincronizarea.
Cum îți scoți datele din sistem? Rapoarte, documente și jurnale, în formate pe care le poți preda unui contabil.

Fiecare dintre aceste aspecte poate fi testat într-o după-amiază pe o companie de test (sandbox company). Listele de funcționalități ale furnizorilor nu constituie dovezi; un test care poate fi reprodus, da.

FAQ

Este un API de contabilitate același lucru cu un program de contabilitate?

Este un program de contabilitate căruia i s-a mutat interfața. Software-ul contabil tradițional pune o persoană în fața registrului; un API de contabilitate pune codul tău acolo. Obligațiile de bază, structura în partidă dublă și rapoartele sunt aceleași.

Mai am nevoie de un contabil dacă folosesc unul?

Da. Un API automatizează înregistrarea, calculul și raportarea. Nu ia decizii de judecată profesională cu privire la clasificare, provizioane sau modul în care ar trebui tratat un anumit contract și, în cele mai multe țări, nu semnează și nu depune situațiile financiare anuale.

Pot folosi un API de contabilitate fără să înțeleg partida dublă?

Parțial. Un API bun construiește notele contabile pentru tine pe baza unui document de afaceri, cum ar fi o factură. Tot trebuie să înțelegi ce înseamnă conturile atunci când citești un raport sau când explici un sold unui auditor.

Care este diferența dintre un API de contabilitate și un API de tip registru (ledger API)?

Un API de registru înregistrează mișcări echilibrate între conturi. Un API de contabilitate face acest lucru și adaugă stratul legal deasupra: documente cu numerotare legală, tratament pentru TVA, jurnale de taxe, mijloace fixe, închiderea perioadei și rapoartele pe care o jurisdicție le așteaptă. Orice API de contabilitate conține un registru, dar nu orice registru este un sistem contabil.

Cât durează o astfel de integrare?

Pentru un primul flux funcțional - crearea unui client, emiterea unei facturi, încasarea unei plăți, vizualizarea notei contabile -, planifică mai curând în zile decât în săptămâni, folosind un SDK cu tipuri de date (typed SDK) și un mediu sandbox. O integrare de producție care acoperă rambursări, corecții, multi-valută, reconciliere și închiderea perioadei reprezintă o muncă mai amplă, iar estimarea onestă depinde de câte dintre aceste cazuri generează efectiv produsul tău.