oneapi
Sign in
Financiar v1 / Curs

Exchange rate for one currency

The quotation of a single currency on the requested day — ?data= is required. If that day has no publication (weekend, holiday, the morning of a banking day), valoare is empty and the last preceding quote comes back in ultima, with its own date. Anyone who needs strictly the requested day just reads valoare.

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

Path parameters

NameTypeDescriptionExample
valutarequired string ISO 4217 currency code (EUR, USD, XAU…).

Query parameters

NameTypeDescriptionAccepted values
datarequired string Required: the day, YYYY-MM-DD. Cannot be in the future. The central bank does not publish on weekends and holidays — then valoare is empty and the applicable quote comes in ultima. e.g. 2024-06-14e.g. 2024-06-16

How it behaves

  • ?data= is required, and the response always has the same shape: data (the day you asked for), valoare (filled ONLY if we have that exact day) and ultima (the last day published on or before it, with its value). valoare stays empty DELIBERATELY when the requested day has no publication — a figure from another day sits separately, under ultima, so it cannot be used by mistake in a calculation. Missing data is no longer an error: the response is 200, and comparing data with ultima.data tells you everything.
  • The quote of a single currency on the requested day. ?data= is required — there is no implicit day, because „today" and „the last day we hold" are two different things, and conflating them served stale quotes as if they were the day's own.
  • The same mechanism covers both cases where the requested day has no quote: a non-publication day (Sunday → Friday, exactly the NBR rule) and an import that is behind (today → the last day ingested). The difference is read from ultima.data, with no extra field.
  • Anyone who strictly needs the requested day simply reads valoare: it is empty unless the day is an exact match, so no parameter is needed to enforce it.
  • There is no age ceiling. The route REPORTS what exists, and how old the figure is can be read from ultima.data — a ceiling would have turned an import delay into "does not exist", which would be false. The dangerous case it used to guard against is handled by the shape itself: a delisted currency returns valoare: null, never a years-old quote dressed up as the applicable rate.
  • Coverage in new lei starts on 2005-01-03. Earlier dates belong to the ROL era and are requested separately; the request returns 404 with in_afara_acoperirii.
  • Future dates are refused with 422: NBR publishes the rate on the day itself, not in advance.
  • Missing data is not an error: the response is 200. A 404 is left only for a currency the central bank has never quoted, and a 422 for a date that is missing or malformed.

What it is for

  • Converting an invoice amount at today's rate.
  • Showing a single rate in a widget, without pulling the whole list.
  • A quick rate check before an outbound payment.
  • Converting a foreign-currency invoice at the rate of the invoice date.
  • Reconstructing a historical rate for reporting or litigation.

Response structure

FieldTypeDescription
data.data string The day the returned quote comes from.
data.valoare.valuta string ISO 4217 currency code.
data.valoare.moneda_baza string The currency the quote is expressed in. Always RON on this route.
data.valoare.valoare string The quote for the requested day: valoare, multiplicator, valoare_unitara. null if that day has no publication.
data.valoare.multiplicator integer Factor the value is multiplied by to reach the base unit.
data.valoare.valoare_unitara string The value per single unit.
data.ultima object The last day published on or before data, with its quote: {data, valoare}. null only if nothing exists before the requested day. When the requested day does have a publication, ultima.data equals data — the duplication is intentional, so you always compare the same two fields.
data.ultima.data string
data.ultima.valoare.valuta string ISO 4217 currency code.
data.ultima.valoare.moneda_baza string
data.ultima.valoare.valoare string The quote for the requested day: valoare, multiplicator, valoare_unitara. null if that day has no publication.
data.ultima.valoare.multiplicator integer Factor the value is multiplied by to reach the base unit.
data.ultima.valoare.valoare_unitara string The value per single unit.
meta.sursa string The official source the data comes from, with its licence where one is required.
meta.nota string A note on how to read the response — a pitfall, a convention or a limit of the source.

Response examples

GEThttps://oneapi.ro/api/financiar/v1/curs/EUR?data=2024-06-14
{
    "data": {
        "data": "2024-06-14",
        "valoare": {
            "valuta": "EUR",
            "moneda_baza": "RON",
            "valoare": "4.9771",
            "multiplicator": 1,
            "valoare_unitara": "4.9771"
        },
        "ultima": {
            "data": "2024-06-14",
            "valoare": {
                "valuta": "EUR",
                "moneda_baza": "RON",
                "valoare": "4.9771",
                "multiplicator": 1,
                "valoare_unitara": "4.9771"
            }
        }
    },
    "meta": {
        "sursa": "Banca Naţională a României",
        "nota": "Valoare publicată în ziua cerută."
    }
}

Error codes

CodeSlugWhen it occurs
401neautentificatToken missing, invalid, expired or revoked.
403feature_indisponibilThe current plan does not include the feature the route depends on.
404negasitThe currency was never quoted by the NBR. The nomenclature is at /financiar/v1/valute.
422validareA currency code that is not 3 letters, or a malformed or future date.
429cota_depasitaThe plan's monthly quota has been exceeded (see Retry-After).

All errors share the same shape. eroare.cod is stable and is the value you should branch on in code — not the text in mesaj, which may change.

{
    "eroare": {
        "cod": "validare",
        "mesaj": "A currency code that is not 3 letters, or a malformed or future date.",
        "detalii": {
            "valuta": [
                "The value sent does not satisfy the parameter rule."
            ]
        }
    }
}