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 17 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, Renavam e CPF/CNPJ.

Para RJ (estado de Rio de Janeiro) os campos obrigatórios são Placa, Renavam e CPF/CNPJ

Para SC (estado de Santa Catarina) o campo obrigatório são Placa e Renavam. Porém o dado que é validado é o Renavam.

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
Distrito Federal
Espírito Santo
Goiás
Maranhão
Minas Gerais
Mato Grosso
Mato Grosso do Sul
Pernambuco
Piauí
Rio de Janeiro
Rio Grande do Norte
Rondônia
Rio Grande do Sul
Roraima
Santa Catarina
São Paulo

⚠️
Atenção!
Em ambiente de sandbox é possível testar todos os cenários existentes no produto independente do estado. Mais detalhes na nossa Massa de Testes .

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 um pagamento, onde é possivel validar se o pagamento foi processado corretamente, ou se ocorreu uma 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).

🚧
Por medidas de segurança e compliance, os webhooks cadastrados no produto de Débito Veicular devem ser autenticados, para isso disponibilizamos as autenticações Basic Auth e também o token JWT.

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 ou na api Registrar Webhook Com Token - JWT. 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.

A seguir os modelos de request de registro de webhook, com as duas autenticações disponíveis no produto de Débito Veicular:

Modelo de request Basic Auth:

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"
  "clientId": "string",
  "clientSecret": "string"
}'

Modelo de request Token JWT:

curl --location --request POST 'https://sandbox.openfinance.celcoin.dev/vehicledebtsapi/v1/webhook/registerWithToken' \
--header 'accept: application/json' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer acess_token' \
--data-raw '{
  "url": "https://gatilho.com.br",
  "url_token": "https://gerartokengatilho.com.br",
  "client_id": "d35f22170e.meucarrosemdebito.celcoinapi.v5",
  "client_secret": "777f7e971374e03ae92128c10ab45e677oi5ce97f684fde8c527b123456789f",
  "content_type": "application/x-www-form-urlencoded",
  "token_type": "Bearer",
  "grant_type": "client_credentials",
  "token_field": "access_token",
  "handles": [
    {
      "name": "Escope",
      "value": "Débito Veicular"
    }
  ]
}
'

📘

Note que os endereços para realizar o cadastro do webhook são diferentes entre os tipos de autenticação.

Você deve escolher um dos modelos de autenticação disponível para cadastrar seu webhook.

Não é mais necessário cadastrar o "type:settlement" para receber os webhooks de liquidação. Apenas cadastrando os webhooks conforme exemplos, enviaremos todos os tipos de webhooks disponíveis no produto para você.

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"
}

📘
Quando configurado o webhook pela primeira vez em nossa api, será enviado um gatilho GET no webhook da api, para validar se a url enviada na request é valida. Esse processo ocorre apenas uma vez na configuração.

Modelo de webhook enviado quando configurado pela primeira vez:

{
  "type": "webhook-register",
  "errorCode": "000",
  "url": "https://webhook.site/38625015-d2f3-440a-97a5-0883a84a5575",
  "message": "URL do Webhook registrada com Sucesso"
}

📘
Para mais detalhes sobre a autenticação via token JWT, Acesse a documentação.

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

Simulação Consulta e Pagamentos Débitos Veiculares

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

Link do Figma

📘
Antes de prosseguir com a leitura desta documentação, conheça mais detalhes sobre os retornos Síncronos e Assíncronos das APIs de Débitos Veiculares.
Clique aqui

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": "JFI8753",
 "renavam": "56387604559",
 "cpfCnpj": "11111111111",
 "clientRequestId": "teste hml 20221014 01"
}
'

Parâmetros do Body:

Campo	Descrição	Tipo
state	Estado onde o veículo está registrado	String (2)
licensePlate	Placa do veículo	String (10)
renavam	Renavam do veículo	String (20)
cpfCnpj	Documento do proprietário do veículo	String (20)
clientRequestId	Identificador da transação, pode ser um ID interno da transação	String (36)

📘
Caso você tenha o serviço de Consulta Enriquecida contratado, basta informar a placa e o clientRequestId na requisição da API.

Modelo de retorno:


{
 "transactionId": 9393366,
 "message": "processing",
 "errorCode": "000"
}

