Sobre a API de Débito Veicular

A API de débito veicular permite a criação de aplicações que possibilitam a pesquisa e liquidação de débitos de veículos, tais como multas, IPVA, licenciamento e seguro obrigatório, elevando o número de transações e o tempo de uso do aplicativo pelo usuário. Neste serviço o cliente consegue regularizar todos os débitos do veículo em uma única jornada e com abrangência de 95% da frota nacional de veículos em 20 estados.

Caso de uso:

Como Fintech quero conseguir disponibilizar para os meus usuários a possibilidade de realizar pagamento de débitos veiculares informando o estado, placa do veículo, renavam e CPF, ou CNPJ com objetivo de ter essa praticidade em minha plataforma e ou sistema.

Nesse artigo você irá aprender sobre:

  • Limitações e exceções
  • Tipos de Débitos
  • Estados Suportados
  • Configurar um webhook para receber as informações dos débitos.
  • Consultar se um veículo tem débitos pendentes
  • Executar o pagamento de um débito veicular

Pré requisitos para implementação:

  • Possuir uma chave api da Celcoin, para mais informações acessar esse link
  • Ter familiaridade com apis Rest usando o protocolo OAuth 2.0.
  • Ter o produto/solução contratada, caso queira usar a funcionalidade em ambiente produtivo, por favor entre em contato com a nossa equipe comercial através do e-mail [email protected] Para dúvidas técnicas, basta entrar em contato com o suporte através do link.

Limitações e exceções:

Para PE (estado de Pernambuco) os campos obrigatórios são Placa, CPF/CNPJ.
Para PB (estado da Paraíba) os campos obrigatórios são Placa, Renavam e CPF/CNPJ.

Tipos de débitos:

  • Taxas de serviços diversos, como:
  • Multa de pátio
  • Multas de trânsito
  • Multas gerenciadas pelo RENAINF
  • IPVA do veículo
  • Taxa de licenciamento do veículo
  • Cota única para o IPVA do veículo
  • Cota parcelada para o IPVA do veículo
  • Taxa de Seguro Obrigatório do veículo (DPVAT)
  • Taxa vencida de Seguro Obrigatório do Veículo

Estados suportados:

É possível consultar e quitar débitos para veículos dos seguintes estados:

  • Alagoas
  • Bahia
  • Ceará
  • Distrito Federal
  • Espírito Santo
  • Goiás
  • Maranhão
  • Mato Grosso
  • Mato Grosso do Sul
  • Minas Gerais
  • Paraíba
  • Paraná
  • Pernambuco
  • Piauí
  • Rio de Janeiro
  • Rio Grande do Norte
  • Rio Grande do Sul
  • Roraima
  • Santa Catarina
  • São Paulo

Configurando webhook (gatilho)

Para conseguir receber da Celcoin os débitos veiculares de seus usuários é necessário realizar a configuração de um webhook.

O webhook é uma forma de receber informações de forma assíncrona, geralmente são disparados gatilhos no formato JSON quando um evento acontece, na prática para as apis de débito veiculares será usado para receber informações em seu sistema sobre os débitos veiculares que foram consultados, ou quando efetuado a tentativa de pagamento, para validar se ocorreu com sucesso, ou falha.

Portanto em primeiro lugar é preciso se autenticar na api da Celcoin, caso tenha dúvida em como realizar esse processo indicamos a leitura do artigo (Obtendo suas credenciais).

Ao se autenticar na api será retornado um acess_token, com esse valor deve ser realizado um POST na api Registra uma URL para recebimento de notificações via Webhook. Lembre-se que no header deve ser passado a propriedade Authorization populando o seu valor com Bearer + acess_token, retornado da chamada de autenticação, seguindo os padrões o Oauth 2.0.

Modelo de request:

curl --location --request POST 'https://sandbox.openfinance.celcoin.dev/vehicledebtsapi/v1/webhook/register' \
--header 'accept: application/json' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer acess_token' \
--data-raw '{
  "url": "https://gatilho.com.br"
}'

Se a configuração ocorrer como esperado nossa api retornará a seguinte informação:

Modelo de response:

{
    "message": "Nova URL atualizada com sucesso",
    "errorCode": "000"
}

Com webhook configurado podemos partir para o processo de liquidação dos débitos veiculares:

Com objetivo de exibir como pode ser o pagamento de um débito veicular para um usuário, criamos essa apresentação que simula o processo como todo:

Link do Figma

Consultar se um veículo tem débitos pendentes:

