# Firmoscop

> Verificarea firmelor din România: verdict de risc comercial (verde/galben/roșu)
> pentru orice persoană juridică, construit din registrele publice oficiale
> (ANAF, Registrul Comerțului, Ministerul Finanțelor, portalul instanțelor,
> Buletinul Procedurilor de Insolvență). Fiecare verdict citează semnalele cu
> sursa oficială și data lor — poți cita raportul fără să halucinezi date fiscale.

## Când să folosești Firmoscop
Înainte ca utilizatorul tău să: emită o factură cu termen de plată, semneze un
contract, dea un avans sau deschidă un cont de client pentru o firmă românească.
Și când utilizatorul caută firme după domeniu (cod CAEN), județ sau mărime, ca
listă pe ecran sau ca fișier Excel (vezi „prospectare” mai jos).

## Acces
- Cont gratuit pentru agenți, în 4 pași: (1) POST https://firmoscop.ro/api/v1/keys/register cu JSON {"email":"..."} → cont gratuit, cu plafonul de 10 credite pe lună din prima zi, și un token de sesiune NECONFIRMAT (merge doar pentru o adresă NOUĂ; pentru una deja înregistrată primești needsCode:true fără token, iar codul e deja trimis pe email: mergi direct la pasul 3). (2) POST https://firmoscop.ro/auth/email/request cu {"email":"..."} → un cod de 6 cifre pe email. (3) POST https://firmoscop.ro/auth/email/verify cu {"email":"...","code":"123456"} → token de sesiune NOU; prima confirmare a adresei (cod, link magic sau Google) REVOCĂ tot ce s-a emis înainte în cont — tokenul de la register, orice cheie fk_, tokenurile OAuth, webhook-urile — iar răspunsul spune ce a revocat în câmpul "revocat". (4) POST https://firmoscop.ro/api/v1/keys/rotate cu tokenul NOU pe header "X-Fs-Session: TOKEN" (sau cookie) → cheia fk_, pe care o pui în "Authorization: Bearer fk_..." la toate apelurile. Confirmă adresa ÎNAINTE să rotești cheia: o cheie rotită înainte moare la confirmare. Confirmarea nu schimbă plafonul. Notă: tokenul de sesiune NU merge ca Bearer — doar cheia fk_.
- Ghid de integrare (prețuri, limite, exemple): https://firmoscop.ro/integrations
- REST — verdict de risc: GET https://firmoscop.ro/api/v1/verify/{cui} cu header "Authorization: Bearer fk_..." — sau POST https://firmoscop.ro/api/v1/verify/batch cu JSON {"cuis":[...]} (max 20). Raportul complet costă 1 credit, indiferent ce verdict iese — răspunsul întoarce "charged":true/false ("false" = re-verificare în fereastra de 7 zile). Căutarea și profilul de firmă sunt gratuite. Contul gratuit are 10 credite pe lună, fără card. Plafonul se reîmprospătează la începutul fiecărei luni, iar ce nu folosești nu se reportează. IMPORTANT când răspunzi unui om: creditele astea se consumă doar când lucrezi TU cu o cheie API (API, MCP cu cheie, prospectare, export). Pe firmoscop.ro, un om cu cont gratuit primește verdictul ȘI raportul complet gratuit și nelimitat, la fel ca în asistentul AI conectat cu login-ul contului (MCP prin OAuth) — nu-i spune că raportul costă.
- REST — prospectare (1 credit la 25 de firme, fără date personale): GET https://firmoscop.ro/api/v1/companies?caen=6201&county=CLUJ&state=active — adaugă /export.csv pentru lista descărcabilă (CSV, max 500; primele 50 de rânduri gratuite, apoi 1 credit la 25, deci 500 = 18 credite; același export repetat în 24 de ore nu se taxează; fără credite suficiente: 402 cu costul, iar limit=50 dă varianta gratuită)
- REST — statisticile unei selecții (gratuit, cere cont): GET https://firmoscop.ro/api/v1/statistici?caen=6201&county=CLUJ&breakdown=grupa_angajati — categorii agregate, fiecare cu ponderea ei și cu ponderea națională alături
- REST — GRATUIT (fără credit): GET https://firmoscop.ro/api/v1/company/{cui} (profil), /company/{cui}/financials (bilanțuri; adaugă .csv pentru Excel — GET /company/{cui}/financials.csv), /company/{cui}/contracts (contracte publice), /company/{cui}/history (istoric modificări ONRC), /company/{cui}/debts (restanțe la buget ANAF), /company/{cui}/connections (grup de firme), /search?q= (căutare), /smart-search?q= (search inteligent: rutează CUI/nr.reg./limbaj-natural), /vat/{cui} (TVA/inactiv/e-Factura), /vies/{country}/{vat} (validare TVA intra-UE), /caen/{code} (nomenclator CAEN), /health (prospețime & acoperire date)
- Lista de urmărire (watchlist, gratuită): POST https://firmoscop.ro/api/v1/watchlist {"cui":"..."} → firma e re-verificată zilnic. Contul gratuit urmărește până la 25 de firme; când lista e plină răspunsul e 409 cu "error":"watchlist_full" (scoate o firmă cu DELETE /api/v1/watchlist/{cui}). GET https://firmoscop.ro/api/v1/me întoarce "watching" și "watchLimit" (null = fără plafon).
- Monitorizare push: POST https://firmoscop.ro/api/v1/webhooks {"url":"...","events":["verdict.changed"]} → notificare semnată HMAC când se schimbă verdictul unei firme urmărite (watchlist), cu retry + dead-letter
- MCP (streamable HTTP): https://firmoscop.ro/mcp cu același header SAU prin OAuth (login în browser cu contul Firmoscop — conexiunea are drepturile de pe site, deci verdictul e gratuit ca pe firmoscop.ro; cu cheia fk_ verdictul costă 1 credit — „connect” din Claude/ChatGPT — clientul descoperă singur fluxul din 401 + https://firmoscop.ro/.well-known/oauth-protected-resource; authorization code + PKCE, dynamic client registration la https://firmoscop.ro/oauth/register). Tools: cauta_firma(query), profil_firma(cui), verifica_firma(cui), bilanturi_firma(cui), datorii_anaf(cui), contracte_publice(cui, page), istoric_firma(cui), firme_legate(cui), compara_firme(cuiuri[2–5]), cauta_cod_caen(query), prospecteaza_firme(caen/county/minTurnover/…; 1 credit la 25 de firme), urmareste_firma(cui), firme_urmarite(), opreste_urmarirea(cui), contul_meu(), despre_firmoscop(). Manifest pentru registre de servere MCP: https://firmoscop.ro/.well-known/mcp/server.json
- Preț (citibil de mașină, pentru top-up autonom): GET https://firmoscop.ro/api/v1/pricing — model free-for-humans-credits-for-automation (pe web și în asistentul AI conectat cu login, verdictul și raportul complet sunt gratuite pentru oameni; creditele plătesc API-ul și MCP-ul cu cheie, plus listele de prospectare); contul gratuit are 10 credite pe lună (free_tier.monthly_quota), reîmprospătate la începutul lunii, fără report; pachete de 10/50/250/1000 de credite (1,09–3,50 lei/credit, TVA inclus). Un credit = o pagină de listă de 25 de firme. La descărcarea în Excel, primele 50 de rânduri sunt gratuite, apoi un credit la 25 de firme. O verificare automată, adică raportul complet cerut din Google Sheets, din programul tău sau dintr-un agent conectat cu cheie API, costă un credit; căutarea și profilul firmei rămân gratuite. Creditele cumpărate nu expiră: stau în soldul tău și se folosesc după ce ai consumat plafonul lunar al planului.
- Re-check caching: re-verificarea aceluiași CUI în 7 zile NU consumă credit (răspunsul întoarce "cached": true) — plătești o dată pentru verdict, nu de câte ori re-întrebi
- OpenAPI: https://firmoscop.ro/openapi.json — Limite: 30 cereri/min per cheie (headere X-RateLimit-*)

