Skip to main content

​
Visão Geral

A API da Uvvipague utiliza autenticação baseada em API Key para garantir a segurança e identificação de cada cliente. Todas as requisições HTTP devem incluir sua chave de API no header para serem processadas.
Autenticação Simples e Segura: Basta incluir sua API Key no header x-api-key de todas as requisições.

​
Como Funciona

​
Header Obrigatório

Todas as requisições à API devem incluir o seguinte header: 
x-api-key: SUA_API_KEY_AQUI

​
Exemplo de Requisição Autenticada

curl --request GET \
  --url 'https://api.uvvipague.com.br/api/v1/vehicle/enrichment/ABC1234' \
  --header 'x-api-key: SUA_API_KEY_AQUI' \
  --header 'Content-Type: application/json'

​
Obtendo sua API Key

1

Acesse o Painel

Faça login no painel administrativo da Uvvipague em dashboard.uvvipague.com.br
2

Navegue até Configurações

No menu lateral, acesse a seção Configurações > API Keys
3

Gere ou Copie sua Chave

  • Se você ainda não tem uma API Key, clique em “Gerar Nova Chave”
  • Se já possui, copie a chave existente
  • Guarde a chave em local seguro
4

Configure em sua Aplicação

Adicione a API Key nas variáveis de ambiente da sua aplicação

​
Detalhes Importantes

Chave Única

Cada cliente possui uma API Key única associada à sua conta. Não compartilhe sua chave com terceiros.

Identificação

A API Key é utilizada para autenticação, identificação do cliente e aplicação de regras de segurança.

Obrigatória

Todas as requisições devem incluir o header x-api-key. Requisições sem o header resultarão em erro.

Rate Limiting

Sua API Key está associada aos limites de requisições do seu plano contratado.

​
Erros de Autenticação

​
HTTP 401 - Unauthorized

Este erro ocorre quando há problemas com a autenticação:
Causa: O header x-api-key não foi incluído na requisição.Solução: Adicione o header com sua API Key válida.
{
  "error": "Unauthorized",
  "message": "API Key não fornecida",
  "statusCode": 401
}
Causa: A API Key fornecida não existe ou está incorreta.Solução: Verifique se copiou a chave corretamente do painel.
{
  "error": "Unauthorized",
  "message": "API Key inválida",
  "statusCode": 401
}
Causa: A API Key foi revogada ou expirou.Solução: Gere uma nova API Key no painel administrativo.
{
  "error": "Unauthorized",
  "message": "API Key expirada ou revogada",
  "statusCode": 401
}
Causa: Sua conta foi suspensa por violação dos termos ou falta de pagamento.Solução: Entre em contato com o suporte.
{
  "error": "Unauthorized",
  "message": "Conta suspensa",
  "statusCode": 401
}

​
HTTP 429 - Too Many Requests

{
  "error": "Too Many Requests",
  "message": "Limite de requisições excedido",
  "statusCode": 429,
  "retryAfter": 60
}
Este erro indica que você excedeu o limite de requisições do seu plano. Aguarde o tempo indicado em retryAfter (em segundos) antes de fazer novas requisições.

​
Segurança e Boas Práticas

Nunca exponha sua API Key: Não inclua sua API Key diretamente no código-fonte, especialmente em repositórios públicos ou aplicações client-side (frontend).

​
Recomendações de Segurança

1

Use Variáveis de Ambiente

Armazene sua API Key em variáveis de ambiente, nunca no código-fonte.
.env
UVVIPAGUE_API_KEY=sua_api_key_aqui
2

Backend Only

Faça as chamadas à API apenas do backend. Nunca exponha a API Key no frontend (JavaScript, apps mobile, etc.).
3

Rotação de Chaves

Considere rotacionar sua API Key periodicamente (a cada 3-6 meses) como medida preventiva de segurança.
4

Monitore o Uso

Acompanhe o uso da sua API Key no painel. Atividades suspeitas podem indicar comprometimento.
5

Revogue se Comprometida

Se suspeitar que sua API Key foi comprometida, revogue-a imediatamente e gere uma nova no painel.

​
Práticas a Evitar

Código Frontend

// NUNCA faça isso
const apiKey = "sk_live_abc123...";
fetch(url, { headers: { 'x-api-key': apiKey } });

Repositórios Públicos

// NUNCA commite isso
const config = {
  apiKey: "sk_live_abc123..."
};

Logs Públicos

// NUNCA logue a API Key
console.log('API Key:', apiKey);
logger.info(`Using key: ${apiKey}`);

URLs ou Query Params

# NUNCA passe na URL
curl https://api.uvvipague.com.br/api?key=sk_live_abc123

​
Implementação Correta

// Carregue da variável de ambiente
require('dotenv').config();

const express = require('express');
const app = express();

app.get('/api/consultar-veiculo', async (req, res) => {
  const { placa } = req.query;
  
  try {
    const response = await fetch(
      `https://api.uvvipague.com.br/api/v1/vehicle/enrichment/${placa}`,
      {
        headers: {
          'x-api-key': process.env.UVVIPAGUE_API_KEY,
          'Content-Type': 'application/json'
        }
      }
    );
    
    const data = await response.json();
    res.json(data);
  } catch (error) {
    res.status(500).json({ error: 'Erro ao consultar veículo' });
  }
});

​
Ambientes de Teste e Produção

URL Base: https://api.uvvipague.com.br
  • Use sua API Key de produção (começa com sk_live_)
  • Todas as transações são reais e cobradas
  • Dados reais dos Detrans
x-api-key: sk_live_abc123def456...
Dica: Durante o desenvolvimento, sempre use o ambiente de Sandbox para evitar cobranças desnecessárias e testar diferentes cenários.

​
Testando sua Autenticação

Você pode testar rapidamente se sua API Key está funcionando com este comando: 
curl --request GET \
  --url 'https://api.uvvipague.com.br/api/v1/health' \
  --header 'x-api-key: SUA_API_KEY_AQUI'
Resposta esperada (200 OK): 
{
  "status": "ok",
  "authenticated": true,
  "account": {
    "id": "acc_123456",
    "name": "Sua Empresa",
    "plan": "professional"
  }
}

​
Próximos Passos

Agora que você sabe como autenticar suas requisições, explore as funcionalidades da API:

Enriquecimento de Placa

Consulte informações detalhadas de veículos através da placa.

Consulta de Débitos

Busque débitos pendentes de veículos.

Webhooks

Configure notificações automáticas de eventos.

Fluxo Completo

Veja o fluxo completo de integração.

​
Suporte

Precisa de ajuda com autenticação?

Documentação da API

Consulte a referência completa da API.

Fale com o Suporte

Entre em contato com nossa equipe.