oneapi
Autentificare
Financiar v1 / CursMediu

Curs mediu (oficial BNR)

Media oficială BNR a unei luni (?luna=AAAA-LL), a unui trimestru (?trimestru=AAAA-Tn) ori a unui an
(?an=AAAA), pentru toate valutele sau pentru o listă (?valuta=EUR,USD). Fără perioadă, ultima lună
publicată. Media trimestrială şi cea anuală sunt construite din mediile LUNARE, nu din cotaţiile zilnice —
cum le publică BNR; răspunsul arată componentele şi ce ar ieşi din metoda intuitivă.

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

Parametri de interogare

NumeTipDescriereValori acceptate
lunaopțional string | null O lună, AAAA-LL, din 2005. Fără nicio perioadă, ultima lună publicată. ex. 2024-06
trimestruopțional string | null Un trimestru, AAAA-Tn (2024-T2), ca eticheta BNR. ex. 2024-T2
anopțional integer | null Un an, AAAA, din 2005, până la ultimul an încheiat şi publicat. 2005 – 2100
valutalistăopțional text Filtru opţional: ?valuta=EUR,USD. Fără el se întorc toate valutele perioadei. ex. EURex. EUR,USD

Cum se comportă

  • Media oficială BNR pe o lună (?luna=AAAA-LL), un trimestru (?trimestru=AAAA-Tn) ori un an (?an=AAAA) — una singură. Fără perioadă, ultima lună publicată. Granularitatea o dă parametrul trimis, iar răspunsul are forma ei: la trimestru şi an vin şi componentele lunare.
  • Media lunară a cursului de schimb, aşa cum o publică BNR în seriile lunare ale pieţei valutare. E cifra cerută în raportări contabile şi fiscale.
  • Media oficială E media aritmetică a cotaţiilor zilnice, rotunjită la patru zecimale. Nu e o presupunere: verificat pe toate cele 7.567 de perechi lună×valută din 2005 încoace, abaterea maximă e 0,00005 — exact jumătate de unitate pe ultima zecimală, adică semnătura rotunjirii. Aşadar ruta nu alege între două metodologii; întoarce cifra publicată şi arată alături recalcularea.
  • verificare conţine media recalculată de noi din cotaţiile zilnice ale aceleiaşi luni, numărul de zile bancare care au intrat în ea şi diferenţa faţă de cifra oficială. Rezultatul e verificabil fără să reproduci logica — şi se vede pe ce s-a calculat.
  • Valorile sunt RON pentru O UNITATE de valută. Seria lunară e deja împărţită la multiplicator, spre deosebire de /curs, unde cinci valute se publică la 100: yenul apare aici ca 0.02823, nu ca 2.823. De aceea răspunsul n-are câmp multiplicator — n-ar fi nimic de aplicat, iar prezenţa lui ar invita înmulţirea greşită.
  • Luna în curs întoarce 404 cu luna_neincheiata, nu o medie parţială. O medie pe o lună neîncheiată arată exact ca una finală şi se citează la fel, deci nu se întoarce deloc. Codul e distinct de nepublicata, care înseamnă „luna s-a încheiat, dar BNR n-a publicat încă".
  • Acoperirea începe în ianuarie 2005. Pentru perioade anterioare nu există medie oficială — moneda era leul vechi, iar seriile lunare încep odată cu leul nou. Media zilnicelor de atunci se poate calcula din /curs-istoric/interval, dar e o cifră a ta, nu una publicată.
  • Fără filtru se întorc toate valutele cu medie publicată în luna respectivă. Numărul variază în timp: valutele delistate (BGN din 2026) dispar din lunile de după.
  • Media trimestrială a cursului de schimb, aşa cum o publică BNR în seriile trimestriale ale pieţei valutare.
  • Nu e media cotaţiilor zilnice din trimestru, ci media celor TREI MEDII LUNARE. Verificat pe 2.502 de perechi trimestru×valută: potrivire 100% cu media de medii (abatere maximă 0,000033, adică rotunjire) faţă de doar 36,9% cu media zilnicelor. Cine calculează „media EUR pe T1" din cotaţii obţine alt număr decât cel oficial.
  • Diferenţa vine din ponderare şi e frecventă, nu exotică. Media de medii cântăreşte lunile egal; media zilnicelor le cântăreşte după numărul de zile bancare, care diferă de la lună la lună. Rezultat: 70,4% dintre perechi se abat cu peste 0,01%, mediana e 0,0226%, iar în trimestrele volatile urcă la ~0,9% — rubla în T1 2022 (0,0519 oficial faţă de 0,051427 din zilnice), lira turcească în T2 2006, lira egipteană în T4 2016.
  • construita_din arată construcţia reală: cele trei medii lunare, media lor şi diferenţa faţă de cifra publicată. din_zilnice arată ce ar produce metoda intuitivă, cu diferenţa faţă de oficial. A doua nu e o variantă corectă — e capcana, pusă la vedere tocmai ca să nu fie folosită din neatenţie.
  • Trimestrul în curs întoarce 404 cu trimestru_neincheiat, nu o medie pe două luni din trei. Ar arăta exact ca una finală şi s-ar cita la fel. Codul e distinct de nepublicata, care înseamnă „s-a încheiat, dar BNR n-a publicat încă".
  • Valorile sunt RON pentru O UNITATE de valută, deja împărţite la multiplicator — ca la seria lunară şi spre deosebire de /curs.
  • Acoperirea începe cu T1 2005.
  • Media anuală a cursului de schimb, aşa cum o publică BNR în seriile anuale ale pieţei valutare. E cifra pentru raportări anuale şi pentru conversii de bilanţ.
  • E media celor DOUĂSPREZECE medii lunare, ca la trimestru dar dusă mai departe. Verificat pe 597 de perechi an×valută: potrivire 100% cu media celor 12 luni, 98,5% cu media celor 4 trimestre şi doar 27,6% cu media cotaţiilor zilnice.
  • Media celor patru valori trimestriale nu e o a doua metodă. Dă matematic acelaşi rezultat — fiecare trimestru are exact 3 luni, cântărite egal — dar se abate în 1,5% din cazuri fiindcă valorile trimestriale sunt rotunjite la 4 zecimale înainte de a fi mediate. E aceeaşi construcţie, cu o rotunjire în plus.
  • Capcana e mai mare decât la trimestru: abaterea maximă faţă de media zilnicelor urcă la 1,07 — peste un leu. Cu cât perioada e mai lungă, cu atât diferenţa de ponderare dintre luni se acumulează.
  • construita_din arată construcţia reală: cele douăsprezece medii lunare, media lor şi diferenţa faţă de cifra publicată. din_zilnice arată ce ar produce metoda intuitivă. A doua nu e o variantă corectă — e capcana, pusă la vedere.
  • Componentele sunt mereu prezente, indiferent dacă filtrezi pe valute sau nu. Fără filtru răspunsul are 40 de valute × 12 luni, deci în jur de 20 KB — o rută care îşi schimbă structura după prezenţa unui parametru e mai greu de folosit decât una puţin mai mare.
  • Anul în curs întoarce 404 cu an_neincheiat, nu o medie parţială. Codul e distinct de nepublicata, care înseamnă „anul s-a încheiat, dar BNR n-a publicat încă".
  • Valorile sunt RON pentru O UNITATE de valută, deja împărţite la multiplicator. Acoperirea începe în 2005.

