Business v1 / Firme

Statut TVA

Statutul de TVA al firmei, cu cele trei lucruri care se confundă: plătitor de TVA, TVA la încasare şi inactivitate fiscală. Fiecare cu data de la care se aplică.

GET

https://oneapi.ro/api/business/v1/firme/{cui}/tva

Parametri de cale

NumeTipDescriereExemplu

cuiobligatoriu string Codul de identificare fiscală al firmei, fără prefixul RO (ex. 6719278).

Parametri de interogare

Ruta nu acceptă parametri de interogare.

Cum se comportă

„Nu are” e un răspuns, nu o eroare. Când firma există, dar n-are ce cere ruta, răspunsul e 200 cu data: null şi motivul în meta.fara_date. 404 înseamnă doar că firma (CUI-ul) nu există — aşa poţi deosebi cele două cazuri şi poţi păstra în cache răspunsul negativ.
Felia strict de TVA: dacă firma e plătitoare, de la ce dată, dacă e la încasare, dacă e în split sau inactivă. Convenabil când te interesează doar TVA-ul, fără restul stării fiscale.

La ce folosește

Un apel scurt în fluxul de facturare, când te interesează strict TVA-ul.
Validarea rapidă a unui cod de TVA la casă sau în checkout.
Marcarea în CRM a clienţilor la TVA la încasare, care au termene de plată diferite.

Structura răspunsului

CâmpTipDescriere

data.cui integer Codul fiscal.

data.platitor boolean Plătitoare de TVA.

data.de_la string De când e valabilă situaţia.

data.pana_la string | null Până când e valabilă situaţia.

data.la_incasare.activ boolean Este activ.

data.la_incasare.de_la string | null De când se aplică TVA la încasare.

data.la_incasare.pana_la string | null Până când s-a aplicat TVA la încasare.

data.split.activ boolean Este activ.

data.split.de_la string | null De când se aplică split TVA.

data.split.anulare string | null Data anulării split TVA.

meta.fara_date Doar când răspunsul e gol: de ce nu există date (de pildă „Firma nu are cod LEI înregistrat la GLEIF.”). Lipseşte când data e completat.

meta.fara_date_cod Cuvântul scurt şi STABIL al motivului, pentru clienţii care comută pe el în cod: fara_date e proză şi se poate reformula, ăsta nu.

Exemple de răspuns

GEThttps://oneapi.ro/api/business/v1/firme/6719278/tva

{
    "data": {
        "cui": 6719278,
        "platitor": true,
        "de_la": "1995-01-04",
        "pana_la": null,
        "la_incasare": {
            "activ": false,
            "de_la": null,
            "pana_la": null
        },
        "split": {
            "activ": false,
            "de_la": null,
            "anulare": null
        }
    }
}

GEThttps://oneapi.ro/api/business/v1/firme/14399840/tva

{
    "data": {
        "cui": 14399840,
        "platitor": true,
        "de_la": "2002-02-01",
        "pana_la": null,
        "la_incasare": {
            "activ": false,
            "de_la": null,
            "pana_la": null
        },
        "split": {
            "activ": false,
            "de_la": null,
            "anulare": null
        }
    }
}

GEThttps://oneapi.ro/api/business/v1/firme/2054341/tva

{
    "data": {
        "cui": 2054341,
        "platitor": true,
        "de_la": "1993-07-01",
        "pana_la": "2025-05-13",
        "la_incasare": {
            "activ": false,
            "de_la": null,
            "pana_la": null
        },
        "split": {
            "activ": false,
            "de_la": null,
            "anulare": null
        }
    }
}

GEThttps://oneapi.ro/api/business/v1/firme/24890577/tva

{
    "data": {
        "cui": 24890577,
        "platitor": true,
        "de_la": "2009-01-06",
        "pana_la": null,
        "la_incasare": {
            "activ": false,
            "de_la": null,
            "pana_la": null
        },
        "split": {
            "activ": false,
            "de_la": null,
            "anulare": 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.
404	negasit	Firma cu CUI [{cui}] nu a fost găsită.
422	validare	Ruta nu primeşte parametri, în afară de `lang`: orice alt parametru dă 422, nu e ignorat.
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": "Ruta nu primeşte parametri, în afară de lang: orice alt parametru dă 422, nu e ignorat.",
        "detalii": {
            "cui": [
                "Valoarea trimisă nu respectă regula parametrului."
            ]
        }
    }
}