Curs BNR API: preluarea automata a cursului valutar in Zoho Books si Zoho CRM

Prin curs bnr api se intelege, in practica, orice mecanism prin care o aplicatie preia automat cursul de schimb publicat de Banca Nationala a Romaniei, fara ca cineva sa il copieze manual de pe o pagina web. Pentru o firma care factureaza in euro sau in dolari din Zoho Books ori care tine oferte in valuta in Zoho CRM, diferenta dintre un curs introdus manual si unul preluat automat se vede in fiecare document.

Copierea manuala aduce trei riscuri clare: cursul unei alte zile, moneda gresita si o valoare tastata cu o cifra lipsa sau inversata. Niciunul nu este spectaculos, dar toate se acumuleaza in rapoarte, in reconcilieri si in discutiile cu clientii care verifica facturile.

Sursa oficiala nu este un API cu parametri si autentificare, ci un set de fisiere XML publicate la adrese fixe. Exista si servicii terte care transforma aceste date intr-o interfata JSON. Mai jos gasiti ce surse aveti, ce conditii tehnice impun, ce valoare are cursul publicat si cum il puteti aduce in sistemele Zoho intr-un mod care rezista in timp.

BNR publica cursurile pietei valutare in format XML pe un server dedicat, curs.bnr.ro. Pentru integrare conteaza trei tipuri de fisiere, fiecare cu alt rol.

• Ultima cotatie: https://curs.bnr.ro/nbrfxrates.xml. Este fisierul pe care il citeste o sincronizare zilnica.
• Ultimele 10 inregistrari: https://curs.bnr.ro/nbrfxrates10days.xml. Util cand un proces a ratat cateva zile si trebuie sa recupereze.
• Fisiere anuale: de exemplu https://curs.bnr.ro/files/xml/years/nbrfxrates2026.xml, cu variante analoage pentru anii anteriori. Acestea servesc la incarcarea istoricului.

Avantajul principal este ca sursa este chiar emitentul. Nu depindeti de un intermediar care poate schimba conditiile sau poate intarzia publicarea. Dezavantajul este ca trebuie sa construiti partea care citeste XML-ul, extrage moneda dorita si o transforma intr-o valoare numerica.

BNR face doua recomandari care conteaza la proiectare. Prima: evitati preluarea automata din paginile site-ului, pentru ca structura acestora se poate modifica fara preaviz, si folositi fisierele XML. A doua: stocati local informatiile preluate, la nivelul aplicatiei, pentru a evita traficul redundant. Cu alte cuvinte, cititi cursul o data pe zi si refolositi-l, nu il cereti la fiecare factura.

Datele se actualizeaza in timp real, imediat dupa ora 13:00, in fiecare zi bancara. Aceasta fraza scurta din documentatia BNR determina aproape toata logica unei integrari corecte.

Ce inseamna ora 13:00 pentru programare

Daca programati preluarea la 9 dimineata, veti citi cotatia zilei bancare anterioare. Pentru facturile cu TVA la care se foloseste cursul BNR, normele de aplicare a Codului fiscal precizeaza ca ultimul curs comunicat este cel comunicat in ziua anterioara si valabil pentru operatiunile din ziua urmatoare, deci cotatia publicata azi dupa ora 13:00 se aplica operatiunilor cu data exigibilitatii incepand de maine, pana la urmatoarea publicare; pentru oferte si alte documente fara efect fiscal, regula se stabileste impreuna cu contabilitatea. O preluare programata dupa ora 13:00, cu o a doua incercare mai tarziu in cazul unei erori de retea, acopera majoritatea situatiilor.

Zilele fara cotatie

In zilele care nu sunt bancare nu apare o cotatie noua. Integrarea trebuie sa stie ce face atunci: pastreaza ultima valoare disponibila si inregistreaza data la care a fost publicata. Salvati intotdeauna, langa curs, data din fisier, nu data la care a rulat procesul, astfel incat un utilizator sa vada exact carei cotatii ii corespunde suma in lei.

Fisierul cu ultimele 10 inregistrari ajuta aici. Daca procesul a fost oprit cateva zile, il poate folosi pentru a completa golurile fara interventie manuala.

Accesul la fisierele XML se face securizat, prin protocolul https, pe portul 443. BNR precizeaza ca aplicatiile care colecteaza automat cursul trebuie sa implementeze criptare prin protocolul TLS1.2 si anumite Cipher Suites, printre care TLS_ECDHE_RSA_WITH_AES_128_GCM_SHA256.

Pentru o aplicatie moderna aceasta cerinta este de obicei indeplinita implicit. Problemele apar la scripturi vechi, la servere interne neactualizate sau la instrumente de automatizare configurate cu ani in urma. Daca o sincronizare care a functionat mult timp se opreste brusc cu o eroare de conexiune, verificarea configuratiei TLS este unul dintre primii pasi.

Validarea structurii

Fisierele de curs sunt generate conform schemei https://curs.bnr.ro/xsd/nbrfxrates.xsd. Schema va spune ce elemente si atribute sa asteptati, deci puteti scrie un cititor care nu ghiceste structura din exemple. Recomandarea practica este sa validati fisierul inainte de a scrie orice valoare in Zoho.

