oneapi
Autentificare
Financiar v1 / CursIstoric

Curs istoric (epoca leului vechi)

Cotaţia BNR a unei valute la o zi din perioada 1998-01-05 → 2004-12-31, când moneda naţională
era leul vechi (ROL).

Cifrele sunt în LEI VECHI. Un curs de 638 nu se compară cu unul de 5,25 de azi: sunt patru
ordine de mărime între ele. Fiecare răspuns declară denominare: "ROL" şi cară şi echivalentul în
lei noi, în echivalent_ron, ca o sumă din acte vechi să poată fi adusă la unitatea de azi.

Acoperă 30 de valute, dintre care 13 nu mai există: ATS, BEF, DEM, ESP, FIM, FRF, GRD, IEP,
ITL, NLG, PTE (monede naţionale înlocuite de euro), TRL (lira turcească dinaintea redenominării)
şi XEU (ECU). Pentru datele de după 2005 foloseşte /curs/{valuta}?data=.

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

Parametri de cale

NumeTipDescriereExemplu
valutaobligatoriu string Codul ISO 4217 al valutei căutate în seria istorică.

Parametri de interogare

NumeTipDescriereValori acceptate
dataobligatoriu string Obligatorie: ziua, ?data=AAAA-LL-ZZ, între 1998-01-05 şi 2004-12-31. ex. 1998-06-15ex. 2001-03-15ex. 1999-01-15

Cum se comportă

  • Cotaţia BNR a unei valute la o zi din perioada 1998-01-05 → 2004-12-31, când moneda naţională era leul vechi (ROL).
  • Cifrele sunt în LEI VECHI şi nu se compară cu cele de azi. Un curs de 638 (şiling austriac, 1998) şi unul de 5,25 (euro, azi) au patru ordine de mărime între ele. De aceea răspunsul declară denominare: "ROL" şi cară şi echivalent_ron — aceeaşi cotaţie adusă la lei noi, ca o sumă din acte vechi să poată fi folosită fără să ţii minte raportul.
  • Rută separată de /curs, nu un parametru al ei. Puse în acelaşi câmp, cele două unităţi ar fi indistingibile: nimic din forma unui număr nu spune în ce leu e. Când ceri /curs/{valuta}?data= cu o dată dinainte de 2005, răspunsul te trimite explicit aici, cu calea completă.
  • Acoperă 30 de valute, dintre care 13 nu mai există: ATS, BEF, DEM, ESP, FIM, FRF, GRD, IEP, ITL, NLG, PTE — monedele naţionale înlocuite de euro între 1999 şi 2002 — plus TRL (lira turcească dinaintea redenominării din 2005) şi XEU (ECU, unitatea de cont care a precedat euro). Denumirile lor sunt în răspuns: nimeni nu mai ştie ce a fost IEP sau NLG.
  • XEU nu e monedă, ci un coş de monede — la fel ca XDR pe seria modernă. este_moneda: false îl separă, ca să nu ajungă într-o listă de selecţie valutară alături de marca germană.
  • Zilele fără publicare primesc ultima cotaţie anterioară, marcată cu exact: false şi zile_inapoi — acelaşi vocabular ca la /curs. Căutarea nu trece niciodată graniţa epocii: o cerere pentru 2004-12-31 nu poate cădea pe o cotaţie din 2005, fiindcă aceea e în altă unitate.
  • Graniţa urmează convenţia sursei, nu calendarul legal. Denominarea a avut loc la 1 iulie 2005, dar BNR îşi exprimă arhiva în lei noi din 1 ianuarie 2005 — de aceea seria ROL se opreşte la 2004-12-31. E aceeaşi fereastră ambiguă pe care o declară şi /calcul/denominare, iar cele două rute spun acelaşi lucru.
  • Data e OBLIGATORIE, spre deosebire de /curs/{valuta}, unde lipsa ei înseamnă „azi". În arhiva ROL nu există „azi": epoca s-a încheiat în 2004, iar o valoare implicită ar fi arbitrară.

La ce folosește

  • Reconstituirea unui curs pentru un contract sau un litigiu dinainte de 2005.
  • Conversia unei sume dintr-un act vechi, în paşi: cursul de atunci, apoi denominarea.
  • Regăsirea cotaţiei unei monede care nu mai există (marcă germană, liră italiană).

Structura răspunsului