Note que essa api é assíncrona, sendo assim, 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",
    "transactionId": 817210768,
    "clientRequestId": "c676c954-aa6d-4cb5-a812-c1907a53a442",
    "vehicle": {
        "uf": "DF",
        "document": "39268450828",
        "licensePlate": "DIS9865",
        "renavam": "01203988813"
    },
    "debts": [
        {
            "id": "9547B3A8-05B9-4D1C-8C72-A500BB6D93EF",
            "amount": 85.13,
            "title": "Infração Vencida - I004242123",
            "description": "I004242123 - Infração de Trânsito",
            "ait": "5E0083715",
            "dueDate": null,
            "expirationDate": null,
            "hasDiscount": false,
            "isExpired": true,
            "type": "ticket",
            "year": null,
            "required": false,
            "dependsOn": [
                "1F6F233B-468D-4F5B-A7E7-8F9AF7DF571D",
                "1ACB4E2C-8880-4B13-BA8E-86E070DD9717",
                "2D377399-CF39-4407-99F5-7553A2D77C44",
                "CC811B6A-6096-4C5E-A159-4AF437F72DCE",
                "FAB7FDDE-4864-489B-A8AB-40697649ECF0",
                "01F89CC3-152C-4E37-9072-FB8AE5FF01CD",
                "B1E18EAE-E7A0-4B6C-8E9B-45503FA32A64",
                "954AE42A-CD32-4CCA-AF9F-27E00C7593FE"
            ],
            "distinct": []
        },
        {
            "id": "01F89CC3-152C-4E37-9072-FB8AE5FF01CD",
            "amount": 296.4,
            "title": "Infração Vencida - I004242123",
            "description": "I004242123 - Infração de Trânsito",
            "ait": "5E0083715",
            "dueDate": "2022-12-28T00:00:00",
            "expirationDate": "2022-12-28T00:00:00",
            "hasDiscount": false,
            "isExpired": true,
            "type": "ticket",
            "year": null,
            "required": false,
            "dependsOn": [
                "1F6F233B-468D-4F5B-A7E7-8F9AF7DF571D",
                "9547B3A8-05B9-4D1C-8C72-A500BB6D93EF",
                "1ACB4E2C-8880-4B13-BA8E-86E070DD9717",
                "2D377399-CF39-4407-99F5-7553A2D77C44",
                "CC811B6A-6096-4C5E-A159-4AF437F72DCE",
                "FAB7FDDE-4864-489B-A8AB-40697649ECF0",
                "B1E18EAE-E7A0-4B6C-8E9B-45503FA32A64",
                "954AE42A-CD32-4CCA-AF9F-27E00C7593FE"
            ],
            "distinct": []
        },
        {
            "id": "1ACB4E2C-8880-4B13-BA8E-86E070DD9717",
            "amount": 296.4,
            "title": "Infração Vencida - I004242123",
            "description": "I004242123 - Infração de Trânsito",
            "ait": "5E0083715",
            "dueDate": "2022-12-28T00:00:00",
            "expirationDate": "2022-12-28T00:00:00",
            "hasDiscount": false,
            "isExpired": true,
            "type": "ticket",
            "year": null,
            "required": false,
            "dependsOn": [
                "1F6F233B-468D-4F5B-A7E7-8F9AF7DF571D",
                "9547B3A8-05B9-4D1C-8C72-A500BB6D93EF",
                "2D377399-CF39-4407-99F5-7553A2D77C44",
                "CC811B6A-6096-4C5E-A159-4AF437F72DCE",
                "01F89CC3-152C-4E37-9072-FB8AE5FF01CD",
                "FAB7FDDE-4864-489B-A8AB-40697649ECF0",
                "B1E18EAE-E7A0-4B6C-8E9B-45503FA32A64",
                "954AE42A-CD32-4CCA-AF9F-27E00C7593FE"
            ],
            "distinct": []
        },
        {
            "id": "1F6F233B-468D-4F5B-A7E7-8F9AF7DF571D",
            "amount": 140.5,
            "title": "Infração Vencida - I004242123",
            "description": "I004242123 - Infração de Trânsito",
            "ait": "5E0083715",
            "dueDate": "2022-12-28T00:00:00",
            "expirationDate": "2022-12-28T00:00:00",
            "hasDiscount": false,
            "isExpired": true,
            "type": "ticket",
            "year": null,
            "required": false,
            "dependsOn": [
                "9547B3A8-05B9-4D1C-8C72-A500BB6D93EF",
                "1ACB4E2C-8880-4B13-BA8E-86E070DD9717",
                "2D377399-CF39-4407-99F5-7553A2D77C44",
                "CC811B6A-6096-4C5E-A159-4AF437F72DCE",
                "FAB7FDDE-4864-489B-A8AB-40697649ECF0",
                "01F89CC3-152C-4E37-9072-FB8AE5FF01CD",
                "B1E18EAE-E7A0-4B6C-8E9B-45503FA32A64",
                "954AE42A-CD32-4CCA-AF9F-27E00C7593FE"
            ],
            "distinct": []
        },
        {
            "id": "FAB7FDDE-4864-489B-A8AB-40697649ECF0",
            "amount": 85.13,
            "title": "Infração Vencida - I004242123",
            "description": "I004242123 - Infração de Trânsito",
            "ait": "5E0083715",
            "dueDate": "2022-12-28T00:00:00",
            "expirationDate": "2022-12-28T00:00:00",
            "hasDiscount": false,
            "isExpired": true,
            "type": "ticket",
            "year": null,
            "required": false,
            "dependsOn": [
                "1F6F233B-468D-4F5B-A7E7-8F9AF7DF571D",
                "9547B3A8-05B9-4D1C-8C72-A500BB6D93EF",
                "1ACB4E2C-8880-4B13-BA8E-86E070DD9717",
                "2D377399-CF39-4407-99F5-7553A2D77C44",
                "CC811B6A-6096-4C5E-A159-4AF437F72DCE",
                "01F89CC3-152C-4E37-9072-FB8AE5FF01CD",
                "B1E18EAE-E7A0-4B6C-8E9B-45503FA32A64",
                "954AE42A-CD32-4CCA-AF9F-27E00C7593FE"
            ],
            "distinct": []
        },
        {
            "id": "CC811B6A-6096-4C5E-A159-4AF437F72DCE",
            "amount": 127.69,
            "title": "Infração em Notificação - I004242492",
            "description": "I004242492 - Infração de Trânsito",
            "ait": "5E0083715",
            "dueDate": null,
            "expirationDate": "2022-12-28T00:00:00",
            "hasDiscount": true,
            "isExpired": false,
            "type": "ticket",
            "year": null,
            "required": false,
            "dependsOn": [
                "1F6F233B-468D-4F5B-A7E7-8F9AF7DF571D",
                "9547B3A8-05B9-4D1C-8C72-A500BB6D93EF",
                "1ACB4E2C-8880-4B13-BA8E-86E070DD9717",
                "2D377399-CF39-4407-99F5-7553A2D77C44",
                "FAB7FDDE-4864-489B-A8AB-40697649ECF0",
                "01F89CC3-152C-4E37-9072-FB8AE5FF01CD",
                "B1E18EAE-E7A0-4B6C-8E9B-45503FA32A64",
                "954AE42A-CD32-4CCA-AF9F-27E00C7593FE"
            ],
            "distinct": []
        },
        {
            "id": "954AE42A-CD32-4CCA-AF9F-27E00C7593FE",
            "amount": 85.13,
            "title": "Infração em Notificação - I004242492",
            "description": "I004242492 - Infração de Trânsito",
            "ait": "5E0083715",
            "dueDate": null,
            "expirationDate": "2022-12-28T00:00:00",
            "hasDiscount": true,
            "isExpired": false,
            "type": "ticket",
            "year": null,
            "required": false,
            "dependsOn": [
                "1F6F233B-468D-4F5B-A7E7-8F9AF7DF571D",
                "9547B3A8-05B9-4D1C-8C72-A500BB6D93EF",
                "1ACB4E2C-8880-4B13-BA8E-86E070DD9717",
                "2D377399-CF39-4407-99F5-7553A2D77C44",
                "CC811B6A-6096-4C5E-A159-4AF437F72DCE",
                "FAB7FDDE-4864-489B-A8AB-40697649ECF0",
                "01F89CC3-152C-4E37-9072-FB8AE5FF01CD",
                "B1E18EAE-E7A0-4B6C-8E9B-45503FA32A64"
            ],
            "distinct": []
        },
        {
            "id": "B1E18EAE-E7A0-4B6C-8E9B-45503FA32A64",
            "amount": 85.13,
            "title": "Infração a Vencer - CJ00729123",
            "description": "CJ00729123 - Infração de Trânsito",
            "ait": "5E0083715",
            "dueDate": "2022-12-28T00:00:00",
            "expirationDate": "2022-12-28T00:00:00",
            "hasDiscount": true,
            "isExpired": false,
            "type": "ticket",
            "year": null,
            "required": false,
            "dependsOn": [
                "1F6F233B-468D-4F5B-A7E7-8F9AF7DF571D",
                "9547B3A8-05B9-4D1C-8C72-A500BB6D93EF",
                "1ACB4E2C-8880-4B13-BA8E-86E070DD9717",
                "2D377399-CF39-4407-99F5-7553A2D77C44",
                "CC811B6A-6096-4C5E-A159-4AF437F72DCE",
                "FAB7FDDE-4864-489B-A8AB-40697649ECF0",
                "01F89CC3-152C-4E37-9072-FB8AE5FF01CD",
                "954AE42A-CD32-4CCA-AF9F-27E00C7593FE"
            ],
            "distinct": []
        },
        {
            "id": "2D377399-CF39-4407-99F5-7553A2D77C44",
            "amount": 206.86,
            "title": "Infração a Vencer - CJ00729123",
            "description": "CJ00729123 - Infração de Trânsito",
            "ait": "5E0083715",
            "dueDate": "2022-12-28T00:00:00",
            "expirationDate": "2022-12-28T00:00:00",
            "hasDiscount": true,
            "isExpired": false,
            "type": "ticket",
            "year": null,
            "required": false,
            "dependsOn": [
                "1F6F233B-468D-4F5B-A7E7-8F9AF7DF571D",
                "9547B3A8-05B9-4D1C-8C72-A500BB6D93EF",
                "1ACB4E2C-8880-4B13-BA8E-86E070DD9717",
                "CC811B6A-6096-4C5E-A159-4AF437F72DCE",
                "FAB7FDDE-4864-489B-A8AB-40697649ECF0",
                "01F89CC3-152C-4E37-9072-FB8AE5FF01CD",
                "B1E18EAE-E7A0-4B6C-8E9B-45503FA32A64",
                "954AE42A-CD32-4CCA-AF9F-27E00C7593FE"
            ],
            "distinct": []
        },
        {
            "id": "E9B42A19-7E70-4E86-98A6-82B6EECC8EE4",
            "amount": 5.23,
            "title": "Seguro Obrigatório 2022",
            "description": "Seguro Obritatório 2022",
            "dueDate": null,
            "expirationDate": "2022-12-28T00:00:00",
            "hasDiscount": false,
            "isExpired": true,
            "type": "insurance",
            "year": 2022,
            "required": false,
            "dependsOn": [],
            "distinct": [
                "312D6A5F-2B5A-4694-84DA-F640FC01CC74"
            ]
        },
        {
            "id": "312D6A5F-2B5A-4694-84DA-F640FC01CC74",
            "amount": 1009.36,
            "title": "Licenciamento 2022",
            "description": "Licenciamento 2022",
            "dueDate": null,
            "expirationDate": "2022-12-28T00:00:00",
            "hasDiscount": false,
            "isExpired": true,
            "type": "licensing",
            "year": 2022,
            "required": false,
            "dependsOn":[],
            "distinct": [
                "E9B42A19-7E70-4E86-98A6-82B6EECC8EE4"
            ]
        }
    ]
}

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",
  "transactionId": 817622466,
  "clientRequestId": "0a384059-eaf0-4240-9dc7-f4125671b4c9",
  "vehicle": {
    "uf": "DF",
    "document": "3138777503",
    "licensePlate": "RCK0E56",
    "renavam": "33864569420"
  }
}

