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 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.

Em construção