Consulta de débitos

Integrando com API de Consulta de débitos Zapay

Este guia foi elaborado para auxiliá-lo na navegação e para que você possa entender melhor todos os nossos recursos disponíveis no módulo de débitos veiculares e seu funcionamento.

📘

Dica

Antes de seguir para a referência da API, consulte informações da preparação do ambiente e autenticação necessária.

Consultando um débito veicular

O ciclo de vida de uma consulta de débito compreende diversos estágios, delineados pelos diferentes status e retornos associados a ele. Abaixo temos uma ilustração do processo de pesquisa:

Forneça os campos necessários

Atualmente, o Detran de cada estado possui suas obrigatoriedades específica nos dados necessários para realização de consulta dos débitos, porém, a Zapay possui dois formatos para realização de consulta, sendo:

• Com enriquecimento de dados Zapay: Enriquecemos os dados obrigatórios para a consulta de cada Estado, somente recepcionando a placa do veículo.
• Sem enriquecimento de dados Zapay: Não enriquecemos dados do veículo. São utilizados os dados enviados na API pelo parceiro para as consultas.

1. Com enriquecimento Zapay:
   Para simplificar a necessidade de solicitação de campos obrigatórios, realizamos um processo de enriquecimento pré consulta, que é totalmente transparente para os nossos parceiros e cliente final e com o cambo obrigatório "placa do veículo".
   Obs.: O processo de enriquecimento pode sofrer cobranças adicionais. Para verificar, entre em contato com o time de negócios.

   

                             O retorno da consulta é realizado de maneira assíncrona.
   

2. Sem enriquecimento Zapay:
   Antes de iniciar a pesquisa, você tem a opção de coletar todos os dados necessários do seu cliente. Se optar por esse caminho, utilizaremos exclusivamente as informações fornecidas por eles, sem realizar nenhum enriquecimento adicional de dados.
   Para garantir que você tenha tudo o que é necessário, confira a tabela de dados obrigatórios por estado que disponibilizamos aqui.

                           O retorno da consulta é realizado de maneira assíncrona.

Veja detalhadamente as informações de solicitação de consulta de débitos por meio de nossa API Reference!

Portanto, para iniciar o processo de pesquisa dos débitos de um veículo você deverá realizar uma chamada HTTP POST na API de requisição de consulta de débitos veiculares e com a nossa busca simplificada, o único dado obrigatório para a maioria dos estados para realização das consultas de débitos veiculares é a placa do veículo.

Após a solicitação de consulta você receberá como retorno apenas um request_id que é um identificador único da solicitação de consulta de débitos.

🚧

Em casos onde não conseguimos enriquecer previamente os dados para consulta, retornamos solicitando a informação dos dados complementares necessários para realização da consulta.

Devido às características únicas do processo de pesquisa de débitos no estado de Sergipe, que requer o redirecionamento para uma página externa do DETRAN-SE, informamos que, no momento, nossa API não oferece suporte para consultas de débitos neste estado específico.

❗️

Campos obrigatórios por Estado

Veja aqui a lista dos estados suportados pela nossa API e os dados obrigatórios para realização da consulta.

Veja detalhadamente as informações de solicitação de consulta de débitos por meio de nossa API Reference!

Comportamento das solicitações de consulta de débitos

Após a solicitação de consulta, os débitos encontrados para o veículo informado serão enviados para o webhook que você cadastrou anteriormente, assim você conseguirá exibir o retorno e seus detalhamentos ao usuário.

❗️

Retornos webhook

Você receberá um resultado diferente com a informação no campodetaildo webhook, para os casos com retornos:

• Nenhum débito tenha sido localizado
• Veículo não tenha sido localizado
• Veículo apresente alguma restrição
• DENTRAN apresente alguma lentidão excessiva ou indisponibilidade dos serviços

Em algumas ocasiões excepcionais, se não conseguirmos acessar esses dados diretamente somente com a placa do veículo, não se preocupe! Vamos notificar você imediatamente através de um webhook. Esse alerta conterá as informações específicas que você precisará obter do seu cliente para finalizar a consulta com sucesso.

Após obter os dados complementares do seu cliente realize uma nova requisição HTTP POST ao endpoint /v2/vehicle/debts informando os dados adicionais e também o request_id da requisição original.

📘

Dica!

Informar o request_id da solicitação de consulta original ajudará nossa API a rastrear melhor as pesquisas que falham e ajudará na melhoria contínua das nossas fontes de pesquisa e consequentemente na experiência de uso por parte dos seus clientes.

🚧

Tempo de expiração das consultas

É importante lembrar que cada consulta realizada em nossa plataforma tem validade até as 23:59:59 do dia em que foi efetuada. Após esse horário, o processo de pagamento não poderá ser continuado com os dados da consulta anterior. Isso significa que será necessário realizar uma nova consulta.
Essa medida é fundamental para garantir a precisão dos valores a serem pagos. Os débitos podem sofrer alterações de um dia para o outro, e nossa política assegura que o pagamento seja efetuado com os valores corretos e atualizados, evitando discrepâncias que poderiam surgir com valores desatualizados.

Tentativas de reenvio

No caso de seu endpoint cadastrado não ser alcançado ou se ele retornar um código de status HTTP que não esteja na lista de status não recuperável, procederemos com uma nova tentativa de envio após 10 segundos.

Cada tentativa de entrega do webhook irá gerar um evento com informações de retorno do seu endoint como cabeçalho, corpo da requisição e status HTTP retornado. Realizaremos um máximo de 3 tentativas de entrega do webhook e caso nenhuma dessas tentativas ocorra com sucesso, você ainda poderá forçar o reenvio manualmente.

Clique aqui para saber mais detalhes sobre as políticas de retentativas.

📘

A retentativa de envio do webhook acontecerá de forma síncrona e você receberá o status do retorno ao final da requisição.

Para acompanhar o histórico de envios de webhooks e as respostas de cada tentativa, consulte o endpoint /webhook/{hook_id}/events/. Esse endpoint fornece uma lista detalhada com o histórico de envios, incluindo informações sobre o resultado de cada chamada.

Possuindo o identificador único do evento, você tem a opção de forçar o reenvio do mesmo, caso necessário. Isso pode ser feito através do endpoint /v2/webhook/{hook_id}/events/retry.

Explore detalhadamente as informações dos webohooks por meio de nossa API Reference!