API Firmly

Datele despre firmele din România, direct în CRM-ul sau aplicația ta: dosarul unei firme după CUI, liste filtrate după județ, industrie, cifră de afaceri sau semnale de pe site, și căutări după telefon, e-mail ori domeniu. Răspunsurile sunt JSON, doar citire.

Cum începi

Proprietarul contului deschide în aplicație Contul meu → API și creează un token (planurile Pro și Agenție).
Tokenul se vede o singură dată: păstrează-l ca pe o parolă.
Trimite-l la fiecare cerere în antetul Authorization: Bearer fy_….

curl -H "Authorization: Bearer fy_TOKENUL_TAU" \
     https://firmly.ro/api/v1/firme/123456

curl -H "Authorization: Bearer fy_TOKENUL_TAU" \
     "https://firmly.ro/api/v1/firme?judet=cluj&caen=6201&ca_min=1000000&pe_pagina=50"

CUI-ul și filtrele de mai sus sunt exemple; răspunsul conține datele reale ale firmelor găsite.

Limite

Pro: 10.000 de cereri pe lună
Agenție: 50.000 de cereri pe lună
Cel mult 120 de cereri pe minut pe token (10 pe minut la /intreaba).
În listele /api/v1/firme (și la sincronizare), fiecare firmă care vine cu telefon se scade din limita lunară de export a planului, ca un rând exportat. Când limita s-a terminat, listele vin în continuare, dar fără telefoane, cu câmpurile telefoane_oprite și nota_limita. Dosarul unei singure firme (/api/v1/firme/{cui}) nu se scade din export.

Peste cota lunară, API-ul răspunde cu codul 429 și un mesaj în română până la începutul lunii următoare.

Vezi planurile și prețurile →

Endpointuri

GET/api/v1/cauta?q=dedeman #

Caută după CUI, număr de registru (J…), telefon, e-mail, domeniu sau denumire.

Exemplu de răspuns (JSON)

Cerere: GET /api/v1/cauta?q=exemplu&limita=2

{
    "intrebare": "exemplu",
    "tip": "nume",
    "firme": [
        {
            "id": 528533,
            "cui": 99999801,
            "cod_inmatriculare": "J05/1234/2015",
            "denumire": "EXEMPLU SRL",
            "judet": "BIHOR",
            "localitate": "Oradea",
            "stare": "activa",
            "activa": true,
            "caen_principal": "6201",
            "cifra_afaceri": 1250000,
            "profit_net": 180000,
            "angajati": 12,
            "ultim_an": 2025,
            "link": "https://firmly.ro/firma/528533"
        },
        {
            "id": 528534,
            "cui": 99999802,
            "cod_inmatriculare": "J05/5678/2018",
            "denumire": "ALT EXEMPLU SRL",
            "judet": "BIHOR",
            "localitate": "Oradea",
            "stare": "activa",
            "activa": true,
            "caen_principal": "6201",
            "cifra_afaceri": 640000,
            "profit_net": 52000,
            "angajati": 6,
            "ultim_an": 2025,
            "link": "https://firmly.ro/firma/528534"
        }
    ],
    "persoane": []
}

GET/api/v1/firme/{cui} #

Dosarul firmei: identitate, stare ONRC și ANAF, bilanțuri pe ani, contacte cu sursa, site-uri cu scoruri, semnale, firme legate, scorurile de dinamică și de risc, plus istoric_scoruri (ultimele 12 schimbări de cel puțin 5 puncte, cu motivele).

Exemplu de răspuns (JSON)

Cerere: GET /api/v1/firme/99999801

{
    "firma": {
        "id": 528533,
        "cui": 99999801,
        "nr_registru": "J05/1234/2015",
        "coduri_onrc": [],
        "denumire": "EXEMPLU SRL",
        "forma_juridica": "SRL",
        "stare": "activa",
        "stare_detalii": null,
        "activa": true,
        "data_inmatriculare": "2015-03-02",
        "judet": "BIHOR",
        "localitate": "Oradea",
        "adresa": "Str. Exemplului 1",
        "cod_postal": "410001",
        "caen_principal": "6201",
        "caen_autorizate": [],
        "tva": true,
        "tva_la_incasare": null,
        "split_tva": null,
        "efactura": null,
        "inactiv_anaf": null,
        "site_declarat_onrc": null,
        "ultim_bilant": {
            "an": 2025,
            "cifra_afaceri": 1250000,
            "profit_net": 180000,
            "angajati": 12,
            "capitaluri": 400000,
            "datorii": 150000,
            "crestere_ca_pct": 13.64,
            "ca_recenta": 1250000,
            "motiv_fara_bilant_recent": null
        },
        "opozitie": false,
        "link": "https://firmly.ro/firma/528533"
    },
    "bilanturi": {
        "sursa": "mf_bilant",
        "ani": [
            {
                "an": 2025,
                "tip": "UU",
                "caen": "6201",
                "cifra_afaceri": 1250000,
                "venituri": 1275000,
                "cheltuieli": null,
                "profit_brut": null,
                "pierdere_bruta": null,
                "profit_net": 180000,
                "pierdere_neta": 0,
                "angajati": 12,
                "active_imobilizate": null,
                "active_circulante": null,
                "stocuri": null,
                "creante": null,
                "casa_banci": null,
                "datorii": null,
                "capitaluri": null,
                "capital_subscris": null,
                "suspect": false
            },
            {
                "an": 2024,
                "tip": "UU",
                "caen": "6201",
                "cifra_afaceri": 1100000,
                "venituri": 1122000,
                "cheltuieli": null,
                "profit_brut": null,
                "pierdere_bruta": null,
                "profit_net": 150000,
                "pierdere_neta": 0,
                "angajati": 11,
                "active_imobilizate": null,
                "active_circulante": null,
                "stocuri": null,
                "creante": null,
                "casa_banci": null,
                "datorii": null,
                "capitaluri": null,
                "capital_subscris": null,
                "suspect": false
            }
        ]
    },
    "contacte": [
        {
            "al_cui_e_probabil": [],
            "tip": "email",
            "valoare": "office@exemplu.ro",
            "normalizat": "office@exemplu.ro",
            "sursa": "site",
            "sursa_descriere": "de pe site",
            "sursa_url": null,
            "domeniu": null,
            "incredere": "tare",
            "generic": false,
            "vazut_de": 3,
            "apare_la_nr_firme": 1,
            "prima_data": "2026-11-05 14:44:11+02",
            "ultima_data": "2026-11-05 14:44:11+02",
            "scor_incredere": 85,
            "motive_scor": [],
            "server_email_valid": null,
            "tip_adresa": null
        },
        {
            "al_cui_e_probabil": [],
            "tip": "telefon",
            "valoare": "0259000000",
            "normalizat": "0259000000",
            "sursa": "mf",
            "sursa_descriere": "Ministerul Finanțelor — date de identificare",
            "sursa_url": null,
            "domeniu": null,
            "incredere": "tare",
            "generic": false,
            "vazut_de": 1,
            "apare_la_nr_firme": 1,
            "prima_data": "2026-11-05 14:44:11+02",
            "ultima_data": "2026-11-05 14:44:11+02",
            "scor_incredere": 90,
            "motive_scor": [],
            "server_email_valid": null,
            "tip_adresa": null
        }
    ],
    "site_uri": [
        {
            "email_si_dns": null,
            "viteza_reala_chrome": null,
            "masurare": {
                "conversii_google_ads": null,
                "consent_mode": null,
                "conversii_imbunatatite": null,
                "server_side": null
            },
            "curieri": [],
            "limbi": [],
            "adrese_pe_site": null,
            "agentie_web": null,
            "incarcare_ms": null,
            "domeniu": "exemplu.ro",
            "status": "viu",
            "http": null,
            "url_final": null,
            "legatura": {
                "incredere": 99,
                "metoda": "cui_site",
                "sigura": true,
                "sursa": "onrc",
                "dovezi": null,
                "verificata": null
            },
            "titlu": "Exemplu SRL — aplicații web",
            "descriere": null,
            "platforma": "wordpress",
            "magazin": null,
            "tema": null,
            "versiune_cms": null,
            "versiuni": null,
            "produse": null,
            "semnale": [],
            "lipsuri": [],
            "prin_google_tag_manager": [],
            "scor_calitate": 72,
            "scor_seo": 64,
            "seo_lipsuri": [],
            "scor_ai": null,
            "ai_lipsuri": [],
            "llms_txt": null,
            "probleme": [],
            "chat": [],
            "ssl_expira": null,
            "mobil": null,
            "sitemap_ultima_modificare": null,
            "id_uri_masurare": [
                {
                    "tip": "gtm",
                    "id": "GTM-EXEMPLU",
                    "sursa": "direct pe pagină",
                    "alte_site_uri_cu_acelasi_id": 0,
                    "prima_data": "2026-11-05 14:44:11+02",
                    "ultima_data": "2026-11-05 14:44:11+02"
                }
            ],
            "tehnologii": null,
            "ultimul_crawl": null,
            "nr_crawluri": null,
            "sursa": "site"
        }
    ],
    "mentionata_pe": [],
    "asociati_monitorul_oficial": null,
    "semnale_financiare": null,
    "scoruri": null,
    "limita_credit": {
        "limita_lei": null,
        "nivel": null,
        "nivel_eticheta": null,
        "motive": [
            "Limita nu e calculată încă pentru această firmă: se calculează în fiecare dimineață, după scorurile de risc."
        ],
        "baza_lei": null,
        "calculat_la": null,
        "nota": "Estimare automată din date publice (bilanțul MF, ANAF, ONRC, instanțe), recalculată zilnic — nu e o garanție de plată și nu înlocuiește verificarea ta (contract, garanții, istoricul plăților cu tine)."
    },
    "istoric_scoruri": [],
    "sediu": null,
    "dosare_instante": [],
    "subventii_afir": [],
    "pe_harta": [],
    "firme_legate": [],
    "anaf": null,
    "mf_identificare": null,
    "modificari": [],
    "istoric": [],
    "grup_firme": null,
    "contracte_publice": {
        "sursa": "SEAP (ADR, data.gov.ro)",
        "total": null,
        "ultimele": []
    },
    "fonduri_ue": [],
    "marci_osim": [],
    "reclame_meta": [],
    "social": {
        "profiluri": [],
        "reclame_meta": {
            "active_acum": 0,
            "minim": null,
            "de_la": null,
            "platforme": [],
            "verificat_la": null,
            "ultimele": []
        },
        "sursa": "linkurile de pe site-ul firmei și din hărți (Overture, OSM); metricele paginilor doar din API-uri oficiale; reclamele din biblioteca publică Meta"
    },
    "surse": {
        "onrc": "ONRC — Registrul Comerțului (date deschise)",
        "mf": "Ministerul Finanțelor — date de identificare",
        "mf_bilant": "Ministerul Finanțelor — situații financiare",
        "anaf": "ANAF — serviciul web de verificare TVA",
        "site": "site-ul firmei (crawl propriu)",
        "site_pista": "site legat probabil de firmă (nu prin CUI)"
    },
    "persoane_ascunse": "Datele despre persoane fizice nu sunt incluse în planul acestui cont."
}