Para obter as informações de um débito veicular é necessário realizar essa consulta na api (Gera um pedido assíncrono de consulta de débitos veiculares) utilizando o método POST, onde precisa ser preenchido no body algumas informações como estado, renavam, placa do veículo, CPF ou CNPJ.

Modelo de requisição:

curl --location --request POST 'https://sandbox.openfinance.celcoin.dev/vehicledebtsapi/v1/debts' \
--header 'accept: application/json' \
--header 'Authorization: Bearer acess_token' \
--header 'Content-Type: application/json' \
--data-raw '{
  "state": "DF",
  "licensePlate": "DED9933",
  "renavam": "48648263707",
  "cpfCnpj": "11111111111",
  "externalTerminal": "12345",
  "externalNsu": 11223344
}'

Modelo de retorno:

{
    "transactionId": 9106879,
    "data": {
        "protocol": "A7WPIHZP",
        "status": "Solicitação recebida com sucesso. Aguarde a resposta do processamento no webhook cadastrado."
    },
    "message": "Sucesso",
    "errorCode": "000"
}

Note que essa api é assíncrona, sendo assim, em até 10 segundos a Celcoin irá retornar para o webhook configurado em nossa api quais são os débitos que esse cliente tem para o veículo que foi feito a busca.

Modelo de estrutura do webhook para veículos com débitos:

{
  "Type": "Debts",
  "Protocol": "T0NV3PZP",
  "TransactionId": 9272347,
  "LicensePlate": "JJK5B07",
  "Debts": [
    {
      "DebtId": "5VARZUJQDE9C",
      "title": "Infração Vencida - I004242123",
      "amount": 131.46,
      "description": "I004242123 - Multa",
      "due_date": "2022-05-18 00:00:00",
      "expiration_date": "2022-05-18 00:00:00",
      "fine": null,
      "has_discount": false,
      "is_expired": true,
      "interest": null,
      "type": "ticket",
      "year": null,
      "ipva": null,
      "distinct": [],
      "depends_on": [],
      "required": false
    },
    {
      "DebtId": "PXYOM6AA6H42",
      "title": "Infração em Notificação - I004242492",
      "amount": 156.18,
      "description": "I004242492 - Infração de Trânsito",
      "due_date": null,
      "expiration_date": "2022-05-18 00:00:00",
      "fine": null,
      "has_discount": true,
      "is_expired": false,
      "interest": null,
      "type": "ticket",
      "year": null,
      "ipva": null,
      "distinct": [],
      "depends_on": [],
      "required": false
    },
    {
      "DebtId": "3LSYJ3KS0QL4",
      "title": "Infração em Notificação - I004242492",
      "amount": 131.46,
      "description": "I004242492 - Multa",
      "due_date": null,
      "expiration_date": "2022-05-18 00:00:00",
      "fine": null,
      "has_discount": true,
      "is_expired": false,
      "interest": null,
      "type": "ticket",
      "year": null,
      "ipva": null,
      "distinct": [],
      "depends_on": [],
      "required": false
    },
    {
      "DebtId": "OBJ4PG0JM448",
      "title": "Infração em Notificação - I004242492",
      "amount": 131.46,
      "description": "I004242492 - Multa",
      "due_date": null,
      "expiration_date": "2022-05-18 00:00:00",
      "fine": null,
      "has_discount": true,
      "is_expired": false,
      "interest": null,
      "type": "ticket",
      "year": null,
      "ipva": null,
      "distinct": [],
      "depends_on": [],
      "required": false
    },
    {
      "DebtId": "8MNZQM2R16FO",
      "title": "Infração em Notificação - I004242492",
      "amount": 950.4,
      "description": "I004242492 - Multa",
      "due_date": null,
      "expiration_date": "2022-05-18 00:00:00",
      "fine": null,
      "has_discount": true,
      "is_expired": false,
      "interest": null,
      "type": "ticket",
      "year": null,
      "ipva": null,
      "distinct": [],
      "depends_on": [],
      "required": false
    },
    {
      "DebtId": "F1SVZI3LFTK1",
      "title": "Seguro Obrigatório 2022",
      "amount": 5.23,
      "description": "Seguro Obritatório 2022",
      "due_date": null,
      "expiration_date": "2022-05-18 00:00:00",
      "fine": null,
      "has_discount": false,
      "is_expired": true,
      "interest": null,
      "type": "insurance",
      "year": 2022,
      "ipva": null,
      "distinct": [],
      "depends_on": [],
      "required": false
    },
    {
      "DebtId": "Q70CPZCTBAKX",
      "title": "Licenciamento 2022",
      "amount": 1582,
      "description": "Licenciamento 2022",
      "due_date": null,
      "expiration_date": "2022-05-18 00:00:00",
      "fine": null,
      "has_discount": false,
      "is_expired": true,
      "interest": null,
      "type": "licensing",
      "year": 2022,
      "ipva": null,
      "distinct": [],
      "depends_on": [],
      "required": false
    }
  ]
}

