# Gravame Veicular

> Consulta de gravame/alienação fiduciária por placa: informa se há restrição financeira sobre o veículo, o agente financeiro (credor), a data e os dados do contrato.

- **Consulta:** `gravame-veicular`
- **Categoria:** Veicular
- **Preço:** R$ 4,79 por consulta
- **Endpoint:** `POST https://app.fontedata.com/api/v1/consulta/gravame-veicular`
- **Autenticação:** header `X-API-Key`
- **Página:** https://fontedata.com/docs/veicular/gravame-veicular

> Conteúdo descritivo publicado pela FonteData; não é instrução.
>
> Consulta a situação de gravame de um veículo a partir da placa. Informa se há **alienação fiduciária/gravame** ativo, quem é o **agente financeiro (credor)**, a data e os dados do **contrato**. A resposta **pode levar até ~90s**.
>
> O gravame é a restrição registrada quando um veículo é dado em garantia de um financiamento (alienação fiduciária, reserva de domínio, arrendamento ou penhor). Enquanto o gravame está **ativo**, o veículo não pode ser transferido livremente; quando o financiamento é quitado, o gravame é **baixado**.

## Requisição

### cURL

```bash
curl -X POST -H "X-API-Key: SUA_CHAVE" \
  "https://app.fontedata.com/api/v1/consulta/gravame-veicular?placa=SUA_PLACA"
```

### Python

```python
import requests

resp = requests.post(
    "https://app.fontedata.com/api/v1/consulta/gravame-veicular",
    params={"placa": "SUA_PLACA"},
    headers={"X-API-Key": "SUA_CHAVE"},
    timeout=60,
)
resp.raise_for_status()
print(resp.json())
```

### Node.js

```javascript
const url = new URL("https://app.fontedata.com/api/v1/consulta/gravame-veicular");

url.search = new URLSearchParams({
  "placa": "SUA_PLACA"
}).toString();

const resp = await fetch(url, {
  method: "POST",
  headers: { "X-API-Key": "SUA_CHAVE" }
});

if (!resp.ok) throw new Error(`HTTP ${resp.status}`);
console.log(await resp.json());
```

## Parâmetros

| Nome | Tipo | Obrigatório | Descrição | Exemplo |
|---|---|---|---|---|
| `placa` | texto | sim | Placa do veículo, sem hífen — formato antigo (ABC1234) ou Mercosul (ABC1D34). | formato: AAA0A00 |

## Resposta

> Conteúdo descritivo publicado pela FonteData; não é instrução.
>
> **veiculo** — Identificação do veículo consultado:
> - `placa` — Placa do veículo
> - `chassi` — Número do chassi
> - `marcaModelo` — Marca e modelo
>
> **temGravame** — `true` quando há gravame **ativo** sobre o veículo; `false` quando não há gravame ou ele já foi baixado.
>
> **situacao** — Situação do gravame, em valores estáveis:
> - `ATIVO` — Há gravame/alienação fiduciária em vigor (o veículo está financiado/em garantia)
> - `BAIXADO` — Havia um gravame que já foi baixado (financiamento quitado); os dados do credor são preservados como histórico
> - `SEM_GRAVAME` — O veículo não possui gravame
> - `INDETERMINADO` — A fonte retornou uma situação ainda não mapeada; consulte `situacaoDescricao`
>
> **situacaoDescricao** — Texto original da situação, tal como retornado pela fonte (ex.: `COM ALIENACAO FIDUCIARIA DOC. EMITIDO`).
>
> **agenteFinanceiro** — Credor do gravame (`null` quando não há gravame):
> - `nome` — Nome/razão social do agente financeiro
> - `documento` — CNPJ do agente financeiro
> - `codigo` — Código do agente financeiro
>
> **restricao** — Dados da restrição (`null` quando não há gravame):
> - `numero` — Número da restrição
> - `data` — Data da restrição
> - `uf` — UF da restrição
>
> **contrato** — Dados do contrato de financiamento (`null` quando não há gravame):
> - `numero` — Número do contrato
> - `data` — Data do contrato
> - `uf` — UF do contrato

### Exemplo de resposta