Modelo de estrutura do webhook para veículos não encontrados:

{
    "type": "VehicleNotFound",
    "transactionId": 817211803,
    "clientRequestId": "0a384059-eaf0-4240-9dc7-f4125671b4c9"
}

Caso os serviços dos DETRANS apresentarem alguma indisponibilidade, lentidão excessiva ou qualquer outro tipo de erro que inviabilize a consulta será enviado um webhook com essa informação.

{
    "type": "search-error-event",
    "status": "ERROR",
    "transactionId": 817211803,
    "clientRequestId": "bbf6c1c8-6c60-4806-9454-21a71e1ce1df",
    "error": [
        {
            "errorCode": "900",
            "message": "Serviço indisponível."
        }
    ]
}

Ao realizar a consulta enriquecida e for identificado um estado que não está disponível no produto, será enviado o seguinte webhook

{
    "type": "search-error-event",
    "status": "ERROR",
    "transactionId": 817211803,
    "clientRequestId": "bbf6c1c8-6c60-4806-9454-21a71e1ce1df",
    "error": [
        {
            "errorCode": "901",
            "message": "O estado {UF} não está disponível para consulta e pagamento."
        }
    ]
}

Tabela descritiva dos campos retornados no webhook

Campo	Descrição	Tipo
transactionId	Identificador da operação de consulta	Numeric(BigInt)
clientRequestId	Identificador da transação, pode ser um ID interno da transação	String
uf	Estado do veículo informado na consulta	String
document	Cpf/Cnpj informado na consulta	String
licensePlate	Placa do veículo informado na consulta	String
renavam	Renavam do veículo informado na consulta	String
id	Identificador do débito	String
amount	Valor a ser pago do débito. Já calculado os juros ou desconto caso aplicado.	Numeric
title	Nome do débito	String
description	Descrição do débito	String
ait	Identificador da multa no Detran. O Auto de Infração (AIT), também conhecido como multa de trânsito, é um documento emitido por autoridade de trânsito competente quando uma infração é cometida. Ele registra os detalhes da infração. Esse dado será apresentado apenas em débitos do tipo multa (ticket). Inicialmente disponível para o estado de São Paulo.	String
dueDate	Data de vencimento original da guia. Mesmo que ela esteja vencida a data que será apresentada nesse campo permanece a do vencimento original. Esse campo pode ser apresentado como nulo.	String
expirationDate	Data máxima permitida do pagamento. Em casos débitos vencidos, o campo expirationDate será a data da consulta, onde a cada dia o valor do amount será atualizado. Esse campo pode ser apresentado como nulo.	String
hasDiscount	Contém a informação se possui desconto. Não é exibido o valor de desconto	Boolean (True or False)
isExpired	Identifica se a consulta já está expirada.	Boolean (True or False)
type	Tipo de débito (IPVA, Multa, Licenciamento) Para mais detalhes veja a tabela abaixo	String
year	Ano do débito	Numeric
required	Indica a obrigatoriedade daquele débito no pagamento	Boolean (True or False)
dependsOn	É uma lista de IDs de outros débitos que indica a necessidade daquele débito estar acompanhado de outros no pagamento	Array (String)
distinct	É uma lista de IDs de outros débitos que indica débitos que não devem ser pagos em conjunto	Array (String)