Daca validarea esueaza, procesul se opreste si trimite o alerta, in loc sa salveze un curs gol sau zero pe care cineva il descopera abia la inchiderea lunii. Aceste trei elemente, https, TLS si schema, sunt suficiente pentru o integrare directa robusta, fara intermediari.

Daca nu doriti sa procesati XML, exista servicii care expun cursul BNR printr-o interfata mai simpla. CursBnr.ro descrie un API care furnizeaza un obiect JSON cu data si valorile valutare solicitate de client. Data si valuta se transmit ca parametri GET, iar API-ul verifica daca data este in formatul YYYY-MM-DD si daca valuta este valida.

Pentru un dezvoltator, JSON cu parametri este mai comod decat un fisier XML complet. Puteti cere direct cursul pentru o anumita zi si o anumita moneda, ceea ce simplifica recalcularea documentelor istorice.

Ce trebuie cantarit

• Accesul: potrivit paginii, accesul la API se obtine prin contactarea serviciului prin formularul de contact. Nu este un acces instant, iar conditiile se stabilesc cu furnizorul.
• Dependenta: introduceti un intermediar intre dumneavoastra si sursa oficiala. Daca serviciul intarzie sau isi schimba formatul, integrarea se opreste.
• Trasabilitatea: pentru audit este mai simplu sa aratati ca valoarea provine direct din fisierul BNR.

Acelasi serviciu ofera si un script de afisare, inserat printr-un iframe, la care puteti modifica latimea modulului, culorile textelor si detaliile afisate. Este util pentru un site de prezentare, dar nu ajuta la calcule: un iframe afiseaza cursul, nu il transmite sistemului dumneavoastra.

Cele trei variante raspund unor nevoi diferite. Tabelul de mai jos rezuma diferentele relevante pentru o firma care vrea cursul in documente contabile si comerciale.

Criteriu	XML BNR	API tert (JSON)	Widget iframe
Sursa	Emitentul oficial	Intermediar care preia cursul BNR	Intermediar
Acces	Public, prin https	Prin solicitare la furnizor	Copierea codului in site
Format	XML conform schemei XSD	JSON, parametri GET	Afisare vizuala
Istoric	Ultimele 10 inregistrari si fisiere anuale	Interogare pe data	Nu se aplica
Potrivit pentru	Integrari contabile si CRM	Aplicatii care cer o valoare punctuala	Site de prezentare
Efort de dezvoltare	Parsare XML si validare	Mai redus	Minim

Pentru majoritatea firmelor care lucreaza in Zoho, recomandarea este fisierul XML oficial. Efortul suplimentar de parsare se face o singura data, iar in schimb eliminati o dependenta externa si aveti trasabilitate directa catre sursa.

API-ul tert are sens cand aveti deja o relatie cu furnizorul sau cand un instrument nu poate procesa XML. Widgetul ramane o solutie de afisare, nu de integrare.

Indiferent de sursa, structura unei integrari solide este aceeasi. O propunem in patru straturi, fiecare cu o responsabilitate clara.

1. Preluarea: o functie programata citeste zilnic, dupa ora 13:00, fisierul cu ultima cotatie, iar la nevoie fisierul cu ultimele 10 inregistrari.
2. Validarea: structura se verifica fata de schema, iar valorile se verifica pentru a nu fi goale sau zero.
3. Stocarea: cursurile se salveaza local, cu data cotatiei, intr-un tabel propriu. Aceasta respecta si recomandarea BNR privind stocarea la nivelul aplicatiei.
4. Distributia: Zoho Books si Zoho CRM citesc cursul din acest tabel, nu direct de la BNR.

Separarea stocarii de distributie inseamna ca ambele sisteme folosesc aceeasi valoare pentru aceeasi zi. O oferta din CRM si factura emisa ulterior din Books nu vor avea cursuri diferite doar pentru ca au fost calculate la ore diferite.

Alternativ, puteti folosi o extensie gata construita in locul codului propriu. Svennis a publicat cinci extensii in Zoho Marketplace, fiecare evaluata cu 5 din 5, iar la orice extensie criteriul decisiv ramane tratarea exceptiilor: zile fara cotatie, erori de retea, monede rare. Cereti sa vedeti cum sunt tratate aceste cazuri inainte de a pune integrarea in functiune.

Un aspect deseori neinteles: potrivit BNR, cursurile din Lista cursurilor medii ale pietei valutare au la baza cotatii ale societatilor bancare autorizate sa efectueze operatiuni pe piata valutara. Potrivit BNR, lista publicata nu implica, prin ea insasi, obligativitatea utilizarii cursurilor in tranzactii efective de schimb valutar. In contabilitate, insa, reglementarile contabile cer inregistrarea operatiunilor in valuta la cursul comunicat de BNR, iar pentru TVA art. 290 din Codul fiscal permite si alte optiuni; stabiliti regulile impreuna cu contabilul.

