API bilanț: situațiile financiare ale oricărei firme, din 2008 până azi

Situațiile financiare ale firmelor din România sunt publice. Asta nu le face și ușor de folosit: Ministerul Finanțelor le publică câte un formular pe an, cu rânduri numerotate care s-au tot mutat de-a lungul timpului. Pentru o singură firmă copiezi cifrele de mână și gata. Când ai sute de clienți, sau vrei cifrele direct în aplicația ta, copiatul nu mai ține.

Mai jos găsești ce întoarce API-ul Bilanț de la BilantAPI.ro, cât costă fiecare rută și cum arată primele cereri. Le poți rula în sandbox, unde nu consumi credite.

Ce date primești

Acoperirea pornește din 2008 și cuprinde bilanțurile depuse la Ministerul Finanțelor pentru aproximativ 1,95 milioane de firme. Datele se actualizează anual, după ce firmele își depun situațiile financiare. Partea care m-a scutit personal de cele mai multe bătăi de cap: câmpurile au aceleași denumiri în toți anii, indiferent de formularul folosit la depunere. Nu mai ții minte că rândul cutare s-a mutat sau și-a schimbat numărul în 2014.

Pentru fiecare exercițiu financiar ai contul de profit și pierdere, în lei: cifra_afaceri, venituri_totale, cheltuieli_totale, profit_brut și pierdere_bruta, profit_net și pierdere_neta. Din bilanț vin active_imobilizate, active_circulante (cu stocuri, creante și casa_si_conturi separat), datorii, capitaluri, provizioane și capital_subscris_varsat.

Mai primești angajati, adică numărul mediu de salariați declarat de firmă, și câteva câmpuri de context: caen și denumire_caen pentru activitatea principală din cel mai recent an, numar_ani (câți ani sunt disponibili) și actualizat_la.

Cifrele din formular stau, pentru fiecare an, în obiectul date. Câmpul tip_bilant îți spune formatul: standard la marea majoritate a firmelor și alte valori la IFN-uri, SIF-uri și ONG-uri, care depun alt formular. Merită să-l verifici înainte să compari două firme între ele.

Peste cifrele brute vin calculele pe care altfel le-ai face în Excel. În indicatori ai rezultat_net cu semn, marja_neta, marja_bruta, roe, roa, lichiditate_curenta, grad_indatorare, capital_de_lucru, ca_per_angajat și profit_per_angajat. În evolutie ai creșterea de la an la an a cifrei de afaceri, a rezultatului și a angajaților, plus rata medie anuală de creștere a cifrei de afaceri, cagr_ca. Iar risc aduce un scor de la 0 la 100, o clasă de la A la E, factorii care l-au stabilit și scorul Altman Z''.

Rutele și cât costă fiecare

Multe aplicații nu au nevoie de tot istoricul, așa că API-ul e împărțit în rute mai mici, fiecare cu un cost fix în credite:

Rută	Ce întoarce	Cost
GET /api/v1/bilant/{cui}/{an}	Bilanțul unui singur exercițiu financiar	1 credit
GET /api/v1/bilant/{cui}	Toți anii, cu datele, indicatorii și evoluția	1 credit
GET /api/v1/bilant/{cui}/sumar	Cifrele principale din ultimul an	1 credit
GET /api/v1/bilant/{cui}/indicatori	Marje, lichiditate, îndatorare, pe ani	2 credite
GET /api/v1/bilant/{cui}/evolutie	Serie multi-an, cu creșteri și CAGR	2 credite
GET /api/v1/bilant/{cui}/pozitie	Locul în sector, percentila, raportul față de mediană	3 credite
GET /api/v1/bilant/{cui}/risc	Scor 0–100, clasă A–E, factori, semnale, Altman Z''	3 credite

Uită-te la primele două rânduri. Bilanțul complet, cu toți anii, costă tot un credit, cât un singur an. Dacă ai nevoie de istoric, ceri ruta completă o dată și nu mai iei anii pe rând.

Prima cerere, în sandbox

Pentru sandbox ai nevoie de o cheie API, deci de un cont. Contul e gratuit și nu cere card. Cererile de acolo nu consumă credite și primesc date fictive, iar fără cont poți folosi doar butonul „Încearcă” de pe paginile de produs. Eu aș începe mereu de aici, ca să văd forma răspunsului înainte să scriu o linie de integrare. CUI-ul de test este 90000010:

curl -H "X-API-KEY: cheia-ta" \
  https://www.bilantapi.ro/api/sandbox/v1/bilant/90000010/sumar

