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
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 campodependsOn que é um array contendo os IDs dos débitos dos quais ele depende:
- 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)
Estrutura da Resposta
Cada débito possui um campodistinct que é um array contendo os IDs dos débitos que não podem ser pagos junto com ele:
- 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 camporequired (booleano) que indica se ele é obrigatório:
- 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:Seleção Automática de Dependências
Seleção Automática de Dependências
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.
Desabilitar Opções Distintas
Desabilitar Opções Distintas
Quando o usuário selecionar um débito, desabilite automaticamente os débitos que são distintos dele.
Destacar Débitos Obrigatórios
Destacar Débitos Obrigatórios
Marque visualmente os débitos obrigatórios e não permita que sejam desmarcados.
Mensagens Explicativas
Mensagens Explicativas
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 pagamento2
Débitos Dependentes
Se um débito possui IDs no array
dependsOn, todos esses débitos devem ser incluídos juntos3
Débitos Distintos
Se um débito possui IDs no array
distinct, nenhum desses débitos pode ser incluído junto4
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