Skip to main content

​
Ambiente de Homologação

Para facilitar o processo de integração e testes, disponibilizamos placas de teste que simulam diversos cenários reais de débitos veiculares. Essas placas devem ser utilizadas exclusivamente no ambiente de sandbox/homologação.
Atenção: As placas de teste listadas abaixo funcionam apenas no ambiente de homologação. Não utilize essas placas em ambiente de produção.

​
Como Usar as Placas de Teste

Para testar com as placas abaixo, utilize o endpoint de consulta de débitos no ambiente de sandbox: 
POST https://api-sandbox.uvvipague.com.br/uvvi/v1/debts
Todas as placas de teste devem ser consultadas com o estado correspondente ao cenário que você deseja testar. Utilize dados fictícios para RENAVAM e CPF/CNPJ.

​
Placas Disponíveis

​
Cenários de Indisponibilidade

Descrição: Simula o cenário em que o sistema do estado está temporariamente indisponível.Tipos de Débitos: Estado indisponívelComportamento Esperado:
  • Status: STATE_UNAVAILABLE
  • Mensagem indicando que o estado está temporariamente indisponível
  • Recomendação para tentar novamente mais tarde
Descrição: Simula erro de sistema indisponível.Tipos de Débitos: N/AComportamento Esperado:
  • Status: SYSTEM_ERROR
  • Erro genérico de sistema

​
Cenários de IPVA

Descrição: Cenários com débitos de IPVA parcelado e cota única disponíveis.Tipos de Débitos:
  • IPVA Parcelado
  • IPVA Cota Única
Use para testar:
  • Listagem de múltiplas opções de pagamento de IPVA
  • Escolha entre parcelamento ou cota única
  • Cálculo de valores e descontos
Descrição: Cenários apenas com IPVA em cota única.Tipos de Débitos:
  • IPVA Cota Única
Use para testar:
  • Pagamento de IPVA em cota única
  • Aplicação de descontos para pagamento à vista

​
Cenários de Infrações

Descrição: Veículo com multas de trânsito pendentes.Tipos de Débitos:
  • Multas de Trânsito (Infrações)
Use para testar:
  • Consulta de multas
  • Pagamento de infrações individuais
  • Pagamento em lote de múltiplas infrações
Descrição: Veículo com infrações comuns e infrações RENAINF.Tipos de Débitos:
  • Infração
  • Infração RENAINF
Use para testar:
  • Diferenciação entre infrações comuns e RENAINF
  • Pagamento de infrações RENAINF

​
Cenários de Licenciamento

Descrição: Veículo com débito de licenciamento anual.Tipos de Débitos:
  • Licenciamento
Use para testar:
  • Consulta de licenciamento
  • Pagamento de taxa de licenciamento
Descrição: Veículo com licenciamento e multa pendentes.Tipos de Débitos:
  • Licenciamento
  • Infração
Use para testar:
  • Múltiplos tipos de débitos
  • Pagamento combinado
Descrição: Veículo com múltiplos débitos: licenciamento, IPVA cota única e infrações.Tipos de Débitos:
  • Licenciamento
  • IPVA Cota Única
  • Infração
Use para testar:
  • Cenário completo com múltiplos débitos
  • Priorização de pagamentos
  • Cálculo de valores totais

​
Cenários de Dependência de Débitos

Débitos Dependentes: Alguns débitos precisam ser pagos em conjunto. Por exemplo, para licenciar um veículo, pode ser necessário quitar o IPVA e multas pendentes.
Descrição: Débitos que devem ser pagos juntos.Tipos de Débitos:
  • Infração
  • Licenciamento
Use para testar:
  • Validação de dependências entre débitos
  • Bloqueio de pagamento parcial quando há dependência
Descrição: IPVA parcelado com licenciamento dependente.Tipos de Débitos:
  • IPVA Parcelado
  • Licenciamento
Descrição: IPVA cota única com licenciamento dependente.Tipos de Débitos:
  • IPVA Cota Única
  • Licenciamento
Descrição: Múltiplos débitos dependentes.Tipos de Débitos:
  • Infração
  • IPVA Parcelado
  • Licenciamento
Descrição: Múltiplos débitos dependentes com IPVA cota única.Tipos de Débitos:
  • Infração
  • IPVA Cota Única
  • Licenciamento
Descrição: Outra variação de débitos dependentes.Tipos de Débitos:
  • Infração
  • Licenciamento
