oneapi
Autentificare
Financiar v1 / Conversie

Conversie la cursul vamal

Converteşte o sumă în valută la cursul vamal al lunii — cifra cu care se determină valoarea în
vamă — nu la cursul zilei.

De ce nu e acelaşi lucru cu /conversie. Cursul vamal e FIX pe toată luna: cotaţia BNR din
penultima zi de miercuri a lunii anterioare (art. 146 din Regulamentul de punere în aplicare (UE)
2015/2447). Cine converteşte la cursul zilei greşeşte baza de impozitare, iar cifra arată la fel de
bine.

Măsurat pe toată acoperirea, pentru EUR: abatere medie faţă de cursul zilei 0,297%, iar 5,2%
din zile depăşesc 1%, cu maxim 3,41%. La lire, în iulie 2016 — luna de după referendumul Brexit —
cursul zilei era 5,2496 iar cel vamal 5,8918, fixat pe 20 iunie: 10,9% diferenţă.

De aceea răspunsul conţine şi la_cursul_zilei, cu abaterea calculată. Nu e cifra care se
declară — e dată ca să se vadă cât s-ar greşi.

Un singur sens: valută → RON. Valoarea în vamă se exprimă în lei dintr-o factură în valută;
inversul n-are înţeles vamal.

Perioada se dă ca data a declaraţiei — regula e lunară, dar declarantul nu trebuie să ştie asta —
sau direct ca an + luna.

GET
https://oneapi.ro/api/financiar/v1/conversie/vamal

Parametri de interogare

NumeTipDescriereValori acceptate
sumaobligatoriu string Obligatoriu. Suma din factură, în valută. ex. 1000
valutaobligatoriu string Obligatoriu. Cod de 3 litere. max 3 car.
dataopțional string | null Data declaraţiei, YYYY-MM-DD. Exclude an + luna. ex. 2024-06-15
anopțional integer | null Anul lunii de aplicare. Cere şi luna. 2016 – 2100
lunaopțional integer | null Luna de aplicare, 1–12. Cere şi an. 1 – 12

Cum se comportă

  • Converteşte o sumă în valută la cursul vamal al lunii — cifra cu care se determină valoarea în vamă — nu la cursul zilei.
  • De ce nu e acelaşi lucru cu /conversie. Cursul vamal e FIX pe toată luna: cotaţia BNR din penultima zi de miercuri a lunii anterioare (art. 146 din Regulamentul de punere în aplicare (UE) 2015/2447). Cine converteşte la cursul zilei greşeşte baza de impozitare, iar cifra arată la fel de bine.
  • Măsurat pe toată acoperirea, pentru EUR: abatere medie faţă de cursul zilei 0,297%, iar 5,2% din zile depăşesc 1%, cu un maxim de 3,41%. La lire, în iulie 2016 — luna de după referendumul Brexit — cursul zilei era 5,2496 iar cel vamal 5,8918, fixat pe 20 iunie: pe 100.000 GBP, 64.220 lei diferenţă, adică 12,23%.
  • la_cursul_zilei conţine conversia greşită, cu abaterea calculată. Nu e cifra care se declară — e dată ca să se vadă cât s-ar greşi. Apare doar când se dă data declaraţiei: fără ea nu există ziua la care s-ar fi putut greşi, iar o zi aleasă de noi ar fi o comparaţie inventată.
  • Un singur sens: valută → RON. Valoarea în vamă se exprimă în lei dintr-o factură în valută; inversul n-are înţeles vamal, iar acceptat ar sugera că are.
  • Perioada se dă ca data a declaraţiei — regula e lunară, dar declarantul nu trebuie să ştie asta ca să pună întrebarea — sau direct ca an + luna, pentru cine ştie deja luna de aplicare.
  • O dată în viitor nu e o eroare: grila lunii următoare e deja fixată, fiindcă se calculează din luna anterioară. Cursul vamal se ştie dinaintea lunii de aplicare — spre deosebire de cursul zilei.
  • Răspunsul cară regula verificabilă: luna de aplicare, penultima miercuri, ziua cotaţiei şi temeiul legal. meta.verificare dă chiar calea pe care se confruntă cotaţia cu /curs/{valuta}?data=.
  • Acoperirea începe în mai 2016. Lunile anterioare sunt refuzate cu explicaţie: până atunci se aplica art. 171 din Reg. 2454/93, cu o clauză de 5% care rupea perioadele la mijloc de lună, iar o grilă lunară nu o poate exprima.

La ce folosește

  • Determinarea valorii în vamă la o declaraţie de import.
  • Verificarea sumei declarate de un comisionar vamal.
  • Estimarea valorii în vamă pentru o livrare din luna viitoare, a cărei grilă e deja fixată.

Structura răspunsului

