Firmoscop API API

{"openapi":"3.1.0","info":{"title":"Firmoscop API","version":"0.3.0","description":"Verificarea firmelor românești, AI-native. Profil de firmă, căutare, grupuri de firme și scor de bonitate — GRATUIT din indexul propriu (ANAF, ONRC, Ministerul Finanțelor, SEAP). Verdictul complet de risc comercial (verde/galben/roșu) e calculat DETERMINIST din surse publice (ANAF, MF, portalul instanțelor, BPI) — 1 credit. Autentificare: cheie Bearer `fk_…` (o generezi la /developers; contul gratuit are 10 credite pe lună). Toate răspunsurile limitate per cheie întorc headere X-RateLimit-*.","contact":{"name":"Firmoscop","url":"https://firmoscop.ro/developers"}},"servers":[{"url":"https://firmoscop.ro"}],"tags":[{"name":"Chei & cont","description":"Emitere cheie, cont, credite."},{"name":"Firme (gratuit)","description":"Index propriu: căutare, profil, grup de firme — fără credit."},{"name":"Verificare (credite)","description":"Verdict de risc calculat la sursă."},{"name":"Prospectare","description":"Liste filtrate de firme (plătit, fără date personale)."},{"name":"Monitorizare","description":"Listă de urmărire, re-verificată zilnic."},{"name":"Meta","description":"Statistici publice, MCP."}],"paths":{"/api/v1/keys/register":{"post":{"tags":["Chei & cont"],"summary":"Creează cont gratuit pe email (10 credite pe lună)","description":"Email NOU → cont gratuit + sesiune (201, cu token și cookie). Email DEJA înregistrat → NU se deschide sesiune: primești 200 cu `needsCode:true` și un cod pe email, pe care îl confirmi la POST /auth/email/verify. Adresa singură nu dă acces la un cont existent. 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ă. Verificarea emailului sau sign-in-ul Google nu schimbă plafonul. Contul e NECONFIRMAT până la prima confirmare a adresei. Pașii care merg: (2) POST /auth/email/request {email} → cod pe email; (3) POST /auth/email/verify {email, code} → token de sesiune NOU (tokenul de aici și orice cheie `fk_`, tokenuri OAuth sau webhook-uri emise înainte se revocă la confirmare; răspunsul le enumeră în `revocat`); (4) POST /api/v1/keys/rotate cu tokenul nou → cheia `fk_`. Confirmă adresa înainte să rotești cheia.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["email"],"properties":{"email":{"type":"string","format":"email"},"label":{"type":"string","description":"numele agentului/aplicației (opțional)"}}}}}},"responses":{"201":{"description":"Cont creat / autentificat (cookie de sesiune setat).","content":{"application/json":{"schema":{"type":"object","properties":{"ok":{"type":"boolean"},"loggedIn":{"type":"boolean"},"isNew":{"type":"boolean"}}}}}},"400":{"description":"Eroare — corp JSON { error, message } în limbaj natural.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Eroare — corp JSON { error, message } în limbaj natural.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/v1/keys/rotate":{"post":{"tags":["Chei & cont"],"summary":"Emite/rotește cheia API `fk_…` (afișată o singură dată)","description":"Necesită sesiune (cookie sau X-Fs-Session) sau o cheie Bearer existentă. Rotația invalidează cheia anterioară. Folosește sesiunea de DUPĂ confirmarea adresei (POST /auth/email/request → POST /auth/email/verify): pe un cont neconfirmat, cheia emisă aici moare la prima confirmare (cod, link magic sau Google). Acreditarea cererii se re-verifică la scriere: o sesiune sau cheie care nu mai e validă primește 401 `credential_revoked`.","security":[{"bearerAuth":[]},{"cookieAuth":[]}],"responses":{"200":{"description":"Cheia nouă.","content":{"application/json":{"schema":{"type":"object","properties":{"key":{"type":"string","example":"fk_…"},"message":{"type":"string"}}}}}},"401":{"description":"Eroare — corp JSON { error, message } în limbaj natural.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Tokenul OAuth (`fso_…`) al unei aplicații conectate, de ex. ChatGPT sau Claude: nu gestionează contul. Merge cu cheia API sau din cont. Eroarea e `insufficient_scope`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/v1/me":{"get":{"tags":["Chei & cont"],"summary":"Contul curent: email, credite, firme urmărite","security":[{"bearerAuth":[]},{"cookieAuth":[]}],"responses":{"200":{"description":"Starea contului.","content":{"application/json":{"schema":{"type":"object","properties":{"email":{"type":"string","nullable":true},"credits":{"type":"integer","description":"Cât mai poate consuma contul acum: plafonul lunar rămas + soldul care nu expiră."},"creditStatus":{"type":"object","description":"Desfacerea lui `credits`. O operație consumă întâi din plafonul lunii, apoi din sold; 402 doar când sunt goale amândouă.","properties":{"remaining":{"type":"integer"},"plan":{"type":"object","properties":{"limit":{"type":"integer"},"used":{"type":"integer"},"remaining":{"type":"integer"}},"description":"Plafonul planului în luna UTC curentă; se reface la începutul lunii."},"topup":{"type":"integer","description":"Soldul: credite din pachete cumpărate sau adăugate manual. Nu expiră și nu se resetează lunar."}}},"watching":{"type":"integer"},"watchLimit":{"type":"integer","nullable":true,"description":"Plafonul listei de urmărire al contului: 25 pe contul gratuit; null = cont fără plafon."},"adresaDovedita":{"type":"boolean","nullable":true,"description":"Adresa contului e confirmată (cod pe email, link magic sau Google). Un cont creat prin register rămâne `false` până la prima confirmare, care revocă cheia și sesiunile emise înainte. `null` = starea n-a putut fi citită."}}}}}},"401":{"description":"Eroare — corp JSON { error, message } în limbaj natural.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/v1/search":{"get":{"tags":["Firme (gratuit)"],"summary":"Caută firme după nume (fără credit)","security":[{"bearerAuth":[]},{"cookieAuth":[]}],"parameters":[{"name":"q","in":"query","required":true,"schema":{"type":"string","minLength":3}}],"responses":{"200":{"description":"Candidați potriviți pe nume.","headers":{"X-RateLimit-Limit":{"schema":{"type":"integer"},"description":"Cereri permise per fereastră."},"X-RateLimit-Remaining":{"schema":{"type":"integer"},"description":"Cereri rămase în fereastra curentă."},"X-RateLimit-Reset":{"schema":{"type":"integer"},"description":"Epoch (secunde) când se eliberează fereastra."}},"content":{"application/json":{"schema":{"type":"object","properties":{"query":{"type":"string"},"hits":{"type":"array","items":{"$ref":"#/components/schemas/SearchHit"}}}}}}},"400":{"description":"Eroare — corp JSON { error, message } în limbaj natural.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Eroare — corp JSON { error, message } în limbaj natural.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Eroare — corp JSON { error, message } în limbaj natural.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/v1/suggest":{"get":{"tags":["Firme (gratuit)"],"summary":"Sugestii publice după nume (fără cont, limitat pe IP)","description":"Câmpuri minime, pentru autocomplete public. Pentru integrare folosește /api/v1/search cu cheie.","parameters":[{"name":"q","in":"query","required":true,"schema":{"type":"string","minLength":1}}],"responses":{"200":{"description":"Până la 10 sugestii.","content":{"application/json":{"schema":{"type":"object","properties":{"query":{"type":"string"},"hits":{"type":"array","items":{"$ref":"#/components/schemas/SuggestHit"}}}}}}},"429":{"description":"Eroare — corp JSON { error, message } în limbaj natural.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/v1/company/{cui}":{"get":{"tags":["Firme (gratuit)"],"summary":"Profil de firmă (identitate, stare, bilanțuri, bonitate, reprezentanți) — fără credit","security":[{"bearerAuth":[]},{"cookieAuth":[]}],"parameters":[{"name":"cui","in":"path","required":true,"schema":{"type":"string","pattern":"^\\d{1,10}$"},"description":"CUI-ul firmei (doar cifre, fără prefix RO)."}],"responses":{"200":{"description":"Profilul firmei din index.","headers":{"X-RateLimit-Limit":{"schema":{"type":"integer"},"description":"Cereri permise per fereastră."},"X-RateLimit-Remaining":{"schema":{"type":"integer"},"description":"Cereri rămase în fereastra curentă."},"X-RateLimit-Reset":{"schema":{"type":"integer"},"description":"Epoch (secunde) când se eliberează fereastra."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CompanyProfile"}}}},"401":{"description":"Eroare — corp JSON { error, message } în limbaj natural.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Eroare — corp JSON { error, message } în limbaj natural.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Eroare — corp JSON { error, message } în limbaj natural.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/v1/company/{cui}/connections":{"get":{"tags":["Firme (gratuit)"],"summary":"Grup de firme (rețea prin reprezentanți comuni) — fără credit","security":[{"bearerAuth":[]},{"cookieAuth":[]}],"parameters":[{"name":"cui","in":"path","required":true,"schema":{"type":"string","pattern":"^\\d{1,10}$"},"description":"CUI-ul firmei (doar cifre, fără prefix RO)."}],"responses":{"200":{"description":"Firmele legate prin administratori/reprezentanți cu același nume.","headers":{"X-RateLimit-Limit":{"schema":{"type":"integer"},"description":"Cereri permise per fereastră."},"X-RateLimit-Remaining":{"schema":{"type":"integer"},"description":"Cereri rămase în fereastra curentă."},"X-RateLimit-Reset":{"schema":{"type":"integer"},"description":"Epoch (secunde) când se eliberează fereastra."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Connections"}}}},"401":{"description":"Eroare — corp JSON { error, message } în limbaj natural.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Eroare — corp JSON { error, message } în limbaj natural.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Eroare — corp JSON { error, message } în limbaj natural.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/v1/verify/{cui}":{"get":{"tags":["Verificare (credite)"],"summary":"Verifică o firmă după CUI (1 credit)","security":[{"bearerAuth":[]},{"cookieAuth":[]}],"parameters":[{"name":"cui","in":"path","required":true,"schema":{"type":"string","pattern":"^\\d{1,10}$"},"description":"CUI-ul firmei (doar cifre, fără prefix RO)."},{"name":"fresh","in":"query","schema":{"type":"string","enum":["1"]},"description":"ocolește cache-ul de 24h"}],"responses":{"200":{"description":"Raport structurat: verdict, semnale cu sursă+dată, financiare, dosare, artifactUrl.","headers":{"X-RateLimit-Limit":{"schema":{"type":"integer"},"description":"Cereri permise per fereastră."},"X-RateLimit-Remaining":{"schema":{"type":"integer"},"description":"Cereri rămase în fereastra curentă."},"X-RateLimit-Reset":{"schema":{"type":"integer"},"description":"Epoch (secunde) când se eliberează fereastra."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/VerifyReport"}}}},"401":{"description":"Eroare — corp JSON { error, message } în limbaj natural.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"402":{"description":"Plafonul lunar al planului e consumat și soldul e gol — mesajul spune când se reface plafonul și cum obții mai multe credite (pachet sau plan).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Doar pe sesiunea de cont (cookie), nu pe cheia Bearer: cererea a pornit dintr-un link de pe alt site (`Sec-Fetch-Site: cross-site`, fără `X-Fs-Session`). Nu se consumă nimic. Eroarea e `cross_site_request`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Eroare — corp JSON { error, message } în limbaj natural.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"502":{"description":"Eroare — corp JSON { error, message } în limbaj natural.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/v1/verify/batch":{"post":{"tags":["Verificare (credite)"],"summary":"Verifică până la 20 de firme într-o cerere (1 credit / firmă reușită)","description":"Sincron. Se taxează doar verificările reușite; se oprește când se termină creditele. Pentru volume mari, împarte în loturi.","security":[{"bearerAuth":[]},{"cookieAuth":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["cuis"],"properties":{"cuis":{"type":"array","items":{"type":"string","pattern":"^\\d{1,10}$"},"maxItems":20}}}}}},"responses":{"200":{"description":"Rezultat per CUI (raport sau eroare) + credite rămase.","headers":{"X-RateLimit-Limit":{"schema":{"type":"integer"},"description":"Cereri permise per fereastră."},"X-RateLimit-Remaining":{"schema":{"type":"integer"},"description":"Cereri rămase în fereastra curentă."},"X-RateLimit-Reset":{"schema":{"type":"integer"},"description":"Epoch (secunde) când se eliberează fereastra."}},"content":{"application/json":{"schema":{"type":"object","properties":{"results":{"type":"array","items":{"type":"object"}},"creditsRemaining":{"type":"integer"}}}}}},"400":{"description":"Eroare — corp JSON { error, message } în limbaj natural.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Eroare — corp JSON { error, message } în limbaj natural.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Eroare — corp JSON { error, message } în limbaj natural.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/v1/company/{cui}/financials":{"get":{"tags":["Firme (gratuit)"],"summary":"Bilanțuri multi-anuale (fără credit)","security":[{"bearerAuth":[]},{"cookieAuth":[]}],"parameters":[{"name":"cui","in":"path","required":true,"schema":{"type":"string","pattern":"^\\d{1,10}$"},"description":"CUI-ul firmei (doar cifre, fără prefix RO)."}],"responses":{"200":{"description":"Istoric financiar din index.","headers":{"X-RateLimit-Limit":{"schema":{"type":"integer"},"description":"Cereri permise per fereastră."},"X-RateLimit-Remaining":{"schema":{"type":"integer"},"description":"Cereri rămase în fereastra curentă."},"X-RateLimit-Reset":{"schema":{"type":"integer"},"description":"Epoch (secunde) când se eliberează fereastra."}},"content":{"application/json":{"schema":{"type":"object","properties":{"cui":{"type":"string"},"count":{"type":"integer"},"financials":{"type":"array","items":{"$ref":"#/components/schemas/FinancialYear"}}}}}}},"401":{"description":"Eroare — corp JSON { error, message } în limbaj natural.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Eroare — corp JSON { error, message } în limbaj natural.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/v1/company/{cui}/financials.csv":{"get":{"tags":["Firme (gratuit)"],"summary":"Bilanțuri multi-anuale ca CSV pentru Excel (fără credit)","description":"Aceleași date ca /financials, dar CSV (UTF-8 cu BOM, un an per rând). Include câmpurile de bilanț extinse (active circulante/imobilizate, profit brut, capital subscris) când sunt disponibile.","security":[{"bearerAuth":[]},{"cookieAuth":[]}],"parameters":[{"name":"cui","in":"path","required":true,"schema":{"type":"string","pattern":"^\\d{1,10}$"},"description":"CUI-ul firmei (doar cifre, fără prefix RO)."}],"responses":{"200":{"description":"Fișier CSV descărcabil.","headers":{"X-RateLimit-Limit":{"schema":{"type":"integer"},"description":"Cereri permise per fereastră."},"X-RateLimit-Remaining":{"schema":{"type":"integer"},"description":"Cereri rămase în fereastra curentă."},"X-RateLimit-Reset":{"schema":{"type":"integer"},"description":"Epoch (secunde) când se eliberează fereastra."}},"content":{"text/csv":{"schema":{"type":"string"}}}},"401":{"description":"Eroare — corp JSON { error, message } în limbaj natural.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Eroare — corp JSON { error, message } în limbaj natural.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/v1/company/{cui}/contracts":{"get":{"tags":["Firme (gratuit)"],"summary":"Contracte publice câștigate, paginat (fără credit)","security":[{"bearerAuth":[]},{"cookieAuth":[]}],"parameters":[{"name":"cui","in":"path","required":true,"schema":{"type":"string","pattern":"^\\d{1,10}$"},"description":"CUI-ul firmei (doar cifre, fără prefix RO)."},{"name":"page","in":"query","schema":{"type":"integer","minimum":1,"default":1}},{"name":"pageSize","in":"query","schema":{"type":"integer","minimum":1,"maximum":100,"default":20}}],"responses":{"200":{"description":"Pagină de contracte SEAP.","headers":{"X-RateLimit-Limit":{"schema":{"type":"integer"},"description":"Cereri permise per fereastră."},"X-RateLimit-Remaining":{"schema":{"type":"integer"},"description":"Cereri rămase în fereastra curentă."},"X-RateLimit-Reset":{"schema":{"type":"integer"},"description":"Epoch (secunde) când se eliberează fereastra."}},"content":{"application/json":{"schema":{"type":"object","properties":{"cui":{"type":"string"},"page":{"type":"integer"},"pageSize":{"type":"integer"},"total":{"type":"integer"},"data":{"type":"array","items":{"$ref":"#/components/schemas/Contract"}}}}}}},"401":{"description":"Eroare — corp JSON { error, message } în limbaj natural.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Eroare — corp JSON { error, message } în limbaj natural.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/v1/company/{cui}/history":{"get":{"tags":["Firme (gratuit)"],"summary":"Istoric de modificări ONRC — mențiuni (fără credit)","description":"Timeline de schimbări (redenumire, sediu, stare juridică, CAEN, nr. înmatriculare) capturate prin CDC, cel mai recent întâi.","security":[{"bearerAuth":[]},{"cookieAuth":[]}],"parameters":[{"name":"cui","in":"path","required":true,"schema":{"type":"string","pattern":"^\\d{1,10}$"},"description":"CUI-ul firmei (doar cifre, fără prefix RO)."}],"responses":{"200":{"description":"Evenimente de istoric.","headers":{"X-RateLimit-Limit":{"schema":{"type":"integer"},"description":"Cereri permise per fereastră."},"X-RateLimit-Remaining":{"schema":{"type":"integer"},"description":"Cereri rămase în fereastra curentă."},"X-RateLimit-Reset":{"schema":{"type":"integer"},"description":"Epoch (secunde) când se eliberează fereastra."}},"content":{"application/json":{"schema":{"type":"object","properties":{"cui":{"type":"string"},"count":{"type":"integer"},"events":{"type":"array","items":{"$ref":"#/components/schemas/HistoryEvent"}}}}}}},"401":{"description":"Eroare — corp JSON { error, message } în limbaj natural.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Eroare — corp JSON { error, message } în limbaj natural.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/v1/company/{cui}/debts":{"get":{"tags":["Firme (gratuit)"],"summary":"Restanțe la buget (ANAF, lista datornicilor) — fără credit","description":"Din lista trimestrială ANAF a datornicilor. `hasDebt:false` = nu figurează (fără restanțe raportate peste pragul ANAF).","security":[{"bearerAuth":[]},{"cookieAuth":[]}],"parameters":[{"name":"cui","in":"path","required":true,"schema":{"type":"string","pattern":"^\\d{1,10}$"},"description":"CUI-ul firmei (doar cifre, fără prefix RO)."}],"responses":{"200":{"description":"Restanțe (sau hasDebt:false).","headers":{"X-RateLimit-Limit":{"schema":{"type":"integer"},"description":"Cereri permise per fereastră."},"X-RateLimit-Remaining":{"schema":{"type":"integer"},"description":"Cereri rămase în fereastra curentă."},"X-RateLimit-Reset":{"schema":{"type":"integer"},"description":"Epoch (secunde) când se eliberează fereastra."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/FiscalDebt"}}}},"401":{"description":"Eroare — corp JSON { error, message } în limbaj natural.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Eroare — corp JSON { error, message } în limbaj natural.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/v1/vat/{cui}":{"get":{"tags":["Firme (gratuit)"],"summary":"Stare fiscală: TVA / inactiv fiscal / e-Factura (fără credit)","security":[{"bearerAuth":[]},{"cookieAuth":[]}],"parameters":[{"name":"cui","in":"path","required":true,"schema":{"type":"string","pattern":"^\\d{1,10}$"},"description":"CUI-ul firmei (doar cifre, fără prefix RO)."}],"responses":{"200":{"description":"Starea fiscală din index.","headers":{"X-RateLimit-Limit":{"schema":{"type":"integer"},"description":"Cereri permise per fereastră."},"X-RateLimit-Remaining":{"schema":{"type":"integer"},"description":"Cereri rămase în fereastra curentă."},"X-RateLimit-Reset":{"schema":{"type":"integer"},"description":"Epoch (secunde) când se eliberează fereastra."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/VatStatus"}}}},"401":{"description":"Eroare — corp JSON { error, message } în limbaj natural.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Eroare — corp JSON { error, message } în limbaj natural.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Eroare — corp JSON { error, message } în limbaj natural.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/v1/vies/{country}/{vat}":{"get":{"tags":["Firme (gratuit)"],"summary":"Validare TVA intracomunitar prin VIES (fără credit)","security":[{"bearerAuth":[]},{"cookieAuth":[]}],"parameters":[{"name":"country","in":"path","required":true,"schema":{"type":"string","pattern":"^[A-Za-z]{2}$"},"description":"Cod stat membru UE (RO, DE, EL, XI…)."},{"name":"vat","in":"path","required":true,"schema":{"type":"string"},"description":"Numărul de TVA, fără codul de țară."}],"responses":{"200":{"description":"Rezultatul validării VIES.","headers":{"X-RateLimit-Limit":{"schema":{"type":"integer"},"description":"Cereri permise per fereastră."},"X-RateLimit-Remaining":{"schema":{"type":"integer"},"description":"Cereri rămase în fereastra curentă."},"X-RateLimit-Reset":{"schema":{"type":"integer"},"description":"Epoch (secunde) când se eliberează fereastra."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ViesResult"}}}},"400":{"description":"Eroare — corp JSON { error, message } în limbaj natural.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Eroare — corp JSON { error, message } în limbaj natural.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"502":{"description":"Eroare — corp JSON { error, message } în limbaj natural.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/v1/caen":{"get":{"tags":["Firme (gratuit)"],"summary":"Caută coduri CAEN după cod sau denumire (fără credit)","security":[{"bearerAuth":[]},{"cookieAuth":[]}],"parameters":[{"name":"q","in":"query","required":true,"schema":{"type":"string","minLength":2}}],"responses":{"200":{"description":"Coduri potrivite.","headers":{"X-RateLimit-Limit":{"schema":{"type":"integer"},"description":"Cereri permise per fereastră."},"X-RateLimit-Remaining":{"schema":{"type":"integer"},"description":"Cereri rămase în fereastra curentă."},"X-RateLimit-Reset":{"schema":{"type":"integer"},"description":"Epoch (secunde) când se eliberează fereastra."}},"content":{"application/json":{"schema":{"type":"object","properties":{"query":{"type":"string"},"results":{"type":"array","items":{"$ref":"#/components/schemas/Caen"}}}}}}},"400":{"description":"Eroare — corp JSON { error, message } în limbaj natural.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Eroare — corp JSON { error, message } în limbaj natural.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/v1/caen/{code}":{"get":{"tags":["Firme (gratuit)"],"summary":"Denumirea unui cod CAEN (fără credit)","security":[{"bearerAuth":[]},{"cookieAuth":[]}],"parameters":[{"name":"code","in":"path","required":true,"schema":{"type":"string","pattern":"^\\d{2,6}$"}}],"responses":{"200":{"description":"Codul + denumirea.","headers":{"X-RateLimit-Limit":{"schema":{"type":"integer"},"description":"Cereri permise per fereastră."},"X-RateLimit-Remaining":{"schema":{"type":"integer"},"description":"Cereri rămase în fereastra curentă."},"X-RateLimit-Reset":{"schema":{"type":"integer"},"description":"Epoch (secunde) când se eliberează fereastra."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Caen"}}}},"401":{"description":"Eroare — corp JSON { error, message } în limbaj natural.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Eroare — corp JSON { error, message } în limbaj natural.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/v1/pricing":{"get":{"tags":["Meta"],"summary":"Prețuri citibile de mașină (public, fără cheie) — pentru top-up autonom al agenților","responses":{"200":{"description":"Unitatea de preț, pachetele de credite, abonamentele, fereastra de re-check și free tier-ul. 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ă. 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. Prețurile sunt cu TVA inclus: `vat_rate` dă cota, iar `price_net_ron` baza fără TVA.","content":{"application/json":{"schema":{"type":"object","properties":{"free_tier":{"type":"object","description":"Poarta contului gratuit: un plafon lunar de credite, nu un sold primit o singură dată.","properties":{"monthly_quota":{"type":"integer","description":"Creditele contului gratuit în fiecare lună. Se reîmprospătează la începutul lunii calendaristice (UTC); ce nu folosești nu se reportează."},"quota_resets":{"type":"string","enum":["month_start_utc"]},"unused_rolls_over":{"type":"boolean"},"card_required":{"type":"boolean"},"deprecated_fields":{"type":"array","items":{"type":"string"},"description":"Cheile vechi păstrate pentru compatibilitate."},"signup_credits":{"type":"integer","deprecated":true,"description":"Depășit din 20 oct 2026: are valoarea lui monthly_quota. Citește monthly_quota."},"verified_credits":{"type":"integer","deprecated":true,"description":"Depășit din 20 oct 2026: are valoarea lui monthly_quota. Citește monthly_quota."},"monthly_free_verifications":{"type":"integer","deprecated":true,"description":"Depășit din 20 oct 2026: are valoarea lui monthly_quota. Citește monthly_quota."}}}}}}}}}}},"/api/v1/companies":{"get":{"tags":["Prospectare"],"summary":"Liste filtrate de firme (1 credit la 25 de firme)","description":"Prospectare pe CAEN / județ / localitate / formă juridică / stare / TVA / e-Factura / vechime / benzi de mărime. Obligatoriu cel puțin `caen` sau `county`. Rândurile conțin DOAR date de persoană juridică — fără reprezentanți sau contact. Sediile secundare (punctele de lucru cu cod fiscal propriu) nu apar: nu sunt firme separate. Revânzarea în bloc e interzisă (ToS).","security":[{"bearerAuth":[]},{"cookieAuth":[]}],"parameters":[{"name":"caen","in":"query","schema":{"type":"string","pattern":"^\\d{2,6}$"},"description":"Cod CAEN sau prefix (ex. 41 = toată diviziunea construcții)."},{"name":"county","in":"query","schema":{"type":"string"},"description":"Județ (ex. Cluj) — diacriticele nu contează."},{"name":"state","in":"query","schema":{"type":"string","enum":["active","insolvent"]}},{"name":"vat","in":"query","schema":{"type":"string","enum":["true","false"]},"description":"Plătitor de TVA."},{"name":"minTurnover","in":"query","schema":{"type":"number","minimum":0,"maximum":1000000000000000},"description":"Cifra de afaceri minimă (lei), din ultimul bilanț."},{"name":"minEmployees","in":"query","schema":{"type":"integer","minimum":0,"maximum":1000000},"description":"Numărul minim de angajați."},{"name":"legalForm","in":"query","schema":{"type":"string"},"description":"Forma juridică, exact (SRL, SA, PFA, II, IF, AF, PF, SNC…)."},{"name":"locality","in":"query","schema":{"type":"string"},"description":"Localitatea (ex. Cluj-Napoca) — diacriticele nu contează."},{"name":"address","in":"query","schema":{"type":"string","minLength":3},"description":"Text din adresa sediului (stradă / cod poștal). ONRC abreviază — caută partea distinctivă."},{"name":"localityType","in":"query","schema":{"type":"string","enum":["urban","rural"]},"description":"Mediul: urban (municipii, orașe, sectoare) sau rural (comune, sate). Localitățile fără prefix recunoscut nu intră în niciuna."},{"name":"finYear","in":"query","schema":{"type":"integer","minimum":2008,"maximum":2026},"description":"Anul de bilanț pe care se aplică pragurile financiare (cifră de afaceri, angajați, evoluție). Implicit: ultimul bilanț al fiecărei firme, dar numai dacă e din ultimul an fiscal publicat sau din cel dinaintea lui; firmele cu bilanț mai vechi nu trec pragurile."},{"name":"turnoverGrowthPct","in":"query","schema":{"type":"number","minimum":-10000,"maximum":10000},"description":"Evoluția cifrei de afaceri față de anul precedent, în %: pozitiv = creștere minimă, negativ = scădere minimă."},{"name":"efactura","in":"query","schema":{"type":"string","enum":["true","false"]},"description":"Înscrisă în RO e-Factura."},{"name":"finantare","in":"query","schema":{"type":"string","enum":["true","false"]},"description":"A încasat finanțare publică (PNRR). Filtru îngust: sub 3.000 de societăți din tot registrul."},{"name":"inactive","in":"query","schema":{"type":"string","enum":["true","false"]},"description":"Declarată inactivă fiscal de ANAF."},{"name":"registeredAfter","in":"query","schema":{"type":"string","format":"date"},"description":"Înmatriculată la/după data asta (YYYY-MM-DD, între 1900 și anul viitor)."},{"name":"registeredBefore","in":"query","schema":{"type":"string","format":"date"},"description":"Înmatriculată până la data asta (YYYY-MM-DD, între 1900 și anul viitor)."},{"name":"maxTurnover","in":"query","schema":{"type":"number","minimum":0,"maximum":1000000000000000},"description":"Cifra de afaceri maximă (lei) — benzi de mărime; 0 = firme fără cifră de afaceri în bilanț."},{"name":"maxEmployees","in":"query","schema":{"type":"integer","minimum":0,"maximum":1000000},"description":"Numărul maxim de angajați; 0 = firme fără angajați în bilanț."},{"name":"sort","in":"query","schema":{"type":"string","enum":["turnover"]},"description":"sort=turnover → cele mai mari firme întâi (implicit: după CUI)."},{"name":"page","in":"query","

# --- truncated at 32 KB (69 KB total) ---
# Full source: https://artifacts.apis.io/firmoscop-ro/openapi/_original/firmoscop-ro-api-openapi.json