oneapi
Autentificare
Financiar v1 / Curs

Cursul unei valute

Cotaţia unei singure valute la ziua cerută — ?data= e OBLIGATORIE. 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).

Acelaşi mecanism acoperă ambele situaţii în care ziua cerută nu are cotaţie: zi nelucrătoare
(duminică → vineri, exact regula BNR) şi import în urmă (azi → ultima zi adusă). Diferenţa se
citeşte din ultima.data. valoare rămâne gol DELIBERAT, ca o cifră care nu e a zilei cerute
să nu poată fi folosită din greşeală.

Lipsa datelor NU e o eroare: răspunsul e 200. 404 rămâne doar pentru o valută pe care BNR n-a
cotat-o niciodată, iar 422 pentru data lipsă ori scrisă greşit.

GET
https://oneapi.ro/api/financiar/v1/curs/{valuta}

Parametri de cale

NumeTipDescriereExemplu
valutaobligatoriu string Codul ISO 4217 al valutei (EUR, USD, XAU…).

Parametri de interogare

NumeTipDescriereValori acceptate
dataobligatoriu string Obligatoriu: ziua, AAAA-LL-ZZ. Nu poate fi în viitor. BNR nu publică în weekend şi de sărbători — atunci valoare e gol şi cotaţia aplicabilă vine în ultima. ex. 2024-06-14ex. 2024-06-16

Cum se comportă

  • Cotaţia unei singure valute la ziua cerută. ?data= e obligatorie — nu există zi implicită, fiindcă „azi" şi „ultima zi pe care o avem" sunt două lucruri diferite, iar confundarea lor servea cotaţii vechi ca şi cum ar fi fost ale zilei.
  • 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 e gol deliberat când ziua cerută n-are publicare. Câmpul pe care îl citeşti firesc rămâne gol, iar cifra de altă zi stă separat, sub ultima — nu poate fi folosită din greşeală într-o factură, dar nici nu trebuie cerută a doua oară. Comparaţia data vs ultima.data îţi spune tot.
  • Acelaşi mecanism acoperă ambele cazuri în care ziua cerută n-are cotaţie: zi nelucrătoare (duminică → vineri, exact regula BNR) şi import în urmă (azi → ultima zi adusă). Diferenţa se citeşte din ultima.data, fără câmp în plus.
  • Nu există plafon de vechime. Ruta RAPORTEAZĂ ce există, iar cât de veche e cifra se vede din ultima.data — un plafon ar fi transformat o întârziere de import în „nu există", ceea ce ar fi fals.
  • Lipsa datelor nu e o eroare: răspunsul e 200. 404 rămâne doar pentru o valută pe care BNR n-a cotat-o niciodată, iar 422 pentru data lipsă ori scrisă greşit.
  • Acoperirea în lei noi începe la 2005-01-03. Pentru o dată anterioară, valoare şi ultima sunt amândouă goale, iar meta.vezi trimite la /curs-istoric/{valuta}, unde stă epoca ROL.
  • Datele viitoare sunt respinse cu 422: BNR publică cursul în ziua respectivă, nu înainte.

La ce folosește

  • Conversia unei sume în factură, la cursul zilei.
  • Afişarea unui singur curs într-un widget, fără să aduci toată lista.
  • Verificarea rapidă a cotaţiei înainte de o plată externă.
  • Conversia unei facturi în valută la cursul zilei facturii.
  • Reconstituirea unui curs istoric pentru raportări sau litigii.

Structura răspunsului

CâmpTipDescriere
data.data string Ziua cerută, exact cum ai trimis-o.
data.valoare.valuta string Codul ISO 4217 al valutei.
data.valoare.moneda_baza string Moneda în care e exprimată cotaţia. Mereu RON pe această rută.
data.valoare.valoare string Cotaţia zilei cerute: valoare, multiplicator, valoare_unitara. null dacă ziua aia n-are publicare.
data.valoare.multiplicator integer Cu cât se înmulţeşte valoarea ca să ajungă în unitatea de bază.
data.valoare.valoare_unitara string Valoarea raportată la o singură unitate.
data.ultima object Ultima zi publicată la sau înainte de data, cu cotaţia ei: {data, valoare}. null doar dacă nu există nimic înaintea zilei cerute. Când ziua cerută are publicare, ultima.data e egală cu data — dublarea e intenţionată, ca să compari mereu aceleaşi două câmpuri.
data.ultima.data string
data.ultima.valoare.valuta string Codul ISO 4217 al valutei.
data.ultima.valoare.moneda_baza string
data.ultima.valoare.valoare string Cotaţia zilei cerute: valoare, multiplicator, valoare_unitara. null dacă ziua aia n-are publicare.
data.ultima.valoare.multiplicator integer Cu cât se înmulţeşte valoarea ca să ajungă în unitatea de bază.
data.ultima.valoare.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.nota string Precizare despre cum se citesc datele din răspuns — o capcană, o convenţie sau o limită a sursei.

Exemple de răspuns

GEThttps://oneapi.ro/api/financiar/v1/curs/EUR?data=2024-06-14
{
    "data": {
        "data": "2024-06-14",
        "valoare": {
            "valuta": "EUR",
            "moneda_baza": "RON",
            "valoare": "4.9771",
            "multiplicator": 1,
            "valoare_unitara": "4.9771"
        },
        "ultima": {
            "data": "2024-06-14",
            "valoare": {
                "valuta": "EUR",
                "moneda_baza": "RON",
                "valoare": "4.9771",
                "multiplicator": 1,
                "valoare_unitara": "4.9771"
            }
        }
    },
    "meta": {
        "sursa": "Banca Naţională a României",
        "nota": "Valoare publicată în ziua cerută."
    }
}

Coduri de eroare

CodSlugCând apare
401neautentificatToken lipsă, invalid, expirat sau revocat.
403feature_indisponibilPlanul curent nu include funcţia de care ţine ruta.
404negasitValuta n-a fost cotată niciodată de BNR. Nomenclatorul e la /financiar/v1/valute.
422validareCod de valută care nu are 3 litere, dată lipsă, malformată ori în viitor.
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": "Cod de valută care nu are 3 litere, dată lipsă, malformată ori în viitor.",
        "detalii": {
            "valuta": [
                "Valoarea trimisă nu respectă regula parametrului."
            ]
        }
    }
}