Documentacao de Integracao - API de Consultas Veiculares

Versao: 1.0.4 Data: 10/04/2026

Inclusão da seção 3.1 Estrutura dos Dados Retornados para esclarecer os dados retornados

Versao: 1.0.3 Data: 02/04/2026

Inclusão dos campos crvNumber, crvIssueDate, brand, model, version e predominantColor em /api/consultas/veiculos.
crvIssueDate, predominantColor e pdfBase64 são campos que podem retornar vazios na resposta caso tenhamos indisponibilidade por conta de integrações.

Versao: 1.0.2 Data: 01/04/2026

Inclusão dos campos manufacturingYear, modelYear e makeModel em /api/consultas/veiculos

Versao: 1.0.1 Data: 31/03/2026

Ajuste de Exemplo cURL /api/consultas/veiculos & criação do status NoSaleIntention

Versao: 1.0.0 Data: 26/03/2026

Documentação inicial

Visao Geral

Esta API permite que parceiros realizem consultas veiculares de forma segura utilizando autenticacao por bearer token.

Fluxo atual de autenticacao:

login retorna access token e refresh token
access token deve ser enviado nas rotas protegidas
refresh token deve ser usado apenas em POST /api/auth/refresh
refresh token e de uso unico e sofre rotacao a cada renovacao

Duracao atual dos tokens:

Access token: 60 minutos
Refresh token: 7 dias

1. Autenticacao

Endpoint

POST /api/auth/login

Descricao

Autentica o cliente e retorna um par de tokens.

Payload


{
  "email": "admin@cliente.com",
  "password": "senha"
}

Exemplo cURL


curl -X POST https://consult.openingfin.com.br/api/auth/login \
  -H "Content-Type: application/json" \
  -d '{
    "email": "admin@cliente.com",
    "password": "senha"
  }'

Exemplo Postman

Method: POST
URL: https://consult.openingfin.com.br/api/auth/login
Body: raw -> JSON

Resposta


{
  "accessToken": "token-duracao-padrao",
  "expiresAtUtc": "2026-03-26T19:00:00Z",
  "refreshToken": "refresh-token",
  "refreshTokenExpiresAtUtc": "2026-04-02T18:00:00Z",
  "tokenType": "Bearer"
}

Observacoes

Use o accessToken no header Authorization: Bearer {token}.
Guarde o refreshToken com seguranca.
Substitua sempre o refresh token antigo pelo novo valor retornado pela API.

2. Renovacao de Token

Endpoint

POST /api/auth/refresh

Descricao

Renova o access token com base em um refresh token valido.

Payload


{
  "refreshToken": "refresh-token-recebido-no-login"
}

Exemplo cURL


curl -X POST https://consult.openingfin.com.br/api/auth/refresh \
  -H "Content-Type: application/json" \
  -d '{
    "refreshToken": "refresh-token-recebido-no-login"
  }'

Resposta


{
  "accessToken": "token-duracao-padrao",
  "expiresAtUtc": "2026-03-26T20:00:00Z",
  "refreshToken": "novo-refresh-token",
  "refreshTokenExpiresAtUtc": "2026-04-02T19:00:00Z",
  "tokenType": "Bearer"
}

Erro de refresh token invalido


{
  "error": "invalid_grant",
  "error_description": "Refresh token expirado ou invalido."
}

3. Consulta Veicular

Endpoint

POST /api/consultas/veiculos

Descricao

Realiza uma consulta veicular autenticada.

Header


Authorization: Bearer {token}

Payload


{
  "plate": "ABC1234",
  "renavam": "12345678901",
  "ownerDocument": "12345678901",
  "crv": "254544800595"
}

Exemplo cURL


curl -X POST https://consult.openingfin.com.br/api/consultas/veiculos \
  -H "Authorization: Bearer {token}" \
  -H "Content-Type: application/json" \
  -d '{
    "plate": "ABC1234",
    "renavam": "12345678901",
    "ownerDocument": "12345678901",
    "crv": "254544800595"
  }'

Exemplo Postman

Method: POST
URL: https://consult.openingfin.com.br/api/consultas/veiculos
Authorization: Bearer Token
Body: raw -> JSON

Resposta