La ce folosește

  • Cursul mediu lunar pentru o raportare contabilă sau fiscală.
  • Conversia unui flux de venituri sau cheltuieli dintr-o lună.
  • Verificarea cifrei folosite de altcineva, cu recalcularea alături.
  • Cursul mediu trimestrial pentru o raportare sau o situaţie financiară interimară.
  • Verificarea unei cifre trimestriale calculate greşit din cotaţii zilnice.
  • Conversia unui flux trimestrial de venituri sau cheltuieli.
  • Cursul mediu anual pentru situaţiile financiare şi raportările de an.
  • Conversia unui flux anual de venituri sau cheltuieli.
  • Verificarea unei cifre anuale calculate greşit din cotaţii zilnice.

Structura răspunsului

CâmpTipDescriere
data.luna string Luna la care se referă datele.
data.de_la string Prima zi a lunii.
data.pana_la string Ultima zi a lunii.
data.moneda_baza string Moneda faţă de care sunt exprimate cotaţiile.
data.medii[].valuta string Codul ISO 4217 al valutei.
data.medii[].denumire string Denumirea, aşa cum o publică sursa.
data.medii[].valoare_unitara string Media oficială BNR, RON pentru O unitate de valută. Cifra care se citează.
data.medii[].verificare.medie_din_zilnice string Recalcularea noastră din cotaţiile zilnice ale lunii.
data.medii[].verificare.zile_bancare integer Câte zile au intrat efectiv în medie.
data.medii[].verificare.diferenta string Oficial minus recalculat. Mereu sub 0,00005 — rotunjire, nu metodologie.
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.valute integer Valutele acoperite de răspuns.
meta.nota_unitate string Ce trebuie ştiut despre unitatea de măsură înainte de a compara sau aduna valorile.
meta.nota_verificare string Precizare despre cum se citeşte răspunsul: o capcană, o convenţie sau o limită a sursei.
meta.zilnic string
meta.fara_valori Valutele cerute prin filtru care nu au medie în luna respectivă.
meta.fara_date data e null, iar aici stă motivul. Nu există seriile respective în bază. Perioada încă se scrie, e înainte de 2005, ori niciuna dintre valutele cerute nu are medie publicată.
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-mediu?valuta=EUR
{
    "data": {
        "luna": "2026-08",
        "de_la": "2026-08-01",
        "pana_la": "2026-08-31",
        "moneda_baza": "RON",
        "medii": [
            {
                "valuta": "EUR",
                "denumire": "Euro",
                "valoare_unitara": "5.2498",
                "verificare": {
                    "medie_din_zilnice": "5.24978571",
                    "zile_bancare": 21,
                    "diferenta": "0.00001429"
                }
            }
        ]
    },
    "meta": {
        "sursa": "BNR — cursul de schimb al pieţei valutare, serii lunare (baza de date interactivă).",
        "acoperire": {
            "de_la": "2005-01",
            "pana_la": "2026-08"
        },
        "valute": 1,
        "nota_unitate": "Valorile sunt RON pentru O unitate de valută, deja împărţite la multiplicator — spre deosebire de `/curs`, unde cinci valute se publică la 100.",
        "nota_verificare": "Media oficială e media aritmetică a cotaţiilor zilnice, rotunjită la 4 zecimale. `verificare` conţine recalcularea noastră şi diferenţa; verificat pe toată seria, abaterea maximă e 0,00005.",
        "zilnic": "Cotaţiile zi cu zi ale aceleiaşi luni: /financiar/v1/curs/interval?valuta=EUR&de_la=2026-08-01&pana_la=2026-08-31"
    }
}

Coduri de eroare

CodSlugCând apare
401neautentificatToken lipsă, invalid, expirat sau revocat.
403feature_indisponibilPlanul curent nu include funcţia de care ţine ruta.
422validareMai multe perioade deodată (luna, trimestru, an nu se combină), perioadă scrisă altfel decât AAAA-LL, AAAA-Tn ori AAAA, perioadă dinainte de 2005 (în lei vechi: /curs-istoric/mediu), cod de valută invalid.
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": "Mai multe perioade deodată (luna, trimestru, an nu se combină), perioadă scrisă altfel decât AAAA-LL, AAAA-Tn ori AAAA, perioadă dinainte de 2005 (în lei vechi: /curs-istoric/mediu), cod de valută invalid.",
        "detalii": {
            "luna": [
                "Valoarea trimisă nu respectă regula parametrului."
            ]
        }
    }
}