GET/api/v1/firme/id/{id} #

Același dosar, după id-ul intern (pentru entitățile fără CUI).

Exemplu de răspuns (JSON)

Cerere: GET /api/v1/firme/id/528534

{
    "firma": {
        "id": 528534,
        "cui": 99999802,
        "nr_registru": "J05/5678/2018",
        "coduri_onrc": [],
        "denumire": "ALT EXEMPLU SRL",
        "forma_juridica": "SRL",
        "stare": "activa",
        "stare_detalii": null,
        "activa": true,
        "data_inmatriculare": "2018-06-11",
        "judet": "BIHOR",
        "localitate": "Oradea",
        "adresa": "Str. Exemplului 2",
        "cod_postal": null,
        "caen_principal": "6201",
        "caen_autorizate": [],
        "tva": true,
        "tva_la_incasare": null,
        "split_tva": null,
        "efactura": null,
        "inactiv_anaf": null,
        "site_declarat_onrc": null,
        "ultim_bilant": {
            "an": 2025,
            "cifra_afaceri": 640000,
            "profit_net": 52000,
            "angajati": 6,
            "capitaluri": null,
            "datorii": null,
            "crestere_ca_pct": null,
            "ca_recenta": 640000,
            "motiv_fara_bilant_recent": null
        },
        "opozitie": false,
        "link": "https://firmly.ro/firma/528534"
    },
    "bilanturi": {
        "sursa": "mf_bilant",
        "ani": [
            {
                "an": 2025,
                "tip": "UU",
                "caen": "6201",
                "cifra_afaceri": 640000,
                "venituri": 652800,
                "cheltuieli": null,
                "profit_brut": null,
                "pierdere_bruta": null,
                "profit_net": 52000,
                "pierdere_neta": 0,
                "angajati": 6,
                "active_imobilizate": null,
                "active_circulante": null,
                "stocuri": null,
                "creante": null,
                "casa_banci": null,
                "datorii": null,
                "capitaluri": null,
                "capital_subscris": null,
                "suspect": false
            }
        ]
    },
    "contacte": [],
    "site_uri": [],
    "mentionata_pe": [],
    "asociati_monitorul_oficial": null,
    "semnale_financiare": null,
    "scoruri": null,
    "limita_credit": {
        "limita_lei": null,
        "nivel": null,
        "nivel_eticheta": null,
        "motive": [
            "Limita nu e calculată încă pentru această firmă: se calculează în fiecare dimineață, după scorurile de risc."
        ],
        "baza_lei": null,
        "calculat_la": null,
        "nota": "Estimare automată din date publice (bilanțul MF, ANAF, ONRC, instanțe), recalculată zilnic — nu e o garanție de plată și nu înlocuiește verificarea ta (contract, garanții, istoricul plăților cu tine)."
    },
    "istoric_scoruri": [],
    "sediu": null,
    "dosare_instante": [],
    "subventii_afir": [],
    "pe_harta": [],
    "firme_legate": [],
    "anaf": null,
    "mf_identificare": null,
    "modificari": [],
    "istoric": [],
    "grup_firme": null,
    "contracte_publice": {
        "sursa": "SEAP (ADR, data.gov.ro)",
        "total": null,
        "ultimele": []
    },
    "fonduri_ue": [],
    "marci_osim": [],
    "reclame_meta": [],
    "social": {
        "profiluri": [],
        "reclame_meta": {
            "active_acum": 0,
            "minim": null,
            "de_la": null,
            "platforme": [],
            "verificat_la": null,
            "ultimele": []
        },
        "sursa": "linkurile de pe site-ul firmei și din hărți (Overture, OSM); metricele paginilor doar din API-uri oficiale; reclamele din biblioteca publică Meta"
    },
    "surse": {
        "onrc": "ONRC — Registrul Comerțului (date deschise)",
        "mf": "Ministerul Finanțelor — date de identificare",
        "mf_bilant": "Ministerul Finanțelor — situații financiare",
        "anaf": "ANAF — serviciul web de verificare TVA",
        "site": "site-ul firmei (crawl propriu)",
        "site_pista": "site legat probabil de firmă (nu prin CUI)"
    },
    "persoane_ascunse": "Datele despre persoane fizice nu sunt incluse în planul acestui cont."
}

GET/api/v1/firme?judet=bihor&caen=4321&ca_min=1000000&are_site=nu #

Listă filtrată, cu aceleași filtre ca pagina Firme din aplicație (paginare: pagina, pe_pagina).

Exemplu de răspuns (JSON)

Cerere: GET /api/v1/firme?caen=6201&stare=toate&pe_pagina=2

{
    "filtre": {
        "stare": "toate",
        "caen": "6201"
    },
    "pagina": 1,
    "pe_pagina": 2,
    "mai_sunt": false,
    "firme": [
        {
            "updated_at": "2026-11-05T14:44:11.000000+02:00",
            "id": 528533,
            "cui": 99999801,
            "cod_inmatriculare": "J05/1234/2015",
            "denumire": "EXEMPLU SRL",
            "forma_juridica": "SRL",
            "judet": "BIHOR",
            "localitate": "Oradea",
            "caen_principal": "6201",
            "stare": "activa",
            "tva": true,
            "cifra_afaceri": 1250000,
            "profit_net": 180000,
            "angajati": 12,
            "ultim_an": 2025,
            "nr_site_uri": 0,
            "platforma_magazin": null,
            "telefon": "0259000000",
            "ca_recenta": 1250000,
            "bilant_lipsa_motiv": null,
            "opozitie": false,
            "limita_credit": null,
            "site_uri": [
                {
                    "domeniu": "exemplu.ro",
                    "platforma": "wordpress",
                    "magazin": null,
                    "scor_seo": 64,
                    "scor_ai": null,
                    "calitate": 72,
                    "probleme": [],
                    "incredere_legatura": 99
                }
            ],
            "site_uri_probabile": [],
            "link": "https://firmly.ro/firma/528533"
        },
        {
            "updated_at": "2026-11-05T14:44:11.000000+02:00",
            "id": 528534,
            "cui": 99999802,
            "cod_inmatriculare": "J05/5678/2018",
            "denumire": "ALT EXEMPLU SRL",
            "forma_juridica": "SRL",
            "judet": "BIHOR",
            "localitate": "Oradea",
            "caen_principal": "6201",
            "stare": "activa",
            "tva": true,
            "cifra_afaceri": 640000,
            "profit_net": 52000,
            "angajati": 6,
            "ultim_an": 2025,
            "nr_site_uri": 0,
            "platforma_magazin": null,
            "telefon": null,
            "ca_recenta": 640000,
            "bilant_lipsa_motiv": null,
            "opozitie": false,
            "limita_credit": null,
            "site_uri": [],
            "site_uri_probabile": [],
            "link": "https://firmly.ro/firma/528534"
        }
    ]
}

