oneapi
Autentificare
Financiar v1 / CursIstoric

Seria cursului peste denominare

Cotaţiile a una până la cinci valute între două date, pe un interval care poate traversa
denominarea din 2005. Până acum, un grafic 1998 → azi era imposibil de făcut corect: cerea două
rute şi lipirea a două serii cu 10.000 diferenţă între unităţi.

Fiecare punct îşi declară unitatea (denominare) şi vine cu două cifre: valoare, aşa cum a
publicat-o BNR atunci, şi valoare_unitara_ron, aceeaşi mărime adusă la lei noi. A doua e coloana
cu care se desenează un grafic continuu; prima e cea care se citează.

Multiplicatorul stă pe fiecare punct, nu o dată pe serie ca la /curs/interval: forintul şi
yenul se publicau la o unitate înainte de 2005 şi se publică la 100 după. multiplicator_variabil
pe serie semnalează cazul, ca nimeni să nu scoată multiplicatorul în afara buclei.

Intervalul e plafonat la 10 ani. O valută care se opreşte înaintea capătului cerut — marca germană
în 2002 — întoarce seria parţială şi apare în meta.serii_oprite, nu 404: datele cerute există,
doar se termină.

GET
https://oneapi.ro/api/financiar/v1/curs-istoric/interval

Parametri de interogare

NumeTipDescriereValori acceptate
de_laobligatoriu string Obligatoriu, YYYY-MM-DD. Poate fi oricât de vechi — se aliniază la acoperire. ex. 2024-06-15
pana_laopțional string | null Opţional, implicit ultima zi acoperită. ex. 2024-06-15ex. 2024-06-30
valutalistăopțional text Obligatoriu, 1–5 coduri: ?valuta=DEM sau ?valuta=EUR,USD. ex. EUR

Cum se comportă

  • Cotaţiile a una până la cinci valute între două date, pe un interval care poate traversa denominarea din 2005.
  • Până la ruta asta, un grafic 1998 → azi nu se putea face corect. Cerea două rute şi lipirea a două serii cu 10.000 diferenţă între unităţi — de unde graficul cu un salt vertical în ianuarie 2005 şi nicio explicaţie. Aici seria vine dintr-o singură cerere, cu unitatea declarată la fiecare punct.
  • Fiecare punct are două cifre. valoare e ce a publicat BNR atunci, în unitatea de atunci — cifra care se citează. valoare_unitara_ron e aceeaşi mărime adusă la lei noi, comparabilă pe toată seria — coloana cu care se desenează graficul. Nu se alege una: ambele sunt necesare, pentru lucruri diferite.
  • Multiplicatorul stă pe FIECARE punct, nu o dată pe serie — spre deosebire de /curs/interval, unde e constant. Peste graniţă nu e: forintul şi yenul se publicau la o unitate în epoca ROL şi se publică la 100 în cea RON. Declarat o singură dată, ar fi greşit pe jumătate de serie cu un factor de 100 care, înmulţit cu cei 10.000 ai denominării, dă un milion. multiplicator_variabil semnalează seriile în care se schimbă.
  • denominare_schimbata şi denominare_schimbata_la spun dacă şi unde se rupe unitatea. Graniţa e 2005-01-03, prima zi în care BNR îşi exprimă arhiva în lei noi — nu 1 iulie 2005, când a avut loc denominarea legală. Aceeaşi fereastră ambiguă declarată de /calcul/denominare.
  • O valută care se opreşte înaintea capătului cerut întoarce seria parţială, nu 404. Marca germană se opreşte în februarie 2002 fiindcă a încetat să existe, nu fiindcă ne lipsesc date; apare în meta.serii_oprite cu ultima zi şi motivul. Un 404 ar sugera că cererea a fost greşită.
  • Intervalul e plafonat la 10 ani, mult peste cele 366 de zile de la /curs/interval, fiindcă scopul e opus: acolo „ultimele 12 luni", aici seria lungă. Plafonul se verifică DUPĂ alinierea marginilor la acoperire, deci o cerere „din 1990" nu e respinsă pentru zilele care oricum n-au date.
  • Marginea din dreapta se aliniază la ultima zi acoperită, nu la ziua curentă: dacă importul e în urmă, o margine pusă pe „azi" ar produce o coadă goală care arată ca o pauză de publicare. Ce s-a ajustat apare în meta.ajustat.

