Documentație API v1 pentru cursul BNR

---

Prezentare

API-ul returnează cursurile de schimb oficiale publicate de Banca Națională a României (BNR), în lei (RON), pentru ultima zi sau pentru orice dată din trecut, în format JSON. Este gratuit și public; nu este nevoie de cheie de acces.

Versiunea 1 înlocuiește /api/json.php, care continuă să fie funcțională. Diferențele pt fi găsite în secțiunea Trecerea de la json.php.

Adresa de bază

https://www.cursbnr.ro/api/v1

Toate endpoint-urile folosesc metoda GET. Răspunsurile sunt în format JSON (UTF-8), cu excepția cazului în care ceri text simplu cu format=text. Cererile din browser de pe alte site-uri sunt permise (Access-Control-Allow-Origin: *).

Endpoint-uri

Parametri pentru /rates

Răspunsul

Răspunsul are aceeași structură, fie că ceri o valută, fie mai multe:

{
  "date": "2026-10-16",
  "requested_date": "2026-10-18",
  "quote": "RON",
  "rates": {
    "EUR": 5.3368,
    "USD": 4.743
  }
}

Valute cotate la 100 de unități. BNR cotează HUF, JPY, KRW, IDR și ISK la 100 de unități. Poți cere oricare dintre forme:

• 100HUF (la fel 100JPY, 100KRW, 100IDR, 100ISK) returnează cursul BNR pentru 100 de unități: "100HUF": 1.4695 înseamnă că 100 de forinți valorează 1,4695 lei.
• HUF (la fel JPY, KRW, IDR, ISK) returnează cursul pentru o unitate, adică cursul BNR împărțit la 100: "HUF": 0.014695.

Cheia din rates este codul pe care l-ai cerut, așa că currency=HUF,100HUF le returnează pe amândouă.

Valute acceptate

EUR, USD, XAU (aur, la gram), AUD, CAD, CHF, CZK, DKK, EGP, GBP, 100HUF, 100JPY, MDL, NOK, PLN, SEK, TRY, XDR, RUB, BGN, SKK, ZAR, BRL, CNY, INR, 100KRW, MXN, NZD, RSD, UAH, AED, THB, HKD, 100IDR, ILS, 100ISK, MYR, PHP, SGD, plus codurile pentru o unitate HUF, JPY, KRW, IDR și ISK.

Aceeași listă este returnată de /api/v1/currencies, împreună cu numărul de unități la care este cotat fiecare cod:

{
  "quote": "RON",
  "currencies": [
    { "code": "EUR", "units": 1 },
    { "code": "100HUF", "units": 100 },
    { "code": "HUF", "units": 1 },
    ...
  ]
}

Exemple

Cel mai recent curs al euro

GET https://www.cursbnr.ro/api/v1/rates

{"date": "2026-10-16", "quote": "RON", "rates": {"EUR": 5.3368}}

Mai multe valute

GET https://www.cursbnr.ro/api/v1/rates?currency=EUR,USD,100HUF

{"date": "2026-10-16", "quote": "RON", "rates": {"EUR": 5.3368, "USD": 4.743, "100HUF": 1.4695}}

Toate valutele

GET https://www.cursbnr.ro/api/v1/rates?all

{"date": "2026-10-16", "quote": "RON", "rates": {"EUR": 5.3368, "USD": 4.743, …}}

Funcționează și cu o dată: /api/v1/rates/2026-10-16?all.

O zi fără cursuri (duminică)

GET https://www.cursbnr.ro/api/v1/rates/2026-10-18?currency=USD

{"date": "2026-10-16", "requested_date": "2026-10-18", "quote": "RON", "rates": {"USD": 4.743}}

Forintul la o unitate și la 100 de unități

GET https://www.cursbnr.ro/api/v1/rates?currency=HUF,100HUF

{"date": "2026-10-16", "quote": "RON", "rates": {"HUF": 0.014695, "100HUF": 1.4695}}

Doar valoarea, ca text simplu

GET https://www.cursbnr.ro/api/v1/rates?currency=USD&format=text

4.743

PHP

$json = file_get_contents('https://www.cursbnr.ro/api/v1/rates?currency=EUR,USD');
$data = json_decode($json, true);
echo $data['rates']['EUR'];

JavaScript

const res = await fetch('https://www.cursbnr.ro/api/v1/rates?currency=EUR,USD');
const data = await res.json();
console.log(data.rates.EUR);

Erori

Erorile folosesc codurile de stare HTTP standard, iar corpul răspunsului este un JSON cu un code ușor de verificat din program și un mesaj message (în engleză):

{
  "error": {
    "code": "invalid_currency",
    "message": "Unknown currency code: XYZ. See /api/v1/currencies for the supported codes."
  }
}

Limita de cereri

Fiecare adresă IP poate face 30 de cereri pe minut. Fiecare răspuns include aceste headere:

• X-RateLimit-Limit: numărul de cereri permise pe minut (30)
• X-RateLimit-Remaining: câte cereri mai rămân în minutul curent
• X-RateLimit-Reset: momentul în care se termină minutul curent, ca timestamp Unix

Peste limită, API-ul răspunde cu HTTP 429 și cu headerul Retry-After, care arată câte secunde trebuie să aștepți. BNR publică cursuri noi o dată pe zi lucrătoare, în jurul orei 13:00 (ora României), așa că rareori are sens să ceri cele mai recente cursuri mai des de câteva minute.

Cache

Răspunsurile conțin headere de cache, astfel încât browserele și clienții HTTP le pot refolosi:

• Cursurile pentru o dată din trecut nu se mai schimbă și pot fi păstrate în cache până la un an.
• Cele mai recente cursuri pot fi păstrate în cache 10 minute.
• Fiecare răspuns are un ETag; trimite-l înapoi în If-None-Match, iar API-ul răspunde cu 304 Not Modified dacă nu s-a schimbat nimic.

Trecerea de la json.php

Ultima actualizare: 21 octombrie 2026