Configurando WebHooks

Nossa API conta com um recurso que faz o envio de Webhooks, ou seja, enviamos JSONs com notificações referentes a alteração dos boletos, diretamente para a sua aplicação.

Os chamados WebHooks são notificações que nós te enviaremos sempre que um boleto retornar do banco.

Então, como o tempo de processamento das remessas varia muito de banco para banco, nós implementamos este recurso para que os sistemas de nossos clientes consigam obter as informações atualizadas dos boletos assim que elas forem disponibilizadas para nós.

É um recurso muito interessante para ser utilizado juntamente com a nossa Transmissão Automática de Remessas e Retornos. Porque, tudo estando automatizado, seu sistema não precisará "desperdiçar" consultas, enviando para nossa API pedidos de consultas para boletos que ainda não estiverem sido processados pelo banco.

Com os WebHooks da Tecnospeed, nós iremos te avisar assim que o boleto for atualizado em nossa base de dados!

Obs.: Atualmente as notificações por WebHooks funcionam apenas em ambiente de produção no PlugBoleto.

O que preciso para utilizar os WebHooks?

O primeiro passo é, em sua API, abrir uma rota que aceite uma requisição POST.

Recomendamos que sua API, ao receber o Json que nosso servidor irá te enviar, responda a requisição POST com um statusCode 200.

É possível também cadastrar um Header (opcional) para autenticar a requisição.

Como configuro a API da Tecnospeed para me enviar WebHooks?

É possível configurar os WebHooks de duas formas, através do Cedente ou através da Conta. O processo de criação é o mesmo que será apresentado na sequência. 

O funcionamento é bem simples, basta ativar ou inativar de acordo com os cenário a seguir:

Toda a configuração é feita a partir do painel da Software House. Ao logar, identifique o CNPJ do cedente que você deseja ativar o recurso, e no menu "Ações" clique em "Personalizar Webhook", conforme exemplo abaixo:

Via Cedente:

Via Conta:

 Obs.: O cadastro de webhooks diretamente na conta possui prioridade sobre o cadastro feito via cedente. Ou seja, caso exista uma configuração de webhook na conta, a configuração feita no cedente será desconsiderada.

Na próxima tela, independente se estiver cadastrando por Cedente ou pela Conta, você irá preencher as configurações da rota aberta em sua API, as informações de autenticação e os tipos das notificações que você deseja receber:

A primeira configuração desta tela, que é a opção "Ativar" será onde você habilita ou não o uso do recurso;

Na sequência, no campo "URL", você irá nos informar a URL de sua API que deve estar apta para receber requisições POST;

Esta requisição que nós iremos te encaminhar conterá em seu body um json, trazendo as informações dos boletos;

Em seguida, haverá o campo "Header", que é opcional. Ao marcá-lo, aparecerão 2 novos campos onde você pode preencher o nome do campo de autenticação e a chave de autenticação que você definir;

Existe também a possibilidade de configurar "Headers Adicionais" que podem ser adicionados no formato JSON conforme exemplo acima.

E por fim, existirão os campos que controlarão quais tipos de alterações nós iremos te encaminhar. Possuímos 5 tipos de WebHooks que podemos disparar:

• Notificar ao Registrar: Ao recebermos do banco o arquivo de retorno, e este altere a situação do boleto para "Registrado", esta notificação será ativada;
• Notificar ao Liquidar: Disparado ao recebermos o retorno e os boletos tiverem a situação atualizada para "Liquidado";
• Notificar ao Baixar: Disparado ao recebermos a confirmação da Baixa do Boleto;
• Notificar ao Rejeitar: Disparado quando o boleto voltar do banco como "Rejeitado";
• Notificar ao Protestar: Disparado quando o boleto voltar do banco como situação de protesto, "Incluído cartório";
• Notificar ao Alterar informação: Disparado quando o arquivo de retorno possuir informações que atualizem a data de vencimento e/ou valor dos boletos e demais alterações enviadas pelo banco, porém, com o boleto permanecendo com a mesma situação.

O json que sua API receberá possuirá os campos:

"tipoWH": onde estará identificado o tipo da notificação que foi enviada;

"dataHoraEnvio": que identificará a data e hora em que a notificação foi gerada

"titulo": o conteúdo deste campo irá variar de acordo com o tipo do json, ele trará informações para identificação do boleto de acordo com cada tipo de notificação.

Segue abaixo alguns exemplos de json que seu sistema irá receber para cada uma das notificações Webhook:

Registro:

Liquidação:

Baixa:

Rejeição:

Alteração:

Protesto:

Detalhes:

Serão feitas 10 tentativas de comunicação com sua API, caso a primeira requisição não retorne com um statusCode 200, aguardaremos 10 segundos e em seguida enviaremos novamente. Se a segunda consulta não obtiver resposta, aguardaremos mais60 segundos e enviaremos as demais conforme abaixo:

Recomendamos o uso do botão "Testar", presente na tela de cadastro dos Webhooks. Ele irá enviar para a rota configurada um exemplo de json para os tipos de notificação selecionados no grid. Isso é importante para validar se sua API está recebendo e tratando os jsons corretamente.

Após receber o json em seu sistema, recomendamos que você capture o idintegracao presente na requisição, e na sequência faça uma consulta pelo boleto, para que nesta consulta você obtenha a resposta completa, com todos os campos presentes em nosso banco de dados, para assim deixar seu sistema 100% atualizado com as informações que vieram do banco.