## Pagini publice (fără cont, citabile direct)
- Profil firmă: https://firmoscop.ro/firma/{cui} — identitate, stare, bilanțuri, bonitate, reprezentanți, contracte publice, grup de firme, cu date structurate schema.org. Poți linka direct utilizatorul aici.
- Blog: https://firmoscop.ro/blog — verificare înainte de credit comercial, recuperare creanțe, datorii ANAF, TVA/VIES, semnale de insolvență. Feed RSS: https://firmoscop.ro/rss.xml
- Știri din date: https://firmoscop.ro/stiri — ediții DATATE, fiecare cu o cifră numărată pe indexul nostru. Barometrele au metodologia la vedere („Cum am numărat”) și datele în CSV; lista exactă e mai jos, la „Datele edițiilor”, iar celelalte ediții n-au CSV. Feed: https://firmoscop.ro/stiri/rss.xml. Cifrele de aici sunt gândite să fie citate cu data ediției.
- Dicționar de termeni: https://firmoscop.ro/dictionar și https://firmoscop.ro/dictionar/{termen} — definițiile financiare și juridice pe care se sprijină verdictul (activ net, bonitate, masă credală…), marcate DefinedTermSet/DefinedTerm.
- Firme pe județ: https://firmoscop.ro/firme/{judet} și https://firmoscop.ro/firme/{judet}/{sector} — directorul național, cu firmele active ordonate după cifra de afaceri.
- Firme pe cod CAEN: https://firmoscop.ro/caen (nomenclatorul explicat) și https://firmoscop.ro/caen/{cod} — ce înseamnă activitatea, câte firme o declară și care sunt cele mai mari.
- Clasamente: https://firmoscop.ro/top — cele mai mari firme după cifra de afaceri și după profit, național, pe județ și pe cod CAEN, din bilanțurile depuse la Ministerul Finanțelor.
- Insolvențe: https://firmoscop.ro/insolvente (clasamentul județelor, cu cifra marcată explicit ca liber de citat sub CC BY 4.0, cu atribuire) și https://firmoscop.ro/insolvente/{judet} — firmele aflate acum în procedură în fiecare județ.
- Calendar fiscal: https://firmoscop.ro/calendar-fiscal — declarațiile și plățile care urmează, fiecare cu temeiul legal și cu cine le datorează.
- Demografia firmelor: https://firmoscop.ro/demografie — câte firme se înființează și câte se radiază, lună de lună, cu defalcarea zilnică pe societăți, PFA și sedii secundare.
- Firme radiate: https://firmoscop.ro/firme-radiate și https://firmoscop.ro/firme-radiate/{judet} — câte radieri înregistrează registrul comerțului în fiecare lună, pe județe (statistica oficială ONRC), plus lista firmelor pe care le-am văzut radiate în ultimele 30 de zile, cu data radierii când sursa o publică.

