---
title: "Conversão de Moedas (BRL/USD/EUR) com IOF"
method: POST
path: "/api/v1/calc/conversao-moedas-iof"
tags: ["calc", "educacao"]
---

# Conversão de Moedas (BRL/USD/EUR) com IOF

`POST /api/v1/calc/conversao-moedas-iof`

## Request

- Base URL: `https://api.calculas.com.br`
- URL: `https://api.calculas.com.br/api/v1/calc/conversao-moedas-iof`
- Auth: HTTP bearer

Converte valor entre moedas considerando IOF (Decreto 11.998/24 cronograma 2024-2029) + spread cambial. Mostra valor recebido líquido.

## Request body

- object
  - `valorOrigemCents` integer, required: Valor em centavos a ser convertido. Ex: R$ 100,00 → 10000. Mínimo R$ 1,00; máximo R$ 1.000.000,00.
  - `moedaOrigem` 'BRL' | 'USD' | 'EUR': Moeda do valor que você quer converter. BRL = Real brasileiro, USD = Dólar americano, EUR = Euro. Padrão: BRL.
  - `moedaDestino` 'BRL' | 'USD' | 'EUR': Moeda para a qual deseja converter o valor. BRL = Real brasileiro, USD = Dólar americano, EUR = Euro. Padrão: USD.
  - `cambioBrlPorMoedaOrigem` number: Cotação em reais (BRL) por uma unidade da moeda de origem. Exemplo: se o dólar está a R$ 5,10, informe 5.10. Ignorado quando a moeda de origem é BRL. Faixa: 0,50 a 50,00.
  - `cambioBrlPorMoedaDestino` number: Cotação em reais (BRL) por uma unidade da moeda de destino. Exemplo: se o euro está a R$ 5,50, informe 5.50. Ignorado quando a moeda de destino é BRL. Faixa: 0,50 a 50,00.
  - `cambioBrlPorMoeda` number: Cotação em reais (BRL) por uma unidade da outra moeda (simplificado). Use quando apenas uma das moedas é BRL. Para conversão entre moedas estrangeiras (USD↔EUR), informe os dois câmbios separados. Faixa: 0,50 a 50,00.
  - `metodoConversao` 'pix_transferencia' | 'cartao_credito' | 'papel_moeda': Método utilizado na conversão, que define a alíquota de IOF aplicada. pix_transferencia = PIX ou transferência cambial (IOF 1,1%); cartao_credito = pagamento com cartão de crédito no exterior (IOF com cronograma de redução 2024-2029); papel_moeda = compra de moeda física em corretora (IOF 1,1%). Padrão: pix_transferencia.
  - `spreadCorretoraPercent` number: Percentual de spread cobrado pela corretora ou banco sobre o câmbio PTAX. Em porcentagem (%). Exemplo: 2 significa 2% de spread. Típico: 1-3% (fintechs), 4-7% (casas físicas). Padrão: 2.
  - `feesAdicionais` object[]: Fees adicionais sobre a operação cambial categorizados (spread_cotacao, tarifa_remessa, taxa_cartao_internacional, tarifa_corretora, iof_complementar, taxa_recepcao_destino, outro). Cada item: { categoria, valorCents, descricao? }. Valor em centavos NA MOEDA DE ORIGEM. Somam aos custos efetivos junto com IOF + spread principal. Padrão []. Use "outro" + descrição (ex: "tarifa fintech extra", "taxa cartão local").
    - `categoria` 'spread_cotacao' | 'tarifa_remessa' | 'taxa_cartao_internacional' | 'tarifa_corretora' | 'iof_complementar' | 'taxa_recepcao_destino' | 'outro', required
    - `valorCents` integer, required: Valor em centavos. Ex: R$ 200 → 20000.
    - `descricao` string: Descrição livre do item (opcional, especialmente útil quando categoria = "outro"). Máx. 60 caracteres.
  - `currentDate` string, date-time: ISO-8601 com offset. Default: tempo do servidor. Use pra reprodutibilidade / cache semantico.

## Response `200`

OK

- object
  - `ok` true, required
  - `data` object, required: Resultado dependente da calc — ver schema individual
  - `meta` object

## Other responses

- `422`: Input invalido (Zod parse falhou)
- `500`: Engine error

---

[API](https://skmtc.dev/calculas/apis/contai-api.md) · [All operations](https://skmtc.dev/calculas/apis/contai-api/llms.txt) · [OpenAPI document](https://skmtc.dev/calculas/apis/contai-api/revisions/26a00749292b?raw)