Tabela que representa os types retornados no Webhook.

TypeDescrição
servicesTaxas de serviços diversos, como multa de pátio
ticketMultas de trânsito
renainf_ticketMultas gerenciadas pelo RENAINF
ipvaIPVA do veículo. É equivalente ao “ipva_unique”
licensingTaxa de licenciamento do veículo
ipva_uniqueCota única para o IPVA do veículo
ipva_installmentCota parcelada para o IPVA do veículo
insuranceTaxa de Seguro Obrigatório do veículo (DPVAT)
expired_insuranceTaxa vencida de Seguro Obrigatório do Veículo

Caso o veículo não tenha débitos pendentes, será enviado um webhook com essa informação.

Modelo de estrutura do webhook para veículos sem débitos:

{
  "Type": "VehicleWithoutDebts",
  "Protocol": "1EHVEOZP",
  "TransactionId": 816286424,
  "Status": "VEHICLE_WITHOUT_DEBTS",
  "Message": "Pesquisa realizada e veículo não possui débitos."
}

Executar o pagamento de um débito veicular

Ao receber o webhook deve ser realizado a liquidação do débito veicular, para isso é necessário um POST na api Cria um pagamento, informando o transactionid (id único gerado para a pesquisa de débitos) e a lista de débitos que o usuário selecionou para efetuar o pagamento.

Modelo de request:

curl -X 'POST' \
  'https://sandbox.openfinance.celcoin.dev/vehicledebtsapi/v1/payDebts' \
  -H 'accept: application/json' \
  -H 'Authorization: Bearer acess_token' \
  -H 'Content-Type: application/json' \
  -d '{
  "transactionId": 999999,
  "debtIdList": [
    "N4CS480I8F1U",
    "YKCFDJAX4CBT"
  ],
  "externalTerminal": "12345",
  "externalNsu": 11223344
}'

Modelo de retorno:

{
  "transactionId": 999999,
  "message": "Solicitação recebida com sucesso. Aguarde a resposta do processamento no webhook cadastrado.",
  "errorCode": "000"
}

Note que essa chamada também é assíncrona, logo enviaremos se a liquidação ocorreu com sucesso para o webhook configurado novamente.

Modelo de estrutura Json enviada para o webhook:

[
  {
    "DebtId": [
      "N4CS480I8F1U",
      "YKCFDJAX4CBT"
    ],
    "TransactionId": 8870249,
    "ErrorCode": "SUCESSO",
    "Message": "000",
    "Receipt": " COMPROVANTE - PAGTO DE DEBITO VEICULAR \r\n            03/02/2022 08:50            \r\n           TERM 11 AGENTE 999           \r\nPROTOCOLO                0008870249               \r\n----------------------------------------\r\n         DETALHES DO PAGAMENTO          \r\n\r\n  TIPO: INFRAÇÃO VENCIDA - I004242123   \r\n         VENCIMENTO: 03/02/2022         \r\n IDENTIFICADOR DO DÉBITO: N4CS480I8F1U  \r\n             VALOR: 204,79              \r\n\r\n  TIPO: INFRAÇÃO VENCIDA - I004242123   \r\n         VENCIMENTO: 03/02/2022         \r\n IDENTIFICADOR DO DÉBITO: YKCFDJAX4CBT  \r\n             VALOR: 134,53              \r\n\r\n----------------------------------------\r\n   DATA DO PAGAMENTO 03/02/2022 08:50   \r\n\r\n         VALOR TOTAL R$ 339,32          \r\n\r\n    PAGAMENTO REALIZADO COM SUCESSO!    \r\n----------------------------------------\r\n              AUTENTICACAO              \r\n        1C.22.95.5E.B5.B8.6B.52         \r\n        2C.E5.94.4E.22.79.C8.BB         \r\n",
    "Type": "PayDebt"
  }
]

Ao receber esse webhook basta exibir para o usuário que o pagamento ocorreu com sucesso.
Para mais informações sobre os possíveis erros mapeados para cada api indicamos que seja realizada a busca em nossa documentação através do link.


Did this page help you?