GET/api/v1/firme?modificate_dupa=2026-10-01T00:00:00%2B03:00 #

Sincronizare: doar firmele schimbate după o dată, în ordinea schimbării (câmpul updated_at), cu paginare prin cursor. Vezi „Sincronizare” mai jos.

Exemplu de răspuns (JSON)

Cerere: GET /api/v1/firme?modificate_dupa=2026-10-01T00:00:00+03:00&caen=6201&pe_pagina=2

{
    "filtre": {
        "caen": "6201",
        "stare": "toate"
    },
    "pagina": null,
    "pe_pagina": 2,
    "mai_sunt": false,
    "modificate_dupa": "2026-10-01T00:00:00.000000+03:00",
    "complet_pana_la": "2026-11-05T14:44:11.239812+02:00",
    "cursor_urmator": null,
    "urmatoarea_pagina": null,
    "firme": [
        {
            "updated_at": "2026-11-05T14:44:11.000000+02:00",
            "id": 528533,
            "cui": 99999801,
            "cod_inmatriculare": "J05/1234/2015",
            "denumire": "EXEMPLU SRL",
            "forma_juridica": "SRL",
            "judet": "BIHOR",
            "localitate": "Oradea",
            "caen_principal": "6201",
            "stare": "activa",
            "tva": true,
            "cifra_afaceri": 1250000,
            "profit_net": 180000,
            "angajati": 12,
            "ultim_an": 2025,
            "nr_site_uri": 0,
            "platforma_magazin": null,
            "telefon": "0259000000",
            "ca_recenta": 1250000,
            "bilant_lipsa_motiv": null,
            "opozitie": false,
            "limita_credit": null,
            "site_uri": [
                {
                    "domeniu": "exemplu.ro",
                    "platforma": "wordpress",
                    "magazin": null,
                    "scor_seo": 64,
                    "scor_ai": null,
                    "calitate": 72,
                    "probleme": [],
                    "incredere_legatura": 99
                }
            ],
            "site_uri_probabile": [],
            "link": "https://firmly.ro/firma/528533"
        },
        {
            "updated_at": "2026-11-05T14:44:11.000000+02:00",
            "id": 528534,
            "cui": 99999802,
            "cod_inmatriculare": "J05/5678/2018",
            "denumire": "ALT EXEMPLU SRL",
            "forma_juridica": "SRL",
            "judet": "BIHOR",
            "localitate": "Oradea",
            "caen_principal": "6201",
            "stare": "activa",
            "tva": true,
            "cifra_afaceri": 640000,
            "profit_net": 52000,
            "angajati": 6,
            "ultim_an": 2025,
            "nr_site_uri": 0,
            "platforma_magazin": null,
            "telefon": null,
            "ca_recenta": 640000,
            "bilant_lipsa_motiv": null,
            "opozitie": false,
            "limita_credit": null,
            "site_uri": [],
            "site_uri_probabile": [],
            "link": "https://firmly.ro/firma/528534"
        }
    ]
}

GET/api/v1/segmente #

Segmentele gata făcute (de exemplu „bani, dar fără marketing”), folosite apoi cu /api/v1/firme?segment=<cheie>.

Exemplu de răspuns (JSON)

Cerere: GET /api/v1/segmente

[
    {
        "cheie": "bani_fara_marketing",
        "titlu": "Bani, dar fără marketing",
        "descriere": "CA peste 1 mil., în creștere, site viu fără GA4, Google Ads și pixel Meta",
        "filtre": {
            "stare": "activa",
            "risc": "nu",
            "client": "nu",
            "opozitie": "nu",
            "ca_min": 1000000,
            "crestere_min": 5,
            "fara_toate": [
                "ga4",
                "google_ads"
            ]
        },
        "folosire": "/api/v1/firme?segment=bani_fara_marketing"
    },
    {
        "cheie": "ads_masurare_slaba",
        "titlu": "Plătesc Google Ads, dar măsoară prost",
        "descriere": "tag Google Ads fără conversii sau fără Consent Mode",
        "filtre": {
            "stare": "activa",
            "risc": "nu",
            "client": "nu",
            "opozitie": "nu",
            "semnal": [
                "google_ads"
            ],
            "ads_conversii": "nu"
        },
        "folosire": "/api/v1/firme?segment=ads_masurare_slaba"
    }
]

GET/api/v1/telefon/{numar} #

Firmele la care apare un număr de telefon, cu sursa.

Exemplu de răspuns (JSON)

Cerere: GET /api/v1/telefon/0259000000

{
    "telefon": "0259000000",
    "firme": [
        {
            "id": 528533,
            "cui": 99999801,
            "denumire": "EXEMPLU SRL",
            "judet": "BIHOR",
            "stare": "activa",
            "activa": true,
            "aparitii": [
                {
                    "sursa": "mf",
                    "domeniu": null,
                    "valoare": "0259000000",
                    "incredere": "tare",
                    "sursa_url": null
                }
            ],
            "link": "https://firmly.ro/firma/528533"
        }
    ],
    "al_cui_e_probabil": []
}

GET/api/v1/email/{adresa} #

Firmele la care apare o adresă de e-mail.

Exemplu de răspuns (JSON)

Cerere: GET /api/v1/email/office@exemplu.ro

{
    "email": "office@exemplu.ro",
    "domeniu": "exemplu.ro",
    "firme": [
        {
            "id": 528533,
            "cui": 99999801,
            "denumire": "EXEMPLU SRL",
            "judet": "BIHOR",
            "stare": "activa",
            "activa": true,
            "aparitii": [
                {
                    "sursa": "site",
                    "domeniu": null,
                    "valoare": "office@exemplu.ro",
                    "incredere": "tare",
                    "sursa_url": null
                }
            ],
            "link": "https://firmly.ro/firma/528533"
        }
    ]
}

GET/api/v1/domeniu/{domeniu} #

Tot ce știm despre un site, plus site-urile cu aceleași coduri de măsurare (GTM, GA, Google Ads, pixel Meta).

Exemplu de răspuns (JSON)

Cerere: GET /api/v1/domeniu/exemplu.ro

{
    "domeniu": {
        "email_si_dns": null,
        "viteza_reala_chrome": null,
        "masurare": {
            "conversii_google_ads": null,
            "consent_mode": null,
            "conversii_imbunatatite": null,
            "server_side": null
        },
        "curieri": [],
        "limbi": [],
        "adrese_pe_site": null,
        "agentie_web": null,
        "incarcare_ms": null,
        "domeniu": "exemplu.ro",
        "status": "viu",
        "http": null,
        "url_final": null,
        "legatura": {
            "incredere": 99,
            "metoda": "cui_site",
            "sigura": true,
            "sursa": "onrc",
            "dovezi": null,
            "verificata": null
        },
        "titlu": "Exemplu SRL — aplicații web",
        "descriere": null,
        "platforma": "wordpress",
        "magazin": null,
        "tema": null,
        "versiune_cms": null,
        "versiuni": null,
        "produse": null,
        "semnale": [],
        "lipsuri": [],
        "prin_google_tag_manager": [],
        "scor_calitate": 72,
        "scor_seo": 64,
        "seo_lipsuri": [],
        "scor_ai": null,
        "ai_lipsuri": [],
        "llms_txt": null,
        "probleme": [],
        "chat": [],
        "ssl_expira": null,
        "mobil": null,
        "sitemap_ultima_modificare": null,
        "id_uri_masurare": [
            {
                "tip": "gtm",
                "id": "GTM-EXEMPLU",
                "sursa": "direct pe pagină",
                "alte_site_uri_cu_acelasi_id": 0,
                "prima_data": "2026-11-05 14:44:11+02",
                "ultima_data": "2026-11-05 14:44:11+02"
            }
        ],
        "tehnologii": null,
        "ultimul_crawl": null,
        "nr_crawluri": null,
        "sursa": "site"
    },
    "firma": {
        "id": 528533,
        "cui": 99999801,
        "denumire": "EXEMPLU SRL",
        "judet": "BIHOR",
        "activa": true
    },
    "site_uri_cu_aceleasi_id_uri": [],
    "istoric_crawl": []
}

GET/api/v1/tracker/{id} #

Toate site-urile cu un cod de măsurare (de exemplu GTM-XXXX sau G-XXXX).

Exemplu de răspuns (JSON)

Cerere: GET /api/v1/tracker/GTM-EXEMPLU

