Verificare firmă după CUI prin API: cum arată cererea și ce citești din răspuns

Un client nou îți trimite CUI-ul pe email și tu trebuie să-l bagi în sistem. Varianta clasică o știi: deschizi site-ul ANAF, copiezi denumirea, apoi adresa, apoi te uiți la TVA și speri că n-ai greșit nicio cifră. Merge la cinci firme pe lună. La cincizeci pe zi, devine o sursă sigură de greșeli, așa că eu aș lăsa aplicația să aducă datele singură, cu API-ul Informații firmă de la BilantAPI.

Ce vine înapoi când trimiți un CUI

Ruta este GET /api/v1/registru/firme/{cui}. Întoarce profilul fiscal al firmei din registrul ANAF, actualizat zilnic, costă un credit pe cerere și acoperă 5,5 milioane de entități. Răspunsul e mai bogat decât pare la prima vedere, așa că merită să știi unde stă fiecare lucru.

Partea de identitate are cui (un număr, nu text), denumire, numar_registru (numărul de la registrul comerțului, de forma J29/3234/2006), data_inregistrare, forma_juridica și stare, adică starea firmei în registru, de exemplu ACTIVA. Activitatea principală e în caen_principal, cu cod și denumire.

Adresele vin în două obiecte, sediu_social și domiciliu_fiscal, împărțite pe câmpuri și cu codurile SIRUTA și NUTS. Dacă ai nevoie de rapoarte pe zone, uită-te în sediu_social.siruta_detalii: acolo ai tipul localității, mediul, comuna sau orașul de care ține, județul și regiunea.

Partea fiscală e cea pe care o vei citi cel mai des. fiscal.platitor_tva e true sau false, iar fiscal.perioade_tva păstrează istoricul. Trei obiecte au starea în câmpul activ: fiscal.tva_la_incasare, fiscal.split_tva și fiscal.inactiv. Înscrierea în e-Factura e în fiscal.e_factura.inscris, cu data în fiscal.e_factura.de_la.

Mai ai stare_juridica, cu starea de la registrul comerțului și trei indicatori: in_insolventa, in_lichidare și in_dizolvare. La final, câteva date declarate la înregistrarea fiscală: iban, fax și cod_postal_declarat.

Ce nu găsești aici sunt telefoanele, emailurile și reprezentanții legali. Ele stau în API-ul Date de contact, pe o rută separată, pentru că au altă sursă și alt cost. Lumea le caută des în profilul fiscal și se miră că lipsesc.

Primul apel îl faci în sandbox

Dacă vrei doar să vezi un răspuns, nu-ți trebuie nici cont. Apeși „Încearcă” pe pagina API Informații firmă și gata. Din codul tău lucrezi în sandbox, care cere o cheie API, deci un cont. Contul e gratuit și nu cere card. Cererile din sandbox nu consumă credite și primesc date fictive, iar CUI-ul de test este 90000010:

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

Forma răspunsului e mereu aceeași: {"success": true, "data": ..., "meta": ...}. Profilul stă în data, iar identificatorul firmei e data.cui, ca număr. Uită-te și la antetele HTTP. X-Credit-Cost îți spune cât costă ruta, X-Credit-Charged cât ți s-a scăzut efectiv (în sandbox e mereu 0), iar în producție primești și X-Credit-Balance, soldul rămas.

Trecerea în producție e banală. Schimbi adresa de bază în https://www.bilantapi.ro/api/v1 și pui cheia reală. Dacă biblioteca ta HTTP preferă antetul Authorization, cheia merge trimisă și ca Bearer token.

Același apel în PHP și JavaScript

PHP

$cui = '90000010';
$ch = curl_init("https://www.bilantapi.ro/api/sandbox/v1/registru/firme/$cui");
curl_setopt_array($ch, [
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_HTTPHEADER => ['X-API-KEY: ' . getenv('BILANTAPI_KEY')],
]);
$raspuns = json_decode(curl_exec($ch), true);
$firma = $raspuns['data'];
echo $firma['denumire'] . ' - ' . $firma['stare'];

JavaScript

const cui = '90000010';
const r = await fetch(`https://www.bilantapi.ro/api/sandbox/v1/registru/firme/${cui}`, {
  headers: { 'X-API-KEY': process.env.BILANTAPI_KEY }
});
const { data } = await r.json();
console.log(data.cui, data.denumire, data.fiscal.platitor_tva, data.fiscal.inactiv.activ);

