oneapi
Autentificare
Financiar v1 / Conversie

Conversie încrucişată, prin leu

Converteşte o sumă între două valute străine, folosind cotaţiile BNR ale amândurora şi trecând
prin leu. Rezultatul nu e un curs oficial BNR — BNR nu publică parităţi între valute străine.
curs.componente arată cele două cotaţii folosite.

Pentru conversii care implică leul, foloseşte /conversie.

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

Parametri de interogare

NumeTipDescriereValori acceptate
sumaobligatoriu string Obligatoriu. Punct zecimal, cel mult 6 zecimale, fără separatori de mii. ex. 1000ex. 2500ex. 5000
dinobligatoriu string Valută străină, cod de 3 litere. Nu poate fi RON. max 3 car.
inobligatoriu string Valută străină, diferită de din. Nu poate fi RON. max 3 car.
dataopțional string | null Opţional, YYYY-MM-DD. Implicit ziua curentă. ex. 2024-06-14ex. 2024-05-20

Cum se comportă

  • Converteşte o sumă între două valute străine, folosind cotaţiile BNR ale amândurora şi trecând prin leu.
  • Rezultatul NU e un curs oficial BNR. BNR nu publică parităţi între valute străine — nu există un „curs BNR EUR/USD". Cifra de aici e corectă matematic, dar nu poate fi prezentată drept curs oficial. curs.componente arată exact cele două cotaţii din care s-a obţinut.
  • Rută separată de /conversie tocmai ca distincţia să nu se piardă: acolo se foloseşte o singură cotaţie oficială, aici două, iar rezultatul are alt statut. Amestecate într-o singură rută, cifra neoficială ar putea trece drept oficială.
  • Ambele cotaţii trebuie să vină din aceeaşi zi. Dacă nu, cererea e respinsă cu 409 în loc să se producă un curs între două zile de piaţă diferite — un rezultat plauzibil şi greşit e mai rău decât o eroare.
  • curs.factor respectă acelaşi contract ca pe ruta oficială: suma × factor = suma_convertita_exacta, cifră cu cifră.
  • Pentru parităţi publicate direct între valute, sursa e BCE (rută viitoare) — acolo cifra e oficială şi nu trece prin leu.

La ce folosește

  • Estimarea unei sume în altă valută străină, pornind de la cotaţiile BNR.
  • Compararea a două oferte exprimate în valute diferite.

Structura răspunsului

CâmpTipDescriere
data.suma string Suma valorilor, în unitatea indicată alături.
data.din string
data.in string
data.suma_convertita string Rezultatul rotunjit la 2 zecimale.
data.suma_convertita_exacta string Rezultatul nerotunjit, pentru calcule în lanţ.
data.curs.factor string Numărul cu care s-a înmulţit suma: cotaţia lui din împărţită la cotaţia lui in.
data.curs.componente[] array Cele două cotaţii oficiale BNR folosite, cu valoarea publicată şi multiplicatorul.
data.curs.componente[].valuta string Codul ISO 4217 al valutei.
data.curs.componente[].valoare string Valoarea publicată de sursă pentru combinaţia de mai sus.
data.curs.componente[].multiplicator integer Cu cât se înmulţeşte valoarea ca să ajungă în unitatea de bază.
data.curs.componente[].valoare_unitara string Valoarea raportată la o singură unitate.
data.curs.data string Ziua din care provine cotaţia. null când valutele sunt identice.
data.curs.data_ceruta string Data cerută de client, înainte de alinierea la o zi cu date.
data.curs.exact boolean true dacă cotaţia e din ziua cerută.
data.curs.zile_inapoi integer
data.curs.prin string Mereu RON pe această rută: moneda prin care s-a făcut trecerea.
meta.sursa string Sursa oficială din care vin datele, cu licenţa ei acolo unde e cerută.
meta.curs string
meta.rotunjire string
meta.avertisment string Atenţionare despre o limită a datelor care schimbă interpretarea.
meta.nota string Precizare despre cum se citesc datele din răspuns — o capcană, o convenţie sau o limită a sursei.
meta.fara_date data e null, iar aici stă motivul. Data cerută e anterioară lui 2005-01-03.
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/conversie/incrucisata?suma=1000&din=USD&in=GBP&data=2024-06-14
{
    "data": {
        "suma": "1000",
        "din": "USD",
        "in": "GBP",
        "suma_convertita": "787.10",
        "suma_convertita_exacta": "787.10244364",
        "curs": {
            "factor": "0.78710244364",
            "componente": [
                {
                    "valuta": "USD",
                    "valoare": "4.6576",
                    "multiplicator": 1,
                    "valoare_unitara": "4.6576"
                }
            ],
            "data": "2024-06-14",
            "data_ceruta": "2024-06-14",
            "exact": true,
            "zile_inapoi": 0,
            "prin": "RON"
        }
    },
    "meta": {
        "sursa": "Banca Naţională a României",
        "curs": "incrucisat",
        "rotunjire": "2 zecimale, jumătate în sus. `suma_convertita_exacta` e nerotunjită — foloseşte-o dacă rezultatul intră într-un alt calcul.",
        "avertisment": "Curs încrucişat, calculat prin leu. BNR nu publică direct paritatea între două valute străine, deci cifra NU e un curs oficial BNR. Pentru parităţi publicate direct, sursa e BCE.",
        "nota": "Cotaţie 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.
404negasitnegasit = valută necunoscută; delistata = una dintre valute nu mai e cotată.
409conflictcotatii_din_zile_diferite = cele două valute nu au cotaţie în aceeaşi zi.
422validarenu_e_incrucisata = una dintre valute e leul, foloseşte /conversie. valute_identice = ambele laturi sunt aceeaşi valută.
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": "nu_e_incrucisata = una dintre valute e leul, foloseşte /conversie. valute_identice = ambele laturi sunt aceeaşi valută.",
        "detalii": {
            "suma": [
                "Valoarea trimisă nu respectă regula parametrului."
            ]
        }
    }
}