{
    "id": "GTM-EXEMPLU",
    "nr_site_uri": 1,
    "site_uri": [
        {
            "kind": "gtm",
            "value": "GTM-EXEMPLU",
            "domain": "exemplu.ro",
            "status": "viu",
            "platform": "wordpress",
            "first_seen_at": "2026-11-05 14:44:11+02",
            "last_seen_at": "2026-11-05 14:44:11+02",
            "firma_id": 528533,
            "cui": 99999801,
            "denumire": "EXEMPLU SRL"
        }
    ]
}

GET/api/v1/stare #

Câte date avem, pe surse.

Exemplu de răspuns (JSON)

Cerere: GET /api/v1/stare

{
    "firme": 8,
    "firme_active": 8,
    "persoane": 5,
    "legaturi_persoana_firma": 7,
    "contacte": [
        {
            "type": "email",
            "source": "site",
            "n": 1
        },
        {
            "type": "telefon",
            "source": "mf",
            "n": 5
        }
    ],
    "telefoane_cu_proprietar_probabil": 3,
    "site_uri": [
        {
            "status": "viu",
            "n": 1
        }
    ],
    "id_uri_masurare": [
        {
            "kind": "gtm",
            "n": 1
        }
    ],
    "bilanturi": [
        {
            "an": 2023,
            "n": 1
        },
        {
            "an": 2024,
            "n": 3
        }
    ],
    "anaf_verificate": 0,
    "actualizat": "2026-11-05T14:44:11+02:00"
}

POST/api/v1/intreaba #

O întrebare liberă despre o firmă, un telefon sau un domeniu; răspunsul se formează doar din datele găsite. Corp JSON: {"intrebare": "..."}.

Exemplu de răspuns (JSON)

Cerere: POST /api/v1/intreaba {"intrebare":"Ce știi despre EXEMPLU SRL, CUI 99999801?"}

{
    "intrebare": "Ce știi despre EXEMPLU SRL, CUI 99999801?",
    "raspuns": "EXEMPLU SRL — CUI 99999801, J05/1234/2015, activa, BIHOR Oradea, CAEN 6201 (ONRC/MF).\n  Bilanț 2025: CA 1.250.000 lei, profit net 180.000 lei, 12 angajați (MF).\n  email: office@exemplu.ro (sursa: de pe site)\n  telefon: 0259000000 (sursa: Ministerul Finanțelor — date de identificare)\n  site exemplu.ro (viu): platformă wordpress, SEO 64, AI , ID-uri: gtm GTM-EXEMPLU.",
    "generat_de": "rezumat automat (fără model de limbaj)",
    "gasite": {
        "firme": [
            528533
        ],
        "persoane": [],
        "telefoane": []
    },
    "analiza": null,
    "date": {
        "firme": [
            {
                "firma": {
                    "id": 528533,
                    "cui": 99999801,
                    "nr_registru": "J05/1234/2015",
                    "coduri_onrc": [],
                    "denumire": "EXEMPLU SRL",
                    "forma_juridica": "SRL",
                    "stare": "activa",
                    "stare_detalii": null,
                    "activa": true,
                    "data_inmatriculare": "2015-03-02",
                    "judet": "BIHOR",
                    "localitate": "Oradea",
                    "adresa": "Str. Exemplului 1",
                    "cod_postal": "410001",
                    "caen_principal": "6201",
                    "caen_autorizate": [],
                    "tva": true,
                    "tva_la_incasare": null,
                    "split_tva": null,
                    "efactura": null,
                    "inactiv_anaf": null,
                    "site_declarat_onrc": null,
                    "ultim_bilant": {
                        "an": 2025,
                        "cifra_afaceri": 1250000,
                        "profit_net": 180000,
                        "angajati": 12,
                        "capitaluri": 400000,
                        "datorii": 150000,
                        "crestere_ca_pct": 13.64,
                        "ca_recenta": 1250000,
                        "motiv_fara_bilant_recent": null
                    },
                    "opozitie": false,
                    "link": "https://firmly.ro/firma/528533"
                },
                "bilanturi": {
                    "sursa": "mf_bilant",
                    "ani": [
                        {
                            "an": 2025,
                            "tip": "UU",
                            "caen": "6201",
                            "cifra_afaceri": 1250000,
                            "venituri": 1275000,
                            "cheltuieli": null,
                            "profit_brut": null,
                            "pierdere_bruta": null,
                            "profit_net": 180000,
                            "pierdere_neta": 0,
                            "angajati": 12,
                            "active_imobilizate": null,
                            "active_circulante": null,
                            "stocuri": null,
                            "creante": null,
                            "casa_banci": null,
                            "datorii": null,
                            "capitaluri": null,
                            "capital_subscris": null,
                            "suspect": false
                        },
                        {
                            "an": 2024,
                            "tip": "UU",
                            "caen": "6201",
                            "cifra_afaceri": 1100000,
                            "venituri": 1122000,
                            "cheltuieli": null,
                            "profit_brut": null,
                            "pierdere_bruta": null,
                            "profit_net": 150000,
                            "pierdere_neta": 0,
                            "angajati": 11,
                            "active_imobilizate": null,
                            "active_circulante": null,
                            "stocuri": null,
                            "creante": null,
                            "casa_banci": null,
                            "datorii": null,
                            "capitaluri": null,
                            "capital_subscris": null,
                            "suspect": false
                        }
                    ]
                },
                "contacte": [
                    {
                        "al_cui_e_probabil": [],
                        "tip": "email",
                        "valoare": "office@exemplu.ro",
                        "normalizat": "office@exemplu.ro",
                        "sursa": "site",
                        "sursa_descriere": "de pe site",
                        "sursa_url": null,
                        "domeniu": null,
                        "incredere": "tare",
                        "generic": false,
                        "vazut_de": 3,
                        "apare_la_nr_firme": 1,
                        "prima_data": "2026-11-05 14:44:11+02",
                        "ultima_data": "2026-11-05 14:44:11+02",
                        "scor_incredere": 85,
                        "motive_scor": [],
                        "server_email_valid": null,
                        "tip_adresa": null
                    },
                    {
                        "al_cui_e_probabil": [],
                        "tip": "telefon",
                        "valoare": "0259000000",
                        "normalizat": "0259000000",
                        "sursa": "mf",
                        "sursa_descriere": "Ministerul Finanțelor — date de identificare",
                        "sursa_url": null,
                        "domeniu": null,
                        "incredere": "tare",
                        "generic": false,
                        "vazut_de": 1,
                        "apare_la_nr_firme": 1,
                        "prima_data": "2026-11-05 14:44:11+02",
                        "ultima_data": "2026-11-05 14:44:11+02",
                        "scor_incredere": 90,
                        "motive_scor": [],
                        "server_email_valid": null,
                        "tip_adresa": null
                    }
                ],
                "site_uri": [
                    {
                        "email_si_dns": null,
                        "viteza_reala_chrome": null,
                        "masurare": {
                            "conversii_google_ads": null,
                            "consent_mode": null,
                            "conversii_imbunatatite": null,
                            "server_side": null
                        },
                        "curieri": [],
                        "limbi": [],
                        "adrese_pe_site": null,
                        "agentie_web": null,
                        "incarcare_ms": null,
                        "domeniu": "exemplu.ro",
                        "status": "viu",
                        "http": null,
                        "url_final": null,
                        "legatura": {
                            "incredere": 99,
                            "metoda": "cui_site",
                            "sigura": true,
                            "sursa": "onrc",
                            "dovezi": null,
                            "verificata": null
                        },
                        "titlu": "Exemplu SRL — aplicații web",
                        "descriere": null,
                        "platforma": "wordpress",
                        "magazin": null,
                        "tema": null,
                        "versiune_cms": null,
                        "versiuni": null,
                        "produse": null,
                        "semnale": [],
                        "lipsuri": [],
                        "prin_google_tag_manager": [],
                        "scor_calitate": 72,
                        "scor_seo": 64,
                        "seo_lipsuri": [],
                        "scor_ai": null,
                        "ai_lipsuri": [],
                        "llms_txt": null,
                        "probleme": [],
                        "chat": [],
                        "ssl_expira": null,
                        "mobil": null,
                        "sitemap_ultima_modificare": null,
                        "id_uri_masurare": [
                            {
                                "tip": "gtm",
                                "id": "GTM-EXEMPLU",
                                "sursa": "direct pe pagină",
                                "alte_site_uri_cu_acelasi_id": 0,
                                "prima_data": "2026-11-05 14:44:11+02",
                                "ultima_data": "2026-11-05 14:44:11+02"
                            }
                        ],
                        "tehnologii": null,
                        "ultimul_crawl": null,
                        "nr_crawluri": null,
                        "sursa": "site"
                    }
                ],
                "mentionata_pe": [],
                "asociati_monitorul_oficial": null,
                "semnale_financiare": null,
                "scoruri": null,
                "limita_credit": {
                    "limita_lei": null,
                    "nivel": null,
                    "nivel_eticheta": null,
                    "motive": [
                        "Limita nu e calculată încă pentru această firmă: se calculează în fiecare dimineață, după scorurile de risc."
                    ],
                    "baza_lei": null,
                    "calculat_la": null,
                    "nota": "Estimare automată din date publice (bilanțul MF, ANAF, ONRC, instanțe), recalculată zilnic — nu e o garanție de plată și nu înlocuiește verificarea ta (contract, garanții, istoricul plăților cu tine)."
                },
                "istoric_scoruri": [],
                "sediu": null,
                "dosare_instante": [],
                "subventii_afir": [],
                "pe_harta": [],
                "firme_legate": [],
                "anaf": null,
                "mf_identificare": null,
                "modificari": [],
                "istoric": [],
                "grup_firme": null,
                "contracte_publice": {
                    "sursa": "SEAP (ADR, data.gov.ro)",
                    "total": null,
                    "ultimele": []
                },
                "fonduri_ue": [],
                "marci_osim": [],
                "reclame_meta": [],
                "social": {
                    "profiluri": [],
                    "reclame_meta": {
                        "active_acum": 0,
                        "minim": null,
                        "de_la": null,
                        "platforme": [],
                        "verificat_la": null,
                        "ultimele": []
                    },
                    "sursa": "linkurile de pe site-ul firmei și din hărți (Overture, OSM); metricele paginilor doar din API-uri oficiale; reclamele din biblioteca publică Meta"
                },
                "surse": {
                    "onrc": "ONRC — Registrul Comerțului (date deschise)",
                    "mf": "Ministerul Finanțelor — date de identificare",
                    "mf_bilant": "Ministerul Finanțelor — situații financiare",
                    "anaf": "ANAF — serviciul web de verificare TVA",
                    "site": "site-ul firmei (crawl propriu)",
                    "site_pista": "site legat probabil de firmă (nu prin CUI)"
                },
                "persoane_ascunse": "Datele despre persoane fizice nu sunt incluse în planul acestui cont."
            }
        ]
    }
}