{
  "plate": "SHX0G81",
  "status": "Success",
  "message": "Consulta Veicular realizada com sucesso.",
  "data": {
    "error": {
      "code": "000",
      "message": ""
    },
    "vehicle": {
      "plate": "SHX0G81",
      "chassis": "9C2MD4110PR009676",
      "renavam": "01346491582",
      "atpveNumber": "260501355491582",
      "crvNumber": "244057819495",
      "crvIssueDate": "02/02/2026",
      "odometer": "0027000",
      "odometerMeasuredAt": "20260213120000",
      "manufacturingYear": "2022",
      "modelYear": "2022",
      "makeModel": "YAMAHA/NMAX 160",
      "brand": "YAMAHA",
      "model": "NMAX",
      "version": "160",
      "predominantColor": "BRANCA"
    },
    "seller": {
      "documentType": "1",
      "document": "04261263602",
      "name": "RENATO JOAO",
      "cityCode": "4553",
      "email": "RENATOJOAO@HOTMAIL.COM"
    },
    "buyer": {
      "documentType": "1",
      "document": "75909731653",
      "name": "MARIO JOAO VINCENTE",
      "email": "MARIO@HOTMAIL.COM",
      "cityCode": "4553",
      "state": "MG",
      "street": "SALINAS",
      "number": "64",
      "complement": "",
      "district": "SANTA HELENA",
      "zipCode": "35059450"
    },
    "sale": {
      "saleValue": "R$ 22.000,00",
      "saleRegistrationState": "MG",
      "intentionStateCode": "2",
      "intentionRegisteredAt": "202602191355326",
      "intentionUpdatedAt": "202603101508323",
      "saleOrigin": "00",
      "canSign": "0",
      "saleDate": "00000000",
      "saleCityCode": "0000"
    },
    "pdfBase64": ""
  },
  "queriedAtUtc": "2026-03-26T18:39:22.6845679Z"
}

Cenario sem intencao de venda

Quando o veiculo consultado nao possui intencao de venda registrada, a API retorna o status NoSaleIntention.

Nesse cenario, a consulta foi processada com sucesso pela integracao, mas nao ha dados de ATPV-e/intencao de venda disponiveis para preenchimento dos blocos de veiculo, vendedor, comprador e venda.

Exemplo de resposta sem intencao de venda


{
  "plate": "SHX0G81",
  "status": "NoSaleIntention",
  "message": "Veículo não tem intenção de venda",
  "data": {
    "error": {
      "code": "001",
      "message": "Veículo não tem intenção de venda"
    },
    "vehicle": {
      "plate": "",
      "chassis": "",
      "renavam": "",
      "atpveNumber": "",
      "crvNumber": "",
      "crvIssueDate": "",
      "odometer": "",
      "odometerMeasuredAt": "",
      "manufacturingYear": "",
      "modelYear": "",
      "makeModel": "",
      "brand": "",
      "model": "",
      "version": "",
      "predominantColor": ""
    },
    "seller": {
      "documentType": "",
      "document": "",
      "name": "",
      "cityCode": "",
      "email": ""
    },
    "buyer": {
      "documentType": "",
      "document": "",
      "name": "",
      "email": "",
      "cityCode": "",
      "state": "",
      "street": "",
      "number": "",
      "complement": "",
      "district": "",
      "zipCode": ""
    },
    "sale": {
      "saleValue": "",
      "saleRegistrationState": "",
      "intentionStateCode": "",
      "intentionRegisteredAt": "",
      "intentionUpdatedAt": "",
      "saleOrigin": "",
      "canSign": "",
      "saleDate": "",
      "saleCityCode": ""
    },
    "pdfBase64": ""
  },
  "queriedAtUtc": "2026-03-31T18:02:08.0599424Z"
}

3.1 Estrutura dos Dados Retornados

Descricao

A resposta da consulta veicular contém blocos estruturados com informações do veículo, vendedor, comprador, dados da venda e documento digital.

Cada campo retornado possui um significado específico conforme detalhado abaixo.

Dados do Veiculo (`vehicle`)

Campo	Descricao
plate	Placa do veículo
chassis	Número do chassi
renavam	Código RENAVAM
atpveNumber	Número do ATPVe (documento de transferência)
crvNumber	Número do CRV
crvIssueDate	Data de emissão do CRV
odometer	Quilometragem do veículo
odometerMeasuredAt	Data/hora da leitura do hodômetro (formato YYYYMMDDHHMMSS)
manufacturingYear	Ano de fabricação
modelYear	Ano do modelo
makeModel	Descrição completa (marca/modelo)
brand	Marca
model	Modelo
version	Versão
predominantColor	Cor predominante

