Business v1 / Firme

Validare în masă

Validează o listă de CUI-uri. Body JSON: { "cui": [...] } (max 50); prefixul RO e acceptat.
UN RÂND PER INTRARE, în ordinea cerută: valoarea trimisă, forma canonică, dacă e CUI ca formă,
dacă trece cifra de control, dacă există în registru, denumire, stare, plătitor TVA, inactiv fiscal.
Util pt validarea listelor la facturare — nicio intrare nu se pierde pe drum.

POST

https://oneapi.ro/api/business/v1/firme/valideaza

Corpul cererii

Se trimite ca JSON, în corpul cererii (Content-Type: application/json) — nu în şirul de interogare.

NumeTipDescriereValori acceptate

cuiopțional array | null Listă de coduri fiscale (max. 50), în corpul cererii.

Două coduri valide Corpul cererii

Valid, necitibil şi inexistent Corpul cererii

{
    "cui": [
        "RO6719278",
        "abc",
        "11111111111"
    ]
}

Coduri inventate şi unul prea scurt Corpul cererii

{
    "cui": [
        "990000005",
        "990000072",
        "1"
    ]
}

Parametri de interogare

Ruta nu acceptă parametri de interogare.

Cum se comportă

Pentru o listă de coduri fiscale, întoarce per CUI: dacă există, starea, dacă e plătitor de TVA şi dacă e inactiv — gândit pentru validarea unei liste înainte de facturare.
Ca la batch, metoda e POST din motive de confidenţialitate a listei.

La ce folosește

Validarea unui fişier de clienţi înainte de a emite facturi în masă.
Curăţarea unei liste importate: care CUI-uri există şi care nu.
Verificarea periodică a statutului de TVA pe tot portofoliul, într-un singur apel.

Structura răspunsului

Toate câmpurile de mai jos sunt în data.

CâmpTipDescriere

rezultate[].cui integer CUI-ul verificat, în ordinea din cerere.

rezultate[].exista boolean CUI-ul există în registru.

rezultate[].denumire string | null Denumirea firmei; null dacă nu există.

rezultate[].stare string | null Starea firmei; null dacă nu există.

rezultate[].platitor_tva boolean | null Plătitoare de TVA; null dacă nu există.

rezultate[].inactiv_fiscal boolean | null Declarată inactivă fiscal; null dacă nu există.

Exemple de răspuns

body: {"cui": [6719278, 14399840]}

POSThttps://oneapi.ro/api/business/v1/firme/valideaza

{
    "data": {
        "rezultate": [
            {
                "valoare": "6719278",
                "cui": 6719278,
                "format_valid": true,
                "cifra_control_valida": true,
                "exista": true,
                "denumire": "MEGA IMAGE SRL",
                "stare": {
                    "cod": "1048",
                    "denumire": "funcțiune",
                    "categorie": "activa"
                },
                "platitor_tva": true,
                "inactiv_fiscal": false,
                "motiv": null
            }
        ]
    }
}

body: {"cui": ["RO6719278", "abc", "11111111111"]}

POSThttps://oneapi.ro/api/business/v1/firme/valideaza

{
    "data": {
        "rezultate": [
            {
                "valoare": "RO6719278",
                "cui": 6719278,
                "format_valid": true,
                "cifra_control_valida": true,
                "exista": true,
                "denumire": "MEGA IMAGE SRL",
                "stare": {
                    "cod": "1048",
                    "denumire": "funcțiune",
                    "categorie": "activa"
                },
                "platitor_tva": true,
                "inactiv_fiscal": false,
                "motiv": null
            }
        ]
    }
}

body: {"cui": ["990000005", "990000072", "1"]}

POSThttps://oneapi.ro/api/business/v1/firme/valideaza

{
    "data": {
        "rezultate": [
            {
                "valoare": "990000005",
                "cui": 990000005,
                "format_valid": true,
                "cifra_control_valida": true,
                "exista": false,
                "denumire": null,
                "stare": null,
                "platitor_tva": null,
                "inactiv_fiscal": null,
                "motiv": null
            }
        ]
    }
}

Coduri de eroare

Cod	Slug	Când apare
401	neautentificat	Token lipsă, invalid, expirat sau revocat.
403	feature_indisponibil	Planul curent nu include funcţia de care ţine ruta.
422	validare	Un parametru nedeclarat ori o valoare care nu trece validarea. Câmpul vinovat e în `detalii`.
422	cui_lipsa	Trimite un array `cui` cu cel puțin un CUI.
429	cota_depasita	Cota lunară a planului a fost depăşită (vezi `Retry-After`).

Toate erorile au aceeași formă. eroare.cod e stabil și e cel după care trebuie să ramifici în cod — nu după textul din mesaj, care se poate schimba.

{
    "eroare": {
        "cod": "validare",
        "mesaj": "Un parametru nedeclarat ori o valoare care nu trece validarea. Câmpul vinovat e în detalii."
    }
}