Concret, pentru TVA art. 290 din Codul fiscal permite utilizarea ultimului curs comunicat de BNR, a ultimului curs publicat de Banca Centrala Europeana sau a cursului bancii prin care se efectueaza decontarile, daca acesta este prevazut in contract, valabil la data exigibilitatii taxei; optiunea firmei se stabileste si se documenteaza impreuna cu contabilul. Integrarea tehnica nu raspunde la aceasta intrebare, ea doar executa decizia.

Ce sa stabiliti inainte de implementare

• ce curs se foloseste pentru documentele comerciale fara efect contabil, cum sunt oferta si comanda, si cum se aplica cursul comunicat de BNR la factura si incasare;
• ce data a cotatiei se aplica, tinand cont ca pentru facturile cu TVA art. 290 din Codul fiscal permite mai multe optiuni (cursul BNR, cursul BCE sau cursul bancii de decontare prevazut in contract), iar optiunea aleasa se documenteaza impreuna cu contabilul;
• cine poate modifica manual un curs si cum se documenteaza modificarea;
• ce se intampla cu documentele emise inainte de publicarea cotatiei zilei.

Aceste reguli trebuie scrise si aprobate de responsabilul financiar sau de contabil, apoi transpuse in configuratie. O integrare construita fara ele va fi corecta tehnic, dar discutabila contabil. Pentru regulile propriu-zise, consultati specialistul contabil care asista firma dumneavoastra.

Pentru majoritatea firmelor, preluarea cursului este o chestiune operationala. Pentru prestatorii de servicii de plata, orice componenta tehnica intra insa intr-un cadru reglementat. De la 17 ianuarie 2025, institutiile de credit, institutiile de plata si institutiile emitente de moneda electronica aplica Regulamentul (UE) 2022/2554 privind rezilienta operationala digitala (DORA).

Reglementarea nationala in domeniu este Regulamentul BNR nr. 2 din 30 ianuarie 2020, publicat in Monitorul Oficial nr. 115 din 14 februarie 2020, in forma sa actualizata. Pentru institutiile de credit, institutiile de plata si institutiile emitente de moneda electronica, cerintele privind riscurile TIC si contractele cu furnizorii terti decurg in principal din DORA; verificati in forma consolidata a Regulamentului BNR nr. 2/2020 care dintre prevederile sale vi se mai aplica. In textul publicat al regulamentului, prevederile legate de externalizarea unei integrari sau a unei platforme includ:

• prestatorii raman pe deplin responsabili pentru evaluarea eficacitatii masurilor de securitate ale functiilor operationale externalizate;
• contractele cu furnizorii trebuie sa includa obiective de securitate a informatiilor, inclusiv cerinte privind criptarea datelor, securitatea retelei si amplasarea centrelor de date;
• drepturile de acces la activele informationale se revizuiesc cel putin anual, iar jurnalele de acces se pastreaza pe o perioada proportionala cu nivelul critic al functiilor si activelor vizate;
• evaluarile riscurilor se efectueaza si se documenteaza cel putin anual.

Separat, Regulamentul BNR nr. 3 din 1 august 2018 privind monitorizarea infrastructurilor pietei financiare si a instrumentelor de plata se aplica si prestatorilor care emit, pun in circulatie sau accepta instrumente de plata pe teritoriul Romaniei. Daca va aflati in aceasta categorie, integrarea cursului trebuie documentata ca orice alt flux, cu jurnale, acces controlat si responsabilitati clare.

Ordinea de mai jos reduce riscul de a construi ceva corect tehnic, dar nealiniat cu nevoile contabilitatii.

1. Stabiliti regulile de curs impreuna cu contabilul: ce cotatie, pentru ce document, cu ce data.
2. Alegeti sursa. Pentru integrari contabile si CRM, fisierul XML oficial de pe curs.bnr.ro este alegerea implicita, iar API-ul unui tert are sens doar daca aveti un motiv concret.
3. Verificati mediul tehnic: acces https pe portul 443 si suport pentru TLS1.2 cu suitele cerute.
4. Programati preluarea dupa ora 13:00, cu reincercare si cu recuperare din fisierul cu ultimele 10 inregistrari.
5. Validati fata de schema XSD si blocati scrierea valorilor goale sau zero.
6. Stocati local cursul cu data cotatiei si faceti ca Zoho Books si Zoho CRM sa citeasca din aceeasi sursa interna.
7. Incarcati istoricul din fisierele anuale, daca aveti documente mai vechi de recalculat.
8. Configurati alerte pentru esecuri, astfel incat o problema sa fie observata in aceeasi zi.

Dupa punerea in functiune, comparati o saptamana la rand cursul salvat cu cel publicat de BNR, inclusiv peste un weekend. Daca sunteti prestator de servicii de plata, includeti integrarea in evaluarile de risc si in revizuirea drepturilor de acces pe care vi le cer DORA si prevederile nationale aplicabile.

• BNR: Cursurile pietei valutare in format XML
• CursBnr.ro: Preluare curs valutar
• Regulamentul BNR nr. 2 din 30 ianuarie 2020 (Portal Legislativ)
• Regulamentul BNR nr. 2 din 30 ianuarie 2020, forma detaliata (Portal Legislativ)
• Regulamentul BNR nr. 3 din 1 august 2018 (Portal Legislativ)