oneapi
Autentificare
Financiar v1 / Bce

Conversie la cursurile BCE

Converteşte o sumă folosind cursurile de referinţă ale Băncii Centrale Europene, fără trecere prin
leu.

Statutul rezultatului nu e acelaşi pe toate perechile, iar răspunsul îl declară de fiecare dată.
Când una dintre laturi e EUR, cursul e chiar cel PUBLICAT de BCE — oficial: true. Când niciuna
nu e euro, rezultatul e un curs ÎNCRUCIŞAT, calculat prin euro: BCE publică EUR/USD şi EUR/GBP, nu
USD/GBP. Atunci oficial: false şi prin: "EUR".

Diferenţa faţă de /conversie/incrucisata e reală, nu doar de statut. USD/GBP calculat prin
euro faţă de acelaşi curs prin leu diferă cu 0,107% în medie şi până la 1,15% — la 100.000 USD,
peste o mie de lei. Sunt două fixinguri independente, iar drumul prin leu cere două conversii în
loc de una.

Sensul e INVERS faţă de BNR: BCE cotează unităţi de valută pentru 1 EUR, nu lei pentru o
unitate. sens şi componente sunt în fiecare răspuns tocmai fiindcă inversarea lor inversează
rezultatul.

Ambele cotaţii vin din ACEEAŞI zi — se caută ultima zi în care toate valutele cerute au cotaţie,
nu ultima zi a fiecăreia. Un curs încrucişat între două zile de piaţă e plauzibil şi greşit.

Leul nu are statut special aici: RON e o valută ca oricare alta în tabelul BCE.

GET
https://oneapi.ro/api/financiar/v1/bce/conversie

Parametri de interogare

NumeTipDescriereValori acceptate
sumaobligatoriu string Obligatoriu. Punct zecimal, cel mult 6 zecimale. Negativul e permis. ex. 1000ex. 250
dinobligatoriu string Obligatoriu. Cod de 3 litere; EUR şi RON sunt acceptate ca oricare alta. max 3 car.
inobligatoriu string Obligatoriu. Cod de 3 litere. max 3 car.
dataopțional string | null Opţional, YYYY-MM-DD. Implicit ziua curentă. Nu poate fi în viitor. ex. 2024-06-15ex. 2024-03-15

Cum se comportă

  • Converteşte o sumă folosind cursurile de referinţă ale Băncii Centrale Europene, fără trecere prin leu.
  • Statutul rezultatului NU e acelaşi pe toate perechile, iar răspunsul îl declară de fiecare dată. Când una dintre laturi e EUR, cursul e chiar cel PUBLICAT de BCE: oficial: true. Când niciuna nu e euro, rezultatul e un curs ÎNCRUCIŞAT — BCE publică EUR/USD şi EUR/GBP, nu USD/GBP — deci oficial: false şi prin: "EUR".
  • Diferenţa faţă de /conversie/incrucisata e reală, nu doar de statut. Acolo drumul trece prin leu, cu cursurile BNR. Măsurat pe zilele comune, USD/GBP prin euro faţă de acelaşi curs prin leu diferă cu 0,107% în medie şi până la 1,15% — la 100.000 USD, peste o mie de lei. Sunt două fixinguri independente, iar drumul prin leu cere două conversii în loc de una.
  • Sensul e INVERS faţă de BNR. BCE cotează „unităţi de valută pentru 1 EUR"; BNR cotează „lei pentru o unitate de valută". Confundarea lor inversează rezultatul, de aceea sens şi componente sunt în fiecare răspuns, cu cotaţiile brute folosite.
  • Ambele cotaţii vin din ACEEAŞI zi. Se caută ultima zi în care TOATE valutele cerute au cotaţie, nu ultima zi a fiecăreia — un curs încrucişat între două zile de piaţă e plauzibil şi greşit. Substituirea se raportează prin exact şi zile_inapoi.
  • Leul nu are statut special aici: RON e o valută ca oricare alta în tabelul BCE, cotată tot ca unităţi per euro. O conversie RON → USD prin euro e legitimă şi dă alt rezultat decât cea la cursul BNR — ambele corecte, cu surse diferite.
  • Valute identice pe ambele laturi: suma trece neschimbată, cu factor: "1", fără cotaţie şi fără dată. Nu e eroare — un client care converteşte o listă nu trebuie să trateze cazul separat.
  • Acoperirea: 44 de valute, din 1999. Pentru lista completă şi cotaţiile zilei, /bce/curs.