GET/api/v1/analize #

Lista analizelor: contracte publice (SEAP, TED), dosare și insolvență, legături și grupuri, risc, indicatori financiari, TVA, mărci, fonduri UE — cu parametrii fiecăreia și exemple de întrebări.
GET/api/v1/analize/{cheie}?firma=<CUI> #

O analiză: titlu, text, cifre-cheie, tabel, surse, limite și datele brute (date). Parametrii comuni: firma, firma2, autoritate, judet, an, de_la, pana_la, cpv, dosar, text, rol, categorie, tip, caen, limita, pagina.

Exemplele sunt răspunsuri reale ale API-ului, rulat pe date de test inventate (EXEMPLU SRL, exemplu.ro); listele lungi sunt scurtate la primele două elemente. Câmpurile sunt exact cele pe care le primești.

Conectorul AI: Claude și ChatGPT (MCP)

Fără cod: în planul Agenție, Firmly se adaugă în Claude sau în ChatGPT ca un conector, iar echipa întreabă direct în conversație — fișe de firme, liste cu filtre, piața, coada de apeluri, pipeline-ul — și face acțiuni (liste, coadă, rezultatul apelurilor) cu confirmare.

În Claude: Setări → Conectori → Adaugă conector personalizat; în ChatGPT: Setări → Aplicații și conectori → Create (modul dezvoltator), cu adresa https://firmly.ro/mcp.
Te loghezi cu contul Firmly și apeși Permite (OAuth 2.1 cu PKCE; fiecare om cu contul lui, cu drepturile lui).
Conexiunile se văd și se opresc din Contul meu → Conector AI; consumul, în Contul meu → Activitate. Totul despre conector: firmly.ro/conector-ai. Claude Code: claude mcp add --transport http firmly https://firmly.ro/mcp.

Sincronizare: doar ce s-a schimbat

Dacă ții o copie a firmelor în CRM, nu descărca totul în fiecare zi: cere doar firmele modificate de la ultima sincronizare. Fiecare firmă din listă are câmpul updated_at — momentul ultimei schimbări a datelor ei la noi.

Prima cerere: /api/v1/firme?modificate_dupa=2026-10-01T00:00:00%2B03:00&pe_pagina=500. Data e în format ISO 8601: doar ziua (2026-10-01) sau ziua cu ora și fusul; fără fus, ora e a României. Semnul „+” din fus se scrie %2B în adresă.
Firmele vin în ordinea schimbării (updated_at, apoi id). Cât timp mai_sunt e true, cere pagina următoare cu cursor= valoarea din cursor_urmator (sau deschide direct urmatoarea_pagina), păstrând aceiași parametri.
Când cursor_urmator e null, ai terminat. Data pentru sincronizarea următoare: cel mai mare updated_at primit.

curl -H "Authorization: Bearer fy_TOKENUL_TAU" \
     "https://firmly.ro/api/v1/firme?modificate_dupa=2026-10-01&judet=cluj&pe_pagina=500"

Cu modificate_dupa, lista cuprinde și firmele radiate sau intrate în insolvență (ca să afli și de ele), dacă nu ceri altfel cu stare=. Celelalte filtre (județ, CAEN, cifră de afaceri…) se aplică la fel.
Paginarea cu cursor e stabilă: o firmă schimbată în timp ce citești paginile nu se pierde — apare din nou la final, cu noul updated_at. Parametrul pagina nu se folosește aici.
Dacă un import de date e chiar în curs, răspunsul se oprește la momentul lui de început (câmpul complet_pana_la); ce scrie importul vine la sincronizarea următoare, deci nu pierzi nimic.
Un cursor sau o dată greșită primesc răspunsul 422, cu explicația în română.
updated_at arată schimbările reale din 6 octombrie 2026; înainte, toate firmele erau rescrise zilnic, așa că o sincronizare cu o dată mai veche le aduce pe toate (o dată, ca o copie completă).

Exporturi CSV: Excel, HubSpot, Pipedrive

Din aplicație (Firme și filtre → Export CSV, firmele bifate sau Liste salvate → Export) descarci firmele filtrului în trei forme. Toate au aceleași rânduri și aceleași reguli: fără firmele și contactele din registrul de opoziție, fără contactele raportate greșit, doar site-uri legate sigur de firmă; intră în limita lunară de export a planului (cel mult 50.000 de rânduri pe export).

CSV pentru Excel

Separator „;”, UTF-8 cu BOM. Coloane: CUI, Nr. registru, Denumire, Formă, Județ, Localitate, Adresă, CAEN, Stare, TVA, Cifră de afaceri, Profit net, Angajați, An bilanț, Telefon, E-mail, Site-uri, Site probabil, De ce avem încredere.

HubSpot (Companies)

Separator „,”, UTF-8. Coloane: Company name, Company domain name, Phone number, City, State/Region, Country/Region, Industry, Number of employees, Annual revenue, CUI, Cod CAEN. „Industry” e completat doar unde codul CAEN se potrivește clar cu lista fixă a HubSpot; „Annual revenue” e în lei; telefonul în format +40.

În HubSpot: CRM → Companii → Importă (dreapta sus) → Începe un import → Fișier de pe calculator → Un fișier → Un obiect → Companii.
Încarcă fișierul; coloanele se potrivesc singure cu proprietățile implicite (Company name, Company domain name, Phone number…).
Pentru „CUI” și „Cod CAEN” alege „Creează o proprietate nouă” (tip text) sau „Nu importa coloana”. Cifra de afaceri e în lei.
Domeniul (Company domain name) e cheia după care HubSpot evită dublurile: firmele fără site sigur intră fără domeniu.

Pipedrive (Organizations)

Separator „,”, UTF-8. Coloane: Name, Address, Phone, Website, CUI, Cod CAEN. Adresa e completă (stradă, localitate, județ, România), site-ul cu https://.

În Pipedrive: Contacte → Organizații → meniul „…” (sau Setări → Unelte → Importă date) → Din foaie de calcul → încarcă fișierul.
La potrivirea coloanelor alege entitatea Organizație: Name → Nume, Address → Adresă (Pipedrive o pune singur pe hartă).
Pentru Phone, Website, CUI și Cod CAEN alege câmpul existent sau „Adaugă un câmp personalizat” (tip text).
Pipedrive caută dublurile după nume: dacă ai deja firma, alege la import „Îmbină cu înregistrarea existentă”.

Perioada de probă: un export de probă de cel mult 100 de rânduri în total (în oricare dintre forme), cu aceleași coloane și aceleași firme (inclusiv PFA, II și IF); firmele livrate prin webhook în perioada de probă se scad din aceleași 100 de rânduri. Aplicația arată câte rânduri ți-au rămas. Din linkul exportului: /firme/export?judet=cluj&caen=6201&format=hubspot (format = hubspot, pipedrive sau lipsă pentru CSV-ul obișnuit).