Dados do Vendedor (`seller`)

Campo	Descricao
documentType	Tipo de documento (1 = CPF, 2 = CNPJ)
document	CPF ou CNPJ
name	Nome ou razão social
cityCode	Código do município
email	Email do vendedor

Dados do Comprador (`buyer`)

Campo	Descricao
documentType	Tipo de documento (1 = CPF, 2 = CNPJ)
document	CPF ou CNPJ
name	Nome completo
email	Email
cityCode	Código do município
state	Estado (UF)
street	Rua
number	Número
complement	Complemento
district	Bairro
zipCode	CEP

Dados da Venda (`sale`)

Campo	Descricao
saleValue	Valor da venda
saleRegistrationState	Estado onde a venda será registrada
intentionStateCode	Código da intenção de venda
intentionRegisteredAt	Data/hora do registro da intenção
intentionUpdatedAt	Data/hora da última atualização
saleOrigin	Código de origem da venda
canSign	Indica se o documento está apto para assinatura
saleDate	Data efetiva da venda
saleCityCode	Código do município da venda

Documento (`pdfBase64`)

Campo	Descricao
pdfBase64	Documento gerado (ex: ATPVe) codificado em Base64

Observacoes

Campos podem ser retornados vazios dependendo da disponibilidade das integrações
Datas podem ser retornadas em formato YYYYMMDDHHMMSS
O campo pdfBase64 somente será preenchido quando houver geração de documento

4. Historico de Consultas

Endpoint

GET /api/consultas/veiculos/historico

Descricao

Retorna o historico de consultas do cliente autenticado.

Exemplo cURL


curl -X GET https://consult.openingfin.com.br/api/consultas/veiculos/historico \
  -H "Authorization: Bearer {token}"

Exemplo Postman

Method: GET
URL: https://consult.openingfin.com.br/api/consultas/veiculos/historico
Authorization: Bearer Token

Resposta


{
  "items": [
    {
      "id": "b2a584c1-79de-486b-99b5-0b23f85a43e2",
      "plate": "SHX0G81",
      "renavam": "01346491582",
      "status": "Success",
      "queriedAtUtc": "2026-03-26T18:39:22.6845679Z"
    }
  ],
  "page": 1,
  "pageSize": 20,
  "totalItems": 1,
  "totalPages": 1
}

5. Health Check

Endpoint

GET /api/health

Descricao

Verifica se a API esta disponivel.

Exemplo cURL


curl https://consult.openingfin.com.br/api/health

Boas Praticas

Renovar o access token antes da expiracao quando necessario.
Armazenar access token e refresh token com seguranca.
Substituir o refresh token anterior pelo novo valor devolvido no endpoint de refresh.
Tratar erros de autenticacao e renovacao de token.
Implementar retries apenas para falhas temporarias de infraestrutura.

Suporte

Para duvidas tecnicas, entre em contato com o time responsavel pela API.

Documentacao de Integracao - API de Consultas Veiculares

Visao Geral

1. Autenticacao

Endpoint

Descricao

Payload

Exemplo cURL

Exemplo Postman

Resposta

Observacoes

2. Renovacao de Token

Endpoint

Descricao

Payload

Exemplo cURL

Resposta

Erro de refresh token invalido

3. Consulta Veicular

Endpoint

Descricao

Header

Payload

Exemplo cURL

Exemplo Postman

Resposta

Cenario sem intencao de venda

Exemplo de resposta sem intencao de venda

3.1 Estrutura dos Dados Retornados

Descricao

Dados do Veiculo (vehicle)

Dados do Vendedor (seller)

Dados do Comprador (buyer)

Dados da Venda (sale)

Documento (pdfBase64)

Observacoes

4. Historico de Consultas

Endpoint

Descricao

Exemplo cURL

Exemplo Postman

Resposta

5. Health Check

Endpoint

Descricao

Exemplo cURL

Boas Praticas

Suporte

Dados do Veiculo (`vehicle`)

Dados do Vendedor (`seller`)

Dados do Comprador (`buyer`)

Dados da Venda (`sale`)

Documento (`pdfBase64`)