La ce folosește

  • Conversie EUR ↔ valută la cursul oficial BCE.
  • Paritate între două valute străine, fără ocolul prin leu.
  • Compararea rezultatului cu cel obţinut prin cursurile BNR.

Structura răspunsului

CâmpTipDescriere
data.suma string Suma valorilor, în unitatea indicată alături.
data.din string
data.in string
data.data_ceruta string Data cerută de client, înainte de alinierea la o zi cu date.
data.data string Ziua cerută, exact cum ai trimis-o.
data.exact boolean true doar dacă ziua întoarsă e cea cerută.
data.zile_inapoi integer Câte zile s-a mers înapoi ca toate valutele să aibă cotaţie în aceeaşi zi.
data.oficial boolean true când o latură e EUR — cursul e publicat de BCE. false la încrucişate.
data.prin null EUR la cursurile încrucişate; null când rezultatul e oficial.
data.sens string Mereu valuta_per_1_eur — convenţia BCE, inversă faţă de BNR.
data.factor string Numărul cu care s-a înmulţit suma: suma × factor = suma_convertita_exacta.
data.componente[].valuta string Codul ISO 4217 al valutei.
data.componente[].denumire null Denumirea, aşa cum o publică sursa.
data.componente[].unitati_per_eur string Cotaţia brută BCE folosită, pentru fiecare valută non-euro.
data.suma_convertita string
data.suma_convertita_exacta string
meta.sursa string Sursa oficială din care vin datele, cu licenţa ei acolo unde e cerută.
meta.sens string Sensul operaţiunii.
meta.statut string Starea în care se află elementul la sursă.
meta.fata_de_bnr string
meta.contract string
meta.nota_substituire string Când şi cu ce s-a înlocuit o valoare lipsă.
meta.fara_date data e null, iar aici stă motivul. Una dintre valute nu e cotată de BCE, sau nu există o zi comună în ultimele 10 zile.
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/bce/conversie?suma=1000&din=EUR&in=RON&data=2024-06-15
{
    "data": {
        "suma": "1000",
        "din": "EUR",
        "in": "RON",
        "data_ceruta": "2024-06-15",
        "data": "2024-06-14",
        "exact": false,
        "zile_inapoi": 1,
        "oficial": true,
        "prin": null,
        "sens": "valuta_per_1_eur",
        "factor": "4.9773",
        "componente": [
            {
                "valuta": "RON",
                "denumire": null,
                "unitati_per_eur": "4.9773"
            }
        ],
        "suma_convertita": "4977.30",
        "suma_convertita_exacta": "4977.3"
    },
    "meta": {
        "sursa": "Banca Centrală Europeană — cursuri de referinţă.",
        "sens": "Cotaţiile BCE sunt „unităţi de valută pentru 1 EUR\", INVERS faţă de BNR care cotează lei pentru o unitate de valută.",
        "statut": "Curs PUBLICAT de BCE: una dintre laturi e euro.",
        "fata_de_bnr": "Prin leu, cu cursurile BNR, acelaşi curs încrucişat diferă cu circa 0,1% în medie şi până la 1,15%: /financiar/v1/conversie/incrucisata.",
        "contract": "suma × factor = suma_convertita_exacta, cifră cu cifră.",
        "nota_substituire": "Ziua cerută nu are publicare la toate valutele; s-a folosit ultima zi în care toate aveau cotaţie."
    }
}

Coduri de eroare

CodSlugCând apare
401neautentificatToken lipsă, invalid, expirat sau revocat.
403feature_indisponibilPlanul curent nu include funcţia de care ţine ruta.
422validareSumă sau cod de valută malformat; dată viitoare.
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": "Sumă sau cod de valută malformat; dată viitoare.",
        "detalii": {
            "suma": [
                "Valoarea trimisă nu respectă regula parametrului."
            ]
        }
    }
}