Webhook „firmă nouă în listă”

Pe o listă salvată (filtrele din Firme și filtre), proprietarul contului poate pune o adresă https (Liste salvate → Webhook). Lista se recalculează în fiecare dimineață; când au apărut firme noi, îți trimitem o cerere POST cu firmele noi, în JSON. Merge direct cu Zapier, Make, n8n sau propriul server.

Antete: Content-Type: application/json, X-Firmly-Eveniment (lista.firme_noi sau test), X-Firmly-Livrare (id unic, același la reîncercări: păstrează-l ca să nu procesezi de două ori), X-Firmly-Semnatura.
Semnătura: sha256= + HMAC-SHA256 (hex) al corpului exact al cererii, cu secretul primit la pornirea webhook-ului. Secretul se vede o singură dată; îl păstrăm criptat și poți genera oricând altul.
Răspunsul tău: orice cod 2xx în cel mult 5 secunde. Altfel reîncercăm de încă 2 ori (după 1 și după 5 minute). Redirecționările (3xx) nu se urmează și contează ca eșec.
Oprire automată: după 10 livrări eșuate la rând webhook-ul se oprește, cu mesaj în Liste salvate; îl pornești din nou după ce repari adresa. Pagina webhook-ului arată ultimele 20 de livrări și are butonul „Trimite un test”.
Adrese permise: doar https, pe portul 443, spre adrese publice (nu IP-uri private, locale sau de metadate cloud). Verificăm DNS-ul la salvare și la fiecare trimitere.
Mărime: cel mult 500 de firme pe cerere; mai multe firme noi pleacă în părți (parte / parti). Firmele din registrul de opoziție nu se trimit.
Limita de export: fiecare firmă trimisă se scade din limita lunară de export a planului, ca un rând exportat (în perioada de probă, din cele 100 de rânduri de probă). Când limita e atinsă, livrarea se suspendă: firmele rămân în coadă și pleacă automat luna următoare sau imediat după trecerea la un plan mai mare; proprietarul contului primește un e-mail (o dată pe lună). Testul nu consumă din limită.

POST /firmly HTTP/1.1
Content-Type: application/json
X-Firmly-Eveniment: lista.firme_noi
X-Firmly-Livrare: 9b2f6c1e-3d4a-4c1b-9a77-2f1e0c5d8a10
X-Firmly-Semnatura: sha256=5d41402abc4b2a76b9719d911017c592...

{"eveniment":"lista.firme_noi","livrare":"9b2f6c1e-3d4a-4c1b-9a77-2f1e0c5d8a10",
 "creat_la":"2026-10-09T06:30:14+03:00",
 "lista":{"id":12,"nume":"Construcții Bihor peste 1 mil.","link":"https://firmly.ro/liste/12"},
 "firme_noi_total":2,"parte":1,"parti":1,
 "firme":[{"cui":12345678,"denumire":"EXEMPLU CONSTRUCT SRL","judet":"BIHOR","localitate":"Oradea",
           "caen":"4120","ca":1850000,"link":"https://firmly.ro/firma/123"}, …]}

Câmpurile firmei: cui, denumire, judet, localitate, caen (codul principal), ca (cifra de afaceri din ultimul bilanț, în lei; null dacă nu există), link (fișa din Firmly). Datele din exemplu sunt inventate.

Verificarea semnăturii

// PHP
$body = file_get_contents('php://input');
$asteptat = 'sha256=' . hash_hmac('sha256', $body, getenv('FIRMLY_SECRET'));
if (! hash_equals($asteptat, $_SERVER['HTTP_X_FIRMLY_SEMNATURA'] ?? '')) {
    http_response_code(401); exit;
}
$date = json_decode($body, true);

// Node.js (Express, corpul brut)
const crypto = require('crypto');
app.post('/firmly', express.raw({ type: 'application/json' }), (req, res) => {
  const asteptat = 'sha256=' + crypto.createHmac('sha256', process.env.FIRMLY_SECRET)
    .update(req.body).digest('hex');
  const primit = req.get('X-Firmly-Semnatura') || '';
  if (primit.length !== asteptat.length ||
      !crypto.timingSafeEqual(Buffer.from(primit), Buffer.from(asteptat))) return res.sendStatus(401);
  res.sendStatus(204);
});

# Python (Flask)
import hmac, hashlib, os
body = request.get_data()
asteptat = 'sha256=' + hmac.new(os.environ['FIRMLY_SECRET'].encode(),
                                 body, hashlib.sha256).hexdigest()
if not hmac.compare_digest(asteptat, request.headers.get('X-Firmly-Semnatura', '')):
    abort(401)

Calculează semnătura pe corpul brut, înainte de orice decodare JSON (o reformatare schimbă semnătura). Câmpul creat_la e semnat și el: poți respinge livrările mai vechi de câteva ore.

Răspunsuri și erori

200 — datele cerute, în JSON (chei în română).
401 — token lipsă, invalid, expirat sau revocat.
403 — planul nu include API sau accesul contului a expirat.
404 — firma sau resursa nu există.
422 — parametri greșiți (mesajul spune ce lipsește).
429 — prea multe cereri pe minut sau cota lunară atinsă.

Date personale

Numele administratorilor și asociaților, telefoanele atribuite unei persoane și legăturile dintre firme prin persoane apar doar dacă accesul la persoane e activat pentru contul tău (la cerere, cu un scop legitim). Datele de naștere nu se trimit prin API-ul clienților. Firmele și contactele din registrul de opoziție sunt excluse din liste.

Politica de confidențialitate →

Pentru asistentul intern

Integrare internă, folosită doar de asistentul Firmly (chat și WhatsApp). Accesul se face cu un token de serviciu separat, setat pe server; tokenurile API ale clienților nu au acces la aceste rute. Fiecare răspuns are câmpul rezumat (1–4 propoziții în română, gata de citit), cifrele ca numere în lei, procentele ca numere (12.5 = 12,5%) și link spre pagina din Firmly.

GET/api/v1/asistent/cauta?q=

Firme (aceeași relevanță ca pagina Firme, cel mult 10) și persoane (cel mult 8), după CUI, denumire, nume, telefon, e-mail sau domeniu.

Exemplu de răspuns (JSON)

Cerere: GET /api/v1/asistent/cauta?q=exemplu

{
    "rezumat": "Pentru „exemplu” am găsit 2 firme. Prima firmă: EXEMPLU SRL (CUI 99999801, Bihor), activă, CA 1,3 mil. lei în 2025.",
    "firme": [
        {
            "cui": 99999801,
            "denumire": "EXEMPLU SRL",
            "judet": "BIHOR",
            "localitate": "Oradea",
            "stare": "activă",
            "activa": true,
            "caen": "6201",
            "ca": 1250000,
            "profit": 180000,
            "angajati": 12,
            "an": 2025,
            "link": "https://firmly.ro/firma/528533"
        },
        {
            "cui": 99999802,
            "denumire": "ALT EXEMPLU SRL",
            "judet": "BIHOR",
            "localitate": "Oradea",
            "stare": "activă",
            "activa": true,
            "caen": "6201",
            "ca": 640000,
            "profit": 52000,
            "angajati": 6,
            "an": 2025,
            "link": "https://firmly.ro/firma/528534"
        }
    ],
    "persoane": [],
    "link": "https://firmly.ro/firme?q=exemplu&stare=toate"
}

GET/api/v1/asistent/firma?cui= sau ?q=<denumire>

Fișa compactă: identitate, bilanțurile pe ultimii 6 ani, creștere, scorurile de dinamică și risc, poziția față de piață, oameni, contacte, semnale, SEAP, instanțe și ce s-a schimbat în 90 de zile.

Exemplu de răspuns (JSON)

Cerere: GET /api/v1/asistent/firma?cui=99999801