CâmpTipDescriere
data.suma string Suma valorilor, în unitatea indicată alături.
data.valuta string Codul ISO 4217 al valutei.
data.in string
data.data_declaratiei string
data.luna_aplicare string
data.curs_vamal.valoare string Valoarea publicată de sursă pentru combinaţia de mai sus.
data.curs_vamal.multiplicator integer Cu cât se înmulţeşte valoarea ca să ajungă în unitatea de bază.
data.curs_vamal.valoare_unitara string Valoarea raportată la o singură unitate.
data.curs_vamal.aplicabil_de_la string
data.curs_vamal.aplicabil_pana_la string
data.curs_vamal.cotatie_din string Ziua din care provine cotaţia BNR folosită.
data.curs_vamal.penultima_miercuri string Penultima miercuri a lunii anterioare — regula din art. 146.
data.curs_vamal.baza_legala string
data.valoare_in_vama string Rezultatul, rotunjit la doi bani. Cifra care se declară.
data.valoare_in_vama_exacta string Rezultatul nerotunjit, pentru calcule în lanţ.
data.factor string Numărul cu care s-a înmulţit suma: suma × factor = valoare_in_vama_exacta.
data.la_cursul_zilei.curs string
data.la_cursul_zilei.data_cotatiei string
data.la_cursul_zilei.exact boolean
data.la_cursul_zilei.valoare string Cât ar ieşi la cursul zilei. Nu se declară.
data.la_cursul_zilei.diferenta_fata_de_vamal string Valoarea la cursul zilei minus valoarea la cursul vamal, în lei: pozitiv înseamnă că cursul zilei ar umfla valoarea în vamă.
data.la_cursul_zilei.abatere_procent string Cu cât s-ar greşi, în procente faţă de valoarea la cursul vamal, cu acelaşi semn ca diferenţa.
data.la_cursul_zilei.nota string Precizare despre cum se citesc datele — o capcană, o convenţie sau o limită a sursei.
meta.sursa string Sursa oficială din care vin datele, cu licenţa ei acolo unde e cerută.
meta.regula string Regula după care s-a calculat sau s-a ales valoarea.
meta.verificare string Ce verificare s-a rulat pe valorile din răspuns.
meta.contract string
meta.nota_curs_zilei string Precizare despre cum se citeşte răspunsul: o capcană, o convenţie sau o limită a sursei.
meta.grila_lunii string
meta.fara_date data e null, iar aici stă motivul. Luna cerută e anterioară lui mai 2016, ori valuta n-are curs vamal publicat pentru ea.
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/conversie/vamal?suma=1000&valuta=EUR&data=2024-06-15
{
    "data": {
        "suma": "1000",
        "valuta": "EUR",
        "in": "RON",
        "data_declaratiei": "2024-06-15",
        "luna_aplicare": "2024-06",
        "curs_vamal": {
            "valoare": "4.9745",
            "multiplicator": 1,
            "valoare_unitara": "4.9745",
            "aplicabil_de_la": "2024-06-01",
            "aplicabil_pana_la": "2024-06-30",
            "cotatie_din": "2024-05-22",
            "penultima_miercuri": "2024-05-22",
            "baza_legala": "art. 146 Reg. (UE) 2015/2447"
        },
        "valoare_in_vama": "4974.50",
        "valoare_in_vama_exacta": "4974.5",
        "factor": "4.9745",
        "la_cursul_zilei": {
            "curs": "4.9771",
            "data_cotatiei": "2024-06-14",
            "exact": false,
            "valoare": "4977.10",
            "diferenta_fata_de_vamal": "2.60",
            "abatere_procent": "0.05",
            "nota": "NU e cifra care se declară. E dată ca să se vadă cât s-ar greşi folosind cursul zilei."
        }
    },
    "meta": {
        "sursa": "Derivat din cursul de referinţă BNR, după regula vamală.",
        "regula": "Cotaţia BNR din penultima zi de miercuri a lunii anterioare, fixă pe toată luna de aplicare.",
        "verificare": "Cotaţia se poate confrunta cerând /financiar/v1/curs/EUR?data=2024-05-22.",
        "contract": "suma × factor = valoare_in_vama_exacta, cifră cu cifră.",
        "nota_curs_zilei": "La cursul zilei, valoarea în vamă ar ieşi cu 2.60 lei (0.05% din valoarea la cursul vamal) mai mare decât cea corectă. `la_cursul_zilei` e dat ca avertisment, nu ca alternativă.",
        "grila_lunii": "Toate valutele lunii: /financiar/v1/curs-vamal?luna=2024-06."
    }
}

Coduri de eroare

CodSlugCând apare
401neautentificatToken lipsă, invalid, expirat sau revocat.
403feature_indisponibilPlanul curent nu include funcţia de care ţine ruta.
422validareSumă sau valută malformată; perioadă lipsă, dublă, ori an fără luna.
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": "Sumă sau valută malformată; perioadă lipsă, dublă, ori an fără luna.",
        "detalii": {
            "suma": [
                "Valoarea trimisă nu respectă regula parametrului."
            ]
        }
    }
}