Caută, apoi alege înregistrarea
Adresa de bază este https://craiova.ro/api/v1. Contractul complet, cu tipuri, parametri, enumerări și răspunsuri, este publicat în schema OpenAPI 3.1.2.
curl --get 'https://craiova.ro/api/v1/companies/search' \
--data-urlencode 'q=RO6488696' \
--data-urlencode 'limit=10'Inspectează data.items și alege company_id pentru înregistrarea dorită. Nu transforma CUI-ul în identificator și nu selecta automat primul rezultat: același CUI poate apărea la mai multe înregistrări.
read -r -p 'company_id ales din rezultate: ' COMPANY_ID
curl "https://craiova.ro/api/v1/companies/${COMPANY_ID}"
curl --get "https://craiova.ro/api/v1/companies/${COMPANY_ID}/financials" \
--data-urlencode 'year_from=2023' \
--data-urlencode 'limit=3'Operații și parametri
Toate căile de mai jos sunt relative la /api/v1. {company_id} este valoarea exactă primită la căutare.
| GET | Parametri și rezultat |
|---|---|
/companies/search | q obligatoriu; opțional county, caen, status, limit. Implicit 10 candidați, maximum 20. |
/companies/{company_id} | Identitate, statut în registru și cel mult 20 de activități CAEN actuale. |
/companies/{company_id}/financials | year_from, year_to, limit, cursor. Fără interval: ultimii 3 ani disponibili. Maximum 10 raportări pe pagină. |
/companies/{company_id}/tax-status | Starea TVA/inactivitate observată și datele ultimei liste ANAF de restanțe. |
/companies/{company_id}/contracts | role=supplier|buyer, kind=award|direct, year, counterparty_cui, cpv, limit, cursor. Implicit: furnizor, contracte atribuite, 10 rezultate; maximum 20. |
/companies/{company_id}/permits | kind=ac|cu, date_from, date_to, limit, cursor. Date în format YYYY-MM-DD; implicit 10 rezultate, maximum 20. |
O căutare numerică, inclusiv cu prefixul RO și spații, folosește CUI-ul exact: RO6488696 și 6488696 sunt echivalente. Zerourile inițiale sunt eliminate. CUI-ul rămâne un șir de cel mult 10 cifre; valorile inutilizabile sunt respinse.
Denumirile se caută fără diferențe de diacritice, atât în numele actuale, cât și în cele anterioare. Sunt necesare cel puțin 3 caractere utile și cel mult 120 de caractere în cerere. Rezultatul indică match_type: exact_cui, current_name sau former_name. Căutarea nu include reprezentanți.
Fără county se caută în toată țara, iar fără status sunt incluse toate stările publicate. Codurile de județ și stările acceptate sunt enumerate în schemă. Filtrul caen folosește patru cifre din Rev.3 și corespondențele publicate din Rev.2. Pentru contracte, rolul buyer este disponibil când firma are o legătură publică cu o autoritate contractantă.
Cum citești răspunsul
| Câmp | Semnificație |
|---|---|
schema_version | Versiunea structurii răspunsului: 1. |
data | Rezultatul operației; blocurile indică sursele prin source_ids. |
sources | Instituția, setul de date, adresa sursei, atribuirea, licența și datele cunoscute. citation_url indică pagina de citat pe craiova.ro. |
warnings | Precizări despre limitele sursei și interpretarea valorilor, în română. |
meta | request_id identifică cererea; retrieved_at este momentul răspunsului. |
availability deosebește available, not_available și not_applicable. null înseamnă necunoscut, niciodată zero. La ANAF, o firmă negăsită sau neverificată este deosebită de o confirmare că nu este înregistrată în scopuri de TVA ori inactivă fiscal.
Sumele sunt șiruri zecimale exacte în RON, cu unitatea lei. Folosește un tip zecimal care păstrează precizia, fără conversie intermediară în virgulă mobilă. Păstrează anul și formularul raportării financiare, data observației fiscale și datele sursei; retrieved_at nu le înlocuiește.
scope: "cui" arată că faptele sunt asociate CUI-ului și pot fi comune mai multor înregistrări. lot_count și award_count au semnificații distincte. Valorile contractelor păstrează maximul raportat după reunirea loturilor și republicărilor; nu le prezenta drept cheltuieli efective. Citește și precizările despre surse.
Continuă cu cursorul returnat
Căutarea returnează un grup limitat de candidați. Dacă truncated este adevărat, restrânge denumirea ori adaugă filtre; căutarea nu are pagini următoare.
Pentru raportări financiare, contracte și urbanism, trimite valoarea next_cursorca parametru cursor, păstrând firma, filtrele și limit. Encodează parametrul în URL, fără să interpretezi sau să modifici cursorul. next_cursor: nullmarchează sfârșitul listei. O pagină poate conține mai puține rânduri decât limita cerută pentru a încăpea în răspuns; continuă cât timp primești un cursor.
Cursorul este valabil cel mult o oră și expiră dacă datele listei se schimbă. La cursor_expired, reia lista de la prima pagină. Numărul returned_countse referă la pagina primită, nu la un total al bazei de date.
Limite, erori și reîncercări
API și MCP împart 60 de cereri pe minut pentru întregul serviciu, cu un vârf de 5 și maximum 2 cereri active simultan. Limitele sunt de 8 KiB pe cerere, 64 KiB pe răspuns complet și 8 secunde pentru o cerere. Fă cererile pe rând și respectă Retry-After.
| HTTP · cod | Ce faci |
|---|---|
400 · invalid_argument | Corectează parametrii după schema OpenAPI; nu retrimite aceeași cerere invalidă. |
403 · forbidden | Folosește API-ul din aplicația de pe server sau dintr-un script. Apelurile directe din pagini de pe alte domenii nu sunt acceptate. |
404 · not_found | Firma nu este disponibilă în serviciu. Revino la căutare și verifică înregistrarea aleasă. |
409 · cursor_expired | Reia lista fără cursor, cu aceleași filtre. |
422 · query_too_broad | Restrânge numele sau folosește CUI-ul. |
429 · rate_limited | Așteaptă secundele din Retry-After și reîncearcă secvențial; bugetul este comun tuturor utilizatorilor. |
503 · temporarily_unavailable | Reîncearcă după intervalul indicat. Dacă problema persistă, păstrează request_id pentru semnalare. |
Erorile includ error.code, un mesaj în română, request_id și retryable. Un eșec nu este o listă goală de rezultate.
În scripturile Python, setează un User-Agent care identifică aplicația, de exemplu CraiovaCompanyReader/1.0. Identificatorul implicit Python-urllib poate primi un răspuns Cloudflare 403 cu textul error code: 1010, înainte ca cererea să ajungă la API. Nu este necesară o cheie sau autentificare.