Descrição: Débitos de licenciamento acumulados desde 2022.Tipos de Débitos:
  • Licenciamento (múltiplos anos)
Use para testar:
  • Débitos acumulados de anos anteriores
  • Cálculo de juros e multas por atraso

​
Cenários de Débitos Distintos

Débitos Distintos: Alguns débitos não podem ser pagos juntos na mesma transação. Por exemplo, IPVA parcelado e cota única são mutuamente exclusivos.
Descrição: Cenários com opções de IPVA que não podem ser pagas juntas.Tipos de Débitos:
  • IPVA Parcelado
  • IPVA Cota Única
Use para testar:
  • Validação de débitos mutuamente exclusivos
  • Mensagens de erro ao tentar pagar débitos incompatíveis
  • Seleção de apenas uma opção de pagamento

​
Cenários de Débitos Obrigatórios

Descrição: Débito de seguro obrigatório (DPVAT).Tipos de Débitos:
  • Seguro Obrigatório
Use para testar:
  • Débitos obrigatórios que devem ser incluídos
  • Validação de seguro obrigatório

​
Cenários Especiais

Descrição: Veículo totalmente regularizado, sem débitos pendentes.Tipos de Débitos: NenhumComportamento Esperado:
  • Status: SUCCESS
  • Lista de débitos vazia
  • Mensagem indicando que o veículo está regularizado
Use para testar:
  • Tratamento de veículos sem débitos
  • Mensagens de sucesso
  • Interface para veículos regularizados

​
Cenários de Débitos Não Autorizados

Débitos Não Autorizados: Simulam débitos que não podem ser pagos através da API por alguma restrição ou bloqueio.
Descrição: Veículo com 5 infrações bloqueadas para pagamento.Tipos de Débitos:
  • Infração (5 débitos não autorizados)
Use para testar:
  • Tratamento de débitos bloqueados
  • Mensagens de erro específicas
  • Filtragem de débitos não pagáveis
Descrição: Veículo com 1 infração bloqueada.Tipos de Débitos:
  • Infração (1 débito não autorizado)
Descrição: Veículo com 3 infrações bloqueadas.Tipos de Débitos:
  • Infração (3 débitos não autorizados)
Descrição: Veículo com 2 débitos não autorizados e 1 débito estornado.Tipos de Débitos:
  • Infração (2 não autorizados, 1 estornado)
Use para testar:
  • Múltiplos status de débitos
  • Combinação de bloqueios e estornos
Descrição: Veículo com 2 infrações bloqueadas.Tipos de Débitos:
  • Infração (2 débitos não autorizados)

​
Cenários de Débitos Estornados

Débitos Estornados: Simulam débitos que foram cancelados ou estornados após a consulta inicial.
Descrição: Veículo com 5 infrações estornadas.Tipos de Débitos:
  • Infração (5 débitos estornados)
Use para testar:
  • Tratamento de débitos estornados
  • Atualização de status após consulta
  • Webhooks de estorno
Descrição: Veículo com 1 infração estornada.Tipos de Débitos:
  • Infração (1 débito estornado)
Descrição: Veículo com 3 infrações estornadas.Tipos de Débitos:
  • Infração (3 débitos estornados)
Descrição: Veículo com 1 débito estornado e 1 não autorizado.Tipos de Débitos:
  • Infração (1 estornado, 1 não autorizado)
Use para testar:
  • Múltiplos status em uma mesma consulta
  • Lógica de filtragem de débitos

​
Cenários de Débitos 2025

Débitos 2025: Placas específicas para testar débitos do exercício de 2025, úteis para validar lógica de ano corrente.
Descrição: Veículo com todos os tipos de débitos para 2025.Tipos de Débitos:
  • Licenciamento
  • IPVA Cota Única
  • IPVA Parcelado
  • Taxas
  • Multas
Use para testar:
  • Débitos do ano corrente
  • Cenário completo de regularização
Descrição: Débitos principais sem multas.Tipos de Débitos:
  • Licenciamento
  • IPVA Cota Única
  • IPVA Parcelado
  • Taxas
Descrição: Somente débito de licenciamento.Tipos de Débitos:
  • Licenciamento
Descrição: IPVA cota única com licenciamento.Tipos de Débitos:
  • IPVA Cota Única
  • Licenciamento
Descrição: Apenas taxas e multas.Tipos de Débitos:
  • Taxas
  • Multas

​
Tabela Resumida de Placas