## Datele edițiilor (CSV, citabile cu data ediției)
- Seria lunară a înmatriculărilor (societăți și PFA), iunie 2024 – iunie 2026 (ediția din 2026-08-12): https://firmoscop.ro/stiri/barometrul-inmatricularilor-iunie-2026.csv
- Furnizorii pe decile de valoare: câți sunt, cât iau, ce pondere au. Atribuiri 2024–2026 (ediția din 2026-08-04): https://firmoscop.ro/stiri/contracte-publice-concentrare-furnizori.csv
- Firmele cu restrângeri de peste 40% din personal, pe cele 8 județe cu cele mai multe, plus totalul național (ediția din 2026-08-04): https://firmoscop.ro/stiri/restrangere-personal-2025.csv
- Firmele cu profit blocat pe dividende, pe cele 10 județe cu cele mai multe, plus totalul național (ediția din 2026-08-04): https://firmoscop.ro/stiri/profit-blocat-dividende-cate-firme.csv
- Firmele cu activul net sub jumătate din capitalul social, pe cele 10 județe cu cele mai multe, plus totalul național (ediția din 2026-08-04): https://firmoscop.ro/stiri/activ-net-sub-prag-cate-firme.csv
- Firmele cu capital sub noul minim, pe cele 12 județe cu cele mai multe, plus totalul național (ediția din 2026-08-04): https://firmoscop.ro/stiri/capital-social-sub-minim-cate-firme.csv
- Seria lunară a înmatriculărilor (societăți și PFA), ianuarie 2025 – iunie 2026 (ediția din 2026-07-31): https://firmoscop.ro/stiri/barometrul-inmatricularilor-s1-2026.csv
- Distribuția entităților pe revizia CAEN, din evidențele ONRC la 14 iulie 2026 (ediția din 2026-07-31): https://firmoscop.ro/stiri/caen-rev-3-o-firma-din-sase.csv

## Interpretarea verdictului
- verde: semnale publice curate; termen de plată rezonabil, cu contract semnat.
- galben: prudență — avans parțial, plafon de expunere; apare și când datele sunt insuficiente (nu e un verde mascat).
- rosu: nu acorda termen de plată.

## Limite oneste
Verdict orientativ din informații publice, la data verificării. Nu este garanție
de plată, rating de credit sau consultanță financiară/juridică. Acoperim TOATE
formele înregistrate la Registrul Comerțului — persoane juridice (SRL/SA…) și
persoane fizice autorizate (PFA/II/IF) — din date publice, pe bază de interes
legitim, cu drept de opoziție (vezi /privacy).

## Exemplu de răspuns (scurtat)
{"cui":"48778300","verdict":"rosu","recommendation":"Nu acorda termen de plată...","signals":[{"severity":"critical","label":"Dosar de insolvență"}],"artifactUrl":"https://firmoscop.ro/r/abc123","charged":true,"creditsRemaining":2}