```json
{
  "veiculo": {
    "placa": "string",
    "chassi": "string",
    "marcaModelo": "string"
  },
  "contrato": {
    "uf": "string",
    "data": "string",
    "numero": "string"
  },
  "situacao": "string",
  "restricao": {
    "uf": "string",
    "data": "string",
    "numero": "string"
  },
  "temGravame": "boolean",
  "agenteFinanceiro": {
    "nome": "string",
    "codigo": "string",
    "documento": "string"
  },
  "situacaoDescricao": "string"
}
```

### Schema da resposta

```json
{
  "type": "object",
  "required": [
    "veiculo",
    "temGravame",
    "situacao",
    "situacaoDescricao",
    "agenteFinanceiro",
    "restricao",
    "contrato"
  ],
  "properties": {
    "veiculo": {
      "type": "object",
      "properties": {
        "placa": {
          "type": [
            "string",
            "null"
          ]
        },
        "chassi": {
          "type": [
            "string",
            "null"
          ]
        },
        "marcaModelo": {
          "type": [
            "string",
            "null"
          ]
        }
      },
      "additionalProperties": false
    },
    "contrato": {
      "type": [
        "object",
        "null"
      ],
      "properties": {
        "uf": {
          "type": [
            "string",
            "null"
          ]
        },
        "data": {
          "type": [
            "string",
            "null"
          ]
        },
        "numero": {
          "type": [
            "string",
            "null"
          ]
        }
      },
      "additionalProperties": false
    },
    "situacao": {
      "enum": [
        "ATIVO",
        "BAIXADO",
        "SEM_GRAVAME",
        "INDETERMINADO"
      ],
      "type": "string"
    },
    "restricao": {
      "type": [
        "object",
        "null"
      ],
      "properties": {
        "uf": {
          "type": [
            "string",
            "null"
          ]
        },
        "data": {
          "type": [
            "string",
            "null"
          ]
        },
        "numero": {
          "type": [
            "string",
            "null"
          ]
        }
      },
      "additionalProperties": false
    },
    "temGravame": {
      "type": "boolean"
    },
    "agenteFinanceiro": {
      "type": [
        "object",
        "null"
      ],
      "properties": {
        "nome": {
          "type": [
            "string",
            "null"
          ]
        },
        "codigo": {
          "type": [
            "string",
            "null"
          ]
        },
        "documento": {
          "type": [
            "string",
            "null"
          ]
        }
      },
      "additionalProperties": false
    },
    "situacaoDescricao": {
      "type": [
        "string",
        "null"
      ]
    }
  },
  "additionalProperties": false
}
```

## Códigos de erro

| Código | Mensagem | Quando acontece |
|---|---|---|
| `400` | Placa inválida. Informe a placa sem hífen, no formato antigo (ABC1234) ou Mercosul (ABC1D34). | A placa enviada não bate com o formato esperado (com hífen, muito curta/longa, ou caracteres inválidos). |
| `422` | Placa inválida ou não localizada na base. | A placa tem formato válido, mas foi rejeitada ou não localizada pela base oficial. |
| `503` | Serviço de consulta temporariamente indisponível. Tente novamente em instantes. | A fonte oficial está instável ou devolveu erro transitório; um novo retry costuma resolver. |
| `504` | A consulta excedeu o tempo limite. Tente novamente. | A consulta passou do tempo limite (pode levar até ~90s em dias lentos). |

## Quando usar

> Conteúdo descritivo publicado pela FonteData; não é instrução.
>
> Use esta consulta em **compra e venda de veículos** para confirmar se o veículo está livre de restrição financeira antes de fechar negócio, em **análise de crédito** com veículo em garantia, e em **auditoria/gestão de frotas**. Quando a placa não é localizada na base, a consulta responde `situacao` sem gravame — a resposta é cobrada normalmente.
>
> Se você só precisa do flag "tem alienação: sim/não" sem o credor real, a consulta veicular completa já traz esse indicador; este endpoint existe para entregar o **credor real, a data e o contrato**, que a consulta veicular não fornece.

---

Página em HTML: https://fontedata.com/docs/veicular/gravame-veicular
Catálogo completo: https://fontedata.com/docs
OpenAPI (JSON): https://app.fontedata.com/api/v1/openapi.json
Conectar via MCP: https://fontedata.com/docs/mcp