❗️

Uma consulta é válida até o final do dia de sua solicitação, após isso não é mais possível seguir com seu fluxo após esse período.

Ao solicitar uma consulta, realizamos a validação do renavam, que consiste em analisar se o dígito verificador é válido ou não. Caso não seja válido não prosseguiremos com a consulta e retornaremos erro na API. Essa validação é realizada tanto no ambiente de sandbox quanto de produção. Mais detalhes, consulte nossa tabela de erros.

O ambiente do Detran do Estado de SP passa por manutenções durante a madrugada, entre 00h e 07h, nesse período não é possível realizar consultas para esse estado. Mais detalhes, consulte nossa tabela de erros.

Quando retornados na consulta os débitos dependentes, distintos e obrigatórios, possuem regras para a solicitação de pagamento que devem ser seguidas , acesse o link a seguir da documentação para melhor entendimentolink.

Para os estados de Goiás, Maranhão, Mato Grosso do Sul e Rio Grande do Sul serão retornados na consulta somente IPVA Cota Única.

Para o estado de Mato Grosso do Sul todos os débitos em aberto retornados na consulta, obrigatoriamente eles devem ser pagos, caso avance para o fluxo de pagamento.

Tabela que representa os types retornados no Webhook.

Type	Descrição
services	Taxas de serviços diversos, como multa de pátio
ticket	Multas de trânsito
renainf_ticket	Multas gerenciadas pelo RENAINF
ipva	IPVA do veículo. É equivalente ao “ipva_unique”
licensing	Taxa de licenciamento do veículo
ipva_unique	Cota única para o IPVA do veículo
ipva_installment	Cota parcelada para o IPVA do veículo
insurance	Taxa de Seguro Obrigatório do veículo (DPVAT)
expired_insurance	Taxa vencida de Seguro Obrigatório do Veículo

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": 9393366,
 "debtIdList": [
   "28850DB5-05EA-4461-A84A-EE04EF9B545D"
 ],
 "clientRequestId": "teste hml 20221014 01"
}

