oneapi
Autentificare
Financiar v1 / Conversie

Conversie la cursul oficial BNR

Converteşte o sumă între leu şi o valută, în orice sens, la cursul de referinţă BNR al unei date
(implicit ziua curentă). Rezultatul vine rotunjit la 2 zecimale şi exact.

Pentru conversia între două valute străine, care trece prin leu şi nu e curs oficial, foloseşte
/conversie/incrucisata.

GET
https://oneapi.ro/api/financiar/v1/conversie

Parametri de interogare

NumeTipDescriereValori acceptate
sumaobligatoriu string Obligatoriu. Punct zecimal, cel mult 6 zecimale, fără separatori de mii şi fără notaţie ştiinţifică (1000, 1234.56). ex. 1000ex. 500
dinobligatoriu string Valuta de plecare: cod de 3 litere sau RON. max 3 car.
inobligatoriu string Valuta de destinaţie: cod de 3 litere sau RON. max 3 car.
dataopțional string | null Opţional, YYYY-MM-DD. Implicit ziua curentă. Dacă ziua nu are publicare, se foloseşte ultima cotaţie anterioară. ex. 2024-06-15ex. 2024-02-01

Cum se comportă

  • Converteşte o sumă la cursul BNR al unei date (implicit ziua curentă). Rezultatul vine în două forme: suma_convertita rotunjită la 2 zecimale şi suma_convertita_exacta nerotunjită.
  • Foloseşte forma exactă dacă rezultatul intră într-un alt calcul, şi rotunjeşte o singură dată, la final. Rotunjirea la fiecare pas al unui lanţ acumulează eroare proporţională cu mărimea sumelor.
  • curs.factor e numărul cu care s-a înmulţit suma, în orice direcţie: suma × factor = suma_convertita_exacta, cifră cu cifră. Aşa rezultatul e verificabil fără să reproduci logica, indiferent dacă e valută → leu, leu → valută sau valută → valută. Factorul are până la 12 zecimale, iar rezultatul exact decurge din el fără trunchiere.
  • Ruta acoperă DOAR conversiile în care apare leul, într-un sens sau altul. Pentru două valute străine, paritatea nu e publicată de BNR şi se calculează prin leu — alt algoritm şi alt statut juridic, deci altă rută: /conversie/incrucisata. O cerere cu două valute străine aici întoarce 422 şi trimite la ruta potrivită.
  • Ambele cotaţii trebuie să vină din aceeaşi zi. Dacă nu, cererea e respinsă cu 409 în loc să se producă un curs încrucişat între două zile de piaţă — un rezultat plauzibil şi greşit e mai rău decât o eroare.
  • Când din şi in sunt aceeaşi valută, suma trece neschimbată, cu factor: "1" şi fără dată: nu s-a folosit nicio cotaţie. Nu e eroare, ca un client care converteşte o listă să nu trateze cazul separat.
  • Sumele negative şi zero sunt permise — notele de credit sunt negative. Rotunjirea la jumătate merge în direcţia opusă lui zero: −0,005 → −0,01.
  • Tot calculul se face în aritmetică zecimală exactă, nu în virgulă mobilă, iar sumele circulă ca string-uri: un float în JSON înseamnă erori de rotunjire în banii cuiva.

La ce folosește

  • Conversia unei facturi în valută la cursul zilei facturii.
  • Afişarea unui preţ în altă monedă.

Structura răspunsului

CâmpTipDescriere
data.suma string Suma valorilor, în unitatea indicată alături.
data.din string
data.in string
data.suma_convertita string Rezultatul rotunjit la 2 zecimale, jumătate în sus. Forma de tipărit.
data.suma_convertita_exacta string Rezultatul nerotunjit. Forma de folosit în alte calcule.
data.curs.factor string Numărul cu care s-a înmulţit suma. suma × factor = suma_convertita_exacta.
data.curs.componente[] array Cotaţiile BNR folosite, cu valoarea publicată şi multiplicatorul. Gol când valutele sunt identice.
data.curs.componente[].valuta string Codul ISO 4217 al valutei.
data.curs.componente[].valoare string Valoarea publicată de sursă pentru combinaţia de mai sus.
data.curs.componente[].multiplicator integer Cu cât se înmulţeşte valoarea ca să ajungă în unitatea de bază.
data.curs.componente[].valoare_unitara string Valoarea raportată la o singură unitate.
data.curs.data string Ziua din care provine cotaţia. null când valutele sunt identice.
data.curs.data_ceruta string Data cerută de client, înainte de alinierea la o zi cu date.
data.curs.exact boolean true dacă cotaţia e din ziua cerută.
data.curs.zile_inapoi integer
meta.sursa string Sursa oficială din care vin datele, cu licenţa ei acolo unde e cerută.
meta.curs string
meta.rotunjire string
meta.nota string Precizare despre cum se citesc datele din răspuns — o capcană, o convenţie sau o limită a sursei.
meta.fara_date string data e null, iar aici stă motivul. Data cerută e anterioară lui 2005-01-03.
meta.fara_date_cod string 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/financiar/v1/conversie?suma=1000&din=EUR&in=RON&data=2024-06-15
{
    "data": {
        "suma": "1000",
        "din": "EUR",
        "in": "RON",
        "suma_convertita": "4977.10",
        "suma_convertita_exacta": "4977.1",
        "curs": {
            "factor": "4.9771",
            "componente": [
                {
                    "valuta": "EUR",
                    "valoare": "4.9771",
                    "multiplicator": 1,
                    "valoare_unitara": "4.9771"
                }
            ],
            "data": "2024-06-14",
            "data_ceruta": "2024-06-15",
            "exact": false,
            "zile_inapoi": 1
        }
    },
    "meta": {
        "sursa": "Banca Naţională a României",
        "curs": "oficial",
        "rotunjire": "2 zecimale, jumătate în sus. `suma_convertita_exacta` e nerotunjită — foloseşte-o dacă rezultatul intră într-un alt calcul.",
        "nota": "Ziua cerută nu are publicare; s-a folosit ultima cotaţie anterioară."
    }
}

Coduri de eroare

CodSlugCând apare
401neautentificatToken lipsă, invalid, expirat sau revocat.
403feature_indisponibilPlanul curent nu include funcţia de care ţine ruta.
404negasitnegasit = valută necunoscută; delistata = valuta nu mai e cotată.
422validarenu_e_curs_oficial = ambele valute sunt străine, foloseşte /conversie/incrucisata. Sau: sumă malformată, cod de valută invalid, dată viitoare.
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": "nu_e_curs_oficial = ambele valute sunt străine, foloseşte /conversie/incrucisata. Sau: sumă malformată, cod de valută invalid, dată viitoare.",
        "detalii": {
            "suma": [
                "Valoarea trimisă nu respectă regula parametrului."
            ]
        }
    }
}