Documentacao de Integracao - API de Consultas Veiculares

Versao: 1.1.0 Data: 26/03/2026

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",
    "chassis": "9BWZZZ377VT004251",
    "ownerDocument": "12345678901"
  }'
            

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",
      "odometer": "0027000",
      "odometerMeasuredAt": "20260213120000"
    },
    "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"
}
            

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.