Caso você tenha contratado o serviço de parcelamento dos débitos, utilizando o próprio serviço de adquirência, é necessário informar os dados acordados do parcelamento com seu usuário no request de pagamento.

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": 9393366,
 "debtIdList": [
   "28850DB5-05EA-4461-A84A-EE04EF9B545D"
 ],
 "clientRequestId": "teste hml 20221014 01",
 "installments": {
		"amount": 1200,
		"quantity": 10,
		"value": 120
	}
}

Parâmetros do Body:

Campo	Descrição	Tipo
debtIdList	Lista de débitos a serem pagos	Array (String 36)
transactionId	Id gerado na consulta de seus débitos	Numeric(BigInt)
clientRequestId	Identificador da transação, pode ser um ID interno da transação.	String (36)
amount	Valor Total do Parcelamento, já incluindo as taxas	Numeric(BigInt)
quantity	Quantidade Total de Parcelas	Numeric(BigInt)
value	Valor de cada Parcela	Numeric(BigInt)

Modelo de retorno:

{
 "paymentId": "507B6664-03AE-40EB-9D53-6D27F25587EA",
 "errorCode": "000",
 "message": "Solicitação recebida com sucesso. Aguarde a resposta do processamento no webhook cadastrado."
}

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

Modelo de estrutura Json enviada para o webhook:

