Jornadas de integração

Considere a seguinte jornada de uma integração: A escola envia um contrato para um aluno, e somente após a finalização desse documento com as assinaturas solicitadas, poderá dar seguimento na matrícula e nos demais processos da escola.

1- Cenário sem webhook:

   I- O sistema da escola gera o documento de matrícula e envia para o aluno.
   II - De tempo em tempo o sistema da escola consulta do status do documento no TAE para saber se o documento já foi assinado. 
        obs: A consulta é unitária, então se enviar 1000 matrículas, e estiver conferindo o status de 2 em 2 minutos, o sistema integrador realizaria 1000 requisições a cada dois minutos nas apis do TAE para conferir se o status do documento mudou.
   III - Quando o status do documento mudar o sistema seguiria com os processos da escola.

2- Cenário com webhook:

  I- O administrador da empresa indica que gostaria de receber notificações de callback (webhook) para documentos finalizados.

  II- O sistema da escola gera o documento de matrícula e envia para o aluno.

  III - Quando o documento for finalizado, o TAE envia uma notificação para o sistema integrador informando que aquele documento foi finalizado e o sistema segue com seus processos da escola.

Vantagens de utilizar o webhook

* Receber notificações em tempo real dos eventos que escolher, para todos os documentos ou apenas documentos específicos;

* Elimina a necessidade de realizar um processamento em loop (repetição "sem fim"), prejudicial a ambos os sistemas;

* Obtem informações detalhadas e personalizadas sobre cada notificação;

* Interface amigável para gerir os webhooks de sua empresa.

Para criar os webhooks para os eventos que deseja que seu sistema seja notificado, basta acessar o TAE com um usuário administrador da empresa, clicar no menu Integrações → Webhook → Criar webhook.

Após cadastrado ele será exibido na lista de webhooks

É importante só manter webhooks ativos se a URL do sistema integrador já estiver online e apta a receber as notificações conforme foi o webhook foi configurado.

Webhooks ativos vão ser executados para todos os documentos da empresa, sempre que o evento definido ocorrer.

Exemplo: No caso acima, todos os documentos da empresa quando finalizados irão realizar uma requisição POST para a URL configurada no webhook informando o id do documento e o status.

Caso só queira notificar documentos específicos, o webhook deve ser setado como status INATIVO, e os passos do guia abaixo devem ser seguidos.

Para realizar um callback para documentos específicos é necessário criar um webhook seguindo os passos acima, e configurá-lo como "inativo".

Assim, ao invés de ser executado para todos os documentos da empresa, ele só será disparado nos documentos que ele for configurado. 

Após criar o webhook utilize a API WEBHOOKS do TAE. 

Necessário autenticar na api com Bearer token do usuário administrador com permissão de Configurações da empresa. (Gerado na rota de login API IDENTITY) - LINK API

Busque pelo Webhook cadastrado anteriormente através da rota Get /v1/subscription -  LINK API

Serão listados todos os webhooks cadastrados da sua empresa:

Para gerar um callback personalizado para esse webhook, possíbilitando incluí-lo em documentos específicos, basta copiar o ID do webhook e utilizar a rota POST /v1/callbacks para criar o callback personalizado.  - LINK API

Nesse momento é necessário indicar o subscriptionId referente ao webhook "pai" desse callback.

Também é possivel definir novos campos para compor o "body" da requisição. Se novos atributos forem enviados, irão sobrescrever os atributos originais do webhook pai. Se nada for enviado no body, os atributos permanecerão conforme configurados no webhook.

É possível consultar os detalhes do webhook também pela API, pela rota GET /v1/subscription/{subscritionId}   -  LINK API

Seu callback personalizado irá utilizar as configurações do webhook pai, podendo ou não ter ser body personalizado.

No exemplo abaixo, não personalizaremos os atributos do body da requisição, mantendo os que foram definidos no webhook.

Ao executar com sucesso, a api retornará o id desse callback personalizado.

Esse id poderá ser atribuido nos documentos no qual você deseja ser notificado sobre esse evento.

A inclusão do callback em uma publicação pode ser feita em qualquer momento após o upload do arquivo, basta ter o id do arquivo e o id do callback.

Utilize a api Sign Integration na rota POST /v1/Publicacoes/{idArquivo}/CallBacks  - LINK API

A api retornará sucesso.

Após isso, quando esse documento for finalizado. O TAE irá notificar o webhook relacionado com esse callback indicado.

Callback recebido pela integração:

Obs: Um documento pode ter N callbacks (desde que sejam distintos).
        Um callback pode estar vinculado a N documentos.

Para conferir todos os registros de falhas de webhook temos a api Deadletter que permite listar, consultar e reprocessar um webhook que falhou.

Necessário autenticar na api com Bearer token do usuário administrador com permissão de Configurações da empresa. (Gerado na rota de login API IDENTITY) - LINK API

É possível listar/filtrar pelos registros de deadletters pela rota  Get /v1/deadletter/pesquisas-  LINK API

Os parâmetros do corpo da requisição são todos opcionais, se forem fornecidos irão filtrar os resultados por eles.

status possíveis: 

Não processado = 0, Processando = 1, Processado com sucesso = 2, Processado com falha = 3

Serão listados todos os deadletters gerados a partir de falhas de webhooks da sua empresa:

Aqui serão exibidos:

id do deadletter para ser possível excluir ou reprocessar;

errorMessage: Qual foi o motivo pelo qual o webhook não conseguiu notificar sua api;

eventType: Qual foi o tipo de notificação do webhook;

date: Data que ocorre o evento;

status: Status do deadletter;

De posse da lista, a integração deverá analisar o que houve e identificar se irá realizar algum ajuste de configuração no webhook ou na sua api, e então solicitar o reprocessamento desse deadletter.

Caso identifique que a api do sistema integrador apenas passou uma indisponibilidade, basta solicitar o reprocessamento do webhook.

Caso identifique que a url ou algum parametro configurado no webhook estava incorreto, basta corrigir o webhook pelo painel administrativo do TAE, e logo após solicitar o reprocessamento do webhook.

Caso não queira reprocessar basta excluir o registro do deadletter.

É possível também consultar mais detalhes de um deadletter pelo seu id, pela rota GET /v1/deadletter/{id}  - LINK API

Aqui serão exibidos as configurações que o webhook utilizou e obteve falha ao comunicar com sua api:

Caso entenda que não será necessário reprocessar aquele webhook, e deseje excluir o registro de deadletter, utilize a rota DELETE /v1/deadletter/{id}   -  LINK API

E desejando reprocessar aquele o registro de deadletter, utilize a rota POST /v1/deadletter/{id}/reprocessar   -  LINK API