Skip to main content

​
Visão Geral

A API Uvvipague oferece endpoints RESTful para integração completa com o sistema de consulta e pagamento de débitos veiculares. Esta seção contém a referência técnica detalhada de todos os endpoints disponíveis.
Base URL: https://api.uvvipague.com.brTodos os endpoints utilizam HTTPS e retornam respostas em formato JSON.

​
Estrutura da API

A API está organizada em módulos funcionais:

Consulta de Veículos

Endpoints para enriquecimento de dados e consulta de débitos veiculares

Pagamentos

Endpoints para processamento de pagamentos e tokenização de cartões

Webhooks

Configuração e gerenciamento de notificações automáticas

Utilitários

Endpoints auxiliares para simulação de parcelas e consultas de status

​
Autenticação

Todos os endpoints da API requerem autenticação via API Key.
1

Obtenha sua API Key

Acesse o painel administrativo e gere sua chave de API na seção de configurações.
2

Inclua o Header

Adicione o header x-api-key em todas as requisições:
x-api-key: SUA_API_KEY_AQUI
3

Teste a Autenticação

Faça uma requisição de teste para validar sua chave:
curl --request GET \
  --url 'https://api.uvvipague.com.br/api/v1/health' \
  --header 'x-api-key: SUA_API_KEY_AQUI'
Segurança: Nunca exponha sua API Key em código client-side ou repositórios públicos. Mantenha-a sempre em variáveis de ambiente no backend.
Para mais detalhes sobre autenticação, consulte a documentação completa de autenticação.

​
Ambientes

A API Uvvipague oferece dois ambientes:
URL Base: https://api.uvvipague.com.br
  • Transações reais e cobradas
  • Dados reais dos Detrans
  • API Key de produção (começa com sk_live_)
# Exemplo de requisição em produção
curl --request GET \
  --url 'https://api.uvvipague.com.br/api/v1/health' \
  --header 'x-api-key: sk_live_...'

​
Formato de Requisições

Todas as requisições devem seguir o formato padrão:

​
Headers Obrigatórios

x-api-key: SUA_API_KEY_AQUI
Content-Type: application/json

​
Corpo da Requisição

{
  "campo1": "valor1",
  "campo2": "valor2"
}

​
Formato de Respostas

​
Resposta de Sucesso (2xx)

{
  "success": true,
  "data": {
    // Dados da resposta
  }
}

​
Resposta de Erro (4xx, 5xx)

{
  "success": false,
  "error": "TipoDoErro",
  "message": "Descrição detalhada do erro",
  "statusCode": 400
}

​
Códigos de Status HTTP

CódigoDescrição
200OK - Requisição processada com sucesso
201Created - Recurso criado com sucesso
CódigoDescrição
400Bad Request - Dados inválidos na requisição
401Unauthorized - API Key inválida ou ausente
404Not Found - Recurso não encontrado
422Unprocessable Entity - Dados não podem ser processados
429Too Many Requests - Limite de requisições excedido
CódigoDescrição
500Internal Server Error - Erro interno do servidor
503Service Unavailable - Serviço temporariamente indisponível

​
Rate Limiting

A API implementa limites de requisições para garantir a qualidade do serviço:

Limite Padrão

1000 requisições/minutoLimite padrão para contas standard

Limite Enterprise

5000 requisições/minutoLimite para contas enterprise
Quando o limite é excedido, você receberá: 
{
  "error": "Too Many Requests",
  "message": "Limite de requisições excedido",
  "statusCode": 429,
  "retryAfter": 60
}
Implemente retry com backoff exponencial para lidar com erros 429 de forma elegante.

​
Versionamento

A API utiliza versionamento na URL: 
https://api.uvvipague.com.br/uvvi/v1/...
  • v1: Versão atual e estável da API
  • Mudanças breaking serão introduzidas em novas versões (v2, v3, etc.)
  • Versões antigas serão mantidas por pelo menos 12 meses após deprecação

​
Idempotência

Para operações críticas, use o campo externalId para garantir idempotência: 
{
  "externalId": "550e8400-e29b-41d4-a716-446655440000",
  // ... outros campos
}
O externalId deve ser um UUID único gerado pelo seu sistema. A API usará este ID para evitar processamento duplicado e para correlacionar webhooks.

​
Especificação OpenAPI

OpenAPI Specification

Baixe a especificação OpenAPI completa para importar em ferramentas como Postman, Insomnia ou gerar SDKs automaticamente.

​
Próximos Passos

Fluxo Completo

Veja o fluxo completo de integração

Autenticação

Entenda como autenticar suas requisições

Webhooks

Configure notificações automáticas

​
Suporte

Precisa de ajuda com a API?

Documentação Completa

Consulte a documentação completa

Fale com o Suporte

Entre em contato com nossa equipe