{
    "type": "receipt",
    "paymentId": "29C32257-2DDB-41B0-9BB0-4CB64783443F",
    "receipt": {
        "licensePlate": "DIS9865",
        "renavam": "01203988813",
        "state": "DF",
        "description": "Licenciamento 2022",
        "debtId": "312D6A5F-2B5A-4694-84DA-F640FC01CC74",
        "amount": 1009.36,
        "authentication": "F2.2D.2C.32.74.24.11.59.81.C1.FD.C2.91.A3.BF.93",
        "dueDate": "2022-12-28T00:00:00",
        "clientRequestId": "29d648b8-594f-436c-ba53-a543fdaf9467",
        "year": 2022,
        "payDate": "2022-12-28T00:00:00"
    }
}

Assim que o débito for liquidado pelos órgãos competentes você receberá um segundo webhook contendo as informações de baixa.

Modelo de estrutura Json enviada para o webhook:

{
		"type": "settlement-events",
		"status": "SUCCESS",
		"paymentId": "D5011AAF-3EB9-41FC-92BB-A1198F4A7E10",
		"clientRequestId":"webhookLiquidacaoSucesso",
		"debtId": "E6D1E0E0-AD5E-4A1C-9E3C-91E02174A485",
		"metaDetran": [
			{
				"state": "SP"
			},
			{
				"licencePlate": "ABC6E61"
			},
			{
				"renavam": "00322732381"
			},
			{
				"document": "05388365760"
			},
			{
				"nsuDetran": "000220114622"
			},
			{
				"settlementBank": "BRADESCO"
			},
			{
				"settlementDateTime": "2023-10-27T19:05:12"
			},
			{
				"amount": "134.20"
			},
			{
				"dueDate": "2023-10-27T00:00:00"
			},
			{
				"debitType": "ticket"
			},
			{
				"year": "2023"
			},
			{
				"debtDescription": "Transitar velocidade superior a maxima permitida em ate 20%"
			}
		]
	}

🚧
Lembrando que a baixa do débito no Detran pode ocorrer entre 3 a 5 dias úteis. Até lá o débito pode ser apresentado em consultas posteriores.

🚧
A depender do Detran, não é disponibilizado todos os dados dos campos do comprovante de liquidação. Caso o dado não seja enviado, o campo será retornado em branco

Caso a Celcoin não consiga realizar o pagamento no Detran, ou ocorra um estorno, será retornado o webhook abaixo.

Modelo de estrutura Json enviada para o webhook:

{
  "paymentId": "9B351F9F-E021-4050-9489-DC1834DFCF4E",
  "clientRequestId": "1672424961",
  "type": "debitNotAuthorized",
  "processedDate": "2022-12-30T18:29:33",
  "errorCode":"900",
  "errorMessage": "Transação não autorizada",
  "debitId": "D22426B6-35A5-4744-A07E-4067AD98F067"
}

Tabela que representa os errorCode retornados no Webhook de Débito Não Autorizado

Mensagem de Erro	Código do Erro	Descrição
Esse pagamento está com processo de liquidação aberto	100	Será retornado esse código de erro ao solicitar um pagamento para um débito que já esteja em processo de liquidação em aberto
Esse débito está vinculado a outro pagamento com processo de liquidação aberto	110	Será retornado esse código quando solicitado o pagamento de um débito que depende da liquidação de outro que está em processo de liquidação
Saldo Insuficiente para efetuar o pagamento do Débito	120	Podem ocorrer situações em que mesmo após validar o saldo via API, a sua conta bolsão fique sem saldo, por exemplo, realizar o pagamento de uma recarga e com isso o saldo não é suficiente para quitar todos os débitos veiculares.
Detran Indisponível para Pagamento	130	Será retornado esse erro em casos em que os Detran estiver indisponível para solicitação de pagamento.
Transação não autorizada	900	Ao solicitar a baixa junto aos órgãos, caso ocorra algum problema na liquidação dos débitos, retornaremos essa mensagem de erro.

🚧
Os códigos de erro 100 e 110, Só irão ocorrer apenas quando o nosso sistema identificar um possível pagamento em duplicidade. Não podemos garantir a unicidade dos débitos para todos os Detrans.

📘
O exemplo do Webhook de Débito não autorizado reflete o cenário de "Transação não autorizada". Nota-se que podemos ter outros códigos de erro, conforme tabela acima.

Nesse cenário recomendamos que seja realizado a abertura de um ticket para o nosso time analisar o ocorrido.

❗️
Atenção!

Os ids dos débitos mudam a cada nova consulta, exceto para o estado de SP, onde o Id permanece o mesmo, por padrão uma consulta é válida até o final do dia em que foi realizada, e os ids não alteram nesse período até que seja solicitado o pagamento.

Uma vez que realizado uma consulta e nela é retornado mais de um débito veicular, caso seja selecionado no momento do pagamento realizar apenas a quitação de um débito, se faz necessário realizar uma nova consulta, isso ocorre, pois o Detran não realiza a liquidação do pagamento no momento que recebe a solicitação.

Criamos essa dinâmica para garantir que não ocorra duplicidade de um pagamento.

Os Comprovantes são enviados em um JSON em campos separados. Isso permite compor o comprovante de acordo com a necessidade de seu negócio.

O comprovante é individualizado, isso quer dizer que ao solicitar um pagamento onde exista mais de um débito, você receberá mais de um webhook de comprovante, conforme eles forem liquidados pelo órgão

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.

Sobre a API de Débito Veicular

Caso de uso:

Limitações e exceções:

Tipos de débitos:

Estados suportados:

⚠️
Atenção!

Configurando webhook (gatilho)

🚧
Por medidas de segurança e compliance, os webhooks cadastrados no produto de Débito Veicular devem ser autenticados, para isso disponibilizamos as autenticações Basic Auth e também o token JWT.

📘

📘
Quando configurado o webhook pela primeira vez em nossa api, será enviado um gatilho GET no webhook da api, para validar se a url enviada na request é valida. Esse processo ocorre apenas uma vez na configuração.

📘
Para mais detalhes sobre a autenticação via token JWT, Acesse a documentação.

Simulação Consulta e Pagamentos Débitos Veiculares

📘
Antes de prosseguir com a leitura desta documentação, conheça mais detalhes sobre os retornos Síncronos e Assíncronos das APIs de Débitos Veiculares.

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

📘
Caso você tenha o serviço de Consulta Enriquecida contratado, basta informar a placa e o clientRequestId na requisição da API.

Tabela descritiva dos campos retornados no webhook

❗️

Uma consulta é válida até o final do dia de sua solicitação, após isso não é mais possível seguir com seu fluxo após esse período.

Tabela que representa os types retornados no Webhook.

Executar o pagamento de um débito veicular

🚧
Lembrando que a baixa do débito no Detran pode ocorrer entre 3 a 5 dias úteis. Até lá o débito pode ser apresentado em consultas posteriores.

