Analize curs valutar BNR

API Convertesc: cursul curent vs cursul istoric, `strict_date` și revenirea la ultima zi disponibilă

Publicat pe | Actualizat pe

Ilustrație conceptuală pentru API-ul de curs curent și curs istoric

Context

După lansarea API-ului public Convertesc.ro, întrebarea cea mai frecventă de la integratori a fost simplă: „Când folosesc latest și când folosesc historical?”. Răspunsul nu ține doar de preferință, ci de natura produsului pe care îl construiești. Dacă ai nevoie de stare curentă pentru ecrane operative, latest este opțiunea naturală. Dacă ai nevoie de reproducibilitate pe o dată fixă, historical devine obligatoriu.

În practică, multe aplicații au nevoie de ambele: un tablou de bord pentru ziua curentă și rapoarte refăcute exact pentru perioade trecute. De aceea este important ca integrarea să trateze explicit scenariile fără publicare nouă în calendar. Parametrul strict_date există tocmai pentru a transforma această alegere într-o regulă declarată, nu într-un efect secundar ascuns.

Pe 24 aprilie 2026, contractul API v1 clarifică aceste comportamente și oferă semnale utile (requested_date, fallback_applied) pentru trasabilitate. Dacă această semnificație este respectată în aplicația care consumă API-ul, integrarea devine robustă și ușor de întreținut.

Cum funcționează

Endpoint-ul GET /api/v1/latest livrează cele mai noi rate disponibile din sistem. Este ideal pentru componente care trebuie să afișeze rapid situația actuală, fără control fin pe data exactă. În general, îl folosești în ecrane de ansamblu, module compacte sau verificări automate în care interesul principal este recența.

Endpoint-ul GET /api/v1/historical/{date} primește o dată țintă. Dacă data are valori, le returnează. Dacă data nu are valori și strict_date nu este activ, endpoint-ul poate reveni la ultima zi disponibilă anterioară. Când se întâmplă asta, răspunsul păstrează contextul astfel încât aplicația care îl consumă să știe exact ce s-a întâmplat.

strict_date=1 schimbă contractul într-un mod util pentru audit: dacă data cerută nu are rate, primești un răspuns explicit de eroare în locul revenirii la o zi anterioară. Alegerea între cele două moduri trebuie făcută la nivel de scenariu, nu global. De exemplu, pentru afișare în aplicație, revenirea la ultima zi disponibilă este adesea preferabilă. Pentru o reconciliere legală pe o anumită dată, modul strict poate fi mai corect.

Ca structură de integrare, recomandarea este să izolezi această logică într-un strat intern clar, astfel încât aplicația de business să consume o interfață stabilă și să nu repete aceiași parametri în mai multe module.

Exemplu practic

Flux mixt pentru o aplicație de raportare:

  1. pentru tabloul de bord curent: latest;
  2. pentru export pe dată selectată: historical;
  3. pentru audit: historical cu strict_date=1.

Cerere pentru latest:

curl "https://convertesc.ro/api/v1/latest?base=EUR&symbols=RON,USD"

Cerere pentru historical, cu revenire automată la ultima zi disponibilă:

curl "https://convertesc.ro/api/v1/historical/2026-03-15?base=EUR&symbols=RON"

Cerere pentru historical, în mod strict:

curl "https://convertesc.ro/api/v1/historical/2026-03-15?base=EUR&symbols=RON&strict_date=1"

Modelul recomandat în aplicația care consumă API-ul este acesta: tratezi răspunsul obținut prin revenire la o zi anterioară ca rezultat valid, dar îl marchezi clar în interfață și în jurnale. Pentru modul strict, tratezi răspunsul ca pe o eroare reală ce trebuie rezolvată de fluxul de business, de exemplu prin alegerea altei date. În acest fel, nu amesteci politici diferite în același ecran.

Dacă ai nevoie de o listă paginată a datelor disponibile pentru selector, continuă cu articolul despre paginarea cu cursor pe /dates. Pentru comportamentul din interfață atunci când lipsește o zi de publicare, vezi articolul despre zilele fără curs BNR.

Greșeli frecvente

Prima greșeală este folosirea latest în rapoarte care trebuie reproduse exact ulterior. Astfel de rapoarte devin instabile prin definiție, pentru că „latest” se schimbă în timp. Regula corectă: orice artefact care trebuie refăcut identic are nevoie de dată explicită.

A doua greșeală este ignorarea câmpurilor de context din historical. Dacă aplicația citește doar rates și ignoră requested_date sau fallback_applied, pierde exact informația care explică de ce rezultatul nu este pe data cerută inițial.

A treia greșeală este aplicarea lui strict_date=1 peste tot, fără diferențiere pe scenarii. În medii operaționale, asta produce multe erori evitabile în weekend și sărbători. E mai sănătos să activezi modul strict doar acolo unde există obligația de exactitate pe data calendaristică.

A patra greșeală este lipsa unei strategii de reluare și observabilitate. Dacă integrarea nu monitorizează endpoint-ul de stare și nu notează codurile de eroare, echipa reacționează târziu la incidente. Articolul despre verificările de stare și alerte acoperă partea operațională.

Pentru acoperire completă în integrare, combină acest ghid cu api curs valutar cu fallback weekend, cu bnr api cursor pagination dates și cu bnr api health endpoint.

Concluzie

latest și historical nu concurează, ci se completează. Primul optimizează recența, al doilea optimizează reproducibilitatea. strict_date completează modelul printr-o alegere explicită între continuitate și exactitate strictă. O integrare matură folosește toate trei mecanismele, dar în locul corect din flux.

Dacă implementezi această separare în stratul tău intern de integrare, vei avea mai puține erori de interpretare și o trasabilitate mai bună în producție. Pentru pașii următori, recomand să implementezi selectorul de date cu paginare cu cursor și să pui în producție monitorizare automată pe endpoint-ul de stare.