Răspunsul are forma {"success": true, "data": {...}}. La sumar, cifrele stau în data.sumar: data.sumar.cifra_afaceri, data.sumar.rezultat_net, data.sumar.angajati. Listele au în plus un obiect meta, cu paginarea și taxarea. O eroare vine cu "success": false și cu câmpurile error, code și message, de exemplu BILANT_NOT_FOUND.

În producție, antetele HTTP X-Credit-Cost, X-Credit-Charged și X-Credit-Balance îți spun cât costă cererea, cât ți s-a scăzut efectiv și ce sold mai ai. Cererile fără rezultat și erorile 400 nu consumă credite. Ca să treci pe producție schimbi adresa de bază în https://www.bilantapi.ro/api/v1 și pui cheia reală. Cheia merge în antetul X-API-KEY sau ca Bearer token. OAuth nu există, deci n-ai fluxuri de autorizare de întreținut.

Istoricul unei firme în Python

Să zicem că vrei cifra de afaceri și profitul net ale unui partener pe ultimii trei ani, ca să le pui în fișa lui din CRM. Varianta cea mai directă e să ceri fiecare an pe ruta de un an:

import requests

BAZA = "https://www.bilantapi.ro/api/sandbox/v1"
ANTETE = {"X-API-KEY": "cheia-ta"}

for an in (2021, 2022, 2023):
    r = requests.get(f"{BAZA}/bilant/90000010/{an}", headers=ANTETE)
    if r.status_code != 200:
        continue
    d = r.json()["data"]
    cifre = d["date"]
    print(an, cifre.get("cifra_afaceri"), d["indicatori"]["rezultat_net"], cifre.get("angajati"))

Cifrele din formular sunt în data.date, iar rezultatul cu semn în data.indicatori.rezultat_net. Greșeala pe care o văd des e citirea lui profit_net ca rezultat: la o firmă pe pierdere, profit_net e 0, iar pierderea stă în pierdere_neta. Cine face media pe profit_net ajunge să creadă că firma a stat pe zero.

Codul de mai sus e bun ca exemplu, dar în producție l-aș scrie altfel. Trei cereri costă trei credite, pe când o singură cerere la /bilant/{cui} îți aduce toți anii, cu evoluția calculată, pentru unul. Anii vin în data.ani, fiecare cu an, tip_bilant, date și indicatori. Structura exactă a răspunsului pentru fiecare rută e în documentație, unde e și fișierul OpenAPI.

Ce rută pentru ce treabă

Când cineva introduce un CUI într-un formular sau deschide fișa unui client, /sumar e de ajuns. Îți dă cifrele principale din ultimul an în data.sumar și indicatorii acelui an în data.sumar.indicatori. Pentru un ecran de prezentare asta vrei să vezi: cât vinde firma, cât câștigă, câți oameni are.

Analiza de credit cere mai mult. Înainte să dai termen de plată unui client nou, te interesează dacă are capitaluri pozitive, lichiditate și profit. /indicatori îți dă rapoartele pe ani, iar /risc adaugă scorul și factorii care îl explică. Un scor mare înseamnă risc mic: clasa A e între 80 și 100, clasa E sub 35. Pune scorul în regulile de aprobare și păstrează factorii ca justificare a deciziei, pentru că peste șase luni cineva o să întrebe de ce ai aprobat. Detaliile de calcul sunt pe pagina metodologiei scorului de risc.

Pentru partenerii cu care lucrezi ani la rând, un an bun spune puțin. /evolutie arată dacă firma crește constant sau doar se menține, iar /pozitie o pune lângă celelalte firme din același sector.

Ce te poate încurca

Datele vin anual. Bilanțul pe un an apare după termenul de depunere, așa că cel mai nou exercițiu disponibil poate fi cel de anul trecut sau cel de acum doi ani, în funcție de luna în care faci cererea. Dacă cineva din vânzări se plânge în martie că „lipsesc cifrele de anul ăsta”, asta e explicația.

Nu toate firmele depun. O firmă nouă sau una care nu și-a depus situațiile nu are încă bilanț, deci nu primești rezultat și nici nu plătești. CAEN-ul din bilanț e cel din cel mai recent an; pentru toate activitățile autorizate există un API separat.

Și salvează răspunsurile. Un bilanț depus nu se schimbă de la o zi la alta. Îl ții în baza ta și îl reînnoiești după sezonul de depunere, în loc să-l ceri din nou la fiecare deschidere de fișă.

Toate rutele și câmpurile sunt pe pagina API-ului Bilanț. La înregistrare primești 250 de credite gratuite, fără card. Ajung pentru bilanțul complet a 250 de firme, deci poți verifica pe clienții tăi dacă datele îți folosesc.