Qual a diferença entre os retornos síncronos e assíncronos das APIs de débitos veiculares?

As APIs de Débitos Veiculares da Celcoin são consideradas assíncronas, pois seguem um fluxo específico para cada requisição. Veja como funciona:

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

Todos os webhooks enviados pela Celcoin são assíncronos. Ou seja, após realizar uma consulta, você precisará aguardar o envio do webhook para a URL configurada, que trará as informações sobre os débitos pendentes do veículo consultado. Da mesma forma, ao criar um pagamento, o webhook informará a confirmação sobre o processamento da transação.

Exemplos de retornos assíncronos:

Webhook retornado após uma consulta:

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

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

Se o veículo não for encontrado, será enviado um webhook informando essa situação.

Exemplo de 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 será retornada conforme o exemplo abaixo.

Exemplo de webhook para débitos pendentes:

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

A Celcoin envia dois tipos de comprovantes: um informando que o pagamento foi aceito (Comprovante Celcoin) e outro indicando que o órgão responsável aceitou o pagamento (Comprovante de Liquidação).

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

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

Se houver falha no pagamento, um webhook será enviado informando o erro.
Exemplo de webhook de falha no pagamento:

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

Quais são os retornos considerados síncronos?

Os retornos síncronos são aqueles que vêm diretamente na resposta da chamada à API de Consulta ou de Pagamento.

• Na API de Consulta, quando a resposta da requisição for "200", será informada a mensagem "processing" de forma síncrona.
• Na API de Pagamento, como o processamento do pagamento leva algum tempo, o retorno da requisição com status "200" será a mensagem: "Solicitação recebida com sucesso. Aguarde a resposta do processamento no webhook cadastrado."

Quando ocorre um erro síncrono, normalmente ele está relacionado a algum formato incorreto nos campos da requisição, como uma sequência inválida ou o envio de uma propriedade de tipo errado.

Exemplos de erros síncronos:

• Response da API de Consulta:

Para conferir os tipos de erro da API de Consulta de Débitos Veiculares, acesse a tabela de erros da API de Consulta.

• Response da API de Pagamento:

Se algum débito dependente não for incluído na solicitação de pagamento, o erro retornado será:

{
  "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 um débito não deve ser pago junto com outro (distinto), a API retornará:

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

Se um débito obrigatório não for incluído na solicitação de pagamento, o erro será:

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

Para mais detalhes sobre débitos distintos, dependentes e obrigatórios, recomendamos a leitura da documentação sobre débitos dependentes, distintos e obrigatórios.

Além desses erros, outros podem ser retornados na resposta da API de Pagamento. Para consultar todos os erros possíveis, acesse a tabela de erros da API de Pagamentos de Débitos Veiculares.