CâmpTipDescriere
data.valuta string Codul ISO 4217 al valutei.
data.denumire string Denumirea valutei; la cele înlocuite de euro, cu anul trecerii.
data.este_moneda boolean false la XEU, care era unitate de cont, nu monedă.
data.data string Ziua cerută, exact cum ai trimis-o.
data.data_ceruta string Data cerută de client, înainte de alinierea la o zi cu date.
data.exact boolean true doar dacă ziua cerută are publicare proprie.
data.zile_inapoi integer Câte zile s-a mers înapoi ca să se găsească o cotaţie. Maxim 10.
data.denominare string Mereu ROL pe această rută. Unitatea în care e exprimată valoare.
data.moneda_baza string Mereu ROL: cotaţia e lei vechi per unitate de valută.
data.valoare string Cifra publicată de BNR, în lei vechi.
data.multiplicator integer Cu cât se înmulţeşte valoarea ca să ajungă în unitatea de bază.
data.valoare_unitara string Lei vechi pentru O unitate de valută. În arhiva ROL toţi multiplicatorii sunt 1, deci coincide cu valoare.
data.echivalent_ron.valoare_unitara string Aceeaşi cotaţie în lei NOI — valoare_unitara împărţită la 10.000.
data.echivalent_ron.raport_denominare integer Mereu 10.000 (Legea 348/2004).
data.echivalent_ron.temei string
meta.sursa string Sursa oficială din care vin datele, cu licenţa ei acolo unde e cerută.
meta.acoperire.de_la string Prima perioadă pentru care avem date.
meta.acoperire.pana_la string Ultima perioadă pentru care avem date.
meta.temei_denominare string
meta.nota_unitate string Ce trebuie ştiut despre unitatea de măsură înainte de a compara sau aduna valorile.
meta.nota_fereastra string Precizare despre cum se citeşte răspunsul: o capcană, o convenţie sau o limită a sursei.
meta.dupa_2005 string
meta.fara_date data e null, iar aici stă motivul. Data cerută e înainte de 1998-01-05, în afara acoperirii.
meta.fara_date_cod 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/curs-istoric/USD?data=1998-06-15
{
    "data": {
        "valuta": "USD",
        "denumire": "Dolar american",
        "este_moneda": true,
        "data": "1998-06-15",
        "data_ceruta": "1998-06-15",
        "exact": true,
        "zile_inapoi": 0,
        "denominare": "ROL",
        "moneda_baza": "ROL",
        "valoare": "8556",
        "multiplicator": 1,
        "valoare_unitara": "8556",
        "echivalent_ron": {
            "valoare_unitara": "0.8556",
            "raport_denominare": 10000,
            "temei": "Legea 348/2004 — 1 RON = 10.000 ROL, în vigoare de la 1 iulie 2005."
        }
    },
    "meta": {
        "sursa": "BNR — arhiva cursului de schimb în lei vechi (baza de date interactivă).",
        "acoperire": {
            "de_la": "1998-01-05",
            "pana_la": "2004-12-31"
        },
        "temei_denominare": "Legea 348/2004: 1 RON = 10.000 ROL, în vigoare de la 1 iulie 2005.",
        "nota_unitate": "Cifrele din `valoare` sunt în LEI VECHI. Nu se compară cu cursul de azi fără trecerea prin raportul de denominare; `echivalent_ron` o face deja.",
        "nota_fereastra": "Seria ROL se încheie la 2004-12-31 fiindcă BNR îşi exprimă arhiva în lei noi din 1 ianuarie 2005, deşi denominarea legală a fost la 1 iulie 2005. Aceeaşi fereastră ambiguă e declarată şi de `/calcul/denominare`.",
        "dupa_2005": "Pentru date de după denominare: /financiar/v1/curs/USD?data=AAAA-LL-ZZ."
    }
}

Coduri de eroare

CodSlugCând apare
401neautentificatToken lipsă, invalid, expirat sau revocat.
403feature_indisponibilPlanul curent nu include funcţia de care ţine ruta.
404negasitalta_epoca = data e după 2004-12-31, iar răspunsul dă calea către /curs; negasit = valuta n-a fost cotată niciodată în epoca ROL; iesita_din_circulatie = a fost cotată, dar nu la data cerută (răspunsul dă perioada în care era).
422validareCod de valută care nu are 3 litere, dată lipsă sau malformată.
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ă sau malformată.",
        "detalii": {
            "valuta": [
                "Valoarea trimisă nu respectă regula parametrului."
            ]
        }
    }
}