Skip to main content

Introdução

Ao consultar débitos veiculares, é comum encontrar situações onde alguns débitos possuem relacionamentos e restrições entre si. A API Uvvipague retorna três tipos de relacionamentos que você precisa entender e tratar corretamente:

Dependentes

Débitos que devem ser pagos juntos

Distintos

Débitos que não podem ser pagos juntos

Obrigatórios

Débitos que sempre devem ser incluídos
Importante: Ignorar essas regras resultará em erro na solicitação de pagamento. É fundamental validar esses relacionamentos antes de processar o pagamento.

Débitos Dependentes (dependsOn)

O que são?

Débitos dependentes são aqueles que precisam ser pagos em conjunto. Quando um débito possui dependência de outro, ambos devem ser incluídos na mesma solicitação de pagamento.

Exemplo Comum

O caso mais comum é o licenciamento, que geralmente depende da quitação do IPVA e/ou multas pendentes.
Regra: Para licenciar um veículo, é necessário estar com o IPVA e multas em dia. Por isso, o débito de licenciamento pode ter dependência desses outros débitos.

Estrutura da Resposta

Cada débito retornado pela API possui um campo dependsOn que é um array contendo os IDs dos débitos dos quais ele depende:
No exemplo acima:
  • O débito de Licenciamento (B8E1F87B-...) depende da Infração (17BD43F1-...)
  • Para pagar o licenciamento, você deve incluir a infração na mesma solicitação

Como Validar

Antes de enviar a solicitação de pagamento, valide se todos os débitos dependentes estão incluídos:

Erro ao Não Respeitar Dependências

Se você tentar pagar um débito sem incluir suas dependências, a API retornará um erro:

Débitos Distintos (distinct)

O que são?

Débitos distintos são aqueles que não podem ser pagos juntos na mesma transação. Eles são mutuamente exclusivos.

Exemplo Comum

O caso mais comum é quando o IPVA possui duas opções de pagamento:
  • Cota Única (com desconto)
  • Cotas Parceladas (sem desconto)
Você deve escolher apenas uma dessas opções, não pode pagar ambas.
Atenção: Tentar pagar débitos distintos juntos resultará em erro. O usuário deve escolher qual opção deseja.

Estrutura da Resposta

Cada débito possui um campo distinct que é um array contendo os IDs dos débitos que não podem ser pagos junto com ele:
No exemplo acima:
  • IPVA Cota Única e IPVA Parcelado são mutuamente exclusivos
  • O usuário deve escolher apenas uma das opções

Como Validar

Valide se não há débitos distintos selecionados juntos:

Erro ao Não Respeitar Distintos

Se você tentar pagar débitos distintos juntos, a API retornará um erro:

Débitos Obrigatórios (required)

O que são?

Débitos obrigatórios são aqueles que sempre devem ser incluídos no pagamento quando retornados na consulta. Não é possível pagar outros débitos sem incluir os obrigatórios.

Exemplo Comum

O Seguro Obrigatório (DPVAT) é frequentemente marcado como obrigatório quando há outros débitos a serem pagos.
Regra: Se um débito obrigatório está presente na consulta e você está pagando outros débitos, o obrigatório também deve ser incluído.

Estrutura da Resposta

Cada débito possui um campo required (booleano) que indica se ele é obrigatório:
No exemplo acima:
  • O Seguro Obrigatório tem required: true
  • Se você for pagar o Licenciamento, deve incluir o Seguro Obrigatório também

Como Validar

Valide se todos os débitos obrigatórios estão incluídos quando há outros débitos selecionados:

Erro ao Não Incluir Obrigatórios

Se você tentar pagar débitos sem incluir os obrigatórios, a API retornará um erro:

Validação Completa

Para garantir que sua solicitação de pagamento seja processada corretamente, você deve validar todas as três regras:

Experiência do Usuário

Sugestões de Interface

Para uma melhor experiência do usuário, considere:
Quando o usuário selecionar um débito que possui dependências, selecione automaticamente os débitos dependentes e desabilite a opção de desmarcá-los.
Quando o usuário selecionar um débito, desabilite automaticamente os débitos que são distintos dele.
Marque visualmente os débitos obrigatórios e não permita que sejam desmarcados.
Exiba mensagens claras explicando por que certos débitos foram selecionados ou desabilitados.

Testando com Placas de Homologação

Use as placas de teste específicas para validar o tratamento dessas regras:

Débitos Dependentes

DEP0001 a DEP0007Teste cenários com débitos que devem ser pagos juntos

Débitos Distintos

DIS0001 a DIS0003Teste cenários com IPVA parcelado e cota única

Débitos Obrigatórios

REQ0001Teste cenário com seguro obrigatório

Resumo das Regras

1

Débitos Obrigatórios

Se houver débitos com required: true, eles devem ser incluídos no pagamento
2

Débitos Dependentes

Se um débito possui IDs no array dependsOn, todos esses débitos devem ser incluídos juntos
3

Débitos Distintos

Se um débito possui IDs no array distinct, nenhum desses débitos pode ser incluído junto
4

Validação Completa

Valide as três regras antes de enviar a solicitação de pagamento para evitar erros

Referências

Consulta de Débitos

Veja como consultar débitos e obter essas informações

Placas de Teste

Use placas específicas para testar esses cenários

Fluxo Completo

Integração completa incluindo validação de débitos

Referência da API

Documentação técnica completa da API