oneapi
Autentificare
Financiar v1 / Calcul

Diferenţe de curs

Câştigul sau pierderea din curs pe o sumă în valută, între două date, la cursul oficial BNR.

Aceeaşi mişcare de curs dă rezultate opuse după ce ai. Pe 100.000 EUR, între ianuarie 2025 şi
august 2026, cursul a urcat cu 0,2786 lei — 27.860 lei. La o creanţă e câştig: încasezi mai
mulţi lei. La o datorie e pierdere: plăteşti mai mulţi. Cifra e identică, semnul e invers.

De aceea pozitie e obligatorie, fără valoare implicită: o implicită ar face tăcut greşită
jumătate dintre răspunsuri.

Cotaţiile urmează regulile de la /curs: ziua fără publicare primeşte ultima cotaţie
anterioară, marcată cu exact: false şi zile_inapoi. Aceeaşi zi la ambele capete dă diferenţă
zero, nu eroare — cine rulează un raport pe o listă de facturi nu trebuie să trateze cazul separat.

cont_orientativ dă contul din planul general (765 favorabile, 665 nefavorabile). E orientativ:
încadrarea ţine de politica contabilă şi de natura operaţiunii, nu de datele noastre.

GET
https://oneapi.ro/api/financiar/v1/calcul/diferente-curs

Parametri de interogare

NumeTipDescriereValori acceptate
sumaobligatoriu string Obligatoriu. Suma în valută, cel mult 6 zecimale. ex. 1000ex. 2500.75ex. 10000
valutaobligatoriu string Obligatoriu. Cod de 3 litere (EUR, USD). max 3 car.
pozitieobligatoriu string Obligatoriu: creanta (ai de încasat) sau datorie (ai de plătit). Nu are implicit. creantadatorie
de_laobligatoriu string Obligatoriu, YYYY-MM-DD. Data iniţială — tipic data facturii. ex. 2024-06-15ex. 2024-01-15
pana_laobligatoriu string Obligatoriu, YYYY-MM-DD. Data finală — tipic data încasării sau plăţii. Poate fi egală cu de_la. ex. 2024-06-15ex. 2024-06-14

Cum se comportă

  • Câştigul sau pierderea din curs pe o sumă în valută, între două date, la cursul oficial BNR.
  • Aceeaşi mişcare de curs dă rezultate OPUSE după ce ai. Pe 100.000 EUR, între ianuarie 2025 şi august 2026, cursul a urcat cu 0,2786 lei — 27.860 lei. La o creanţă e câştig: încasezi mai mulţi lei. La o datorie e pierdere: plăteşti mai mulţi. Cifra e identică, semnul e invers, iar aici se greşeşte cel mai des.
  • pozitie e obligatorie, fără valoare implicită. Un implicit ar face tăcut greşită jumătate dintre răspunsuri, iar greşeala n-ar sări în ochi: cifra ar fi corectă ca mărime. Aceeaşi decizie ca la tip de la /termen/civil, unde lipsa unui implicit e deliberată fiindcă alegerea schimbă rezultatul.
  • diferenta.valoare e cifra CONTABILĂ, cu semnul potrivit poziţiei. diferenta.variatie_valoare_lei e simpla variaţie a valorii în lei, aceeaşi indiferent de poziţie — ambele sunt în răspuns tocmai ca relaţia dintre ele să fie vizibilă.
  • Cotaţiile urmează regulile de la /curs: ziua fără publicare primeşte ultima cotaţie anterioară, marcată cu exact: false şi zile_inapoi, la fiecare capăt separat. Nu se inventează cotaţii şi nu se ascunde substituirea.
  • Aceeaşi zi la ambele capete dă diferenţă zero, nu eroare. Cine rulează un raport peste o listă de facturi nu trebuie să trateze cazul separat. Felul e atunci neutra, iar contul lipseşte.
  • cont_orientativ dă contul din planul general (OMFP 1802/2014): 765 pentru diferenţe favorabile, 665 pentru nefavorabile. E orientativ, şi e marcat ca atare: încadrarea ţine de politica contabilă şi de natura operaţiunii — decontare sau reevaluare — nu de datele noastre.
  • Nu tratează plăţi parţiale sau decontări eşalonate: o sumă, două date. Un flux de plăţi e altă întrebare, cu altă formă de răspuns.
  • Pentru reevaluarea unui SOLD la închiderea perioadei se foloseşte cursul de închidere, nu cel al unei zile oarecare: /curs-inchidere?luna=AAAA-LL.