Un singur lucru la care te rog să fii atent: cheia stă în variabile de mediu, nu în codul care ajunge în browser. Dacă ai un formular public unde omul își scrie CUI-ul, apelul trece prin serverul tău. Am văzut chei lipite direct în JavaScript-ul din pagină și nu se termină frumos.

Patru câmpuri pe care le citesc primele

Profilul are zeci de câmpuri, dar decizia dacă mergi mai departe cu un partener se ia de obicei pe patru.

Primul e starea. Citești stare și, lângă ea, stare_juridica.in_insolventa, in_lichidare și in_dizolvare. O firmă radiată nu mai poate primi facturi, iar cu una în insolvență discuția comercială arată altfel. Pentru detalii despre procedură, avem un articol separat despre ce înseamnă insolvența unei firme.

Al doilea e fiscal.inactiv.activ. Un partener declarat inactiv fiscal îți poate strica deducerea cheltuielilor și a TVA-ului. Eu l-aș bloca explicit în aplicație, cu mesaj clar, nu doar cu un avertisment pe care îl închide toată lumea.

Al treilea e fiscal.platitor_tva, care decide dacă factura are TVA și ce mențiuni poartă. Fiecare perioadă din fiscal.perioade_tva are de_la, pana_la și data_anularii, deci vezi exact din ce dată e valabilă înregistrarea. Contează când facturezi retroactiv sau când clientul tocmai s-a înregistrat.

Al patrulea sunt regimurile speciale: fiscal.tva_la_incasare.activ și fiscal.split_tva.activ. Ele schimbă felul în care emiți și încasezi factura, iar contabilitatea te va întreba de ele mai devreme sau mai târziu.

Restul, adică adresele cu SIRUTA sau activitatea principală, e bun pentru fișa de client și pentru rapoarte pe județe sau domenii. Util, dar nu te oprește din facturat.

Unde se împiedică lumea

CUI-ul vine în zece forme

Oamenii scriu CUI-ul cu „RO” în față, cu spații, cu puncte, uneori cu tot cu un „CIF:” copiat din factură. Curăță intrarea înainte de apel și păstrează doar cifrele. Căutarea de firme acceptă în parametrul q CUI-ul cu prefixul RO sau fără, dar ruta de profil primește în cale doar cifre. Cu „RO” în față, cererea nu ajunge la profil.

CUI-ul nu există

Atunci nu primești profil, ci un 404 cu "success": false și codul COMPANY_NOT_FOUND. Tratează-l ca pe o greșeală de tastare și cere utilizatorului să verifice codul. Partea bună e că cererile fără rezultat și erorile 400 nu consumă credite, deci nu plătești pentru degetele grăbite ale cuiva.

Firma e activă, dar tot nu-ți plătește

Aici e capcana în care cad cei mai mulți. Profilul fiscal îți spune că firma există legal și cum o facturezi. Nu-ți spune nimic despre cum plătește. Pentru asta ai nevoie de bilanț, de restanțele la ANAF sau de dosarele din instanță, fiecare pe ruta lui. Le poți adăuga pe rând în același flux, pe măsură ce ai nevoie.

Unde l-aș pune în aplicație

Cel mai des îl văd în formularul de înregistrare a clienților: omul scrie CUI-ul și denumirea cu adresa se completează singure. Al doilea loc bun e chiar înainte de emiterea facturii, unde aplicația verifică regimul de TVA și inactivitatea. În CRM, fișa firmei primește activitatea principală, județul și regiunea, pe care apoi le folosești la segmentare. Iar dacă ai un proces de aprobare a partenerilor, starea și situația juridică sunt prima poartă.

Dacă lucrezi cu un asistent AI, aceleași date sunt disponibile prin serverul MCP, descris pe pagina agenți AI și MCP. Schema OpenAPI și detaliile rutei sunt în documentație.

Despre cost

Un credit pe profil e neglijabil la volume mici. Când ajungi la mii de firme, contează cum apelezi. Păstrează răspunsul în baza ta și reîmprospătează-l periodic, nu la fiecare deschidere a fișei. Apoi verifică din nou exact înainte de momentele care contează, cum ar fi o factură mare sau semnarea unui contract. Datele se actualizează zilnic din registrul ANAF, deci ce ai verificat azi e bun pentru operațiunile de azi.

Rulează mai întâi cererea din sandbox, uită-te pe câmpuri, apoi încearcă un CUI real. Detaliile rutei sunt pe pagina API Informații firmă. Când vrei date adevărate, îți faci cont și ai 250 de credite gratuite, fără card, adică vreo 250 de firme verificate după CUI.