oneapi
Autentificare
Financiar v1 / Curs

Curs de referinţă BNR

Cotaţiile zilei cerute — ?data= e OBLIGATORIE — pentru toate valutele sau doar cele din
?valuta=. Răspunsul are aceeaşi formă ca pe curs/{valuta}: data, valoare (completată
numai dacă avem exact ziua cerută) şi ultima (ultima zi publicată la sau înainte de ea).

BNR publică doar în zilele bancare, în general după ora 13:00, iar importul nostru poate fi în
urmă — ambele cazuri ies la fel, prin ultima, şi se deosebesc din ultima.data.

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

Parametri de interogare

NumeTipDescriereValori acceptate
dataobligatoriu string Obligatoriu: ziua, AAAA-LL-ZZ. Nu poate fi în viitor. ex. 2024-06-14ex. 2024-06-15
valutalistăopțional text Filtru opţional: ?valuta=EUR,USD sau ?valuta[]=EUR&valuta[]=USD. Fără el se întorc toate valutele cotate în ziua respectivă. ex. EUR

Cum se comportă

  • ?data= e obligatorie, iar răspunsul are mereu aceeaşi formă: data (ziua cerută), valoare (completată numai dacă avem exact ziua aia) şi ultima (ultima zi publicată la sau înainte de ea, cu valoarea ei). valoare rămâne gol DELIBERAT când ziua cerută n-are publicare — cifra de altă zi stă separat, sub ultima, ca să nu poată fi folosită din greşeală într-un calcul. Lipsa datelor nu mai e o eroare: răspunsul e 200, iar comparaţia data vs ultima.data spune tot.
  • Cotaţiile celei mai recente zile publicate de BNR. Cursul e RON per multiplicator unităţi de valută (moneda_baza: "RON") — invers faţă de BCE, care cotează valuta per 1 EUR.
  • BNR publică numai în zilele bancare, în general după ora 13:00. Nu există curs pentru weekend, sărbători legale sau pentru dimineaţa unei zile bancare. Ruta întoarce ultima zi publicată şi o declară în data; nu inventează niciodată o cotaţie pentru o zi fără publicare.
  • Cinci valute se publică la 100 de unităţi (HUF, JPY, KRW, IDR, ISK). Foloseşte valoare_unitara dacă înmulţeşti direct, sau valoare + multiplicator dacă trebuie să citezi cifra oficială.
  • Sumele sunt string-uri zecimale, nu numere JSON, ca să nu apară erori de rotunjire în float.

La ce folosește

  • Afişarea cursului zilei.
  • Conversia unei facturi în valută la cursul oficial.

Structura răspunsului

CâmpTipDescriere
data.data string Ziua cerută, exact cum ai trimis-o.
data.valoare.moneda_baza string Moneda în care e exprimată cotaţia. Mereu RON pe această rută.
data.valoare.cotatii[].valuta string Codul ISO 4217 al valutei.
data.valoare.cotatii[].valoare string Cifra publicată de BNR, pentru multiplicator unităţi de valută.
data.valoare.cotatii[].multiplicator integer Câte unităţi de valută acoperă valoare (1 sau 100).
data.valoare.cotatii[].valoare_unitara string RON pentru O unitate de valută, deja împărţit la multiplicator.
data.ultima object Ultima zi publicată la sau înainte de data, cu cotaţiile ei: {data, valoare}. null doar dacă nu există nimic înaintea zilei cerute.
data.ultima.data string
data.ultima.valoare.moneda_baza string
data.ultima.valoare.cotatii[].valuta string Codul ISO 4217 al valutei.
data.ultima.valoare.cotatii[].valoare string Cotaţiile zilei cerute: {moneda_baza, cotatii[]}. null dacă ziua aia n-are publicare.
data.ultima.valoare.cotatii[].multiplicator integer Cu cât se înmulţeşte valoarea ca să ajungă în unitatea de bază.
data.ultima.valoare.cotatii[].valoare_unitara string Valoarea raportată la o singură unitate.
meta.sursa string Sursa oficială din care vin datele, cu licenţa ei acolo unde e cerută.
meta.cotatii integer Câte cotaţii intră în răspuns.
meta.nota string Precizare despre cum se citesc datele din răspuns — o capcană, o convenţie sau o limită a sursei.
meta.nota_publicare string Precizare despre cum se citeşte răspunsul: o capcană, o convenţie sau o limită a sursei.
meta.necotate Valutele cerute prin filtru care NU au cotaţie în ziua folosită. Apare doar când lipseşte ceva — altfel un răspuns parţial ar trece neobservat.

Exemple de răspuns

GEThttps://oneapi.ro/api/financiar/v1/curs?data=2024-06-14
{
    "data": {
        "data": "2024-06-14",
        "valoare": {
            "moneda_baza": "RON",
            "cotatii": [
                {
                    "valuta": "AED",
                    "valoare": "1.268",
                    "multiplicator": 1,
                    "valoare_unitara": "1.268"
                }
            ]
        },
        "ultima": {
            "data": "2024-06-14",
            "valoare": {
                "moneda_baza": "RON",
                "cotatii": [
                    {
                        "valuta": "AED",
                        "valoare": "1.268",
                        "multiplicator": 1,
                        "valoare_unitara": "1.268"
                    }
                ]
            }
        }
    },
    "meta": {
        "sursa": "Banca Naţională a României",
        "cotatii": 31,
        "nota": "Valoare publicată în ziua cerută.",
        "nota_publicare": "Curs de referinţă, publicat în zilele bancare, în general după ora 13: 00."
    }
}

Coduri de eroare

CodSlugCând apare
401neautentificatToken lipsă, invalid, expirat sau revocat.
403feature_indisponibilPlanul curent nu include funcţia de care ţine ruta.
422validareDată lipsă, malformată ori în viitor; cod de valută care nu are 3 litere.
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": "Dată lipsă, malformată ori în viitor; cod de valută care nu are 3 litere.",
        "detalii": {
            "data": [
                "Valoarea trimisă nu respectă regula parametrului."
            ]
        }
    }
}