{
    "rezumat": "EXEMPLU SRL (CUI 99999801, Oradea) e activă, înființată în 2015, CAEN 6201. În 2025: cifră de afaceri 1,3 mil. lei (+14% față de 2024), profit net 180.000 lei, 12 angajați.",
    "identitate": {
        "id": 528533,
        "cui": 99999801,
        "nr_registru": "J05/1234/2015",
        "denumire": "EXEMPLU SRL",
        "forma": "SRL",
        "stare": "activă",
        "activa": true,
        "infiintata": "2015-03-02",
        "caen": "6201",
        "caen_nume": null,
        "judet": "BIHOR",
        "localitate": "Oradea",
        "adresa": "Str. Exemplului 1",
        "tva": true,
        "efactura": null
    },
    "financiare": [
        {
            "an": 2025,
            "ca": 1250000,
            "profit": 180000,
            "angajati": 12,
            "active": null,
            "datorii": null,
            "capitaluri": null,
            "marja": 14.4
        },
        {
            "an": 2024,
            "ca": 1100000,
            "profit": 150000,
            "angajati": 11,
            "active": null,
            "datorii": null,
            "capitaluri": null,
            "marja": 13.6
        }
    ],
    "crestere": {
        "ca_pct": 13.6,
        "angajati_pct": 9.1,
        "an": 2025
    },
    "scoruri": null,
    "limita_credit": {
        "limita_lei": null,
        "nivel": null,
        "nivel_eticheta": null,
        "motive": [
            "Limita nu e calculată încă pentru această firmă: se calculează în fiecare dimineață, după scorurile de risc."
        ],
        "baza_lei": null,
        "calculat_la": null,
        "nota": "Estimare automată din date publice (bilanțul MF, ANAF, ONRC, instanțe), recalculată zilnic — nu e o garanție de plată și nu înlocuiește verificarea ta (contract, garanții, istoricul plăților cu tine)."
    },
    "bilant_lipsa_motiv": null,
    "fata_de_piata": null,
    "oameni": [
        {
            "id": 71073,
            "nume": "EXEMPLU ION",
            "calitate": "administrator",
            "activ": true,
            "nascut": "1980-01-01",
            "persoana_juridica": false,
            "link": "https://firmly.ro/persoana/71073"
        }
    ],
    "contacte": {
        "telefon": "0259000000",
        "email": "office@exemplu.ro",
        "site_uri": [
            "exemplu.ro"
        ],
        "alte_telefoane": []
    },
    "social": {
        "profiluri": [],
        "reclame_meta": {
            "active_acum": 0,
            "minim": null,
            "de_la": null,
            "platforme": [],
            "verificat_la": null,
            "ultimele": []
        },
        "sursa": "linkurile de pe site-ul firmei și din hărți (Overture, OSM); metricele paginilor doar din API-uri oficiale; reclamele din biblioteca publică Meta"
    },
    "semnale": [],
    "seap": {
        "contracte_12_luni": 0,
        "valoare_12_luni": 0,
        "total": {
            "contracte": 0,
            "valoare": null,
            "ultimul": null
        }
    },
    "instante": {
        "dosare": 0,
        "ca_parat": 0,
        "insolventa": false,
        "ultimul_dosar": null,
        "verificat_la": null
    },
    "ce_s_a_schimbat": [],
    "link": "https://firmly.ro/firma/528533"
}

GET/api/v1/asistent/persoana?q=<nume> sau ?id=

Persoanele cu acel nume (omonimele separat) și firmele lor, cu cifra de afaceri, profitul și riscul fiecăreia.

Exemplu de răspuns (JSON)

Cerere: GET /api/v1/asistent/persoana?q=exemplu ion

{
    "rezumat": "EXEMPLU ION (n. 01.01.1980) apare la 2 firme, toate active. Principalele: EXEMPLU SRL — administrator, CA 1,3 mil. lei (2025); ALT EXEMPLU SRL — asociat, CA 640.000 lei (2025).",
    "total": 1,
    "persoane": [
        {
            "id": 71073,
            "nume": "EXEMPLU ION",
            "nascut": "1980-01-01",
            "localitate_nastere": null,
            "nr_firme": 2,
            "nr_firme_active": 2,
            "firme": [
                {
                    "cui": 99999801,
                    "denumire": "EXEMPLU SRL",
                    "calitate": "administrator",
                    "mandat_in_vigoare": true,
                    "activa": true,
                    "stare": "activă",
                    "ca": 1250000,
                    "profit": 180000,
                    "angajati": 12,
                    "an": 2025,
                    "risc": null,
                    "risc_nivel": null,
                    "link": "https://firmly.ro/firma/528533"
                },
                {
                    "cui": 99999802,
                    "denumire": "ALT EXEMPLU SRL",
                    "calitate": "asociat",
                    "mandat_in_vigoare": true,
                    "activa": true,
                    "stare": "activă",
                    "ca": 640000,
                    "profit": 52000,
                    "angajati": 6,
                    "an": 2025,
                    "risc": null,
                    "risc_nivel": null,
                    "link": "https://firmly.ro/firma/528534"
                }
            ],
            "link": "https://firmly.ro/persoana/71073"
        }
    ],
    "link": "https://firmly.ro/firme?q=exemplu%20ion&stare=toate"
}

GET/api/v1/asistent/piata?caen=&judet=&nisa=

O piață: firme active, înființări și radieri în 12 luni, cifra de afaceri, mediana, creșterea, marja, firmele pe pierdere, cele mai mari firme. Toți parametrii sunt opționali.

Exemplu de răspuns (JSON)

Cerere: GET /api/v1/asistent/piata?caen=6201&judet=bihor

{
    "rezumat": "Pentru activitatea (CAEN 6201) în județul Bihor: 2 firme active. Cele mai mari: EXEMPLU SRL (1,3 mil. lei), ALT EXEMPLU SRL (640.000 lei). Cifrele financiare ale acestei nișe nu sunt încă precalculate; le calculez acum în fundal — întreabă din nou peste 1–2 minute pentru cifra de afaceri, creștere și marjă.",
    "ce": "activitatea (CAEN 6201) în județul Bihor",
    "firme_active": 2,
    "noi_12_luni": null,
    "radiate_12_luni": null,
    "noi_delta_pct": null,
    "ca_total": null,
    "ca_mediana": null,
    "crestere_ca_pct": null,
    "marja_pct": null,
    "angajati": null,
    "firme_pe_pierdere_pct": null,
    "firme_cu_bilant": null,
    "insolvente_12_luni": null,
    "top": [
        {
            "cui": 99999801,
            "denumire": "EXEMPLU SRL",
            "judet": "BIHOR",
            "ca": 1250000,
            "crestere": 13.6,
            "an": 2025,
            "link": "https://firmly.ro/firma/528533"
        },
        {
            "cui": 99999802,
            "denumire": "ALT EXEMPLU SRL",
            "judet": "BIHOR",
            "ca": 640000,
            "crestere": null,
            "an": 2025,
            "link": "https://firmly.ro/firma/528534"
        }
    ],
    "puls": null,
    "an": 2025,
    "perioada_12_luni": "noiembrie 2025 – octombrie 2026",
    "note": [
        "Cifrele financiare ale acestei nișe nu sunt încă precalculate; le calculez acum în fundal — întreabă din nou peste 1–2 minute pentru cifra de afaceri, creștere și marjă."
    ],
    "link": "https://firmly.ro/piata/nisa?caen=6201&judet=bihor",
    "caen": [
        "6201"
    ]
}

GET/api/v1/asistent/compara?cui=&cui2=

Două firme alăturat, cu diferențele în procente; fără cui2, firma față de piața ei (percentile și mediane).

Exemplu de răspuns (JSON)

Cerere: GET /api/v1/asistent/compara?cui=99999801&cui2=99999802

{
    "rezumat": "În 2025, EXEMPLU SRL a avut cifra de afaceri 1,3 mil. lei, cu 95% mai mare decât ALT EXEMPLU SRL (640.000 lei). Profit net 180.000 lei față de 52.000 lei; 12 angajați față de 6; marjă netă 14% față de 8,1%.",
    "tip": "firma_vs_firma",
    "an": 2025,
    "firma": {
        "cui": 99999801,
        "denumire": "EXEMPLU SRL",
        "judet": "BIHOR",
        "localitate": "Oradea",
        "stare": "activă",
        "activa": true,
        "caen": "6201",
        "ca": 1250000,
        "profit": 180000,
        "angajati": 12,
        "an": 2025,
        "link": "https://firmly.ro/firma/528533",
        "an_comparat": 2025,
        "marja_pct": 14.4,
        "crestere_ca_pct": 13.6,
        "ca_pe_angajat": 104167,
        "profit_pe_angajat": 15000,
        "datorii": null,
        "capitaluri": null,
        "risc": null,
        "risc_nivel": null,
        "dinamica": null
    },
    "firma2": {
        "cui": 99999802,
        "denumire": "ALT EXEMPLU SRL",
        "judet": "BIHOR",
        "localitate": "Oradea",
        "stare": "activă",
        "activa": true,
        "caen": "6201",
        "ca": 640000,
        "profit": 52000,
        "angajati": 6,
        "an": 2025,
        "link": "https://firmly.ro/firma/528534",
        "an_comparat": 2025,
        "marja_pct": 8.1,
        "crestere_ca_pct": null,
        "ca_pe_angajat": 106667,
        "profit_pe_angajat": 8667,
        "datorii": null,
        "capitaluri": null,
        "risc": null,
        "risc_nivel": null,
        "dinamica": null
    },
    "diferente": {
        "ca_pct": 95.3,
        "profit_pct": 246.2,
        "angajati_pct": 100,
        "ca_pe_angajat_pct": -2.3,
        "profit_pe_angajat_pct": 73.1,
        "datorii_pct": null,
        "capitaluri_pct": null,
        "marja_puncte": 6.3,
        "crestere_ca_puncte": null,
        "risc_puncte": null,
        "dinamica_puncte": null
    },
    "explicatie_diferente": "Procentele „_pct” arată cu cât e firma (cui) mai mare (+) sau mai mică (−) decât firma2; „_puncte” e diferența în puncte.",
    "link": "https://firmly.ro/firma/528533"
}