La ce folosește

  • Diferenţa de curs la încasarea unei facturi emise în valută.
  • Diferenţa la plata unei datorii în valută.
  • Verificarea semnului într-un calcul făcut de altcineva.

Structura răspunsului

CâmpTipDescriere
data.suma string Suma valorilor, în unitatea indicată alături.
data.valuta string Codul ISO 4217 al valutei.
data.pozitie string Poziţia elementului în ordinea răspunsului.
data.initial.data_ceruta string Data cerută de client, înainte de alinierea la o zi cu date.
data.initial.data_cotatiei string
data.initial.exact boolean false când ziua cerută n-a avut publicare şi s-a folosit una anterioară.
data.initial.zile_inapoi integer
data.initial.curs string Cursul folosit la prima dată, RON pentru o unitate.
data.initial.valoare_lei string
data.final.data_ceruta string Data cerută de client, înainte de alinierea la o zi cu date.
data.final.data_cotatiei string
data.final.exact boolean
data.final.zile_inapoi integer
data.final.curs string
data.final.valoare_lei string Valoarea sumei în lei la a doua dată.
data.miscare_curs.lei_pe_unitate string Cât s-a mişcat cursul, în lei pe unitate de valută.
data.miscare_curs.procent string Aceeaşi mişcare, în procente.
data.diferenta.valoare string Diferenţa contabilă, cu semnul dat de poziţie.
data.diferenta.valoare_exacta string
data.diferenta.fel string favorabila, nefavorabila sau neutra.
data.diferenta.variatie_valoare_lei string Variaţia brută a valorii în lei, fără semnul poziţiei.
data.diferenta.cont_orientativ null 765 sau 665. Orientativ — vezi nota.
meta.sursa string Sursa oficială din care vin datele, cu licenţa ei acolo unde e cerută.
meta.nota_pozitie string Precizare despre cum se citeşte răspunsul: o capcană, o convenţie sau o limită a sursei.
meta.nota_substituire string Când şi cu ce s-a înlocuit o valoare lipsă.
meta.reevaluare string
meta.fara_date data e null, iar aici stă motivul. Cotaţia există la BNR, dar importul nostru e în urmă. Data cerută e anterioară lui 2005-01-03, unde cotaţiile sunt în lei vechi.
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/calcul/diferente-curs?suma=1000&valuta=EUR&pozitie=creanta&de_la=2024-06-15&pana_la=2024-06-15
{
    "data": {
        "suma": "1000",
        "valuta": "EUR",
        "pozitie": "creanta",
        "initial": {
            "data_ceruta": "2024-06-15",
            "data_cotatiei": "2024-06-14",
            "exact": false,
            "zile_inapoi": 1,
            "curs": "4.9771",
            "valoare_lei": "4977.10"
        },
        "final": {
            "data_ceruta": "2024-06-15",
            "data_cotatiei": "2024-06-14",
            "exact": false,
            "zile_inapoi": 1,
            "curs": "4.9771",
            "valoare_lei": "4977.10"
        },
        "miscare_curs": {
            "lei_pe_unitate": "0",
            "procent": "0.00"
        },
        "diferenta": {
            "valoare": "0.00",
            "valoare_exacta": "0",
            "fel": "neutra",
            "variatie_valoare_lei": "0.00",
            "cont_orientativ": null
        }
    },
    "meta": {
        "sursa": "BNR — cursul de referinţă.",
        "nota_pozitie": "Cursul nu s-a mişcat între cele două date: diferenţa e zero, indiferent de poziţie.",
        "nota_substituire": "Cel puţin una dintre zile n-a avut publicare; s-a folosit ultima cotaţie anterioară. Vezi `exact` şi `zile_inapoi` la fiecare capăt.",
        "reevaluare": "Pentru reevaluarea unui sold la închiderea perioadei se foloseşte cursul de închidere: /financiar/v1/curs-inchidere?luna=AAAA-LL."
    }
}

Coduri de eroare

CodSlugCând apare
401neautentificatToken lipsă, invalid, expirat sau revocat.
403feature_indisponibilPlanul curent nu include funcţia de care ţine ruta.
404negasitValuta n-a fost cotată niciodată; delistata — nu mai e cotată, cu ultima zi.
422validarepozitie lipsă sau invalidă; sumă, valută ori date malformate; dată în viitor; pana_la înainte de de_la.
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": "pozitie lipsă sau invalidă; sumă, valută ori date malformate; dată în viitor; pana_la înainte de de_la.",
        "detalii": {
            "suma": [
                "Valoarea trimisă nu respectă regula parametrului."
            ]
        }
    }
}