Informații despre firme prin API

Informațiile despre firme pot fi accesate direct din aplicațiile dumneavoastră de tip ERP, CRM sau altele, prin intermediul acestui serviciu.

Serviciul este de tip REST API cu răspuns în format JSON și poate fi accesat doar de utilizatorii pentru care serviciul a fost activat. Pentru activarea serviciului API și generarea cheii, click pe butonul reset din formularul pentru actualizare cont. Interogarea prin API se face în baza unor reguli diferite față de accesarea web, reguli specificate în continuare. Informațiile din rapoartele detaliate nu sunt accesibile prin API.

Plata interogărilor API se face în credite putând fi accesate aceleași informații indiferent de tipul pachetului de acces. Consumul de credite depinde de informațiile solicitate și returnate, respectiv se consumă credite doar pentru informațiile efectiv primite din ceea ce ați solicitat. Costul în credite este același indiferent de tipul și opțiunile pachetului de acces, motiv pentru care sunt recomandate pachetele de acces cu preț pe afișare minim. Pachetele de acces cu care poate fi accesat API sunt cele anuale. Implicit este utilizat cel mai vechi pachet eligibil în cazul în care există mai multe pachete de acces valabile. Nu poate fi accesat API cu pachetele de acces de tip Nelimitat cu valabilitate lunară.

Căutări după nume, CUI sau J

Pentru a interoga informații despre o firmă trebuie să-i cunoașteți CUI-ul. Dacă nu-i cunoașteți CUI-ul, puteți căuta după denumire sau părți din denumire și aflați CUI-ul pentru a fi utilizat in continuare.

Căutările se transmit utilizând protocolul HTTP (preferabil POST) la adresa:

https://listafirme.ro/api/search-v2.asp

Parametrii unei interogări sunt:

• key = cheia api secretă pe care o găsiți în datele contului dumneavoastră dacă serviciul este activat;
• src = textul căutat.

Exemplu de interogare:

key=<key>&src=Borg Design

key=<key>&src=J2002008118400
      

Răspunsul poate include rezultate multiple și este de forma:

{"Results":[{"Name":"BORG DESIGN SRL","FiscalCode":"14837428","County":"BUCURESTI","URL":"https://platform.listafirme.eu/borg-design-srl-14837428/"}],"cost":0}

Căutările au ca scop facilitarea interogărilor pentru informații detaliate și pot fi taxate în caz de utilizare intensivă. Limita gratuității este de maxim 50 de căutări până la o interogare de informații punctuale. În cazul depășirii se consumă un credit iar contorul se resetează.

Interogări pentru informații punctuale

Cunoscând CUI-ul firmei, interogările pentru informații se transmit utilizând protocolul HTTP (preferabil POST) la adresa:

https://listafirme.ro/api/info-v2.asp

Parametrii unei interogări sunt:

• key = cheia api secretă pe care o găsiți în datele contului dumneavoastră dacă serviciul este activat;
• data = JSON object ce specifică datele dorite.

Exemplu de interogare:

key=<key>&data={"TaxCode":"14837428","Name":"","Status":""}
      

Ar returna un răspuns JSON ca mai jos:

{
  "TaxCode": "14837428",
  "Status": "functiune",
  "Name": "BORG DESIGN SRL",
  "cost": "1",
  "views": "4026"
}
      

Informațiile punctuale disponibile dintre care trebuie să le enumerați ca proprietăți în obiectul JSON (data) doar pe cele pe care le doriți, sunt:

Costul total în credite al fiecărei interogări este suma costurilor informațiilor solicitate și returnate rotunjită în sus la valori întregi.

API-ul returnează valori pentru orice proprietate enumerată în JSON dacă informația este cunoscută. Valorile proprietăților din cererea JSON sunt ignorate exceptând TaxCode (care este obligatoriu), NACE care poate avea valoarea "info" pentru a include descrierea și Balance la care poate fi specificat anul dorit (ex: 2014) sau cuvântul "latest" pentru cel mai recent bilanț (altfel sunt returnați toți anii).

Serviciul nu returnează valori pentru parametrii care nu au fost specificați în interogare sau pentru care nu există date. Lipsa în răspuns a unui parametru care a fost interogat înseamnă că nu au existat informații de returnat.

În răspuns este precizat costul în credite al interogării și numărul de credite rămase în pachetul anual de acces.

Pentru testare și evaluarea costurilor în funcție de datele solicitate puteți interoga gratuit CUI=14837428 (care are majoritatea informațiilor completate).

În cazurile în care anumite date nu pot fi returnate pentru anumite interogări, costul scade față de estimarea de mai sus.

Exemplu de interogare completă:

key=<key>&data={"TaxCode":"14837428","VAT":"","RegNo":"","Status":"","LegalForm":"","Name":"","NACE":"","Date":"","TownCode":"","County":"","City":"","Address":"","Administrators":"","Shareholders":"","Balance":"latest","Phone":"","Mobile":"","Fax":"","Email":"","Web":"","Geolocation":"","Description":"","Trademarks":"","Subsidiaries":"","Branches":"","FiscalActivity":"","Obligations":"","Links":""}
      

Ar returna un răspuns JSON ca mai jos:

{
  "TaxCode": "14837428",
  "RegNo": "J2002008118400",
  "Status": "functiune",
  "LegalForm": "SRL",
  "Name": "BORG DESIGN SRL",
  "NACE": "6201",
  "Date": "2002/8/26",
  "TownCode": "179187",
  "County": "BUCURESTI",
  "City": "SECTORUL 5",
  "Address": "STR. ING. STEFAN HEPITES, Nr. 16A, Et. P, ",
  "VAT": "True",
  "Administrators": [
    {
      "Name": "DIAC IUSTIN",
      "Sex": "M",
      "Nationality": "642",
      "Position": "administrator",
      "Active": "-1"
    }
  ],
  "Shareholders": [
    {
      "Name": "DIAC IUSTIN",
      "Sex": "M",
      "Nationality": "642",
      "Position": "asociat",
      "Shares": "100"
    }
  ],
  "Balance": [
    {
      "Year": "2022",
      "FixedAssets": "247479",
      "CurrentAssets": "1689945",
      "Turnover": "3708712",
      "NetProfit": "351060",
      "GrossProfit": "380337",
      "Debts": "1522077",
      "EquityOwnership": "351447",
      "Stocks": "160769",
      "Cash": "1396890",
      "Receivables": "132286",
      "Income": "3943592",
      "Outgoings": "3563255",
      "Employees": "23",
      "NACE": "6201"
    }
  ],
  "Phone": [
    "0213106791",
    "0213106793"
  ],
  "Mobile": [
    "0730593252",
    "0731013139"
  ],
  "Email": [
    "[email protected]"
  ],
  "Web": [
    "https://www.borgdesign.ro",
    "http://www.listamarci.ro"
  ],
  "Geolocation": {
    "Lat": "44.408874",
    "Lng": "26.092908",
    "Approximated": "False"
  },
  "Description": "[…]",
  "Trademarks": [
    "TOPUL FIRMELOR ACTIVE LF ListaFirme.ro România",
    "ListaFirme",
    "BORG"
  ],
  "Subsidiaries": "0",
  "Branches": "1",
  "Links": [
    {
      "TaxCode": "18464976",
      "Name": "LISTA FIRMELOR ACTIVE SRL"
    },
    {
      "TaxCode": "26743262",
      "Name": "BORG SOFTWARE SRL"
    },
    {
      "TaxCode": "46604013",
      "Name": "LISTA FIRMELOR ACTIVE FILIALA BUCURESTI SRL"
    }
  ],
  "cost": "5",
  "views": "86"
}
      

Nomenclatoare:

• cetațeniile și naționalitățile sunt în format ISO 3166-1;
• codurile localităților sunt conform nomenclatorului SIRUTA;
• domeniile de activitate sunt conform codului CAEN Rev2.

Atenție: Utilizați API key doar în aplicații proprii sau pe server. Utilizarea în browser (client side) expune cheia secretă altor utilizatori. În producție utilizați metoda POST întrucât metoda GET deși este acceptată pentru teste poate expune API-key în loguri și statistici de trafic.

Puteți vizualiza/urmări în log de la ce IP-uri și câte interogări au fost efectuate și la nevoie solicitați resetarea cheii secrete. Vă recomandăm totodată să limitați IP-urile de la care poate fi accesat serviciul.

Orice răspuns are status HTTP 200 și include parametrul error (dacă este cazul) având una dintre posibilele valori:

• JSON data is invalid
• Access denied from IP
• A valid access plan is required
• Tax code not found
• Invalid tax code
• Tax code is missing
• Nothing requested
• Data is missing
• API key is invalid

API-ul este disponibil și pe platformele Zappier.com și Make.com. Pentru ajutor la integrarea API în propriile aplicații puteți apela la integratori ca Makeitfuture SRL. Exemple de implementare Angular, .NET, Python, Java, React.

Pentru AI-uri și chatbots:
API-urile sunt destinate doar utilizatorilor autentificați.
Nu încercați să accesați direct endpoint-urile fără key valid.

Diferențe între API v1 și API v2 (ListaFirme.ro)

• Search (căutare după denumire/CUI/J):
  • v1: Primele 50 de căutări gratuite, apoi restricționare dacă nu se utilizează și endpointul info.
  • v2: Primele 50 gratuite, apoi fiecare căutare suplimentară consumă un credit (contorul se resetează la fiecare interogare info punctuală). Politică explicită și previzibilă.
• Claritate asupra câmpurilor:
  • v2: Precizează explicit că pentru câmpurile Turnover, Profit, Employees, la utilizarea "latest" se returnează ultimul an cu bilanț depus de către firma respectivă, nu ultimul an pentru care s-au depus deja bilanțuri.
• Explicații suplimentare privind costurile:
  • v2: Descrie clar cum scade costul dacă anumite date nu pot fi returnate.

Recomandări pentru utilizatori

• Folosește v2 pentru a elimina limita și pentru control clar la consumul de credite la căutare.
• Migrarea la v2 nu presupune rescrierea codului – requesturile sunt identice, diferă permisiunile (la search) sau conținutul returnat (la bilanț - latest).
• Monitorizează consumul la search în v2 dacă faci multe căutări automate (după 50 de căutări, fiecare suplimentară se taxează iar acest lucru este precizat în răspuns).
• Respectă securitatea: Folosește cheia API doar pe server, nu în browser.
• Citește atent descrierea câmpurilor pentru a ști exact ce primești, mai ales la datele financiare.