Consideramos as APIs de Débitos Veiculares como assíncronas, pois sempre que uma requisição é realizada, ocorre o seguinte fluxo aqui na Celcoin:

1. Recebemos os dados da requisição;
2. Confirmamos o recebimento;
3. Disparamos o webhook, de forma assíncrona, com as informações sobre a consulta ou confirmação do pagamento. 

Todos os webhooks que enviamos são assíncronos:

• Quando uma Consulta for realizada, será necessário aguardar o envio do webhook destinado à url que você configurou, contendo todas as informações sobre os débitos pendentes do veículo consultado.
• Quando um Pagamento for criado, a confirmação sobre o processamento virá informada no webhook.

Agora vamos aos exemplos de retornos assíncronos:

Webhook retornado após uma Consulta:

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

Caso o veículo não seja encontrado, será enviado um webhook com essa informação.

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

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

Se houver débitos pendentes, a informação virá estruturada como no exemplo abaixo.

{
  "type": "debts",
  "transactionId": 9393366,
  "clientRequestId": "teste hml 20221014 01",
  "vehicle": {
    "uf": "DF",
    "document": "11111111111",
    "licensePlate": "JFI8753",
    "renavam": "56387604559"
  },
  "debts": [
    {
      "id": "28850DB5-05EA-4461-A84A-EE04EF9B545D",
      "amount": 204.79,
      "title": "Infração Vencida - I004242123",
      "description": "I004242123 - Infração de Trânsito",
      "dueDate": "2022-10-14T00:00:00",
      "expirationDate": "2022-10-14T00:00:00",
      "hasDiscount": false,
      "isExpired": true,
      "type": "ticket",
      "year": null,
      "required": false,
      "dependsOn": [],
      "distinct": []
    }
  ]
}

Webhook retornado após um Pagamento:

Lembrando que temos dois comprovantes, um informando que aceitamos o pagamento, aqui vamos falar, “Comprovante Celcoin” e o comprovante de Liquidação, quando o órgão de fato aceitou o pagamento.

Modelo de webhook quando o pagamento é aceito pela Celcoin:

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

Modelo de Comprovante de liquidação do órgão:

{
  "type": "settlement-events",
  "transactionId": 000,
  "status": "SUCCESS",
  "paymentId": "29C32257-2DDB-41B0-9BB0-4CB64783443F",
  "clientRequestId": "29d648b8-594f-436c-ba53-a543fdaf9467",
  "debtId": "312D6A5F-2B5A-4694-84DA-F640FC01CC74",
  "body": {
    "metaDetran": [
      {
        "state": "DF"
      },
      {
        "licensePlate": "DIS9865"
      },
      {
        "renavam": "01203988813"
      },
      {
        "document": "03477457650
      },
      {
        "nsuDetran": "10000008"
      },
      {
        "settlementBank": "Bradesco"
      },
      {
        "settlementDateTime": "2022-12-28T00:00:00"
      },
      {
        "amount": "1009.36"
      },
      {
        "dueDate": "2022-12-28T00:00:00"
      },
      {
        "debitType": "licensing"
      },
      {
        "year": "2023"
      },
      {
        "debtDescription": "Licenciamento 2023"
      }
    ]
  }
}

Modelo de webhook quando ocorre uma falha no pagamento:

{
  "type": "debitNotAuthorized",
  "paymentId": "1C49892E-0594-4E2D-AA8D-0FF2DC735798",
  "clientRequestId": "1671047351",
  "processedDate": "2022-12-14T17:05:33",
  "erroCode": "900",
  "erroMessage": "Transação não autorizada",
  "debitId": "2610EF2D-BE83-49D6-806A-590A84B9F79D"
}

Quais são os retornos considerados síncronos?

Os retornos considerados síncronos, são todos aqueles que virão no response da chamada API de Consulta ou de Pagamento. 

Para a API de Consulta, quando a resposta da requisição for “200”, será informado no response a mensagem "processing" de forma síncrona e para a API de Pagamento, como todo pagamento depende de um processamento, o retorno da requisição de status “200” será a mensagem "Solicitação recebida com sucesso. Aguarde a resposta do processamento no webhook cadastrado.".

Quando mencionamos sobre os retornos de erros síncronos, consideramos que são sempre originários de algum formato incorreto dos campos disponíveis nas chamadas, podendo ser uma sequência inválida, ou um tipo de propriedade enviado de forma incorreta.

Veja os exemplos de erros que podem ser retornados de forma síncrona:

Response da API de Consulta:

Clique no link a seguir para conferir os tipos de erros: Tabela de erro da API de Consulta de Débitos Veiculares

Response da API de Pagamento:

Caso algum débito que seja dependente, fique fora da solicitação de pagamento, a API retornará o seguinte erro:

{
  "transactionId": 9391165,
  "message": "Existem débitos dependentes que devem ser pagos juntos ao débito informado",
  "execute": "2022-09-30 14:41:56",
  "errorCode": "815"
}

Se for solicitado o pagamento de um débito que não deve ser pago junto com outro (distinto), a API retornará o seguinte erro:

{
  "transactionId": 9391167,
  "message": "Existem débitos que não podem ser pagos em conjunto",
  "execute": "2022-09-30 14:40:56",
  "errorCode": "817"
}

Agora, se um débito obrigatório não for enviado na solicitação de pagamento, a API retornará o seguinte erro:

{
  "transactionId": 815949758,
  "message": "Existem débitos obrigatórios que devem ser pagos",
  "execute": "2022-09-30 14:33:35",
  "errorCode": "816"
}

Para mais informações sobre débitos distintos, dependentes e obrigatórios sugerimos a leitura da nossa documentação.

Além desses, outros erros poderão retornar no response da API de Pagamento. Confira aqui.