Referência da API

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.

Obtenha sua API Key

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

Inclua o Header

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

x-api-key: SUA_API_KEY_AQUI

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:

Produção
Sandbox (Teste)

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_...'

URL Base: https://sandbox-api.uvvipague.com.br

Transações simuladas (sem cobrança)
Dados de teste
API Key de teste (começa com sk_test_)

# Exemplo de requisição em sandbox
curl --request GET \
  --url 'https://sandbox-api.uvvipague.com.br/api/v1/health' \
  --header 'x-api-key: sk_test_...'

Use o ambiente sandbox durante o desenvolvimento para testar diferentes cenários sem custos.

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

2xx - Sucesso

Código	Descrição
`200`	OK - Requisição processada com sucesso
`201`	Created - Recurso criado com sucesso

4xx - Erro do Cliente

Código	Descrição
`400`	Bad Request - Dados inválidos na requisição
`401`	Unauthorized - API Key inválida ou ausente
`404`	Not Found - Recurso não encontrado
`422`	Unprocessable Entity - Dados não podem ser processados
`429`	Too Many Requests - Limite de requisições excedido

5xx - Erro do Servidor

Código	Descrição
`500`	Internal Server Error - Erro interno do servidor
`503`	Service 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

Documentação da API

Veículos

Débitos

Pagamentos

Webhooks

Referência da API

Visão Geral

Estrutura da API

Consulta de Veículos

Pagamentos

Webhooks

Utilitários

Autenticação

Ambientes

Formato de Requisições

Headers Obrigatórios

Corpo da Requisição

Formato de Respostas

Resposta de Sucesso (2xx)

Resposta de Erro (4xx, 5xx)

Códigos de Status HTTP

Rate Limiting

Limite Padrão

Limite Enterprise

Versionamento

Idempotência

Especificação OpenAPI

OpenAPI Specification

Próximos Passos

Fluxo Completo

Autenticação

Webhooks

Suporte

Documentação Completa

Fale com o Suporte

​Visão Geral

​Estrutura da API

Consulta de Veículos

Pagamentos

Webhooks

Utilitários

​Autenticação

​Ambientes

​Formato de Requisições

​Headers Obrigatórios

​Corpo da Requisição

​Formato de Respostas

​Resposta de Sucesso (2xx)

​Resposta de Erro (4xx, 5xx)

​Códigos de Status HTTP

​Rate Limiting

Limite Padrão

Limite Enterprise

​Versionamento

​Idempotência

​Especificação OpenAPI

OpenAPI Specification

​Próximos Passos

Fluxo Completo

Autenticação

Webhooks

​Suporte

Documentação Completa

Fale com o Suporte

Visão Geral

Estrutura da API

Autenticação

Ambientes

Formato de Requisições

Headers Obrigatórios

Corpo da Requisição

Formato de Respostas

Resposta de Sucesso (2xx)

Resposta de Erro (4xx, 5xx)

Códigos de Status HTTP

Rate Limiting

Versionamento

Idempotência

Especificação OpenAPI

Próximos Passos

Suporte