Use a tabela abaixo como referência rápida para escolher a placa adequada ao seu cenário de teste.
PlacaDescriçãoTipos de Débitos
SUA0001Estado indisponívelEstado indisponível
IPP0001IPVA com opçõesIPVA Parcelado + Cota Única
IPP0002IPVA com opçõesIPVA Parcelado + Cota Única
IPU0001IPVA cota únicaCota Única
IPU0002IPVA cota únicaCota Única
TIC0001InfraçõesInfração
RTI0001Infrações RENAINFInfração + Infração RENAINF
LIC0001LicenciamentoLicenciamento
LIC0002Licenciamento + MultaLicenciamento + Infração
LIC0003Múltiplos débitosLicenciamento + Cota Única + Infração
DEP0001Débitos dependentesInfração + Licenciamento
DEP0002Débitos dependentesIPVA Parcelado + Licenciamento
DEP0003Débitos dependentesCota Única + Licenciamento
DEP0004Débitos dependentesInfração + IPVA Parcelado + Licenciamento
DEP0005Débitos dependentesInfração + Cota Única + Licenciamento
DEP0006Débitos dependentesInfração + Licenciamento
DEP0007Licenciamentos múltiplosDébitos de Licenciamento desde 2022
DIS0001Débitos distintosIPVA Parcelado + Cota Única
DIS0002Débitos distintosIPVA Parcelado + Cota Única
DIS0003Débitos distintosIPVA Parcelado + Cota Única
REQ0001Débito obrigatórioSeguro Obrigatório
VWD0001Sem débitosVeículo sem débitos
DNA0001Não autorizadosInfração (5 não autorizados)
DNA0002Não autorizadosInfração (1 não autorizado)
DNA0003Não autorizadosInfração (3 não autorizados)
DNA0004Não autorizados + EstornadosInfração (2 não autorizados, 1 estornado)
DNA0005Não autorizadosInfração (2 não autorizados)
REV0001EstornadosInfração (5 estornados)
REV0002EstornadosInfração (1 estornado)
REV0003EstornadosInfração (3 estornados)
REV0005Estornados + Não autorizadoInfração (1 estornado, 1 não autorizado)
ERR0001Sistema indisponívelN/A
IPV2501Débitos 2025 completoLicenciamento, IPVA, Taxas e Multas
IPV2502Débitos 2025Licenciamento, IPVA e Taxas
IPV2503Débitos 2025Somente Licenciamento
IPV2504Débitos 2025IPVA Cota Única e Licenciamento
IPV2505Débitos 2025Taxas e Multas

​
Exemplo de Uso

Veja como consultar débitos usando uma placa de teste: 
const response = await fetch('https://api-sandbox.uvvipague.com.br/uvvi/v1/debts', {
  method: 'POST',
  headers: {
    'x-api-key': process.env.UVVIPAGUE_SANDBOX_API_KEY,
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    state: 'SP',
    licensePlate: 'LIC0003', // Placa de teste
    renavam: '12345678901',
    cpfCnpj: '12345678900',
    externalId: crypto.randomUUID()
  })
});

const data = await response.json();
console.log('Débitos encontrados:', data.debts);

​
Checklist de Testes

Use este checklist para garantir que sua integração está tratando todos os cenários corretamente:
1

Cenários Básicos

  • Veículo sem débitos (VWD0001)
  • Veículo com débitos simples (LIC0001, IPU0001)
  • Estado indisponível (SUA0001)
2

Múltiplos Tipos de Débitos

  • IPVA parcelado vs cota única (IPP0001, IPP0002)
  • Licenciamento + Infrações (LIC0002)
  • Cenário completo (LIC0003)
3

Dependências e Restrições

  • Débitos dependentes (DEP0001 a DEP0007)
  • Débitos distintos (DIS0001 a DIS0003)
  • Débitos obrigatórios (REQ0001)
4

Casos de Erro

  • Débitos não autorizados (DNA0001 a DNA0005)
  • Débitos estornados (REV0001 a REV0005)
  • Sistema indisponível (ERR0001)
5

Cenários Específicos

  • Infrações RENAINF (RTI0001)
  • Débitos acumulados (DEP0007)
  • Débitos do ano corrente (IPV2501 a IPV2505)

​
Próximos Passos

Consulta de Débitos

Aprenda a consultar débitos usando a API

Fluxo Completo

Veja o fluxo completo de integração

Webhooks

Configure notificações automáticas

Referência da API

Documentação técnica completa
Lembre-se: Essas placas são exclusivas para o ambiente de homologação. Em produção, você trabalhará com placas reais de veículos.