Lista firmelor cu datorii la ANAF, filtrată pe județ și CAEN prin API

Să zicem că vrei toate firmele de construcții din Cluj care datorează statului peste 100.000 de lei. Sau vrei să știi câți distribuitori dintr-o regiune au intrat pe lista de restanțe în ultimul trimestru. Verificarea pe o singură firmă nu te ajută aici. Ai nevoie de lista întreagă, filtrată cum vrei tu.

API-ul Datorii ANAF are o rută pentru exact asta. Întoarce toate firmele de pe o listă ANAF de restanțe, fiecare cu profilul complet din registru și cu dosarul ei de restanțe.

Cine are nevoie de lista întreagă

Cel mai des o folosesc echipele de vânzări, ca să-și curețe listele de prospectare: scot din campanie firmele cu restanțe mari înainte să piardă cineva o săptămână cu ele. Analiștii o folosesc pentru sectoare, ca să vadă câte firme dintr-un domeniu și dintr-un județ au datorii la stat și cât datorează împreună. Departamentele de credit compară lista cu portofoliul lor și află cine a intrat pe ea. Iar jurnaliștii și cercetătorii urmăresc cum se mișcă restanțele într-o zonă sau într-o industrie de la un trimestru la altul.

Ruta și filtrele

Cererea e GET /api/v1/fiscal/restante. Fără niciun filtru primești cea mai nouă listă, sortată de la cea mai mare datorie. Filtrele sunt de două feluri: unele țin de restanțe, altele de registru.

Filtrele de restanțe

• publicare: data listei ANAF, în format AAAA-LL-ZZ. Toate listele disponibile vin în meta.publicari_disponibile.
• total_minim și total_maxim: totalul restant în lei, fără separator de mii, de exemplu total_minim=50000.
• buget: stat, asigurari_sociale, somaj, sanatate. Primești firmele cu restanțe la oricare dintre bugetele date.
• situatie: insolvabil, faliment, insolventa sau fara, pentru firmele fără mențiune.
• contestate: da pentru firmele care contestă o parte din sume, nu pentru cele care nu contestă nimic.
• evolutie: crestere, scadere, stabil sau noua, față de lista anterioară.
• sortare: total_desc (implicit), total_asc, variatie_desc pentru cea mai mare creștere sau variatie_asc.

Filtrele din registru

Peste ele poți pune orice filtru de la căutarea de firme: judet, regiune, localitate, siruta, mediu, cod_postal, caen, caen_exclus, tip, stare, capital, q, filtrele fiscale platitor_tva, e_factura, inactiv_fiscal și tva_la_incasare, plus intervalele inregistrate_de_la / inregistrate_pana_la și inactivate_de_la / inactivate_pana_la.

Regula de combinare e aceeași ca peste tot. Filtrele diferite se leagă cu ȘI, iar mai multe valori ale aceluiași filtru, despărțite prin virgulă, înseamnă SAU. judet=CJ,TM înseamnă Cluj sau Timiș. Codul CAEN merge la orice nivel: clasă (4120), grupă (41.2), diviziune (41) sau secțiune (F).

Trei cereri, de la simplu la specific

Prima: firmele din construcții (diviziunea 41) din Cluj, cu restanțe de cel puțin 50.000 de lei, în sandbox. Sandbox-ul cere o cheie API, deci un cont. Contul e gratuit și fără card, iar cererile din sandbox nu consumă credite și primesc date fictive.

curl -H "X-API-KEY: cheia-ta" \
  "https://www.bilantapi.ro/api/sandbox/v1/fiscal/restante?judet=CJ&caen=41&total_minim=50000"

A doua: firmele din regiunea Vest care au intrat pe listă în ultimul trimestru.

/api/v1/fiscal/restante?regiune=vest&evolutie=noua

A treia, mai țintită: transportul rutier de mărfuri (clasa 4941), cu cea mai mare creștere a datoriei la asigurările sociale.

/api/v1/fiscal/restante?caen=4941&buget=asigurari_sociale&evolutie=crestere&sortare=variatie_desc

Pe ultima o găsesc cea mai interesantă. O firmă de transport care nu mai virează contribuțiile pentru șoferi, și suma crește de la o listă la alta, e un semnal pe care nu-l ignori.