POST/api/v1/asistent/intreaba

Motorul „Întreabă Firmly” din aplicație. Corp JSON: {"intrebare": "..."}.

Exemplu de răspuns (JSON)

Cerere: POST /api/v1/asistent/intreaba {"intrebare":"Câte firme de IT sunt în Bihor?"}

{
    "rezumat": "Am găsit 2 firme active din județul Bihor · Programare și consultanță IT. Primele: EXEMPLU SRL (1,3 mil. lei), ALT EXEMPLU SRL (640.000 lei).",
    "tip": "lista",
    "am_inteles": [
        "Programare și consultanță IT",
        "județul Bihor"
    ],
    "titlu": "Am găsit 2 firme active din județul Bihor · Programare și consultanță IT.",
    "text": [],
    "cifre": [],
    "total": 2,
    "tabel": {
        "cap": [
            "Firmă",
            "Județ"
        ],
        "randuri": [
            [
                "EXEMPLU SRL",
                "BIHOR"
            ],
            [
                "ALT EXEMPLU SRL",
                "BIHOR"
            ]
        ],
        "linkuri_randuri": [
            "https://firmly.ro/firma/528533",
            "https://firmly.ro/firma/528534"
        ],
        "randuri_total": 2
    },
    "linkuri": [
        {
            "eticheta": "Deschide lista completă în Firme",
            "url": "https://firmly.ro/firme?stare=activa&judet=bihor&caen=6201%2C6202%2C6209%2C6210%2C6220%2C6290"
        }
    ],
    "link": "https://firmly.ro/intreaba?q=C%C3%A2te%20firme%20de%20IT%20sunt%20%C3%AEn%20Bihor%3F"
}

GET/api/v1/asistent/analize/{cheie}?firma=

Aceleași analize ca /api/v1/analize/{cheie} (contracte publice, dosare, legături, risc, indicatori), pentru organizația Firmly, cu acces la persoane.

POST/api/v1/asistent/lot

Până la 300 de CUI-uri deodată (de exemplu toți clienții din facturi): stare, cifre, risc, insolvență. Corp JSON: {"cui": [..]}.

Exemplu de răspuns (JSON)

Cerere: POST /api/v1/asistent/lot {"cui":[99999801,99999802]}

{
    "rezumat": "Din 2 CUI-uri am găsit 2. Niciuna nu e inactivă, în insolvență sau cu risc ridicat. Cifra de afaceri adunată (ultimul bilanț al fiecăreia): 1,9 mil. lei.",
    "total": 2,
    "gasite": 2,
    "firme": [
        {
            "cui": 99999801,
            "gasita": true,
            "denumire": "EXEMPLU SRL",
            "judet": "BIHOR",
            "stare": "activă",
            "activa": true,
            "ca": 1250000,
            "profit": 180000,
            "angajati": 12,
            "an": 2025,
            "risc": null,
            "risc_nivel": null,
            "dinamica": null,
            "insolventa": false,
            "ultim_bilant": 2025,
            "limita_credit": null,
            "link": "https://firmly.ro/firma/528533"
        },
        {
            "cui": 99999802,
            "gasita": true,
            "denumire": "ALT EXEMPLU SRL",
            "judet": "BIHOR",
            "stare": "activă",
            "activa": true,
            "ca": 640000,
            "profit": 52000,
            "angajati": 6,
            "an": 2025,
            "risc": null,
            "risc_nivel": null,
            "dinamica": null,
            "insolventa": false,
            "ultim_bilant": 2025,
            "limita_credit": null,
            "link": "https://firmly.ro/firma/528534"
        }
    ]
}

GET/api/v1/asistent/cautari

Listele salvate ale echipei: filtre, câte firme au, câte au apărut la ultima rulare.

Exemplu de răspuns (JSON)

Cerere: GET /api/v1/asistent/cautari

{
    "rezumat": "Liste salvate: 1; cu firme noi la ultima rulare: 1.",
    "cautari": [
        {
            "id": 6677,
            "nume": "Exemplu: IT în Bihor",
            "tip": "filtre",
            "firme": 2,
            "firme_noi_ultima_rulare": 2,
            "recalculata": "2026-11-05 14:44:11+02",
            "alerta": true,
            "oprita": false,
            "autor": "Administrator Firmly",
            "link": "https://firmly.ro/liste/6677"
        }
    ],
    "link": "https://firmly.ro/liste"
}

GET/api/v1/asistent/cautari/{id}?toate=&limita=&nume=

Firmele noi apărute la ultima rulare a listei (cel mult 50), fiecare cu motivele potrivirii, observațiile și mesajul de deschidere (fără ciorne pentru firmele cu opoziție).

Exemplu de răspuns (JSON)

Cerere: GET /api/v1/asistent/cautari/6677?toate=1&limita=1

{
    "rezumat": "Lista „Exemplu: IT în Bihor”: 1 firme (cele mai recente din listă), recalculată pe 2026-11-05.",
    "cautare": {
        "id": 6677,
        "nume": "Exemplu: IT în Bihor",
        "tip": "filtre",
        "firme": 2,
        "firme_noi_ultima_rulare": 2,
        "recalculata": "2026-11-05 14:44:11+02",
        "alerta": true,
        "oprita": false,
        "autor": "Administrator Firmly",
        "link": "https://firmly.ro/liste/6677"
    },
    "filtre": [
        "CAEN: 6201",
        "Județ: Bihor"
    ],
    "produs": null,
    "firme": [
        {
            "cui": 99999802,
            "denumire": "ALT EXEMPLU SRL",
            "judet": "BIHOR",
            "localitate": "Oradea",
            "caen": "6201",
            "infiintata": "2018-06-11",
            "ca": 640000,
            "angajati": 6,
            "an_bilant": 2025,
            "administrator": null,
            "site_uri": [],
            "opozitie": false,
            "contacte_ascunse": null,
            "motive": [
                "CAEN: 6201",
                "Județ: Bihor"
            ],
            "observatii": [
                "Nu i-am găsit niciun site.",
                "CA 640.000 lei (2025), 6 angajați, plătitoare de TVA."
            ],
            "mesaj_deschidere": "Bună ziua! M-am uitat la ALT EXEMPLU: nu i-am găsit niciun site. Aveți 15 minute săptămâna asta să vă arăt ce am observat?",
            "script_apel": "Bună ziua, sunt echipa ArhAI. Vă sun pentru că m-am uitat la ALT EXEMPLU: nu i-am găsit niciun site.\n\nCum vă aduceți acum clienții noi?\n\n(Dacă e interesat: propun 15 minute în care îi arăt concret pe datele lui. Dacă nu acum: întreb când e un moment mai bun și notez. Dacă nu: mulțumesc și notez opoziția.)",
            "email_dupa_apel": "Bună ziua,\n\nMulțumesc pentru discuția de azi. Cum v-am spus, m-am uitat la ALT EXEMPLU: nu i-am găsit niciun site.\n\nVă propun 15 minute în care vă arăt concret ce se poate face, pe datele dvs. Vă convine joi sau vineri?\n\nO zi bună,\nechipa ArhAI",
            "link": "https://firmly.ro/firma/528534"
        }
    ],
    "link": "https://firmly.ro/liste/6677"
}

GET/api/v1/asistent/alerte?zile=

Alertele echipei din ultimele N zile (implicit 14): liste cu firme noi, firme și nișe urmărite.

Exemplu de răspuns (JSON)

Cerere: GET /api/v1/asistent/alerte?zile=14

{
    "rezumat": "1 alerte în ultimele 14 zile.",
    "alerte": [
        {
            "id": 4890,
            "tip": "eveniment",
            "titlu": "EXEMPLU SRL: bilanț nou depus (2025)",
            "cand": "2026-11-05 14:44:11+02",
            "pentru": "Administrator Firmly",
            "lista_id": null,
            "detalii": {
                "an": 2025,
                "tip": "bilant_nou"
            },
            "link": "https://firmly.ro/firma/528533"
        }
    ],
    "link": "https://firmly.ro/alerte"
}

Limită: 120 de cereri pe minut. Erorile au forma {"eroare": "…"}, cu codurile 400 (parametri greșiți), 401 (token lipsă sau greșit), 404 (negăsit), 429 (prea multe cereri) și 503 (calcul prea lung, reîncearcă). Fiecare cerere intră în jurnalul de audit, doar cu calea și parametrii.