---
title: "Simulador de Compra do Veículo dos Sonhos"
method: POST
path: "/api/v1/calc/planejamento-compra-veiculo"
tags: ["calc", "veiculos"]
---

# Simulador de Compra do Veículo dos Sonhos

`POST /api/v1/calc/planejamento-compra-veiculo`

## Request

- Base URL: `https://api.calculas.com.br`
- URL: `https://api.calculas.com.br/api/v1/calc/planejamento-compra-veiculo`
- Auth: HTTP bearer

Simule o custo completo de comprar um veículo: parcela CDC ou consórcio, IPVA por estado, seguro estimado, depreciação e custo total de propriedade em 5 anos.

## Request body

- object
  - `valorVeiculoCents` integer, required: Valor do veículo em centavos. Ex: R$ 80.000 → 8000000
  - `custosTransacao` object[]: Custos de transação obrigatórios na aquisição (one-shot), agrupados por categoria: dpvat, licenciamento, emplacamento, taxa_cadastro_financiamento, seguro_prestamista, transferencia_propriedade, outro. Cada item: { categoria, valorCents, descricao? }. Somam ao valor total de aquisição. Padrão [].
    - `categoria` 'dpvat' | 'licenciamento' | 'emplacamento' | 'taxa_cadastro_financiamento' | 'seguro_prestamista' | 'transferencia_propriedade' | '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.
  - `percentualEntrada` number, required: Percentual de entrada (%). Ex: 30 = 30%
  - `prazoMeses` integer, required: Prazo do financiamento em meses. Ex: 48 = 4 anos
  - `taxaJurosAnualBps` integer, required: Taxa de juros anual em basis points. Ex: 1850 = 18,5% ao ano (CDC típico em 2026)
  - `modalidade` 'cdc' | 'consorcio', required: "cdc" = Crédito Direto ao Consumidor (financiamento bancário com juros), "consorcio" = sem juros com taxa de administração
  - `taxaAdminConsorcio` number: Taxa de administração total do consórcio (%). Ex: 20 = 20% diluídos ao longo do prazo
  - `estadoUf` 'AC' | 'AL' | 'AP' | 'AM' | 'BA' | 'CE' | 'DF' | 'ES' | 'GO' | 'MA' | 'MT' | 'MS' | 'MG' | 'PA' | 'PB' | 'PR' | 'PE' | 'PI' | 'RJ' | 'RN' | 'RS' | 'RO' | 'RR' | 'SC' | 'SP' | 'SE' | 'TO', required: Estado de emplacamento do veículo. Usado para calcular o IPVA anual (alíquota varia por UF).
  - `anoFabricacaoVeiculo` integer, required: Ano de fabricação do veículo. Afeta a depreciação estimada no custo total de propriedade.
  - `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)