Identificatori v1 / Identificatori

Validează un identificator

O singură validare, direct în cale: tipul şi valoarea. Întoarce dacă e valid, forma normalizată şi ce s-a putut citi din cod.

GET

https://oneapi.ro/api/identificatori/v1/{tip}/{valoare}

Parametri de cale

NumeTipDescriereExemplu

tipobligatoriu string Tipul identificatorului (cnp, cui, iban, bic, lei, eori, vat…). Lista completă e la /identificatori/v1/tipuri.

valoareobligatoriu string Valoarea de validat, aşa cum apare pe document. Spaţiile şi cratimele se ignoră.

Parametri de interogare

Ruta nu acceptă parametri de interogare.

Cum se comportă

O singură rută pentru toate tipurile, cu tipul ca segment de cale. Zece rute aproape identice ar fi zece locuri de întreținut pentru același comportament, iar catalogul de la /tipuri le descrie oricum pe toate.
CNP-ul NU se poate cere aici. Ruta răspunde 405 și trimite la POST /identificatori/v1/cnp: într-un URL, codul ar ajunge în logurile de acces ale serverului, în istoricul browserului și în antetul Referer al paginii următoare.
Răspunsul are aceeași formă pentru toate tipurile: valid, motive (propoziții, nu coduri de eroare) și componente (ce s-a putut decoda). Cine validează azi un IBAN și mâine un ISIN nu trebuie să învețe două forme.
Ce NU verificăm, pe tipuri: la IBAN, lungimea așteptată pentru țările din afara României — tabelul e registrul SWIFT, iar toate bibliotecile care îl poartă sunt LGPL; cifra de control mod-97 e însă completă. La BIC, existența instituției — registrul e produs comercial SWIFT. La VIN, marca și modelul — lista codurilor de producător e ținută de SAE. Fiecare răspuns spune asta în observatie, nu doar documentația.

La ce folosește

Respingi un IBAN greșit tastat într-un formular, înainte de a iniția o plată.
Verifici un cod EAN scanat, ca să prinzi o citire proastă a codului de bare.
Decodezi un VIN ca să afli anul-model și regiunea de fabricație.
Confirmi cifra de control a unui CUI înainte de a face o căutare care oricum n-ar găsi nimic.

Structura răspunsului

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

CâmpTipDescriere

tip string Tipul folosit la validare.

valoare string Valoarea primită, așa cum a fost trimisă.

valid boolean Dacă identificatorul e bine format după standardul lui.

normalizat string Forma canonică (fără separatori, cu majuscule), doar când e valid.

componente object Ce s-a putut decoda — diferă de la tip la tip.

componente.tara string Ţara la care se referă valoarea.

componente.tara_nume string

componente.cifre_control string

componente.lungime integer

componente.lungime_verificata boolean

componente.format_afisare string

componente.cod_banca string

componente.cont string

motive Ce anume nu e în regulă, în cuvinte. Lipsește când e valid.

observatie string Limita concretă a verificării pentru tipul respectiv.

Exemple de răspuns

GEThttps://oneapi.ro/api/identificatori/v1/iban/RO49AAAA1B31007593840000

{
    "data": {
        "tip": "iban",
        "valoare": "RO49AAAA1B31007593840000",
        "valid": true,
        "normalizat": "RO49AAAA1B31007593840000",
        "componente": {
            "tara": "RO",
            "tara_nume": "România",
            "cifre_control": "49",
            "lungime": 24,
            "lungime_verificata": true,
            "format_afisare": "RO49 AAAA 1B31 0075 9384 0000",
            "cod_banca": "AAAA",
            "cont": "1B31007593840000"
        }
    }
}

GEThttps://oneapi.ro/api/identificatori/v1/bic/BTRLRO22

{
    "data": {
        "tip": "bic",
        "valoare": "BTRLRO22",
        "valid": true,
        "normalizat": "BTRLRO22",
        "componente": {
            "institutie": "BTRL",
            "tara": "RO",
            "tara_nume": "România",
            "locatie": "22",
            "cod_de_test": false,
            "sediu_central": true
        },
        "observatie": "Verificare de FORMĂ. Registrul BIC e produs comercial SWIFT, deci nu putem confirma că instituția există sau cine e — doar că șirul respectă ISO 9362."
    }
}

GEThttps://oneapi.ro/api/identificatori/v1/vin/WVWZZZ1JZXW000010

{
    "data": {
        "tip": "vin",
        "valoare": "WVWZZZ1JZXW000010",
        "valid": true,
        "normalizat": "WVWZZZ1JZXW000010",
        "componente": {
            "wmi": "WVW",
            "regiune_fabricatie": "Europa",
            "vds": "ZZZ1JZ",
            "cifra_control": "Z",
            "cifra_control_asteptata": "1",
            "cifra_control_corecta": false,
            "cifra_control_obligatorie": false,
            "cod_an_model": "X",
            "ani_model_posibili": [
                1999
            ],
            "serie": "000010"
        },
        "observatie": "Decodare PARȚIALĂ: structură, cifră de control, an-model și regiune. NU dăm marca sau modelul — lista completă a codurilor de producător (WMI) e ținută de SAE ca produs comercial, iar un decodor care ghicește dintr-o listă neîntreținută e mai rău decât unul care spune ce știe."
    }
}

GEThttps://oneapi.ro/api/identificatori/v1/cui/14399840

{
    "data": {
        "tip": "cui",
        "valoare": "14399840",
        "valid": true,
        "normalizat": "14399840",
        "componente": {
            "cui": 14399840,
            "prefix_tva_scris": false,
            "cod_tva": "RO14399840"
        },
        "observatie": "Doar cifra de control — nu confirmă că firma există. Pentru asta, /business/v1/firme/{cui}; pentru starea de plătitor de TVA, registrul fiscal din același modul."
    }
}

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	Tipul cerut nu există. Lista e la `/identificatori/v1/tipuri`.
405	eroare	S-a cerut tipul `cnp`, care se acceptă doar prin POST.
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": "negasit",
        "mesaj": "Tipul cerut nu există. Lista e la /identificatori/v1/tipuri."
    }
}