Ce vine în fiecare rezultat

Fiecare element din data[] are profilul complet din registru, în aceeași formă ca la /registru/firme/{cui}: denumire, adrese cu SIRUTA, CAEN, stare, regim de TVA. Lângă el, câmpul restante are același dosar ca la ruta pentru o singură firmă: totalul, structura pe principal și accesorii, bugetele, situația, evoluția și istoricul.

În meta.sumar afli câte firme trec de filtre (firme) și cât datorează împreună (total_restant). În meta.taxare ai credite_pe_rezultat, rezultate_taxate și credite, adică totalul cererii. Data listei folosite e în meta.publicare.

Rezultatele vin pe pagini. Ceri pagina cu ?pagina=N&pe_pagina=M: implicit primești 20 de firme pe pagină, iar maximul e 50. În meta.paginare ai pagina, pe_pagina, total și pagini.

Banii

Lista costă 10 credite pe rezultat. Informația e bogată, deci prețul are sens, dar o cerere prea largă te poate costa surprinzător de mult. Greșeala clasică e să ceri „toată țara, tot ce are restanțe” și să te uiți abia apoi ce ai primit.

Eu pornesc întotdeauna îngust, cu județul, codul CAEN și un prag minim de sumă, și lărgesc doar dacă e nevoie. Prima cerere o fac cu pe_pagina=1, care costă 10 credite. Răspunsul îmi arată în meta.sumar.firme câte firme trec de filtre în total. Dacă numărul e mult mai mare decât mă așteptam, strâng filtrele înainte să merg mai departe.

Pragul de sumă e prietenul tău. Pentru majoritatea deciziilor comerciale, datoriile foarte mici nu schimbă nimic, iar un total_minim potrivit taie mult din listă. Și nu cere aceeași listă de două ori: listele ANAF se schimbă trimestrial, deci păstrezi rezultatul și îl reîmprospătezi doar când apare o publicare nouă.

Un calcul pe care merită să-l faci: dacă ai deja CUI-urile, de exemplu portofoliul de clienți, e adesea mai ieftin să verifici fiecare firmă pe ruta individuală, la trei credite, decât să descarci o listă largă și să cauți în ea. Depinde de câți clienți ai și de cât de largă ar fi lista.

O privire pe sector, din totaluri

Pentru o analiză de piață nu ai nevoie mereu de fiecare firmă în parte. Totalurile din meta.sumar, cerute pentru mai multe județe sau pentru liste succesive, îți arată unde se strâng restanțele și dacă problema crește. Poți compara aceeași diviziune CAEN în două regiuni, sau aceeași regiune pe două trimestre la rând, cu parametrul publicare. Pui cifrele într-un tabel simplu și vezi repede dacă un domeniu o duce greu.

Capcane

Lista nu e un registru complet al datoriilor. Apar doar firmele peste pragul legal de publicare. Sumele contestate intră în total, așa că dacă vrei să le separi, te uiți în structura din dosar.

A treia capcană prinde pe toată lumea măcar o dată: localitatea se potrivește exact. localitate=Cluj nu găsește Cluj-Napoca. Când un nume e purtat de mai multe localități, adaugă și județul.

Și o vorbă despre bun-simț. ANAF publică listele tocmai ca să fie consultate, dar dacă le folosești ca să contactezi firme, nu le trimite mesaje agresive pe tema datoriilor. Datele despre oamenii din spatele firmelor sunt supuse regulilor de protecție a datelor personale.

Unde găsești restul

Filtrele sunt descrise pe pagina API Datorii ANAF. Codurile CAEN le cauți gratuit în nomenclator, de exemplu GET /api/v1/caen/nomenclator?q=transport, cu parametrii q, sectiune și limita. Regiunile se scriu după nume (nord-est, sud-est, sud-muntenia, sud-vest-oltenia, vest, nord-vest, centru, bucuresti-ilfov) sau după număr, de la 1 la 8. Detaliile sunt în documentație, iar dacă vrei să vezi cum se împart firmele pe domenii și județe, poți răsfoi registrul firmelor.

Cele 250 de credite gratuite pe care le primești la înregistrare, fără card, înseamnă 25 de firme pe lista de restanțe. Destul pentru o primă listă îngustă, cât să vezi dacă datele îți folosesc.