oneapi
Autentificare
Financiar v1 / Validare

Validare IBAN

Verifică un IBAN după ISO 13616 (structură, lungime pe ţară, cifre de control mod-97) şi, pentru
IBAN-urile româneşti, identifică banca emitentă.

Un IBAN greşit NU e o eroare a cererii: răspunsul e 200 cu valid: false şi un cod în motiv
care spune ce e greşit — formă, lungime sau cifre de control.

POST
https://oneapi.ro/api/financiar/v1/validare/iban

Corpul cererii

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

NumeTipDescriereValori acceptate
ibanobligatoriu string Obligatoriu, în corpul cererii. Cu sau fără spaţii/cratime, majuscule sau minuscule. max 42 car.
IBAN românesc Corpul cererii 
{
    "iban": "RO49AAAA1B31007593840000"
}
IBAN german Corpul cererii 
{
    "iban": "DE89370400440532013000"
}
Scris cu spaţii şi litere mici Corpul cererii 
{
    "iban": "ro49 aaaa 1b31 0075 9384 0000"
}
Cifre de control greşite Corpul cererii 
{
    "iban": "RO49AAAA1B31007593840001"
}

Parametri de interogare

Ruta nu acceptă parametri de interogare.

Cum se comportă

  • Verifică un IBAN după ISO 13616: structura, lungimea pe ţară şi cifrele de control (mod-97). Pentru IBAN-urile româneşti identifică şi banca emitentă.
  • Se acceptă orice formatare uzuală: spaţii de grupare, cratime, minuscule. Răspunsul întoarce forma canonică în iban.
  • Un IBAN greşit nu e o eroare a cererii. Răspunsul e 200 cu valid: false şi un cod în motiv: forma_invalida, lungime_gresita (cu lungime_asteptata) sau control_invalid. „Invalid" fără explicaţie n-ajută pe cineva care a inversat două cifre.
  • Metoda e POST, nu GET, pentru că un IBAN identifică contul cuiva, iar un query-string ajunge în logurile de acces, în telemetrie şi în istoricul browserului.
  • Banca se declară numai când codul aparţine unei instituţii de credit confirmate. Registrul provine din GLEIF şi conţine toate deţinătoarele de BIC din România — inclusiv o fabrică de bere, Bursa de Valori şi case de brokeraj. Un IBAN construit pe codul unei astfel de entităţi nu poate exista, deci răspunsul e motiv_banca: "nu_e_institutie_de_credit", nu numele entităţii. Numele apare separat, în entitate_cu_acest_cod, ca informaţie de depanare.
  • Identificarea băncii merge doar pentru România: directoarele BIC/SWIFT complete sunt licenţiate şi nu le folosim. Pentru IBAN-uri străine, motiv_banca e doar_pentru_romania — o limitare declarată, nu un null fără explicaţie.
  • Acoperirea: 26 de instituţii de credit confirmate, inclusiv sucursalele băncilor străine (ING, Citibank, Revolut, BNP Paribas). Ele n-au LEI propriu, ci al societăţii-mamă, deci se confirmă prin potrivire pe denumire cu registrul BNR.

La ce folosește

  • Validarea unui IBAN într-un formular, înainte de a-l salva.
  • Identificarea băncii pentru afişare sau rutare de plăţi.
  • Depanarea unui IBAN transcris greşit.

Structura răspunsului

CâmpTipDescriere
data[] object[]
meta.temei string Temeiul legal al valorilor sau al modului de calcul.
meta.sursa_banci string
meta.nota string Precizare despre cum se citesc datele din răspuns — o capcană, o convenţie sau o limită a sursei.
data.iban string Forma canonică: majuscule, fără spaţii.
data.valid boolean Rezultatul verificării ISO 13616.
data.motiv null Codul defectului când valid e false; null altfel.
data.lungime_asteptata integer Lungimea oficială pentru ţara respectivă. null pentru ţările din afara tabelului, unde rămâne doar verificarea mod-97.
data.cod_banca string Cele 4 litere de după cifrele de control, la IBAN-urile româneşti.
data.banca null Instituţia de credit: denumirea din registrul BNR, BIC, CUI, LEI şi starea. null când nu se poate identifica.
data[].banca.tip institutie_credit sau trezoreria_statului — codul TREZ al conturilor de trezorerie, unde cui, lei şi stare sunt null.
data.motiv_banca string De ce lipseşte banca: doar_pentru_romania, cod_necunoscut, nu_e_institutie_de_credit.
data[].entitate_cu_acest_cod Apare doar la nu_e_institutie_de_credit: ce entitate deţine codul, ca ajutor de depanare.

Exemple de răspuns

body: {"iban": "RO49AAAA1B31007593840000"}

POSThttps://oneapi.ro/api/financiar/v1/validare/iban
{
    "data": {
        "iban": "RO49AAAA1B31007593840000",
        "valid": true,
        "tara": "RO",
        "lungime": 24,
        "lungime_asteptata": 24,
        "motiv": null,
        "cod_banca": "AAAA",
        "banca": null,
        "motiv_banca": "cod_necunoscut"
    },
    "meta": {
        "temei": "ISO 13616; control mod-97 calculat pe bucăţi.",
        "sursa_banci": "GLEIF (mapare BIC↔LEI, licenţă CC0) + registrul BNR al instituţiilor de credit; codul `TREZ` al Trezoreriei Statului e ţinut local.",
        "nota": "IBAN valid ca structură, dar codul de bancă nu apare în registru. Verifică transcrierea: cifrele de control nu prind o literă greşită în codul băncii dacă rezultatul rămâne divizibil."
    }
}

Coduri de eroare

CodSlugCând apare
401neautentificatToken lipsă, invalid, expirat sau revocat.
403feature_indisponibilPlanul curent nu include funcţia de care ţine ruta.
422validareLipseşte iban sau are o lungime imposibilă. Un IBAN prezent dar greşit întoarce 200 cu valid: false.
429cota_depasitaCota 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": "Lipseşte iban sau are o lungime imposibilă. Un IBAN prezent dar greşit întoarce 200 cu valid: false."
    }
}