oneapi
Sign in
Financiar v1 / Conversie

Conversion at the customs rate

Converts an amount in foreign currency at the customs rate of the month — the figure the customs value is determined with — not at the day's rate.

Why this is not the same as /conversie. The customs rate is FIXED for the whole month: the NBR quotation from the penultimate Wednesday of the previous month (art. 146 of Implementing Regulation (EU) 2015/2447). Anyone converting at the day's rate gets the tax base wrong, and the figure looks just as convincing.

Measured across the whole coverage, for EUR: mean deviation from the day's rate 0.297%, and 5.2% of days exceed 1%, with a maximum of 3.41%. For sterling, in July 2016 — the month after the Brexit referendum — the day's rate was 5.2496 while the customs rate was 5.8918, fixed on 20 June: a 10.9% difference.

That is why the response also carries la_cursul_zilei, with the deviation computed. It is not the figure you declare — it is given so you can see how far off you would be.

One direction only: foreign currency → RON. The customs value is expressed in lei from an invoice in foreign currency; the inverse has no customs meaning.

The period is given as the declaration's data — the rule is monthly, but the declarant need not know that — or directly as an + luna.

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

Query parameters

NameTypeDescriptionAccepted values
sumarequired string Required. The invoice amount, in foreign currency. e.g. 1000
valutarequired string Required. Three-letter code. max 3 car.
dataoptional string | null The declaration date, YYYY-MM-DD. Excludes an + luna. e.g. 2024-06-15
anoptional integer | null The year of the month of application. Requires luna as well. 2016 – 2100
lunaoptional integer | null The month of application, 1–12. Requires an as well. 1 – 12

How it behaves

  • Converts a foreign-currency amount at the customs rate of the month — the figure used to determine customs value — rather than at the daily rate.
  • Why this is not the same as /conversie. The customs rate is FIXED for the whole month: the NBR quote from the second-to-last Wednesday of the previous month (art. 146 of Commission Implementing Regulation (EU) 2015/2447). Converting at the daily rate misstates the taxable base, and the figure looks just as good.
  • Measured across the whole coverage, for EUR: average deviation from the daily rate 0.297%, with 5.2% of days exceeding 1% and a maximum of 3.41%. For sterling, in July 2016 — the month after the Brexit referendum — the daily rate was 5.2496 while the customs rate was 5.8918, fixed on 20 June: on GBP 100,000 that is RON 64,220, or 12.23%.
  • la_cursul_zilei holds the wrong conversion, with the deviation computed. It is not the figure to declare — it is given so the size of the mistake is visible. It appears only when data is supplied: without it there is no day at which one could have gone wrong, and a day chosen by us would be an invented comparison.
  • One direction only: currency → RON. Customs value is expressed in lei from a foreign-currency invoice; the inverse has no customs meaning, and accepting it would suggest it does.
  • The period is given as the declaration data — the rule is monthly, but the declarant need not know that to ask the question — or directly as an + luna, for whoever already knows the month of application.
  • A future date is not an error: next month's grid is already fixed, because it is computed from the previous month. The customs rate is known before the month of application — unlike the daily rate.
  • The response carries the rule in verifiable form: the month of application, the second-to-last Wednesday, the quote day and the legal basis. meta.verificare even gives the path for checking the quote against /curs/{valuta}?data=.
  • Coverage starts in May 2016. Earlier months are refused with an explanation: until then art. 171 of Reg. 2454/93 applied, with a 5% clause that broke periods mid-month, which a monthly grid cannot express.

What it is for

  • Determining customs value on an import declaration.
  • Checking the amount declared by a customs broker.
  • Estimating customs value for next month's shipment, whose grid is already fixed.

Response structure

FieldTypeDescription
data.suma string Sum of the values, in the unit indicated alongside.
data.valuta string ISO 4217 currency code.
data.in string
data.data_declaratiei string
data.luna_aplicare string
data.curs_vamal.valoare string The value published by the source for the combination above.
data.curs_vamal.multiplicator integer Factor the value is multiplied by to reach the base unit.
data.curs_vamal.valoare_unitara string The value per single unit.
data.curs_vamal.aplicabil_de_la string
data.curs_vamal.aplicabil_pana_la string
data.curs_vamal.cotatie_din string The day the NBR quote used comes from.
data.curs_vamal.penultima_miercuri string The second-to-last Wednesday of the previous month — the art. 146 rule.
data.curs_vamal.baza_legala string
data.valoare_in_vama string The result, rounded to the cent. The figure to declare.
data.valoare_in_vama_exacta string The unrounded result, for chained calculations.
data.factor string The number the amount was multiplied by: 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 What the daily rate would give. Not to be declared.
data.la_cursul_zilei.diferenta_fata_de_vamal string The value at the daily rate minus the value at the customs rate, in lei: positive means the daily rate would inflate the customs value.
data.la_cursul_zilei.abatere_procent string How far off it would be, in percent of the value at the customs rate, with the same sign as the difference.
data.la_cursul_zilei.nota string A note on how to read the data — a pitfall, a convention or a limit of the source.
meta.sursa string The official source the data comes from, with its licence where one is required.
meta.regula string The rule by which the value was computed or chosen.
meta.verificare string Which check was run on the values in the response.
meta.contract string
meta.nota_curs_zilei string A note on how to read the response: a caveat, a convention or a limit of the source.
meta.grila_lunii string
meta.fara_date data is null and this says why. The requested month is before May 2016, or the currency has no customs rate published for it.
meta.fara_date_cod The short, STABLE word for the reason, for clients that branch on it in code: fara_date is prose and may be rephrased, this is not.

Response examples

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."
    }
}

Error codes

CodeSlugWhen it occurs
401neautentificatToken missing, invalid, expired or revoked.
403feature_indisponibilThe current plan does not include the feature the route depends on.
422validareMalformed amount or currency; missing or doubled period, or an without luna.
429cota_depasitaThe plan's monthly quota has been exceeded (see Retry-After).

All errors share the same shape. eroare.cod is stable and is the value you should branch on in code — not the text in mesaj, which may change.

{
    "eroare": {
        "cod": "validare",
        "mesaj": "Malformed amount or currency; missing or doubled period, or an without luna.",
        "detalii": {
            "suma": [
                "The value sent does not satisfy the parameter rule."
            ]
        }
    }
}