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 é 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:

CampoDescriçãoTipo
stateEstado onde o veículo está registradoString (2)
licensePlatePlaca do veículoString (10)
renavamRenavam do veículoString (20)
cpfCnpjDocumento do proprietário do veículoString (20)
clientRequestIdIdentificador da transação, pode ser um ID interno da transaçãoString (36)

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",
            "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",
            "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",
            "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",
            "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",
            "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",
            "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",
            "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",
            "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",
            "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."
        }
    ]
}

Tabela descritiva dos campos retornados no webhook

CampoDescriçãoTipo
transactionIdIdentificador da operação de consultaNumeric(BigInt)
clientRequestIdIdentificador da transação, pode ser um ID interno da transaçãoString
ufEstado do veículo informado na consultaString
documentCpf/Cnpj informado na consultaString
licensePlatePlaca do veículo informado na consultaString
renavamRenavam do veículo informado na consultaString
idIdentificador do débitoString
amountValor a ser pago do débito. Já calculado os juros ou desconto caso aplicado.Numeric
titleNome do débitoString
descriptionDescrição do débitoString
dueDateData 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
expirationDateData 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
hasDiscountContém a informação se possui desconto. Não é exibido o valor de descontoBoolean (True or False)
isExpiredIdentifica se a consulta já está expirada.Boolean (True or False)
typeTipo de débito (IPVA, Multa, Licenciamento) Para mais detalhes veja a tabela abaixoString
yearAno do débitoNumeric
requiredIndica a obrigatoriedade daquele débito no pagamentoBoolean (True or False)
dependsOnÉ uma lista de IDs de outros débitos que indica a necessidade daquele débito estar acompanhado de outros no pagamentoArray (String)
distinctÉ uma lista de IDs de outros débitos que indica débitos que não devem ser pagos em conjuntoArray (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.

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

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

Parâmetros do Body:

CampoDescriçãoTipo
debtIdListLista de débitos a serem pagosArray (String 36)
transactionIdId gerado na consulta de seus débitosNumeric(BigInt)
clientRequestIdIdentificador da transação, pode ser um ID interno da transação.String (36)

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 ErroCódigo do ErroDescrição
Esse pagamento está com processo de liquidação aberto100Será 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 aberto110Será 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ébito120Podem 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 Pagamento130Será retornado esse erro em casos em que os Detran estiver indisponível para solicitação de pagamento.
Transação não autorizada900Ao 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.