🚧
A depender do Detran, não é disponibilizado todos os dados dos campos do comprovante de liquidação. Caso o dado não seja enviado, o campo será retornado em branco

🚧
Os códigos de erro 100 e 110, Só irão ocorrer apenas quando o nosso sistema identificar um possível pagamento em duplicidade. Não podemos garantir a unicidade dos débitos para todos os Detrans.

📘
O exemplo do Webhook de Débito não autorizado reflete o cenário de "Transação não autorizada". Nota-se que podemos ter outros códigos de erro, conforme tabela acima.

❗️
Atenção!

Caso de uso:

Limitações e exceções:

Tipos de débitos:

Estados suportados:

⚠️Atenção!

Configurando webhook (gatilho)

🚧Por medidas de segurança e compliance, os webhooks cadastrados no produto de Débito Veicular devem ser autenticados, para isso disponibilizamos as autenticações Basic Auth e também o token JWT.

📘

📘Quando configurado o webhook pela primeira vez em nossa api, será enviado um gatilho GET no webhook da api, para validar se a url enviada na request é valida. Esse processo ocorre apenas uma vez na configuração.

📘Para mais detalhes sobre a autenticação via token JWT, Acesse a documentação.

Simulação Consulta e Pagamentos Débitos Veiculares

📘Antes de prosseguir com a leitura desta documentação, conheça mais detalhes sobre os retornos Síncronos e Assíncronos das APIs de Débitos Veiculares.

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

📘Caso você tenha o serviço de Consulta Enriquecida contratado, basta informar a placa e o clientRequestId na requisição da API.

Tabela descritiva dos campos retornados no webhook

❗️ Uma consulta é válida até o final do dia de sua solicitação, após isso não é mais possível seguir com seu fluxo após esse período.

Tabela que representa os types retornados no Webhook.

Executar o pagamento de um débito veicular

🚧Lembrando que a baixa do débito no Detran pode ocorrer entre 3 a 5 dias úteis. Até lá o débito pode ser apresentado em consultas posteriores.

🚧A depender do Detran, não é disponibilizado todos os dados dos campos do comprovante de liquidação. Caso o dado não seja enviado, o campo será retornado em branco

🚧Os códigos de erro 100 e 110, Só irão ocorrer apenas quando o nosso sistema identificar um possível pagamento em duplicidade. Não podemos garantir a unicidade dos débitos para todos os Detrans.

📘O exemplo do Webhook de Débito não autorizado reflete o cenário de "Transação não autorizada". Nota-se que podemos ter outros códigos de erro, conforme tabela acima.

❗️Atenção!

⚠️
Atenção!

🚧
Por medidas de segurança e compliance, os webhooks cadastrados no produto de Débito Veicular devem ser autenticados, para isso disponibilizamos as autenticações Basic Auth e também o token JWT.

📘
Quando configurado o webhook pela primeira vez em nossa api, será enviado um gatilho GET no webhook da api, para validar se a url enviada na request é valida. Esse processo ocorre apenas uma vez na configuração.

📘
Para mais detalhes sobre a autenticação via token JWT, Acesse a documentação.

📘
Antes de prosseguir com a leitura desta documentação, conheça mais detalhes sobre os retornos Síncronos e Assíncronos das APIs de Débitos Veiculares.

📘
Caso você tenha o serviço de Consulta Enriquecida contratado, basta informar a placa e o clientRequestId na requisição da API.

❗️

Uma consulta é válida até o final do dia de sua solicitação, após isso não é mais possível seguir com seu fluxo após esse período.

🚧
Lembrando que a baixa do débito no Detran pode ocorrer entre 3 a 5 dias úteis. Até lá o débito pode ser apresentado em consultas posteriores.

🚧
A depender do Detran, não é disponibilizado todos os dados dos campos do comprovante de liquidação. Caso o dado não seja enviado, o campo será retornado em branco

🚧
Os códigos de erro 100 e 110, Só irão ocorrer apenas quando o nosso sistema identificar um possível pagamento em duplicidade. Não podemos garantir a unicidade dos débitos para todos os Detrans.

📘
O exemplo do Webhook de Débito não autorizado reflete o cenário de "Transação não autorizada". Nota-se que podemos ter outros códigos de erro, conforme tabela acima.

❗️
Atenção!