La ce folosește

  • Grafic al cursului pe zeci de ani, fără saltul artificial din 2005.
  • Media cursului pe o perioadă care traversează denominarea.
  • Urmărirea unei monede până la dispariţia ei (marcă germană, liră italiană).

Structura răspunsului

CâmpTipDescriere
data.de_la string Începutul intervalului acoperit de răspuns.
data.pana_la string Sfârşitul intervalului acoperit de răspuns, inclusiv.
data.denominare_schimbata boolean true dacă intervalul traversează 2005-01-03.
data.denominare_schimbata_la null Ziua în care se rupe unitatea; null dacă intervalul e într-o singură epocă.
data.serii array Seriile din răspuns.
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.zile_interval integer Câte zile calendaristice are intervalul cerut.
meta.fara_valori array Valutele cerute care nu au nicio cotaţie în interval.
meta.nota_multiplicator string Precizare despre cum se citeşte răspunsul: o capcană, o convenţie sau o limită a sursei.
meta.temei_denominare string
data.serii[].multiplicator_variabil boolean true când multiplicatorul se schimbă în interval (HUF, JPY). Cine agregă seria nu poate scoate multiplicatorul în afara buclei.
data.serii[].valori[].denominare string ROL sau RON — unitatea punctului.
data.serii[].valori[].valoare string Cifra publicată de BNR, în unitatea de atunci.
data.serii[].valori[].valoare_unitara string Pe O unitate de valută, în unitatea de atunci.
data.serii[].valori[].valoare_unitara_ron string Pe O unitate de valută, în lei NOI. Comparabilă pe toată seria.
meta.serii_oprite Valutele a căror serie se termină înaintea capătului cerut, cu ultima zi şi motivul.
meta.ajustat Marginile aliniate la acoperire. Absent când nu s-a ajustat nimic.
meta.fara_date data e null, iar aici stă motivul. Intervalul e în întregime în afara arhivei.
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/interval?de_la=2024-06-15&valuta=EUR&pana_la=2024-06-15
{
    "data": {
        "de_la": "2024-06-15",
        "pana_la": "2024-06-15",
        "denominare_schimbata": false,
        "denominare_schimbata_la": null,
        "serii": []
    },
    "meta": {
        "sursa": "BNR — arhiva cursului de schimb, ambele epoci (lei vechi şi lei noi).",
        "acoperire": {
            "de_la": "1998-01-05",
            "pana_la": "2026-09-21"
        },
        "zile_interval": 1,
        "fara_valori": [
            "EUR"
        ],
        "nota_multiplicator": "Multiplicatorul e pe fiecare punct, nu pe serie: la HUF şi JPY se schimbă odată cu denominarea (1 → 100).",
        "temei_denominare": "Legea 348/2004 — 1 RON = 10.000 ROL, în vigoare de la 1 iulie 2005."
    }
}

Coduri de eroare

CodSlugCând apare
401neautentificatToken lipsă, invalid, expirat sau revocat.
403feature_indisponibilPlanul curent nu include funcţia de care ţine ruta.
422validareinterval_prea_lung (peste 3.653 de zile), peste 5 valute, cod de valută invalid, pana_la înainte de de_la.
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": "interval_prea_lung (peste 3.653 de zile), peste 5 valute, cod de valută invalid, pana_la înainte de de_la.",
        "detalii": {
            "de_la": [
                "Valoarea trimisă nu respectă regula parametrului."
            ]
        }
    }
}