Skip to main content

Visão Geral

Esta página documenta todos os ENUMs (enumeradores) e tipos de dados utilizados na API Uvvipague. Use esta referência para garantir que está enviando os valores corretos nas requisições.

Status de Pagamento

Payment Status

Status possíveis para transações de pagamento com cartão de crédito:
StatusDescriçãoAção Recomendada
paidPagamento aprovado e processado com sucessoLiberar produto/serviço
in_analysisTransação em análise pelo antifraudeAguardar atualização via webhook
refusedTransação recusada pela operadora ou antifraudeInformar cliente e oferecer nova tentativa
processingTransação sendo processadaAguardar atualização
awaiting_paymentAguardando confirmação de pagamento (comum em PIX)Aguardar pagamento do cliente
cancelledPagamento canceladoTransação encerrada
refundedPagamento estornadoValor devolvido ao cliente
chargebackContestação de pagamentoAnalisar disputa
const PaymentStatus = {
  PAID: 'paid',
  IN_ANALYSIS: 'in_analysis',
  REFUSED: 'refused',
  PROCESSING: 'processing',
  AWAITING_PAYMENT: 'awaiting_payment',
  CANCELLED: 'cancelled',
  REFUNDED: 'refunded',
  CHARGEBACK: 'chargeback'
};

Liquidation Status

Status de liquidação dos débitos junto aos Detrans:
StatusDescrição
pendingLiquidação pendente
processingLiquidação em processamento
settledDébito liquidado com sucesso
failedFalha na liquidação
cancelledLiquidação cancelada
const LiquidationStatus = {
  PENDING: 'pending',
  PROCESSING: 'processing',
  SETTLED: 'settled',
  FAILED: 'failed',
  CANCELLED: 'cancelled'
};

Tipos de Débito

Debt Type

Tipos de débitos veiculares disponíveis:
TipoDescriçãoExemplo
ticketMulta de trânsitoMultas de velocidade, estacionamento, etc.
ipvaIPVA (Imposto sobre Propriedade de Veículos Automotores)IPVA anual, cota única ou parcelada
licensingTaxa de licenciamentoTaxa anual de licenciamento
serviceTaxa de serviçoMulta de pátio, taxas diversas
const DebtType = {
  TICKET: 'ticket',
  IPVA: 'ipva',
  LICENSING: 'licensing',
  SERVICE: 'service'
};

Métodos de Pagamento

Payment Method

Métodos de pagamento aceitos:
MétodoDescriçãoCaracterísticas
credit_cardCartão de créditoParcelamento disponível (1x a 12x)
pixPIXPagamento instantâneo, aguarda confirmação
const PaymentMethod = {
  CREDIT_CARD: 'credit_card',
  PIX: 'pix'
};

Tipos de Resposta de Consulta

Search Response Type

Tipos de resposta ao consultar débitos:
TipoDescrição
debtsVeículo possui débitos pendentes
VehicleWithoutDebtsVeículo sem débitos
VehicleNotFoundVeículo não encontrado nos sistemas do Detran
search-error-eventErro na consulta (indisponibilidade do Detran, etc.)
const SearchResponseType = {
  DEBTS: 'debts',
  VEHICLE_WITHOUT_DEBTS: 'VehicleWithoutDebts',
  VEHICLE_NOT_FOUND: 'VehicleNotFound',
  SEARCH_ERROR: 'search-error-event'
};

Estados (UF)

Brazilian States

Siglas dos estados brasileiros suportados:
UFEstado
ACAcre
ALAlagoas
APAmapá
AMAmazonas
BABahia
CECeará
DFDistrito Federal
ESEspírito Santo
GOGoiás
MAMaranhão
MTMato Grosso
MSMato Grosso do Sul
MGMinas Gerais
PAPará
PBParaíba
PRParaná
PEPernambuco
PIPiauí
RJRio de Janeiro
RNRio Grande do Norte
RSRio Grande do Sul
RORondônia
RRRoraima
SCSanta Catarina
SPSão Paulo
SESergipe
TOTocantins
Limitações por Estado: Alguns estados (GO, MA, MS, RS) retornam apenas IPVA em cota única. Consulte a documentação de consulta de débitos para mais detalhes.

Bandeiras de Cartão

Card Brand

Bandeiras de cartão de crédito aceitas:
BandeiraCódigo
Visavisa
Mastercardmastercard
American Expressamex
Eloelo
Hipercardhipercard
Diners Clubdiners
const CardBrand = {
  VISA: 'visa',
  MASTERCARD: 'mastercard',
  AMEX: 'amex',
  ELO: 'elo',
  HIPERCARD: 'hipercard',
  DINERS: 'diners'
};

Códigos de Erro

Error Codes

Códigos de erro específicos da API:
CódigoDescriçãoSolução
900Serviço indisponívelAguardar e tentar novamente
901Timeout na consulta ao DetranTentar novamente após alguns minutos
902Dados inconsistentes retornados pelo DetranVerificar dados do veículo
903Manutenção programada do DetranAguardar fim da manutenção
const ErrorCode = {
  SERVICE_UNAVAILABLE: '900',
  TIMEOUT: '901',
  INCONSISTENT_DATA: '902',
  SCHEDULED_MAINTENANCE: '903'
};

HTTP Status Codes

Status Codes Comuns

Códigos HTTP utilizados pela API:
CódigoDescrição
200OK - Requisição bem-sucedida
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

Validações e Regras

Formatos de Dados

Formatos esperados para diferentes tipos de dados:

Placa de Veículo

Formato: ABC1234 ou ABC1D23 (Mercosul)
  • 7 caracteres
  • Com ou sem hífen
  • Letras maiúsculas

RENAVAM

Formato: 12345678901
  • 11 dígitos numéricos
  • Validação de dígito verificador

CPF

Formato: 12345678900
  • 11 dígitos numéricos
  • Apenas números, sem pontos ou hífen

CNPJ

Formato: 12345678000100
  • 14 dígitos numéricos
  • Apenas números, sem pontos, barra ou hífen

Limites e Restrições

CampoLimiteDescrição
Parcelas1 a 12Número de parcelas permitido
Valor mínimo por parcelaR$ 5,00Valor mínimo de cada parcela
Timeout de checkout24 horasTempo de validade do checkout
Timeout de PIX30 minutosTempo para pagamento via PIX

Exemplos de Uso

Validação de Enum

function isValidPaymentStatus(status) {
  const validStatuses = [
    'paid', 'in_analysis', 'refused', 'processing',
    'awaiting_payment', 'cancelled', 'refunded', 'chargeback'
  ];
  return validStatuses.includes(status);
}

// Uso
if (isValidPaymentStatus(payment.status)) {
  console.log('Status válido:', payment.status);
}

Switch Case com ENUMs

function handlePaymentStatus(status) {
  switch (status) {
    case 'paid':
      return liberarProduto();
    case 'in_analysis':
      return aguardarAnalise();
    case 'refused':
      return notificarRecusa();
    case 'awaiting_payment':
      return aguardarPagamento();
    default:
      return handleUnknownStatus(status);
  }
}

Próximos Passos