Histórico da Página

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.

Image Modified

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 os eventos que escolher

 * Receber notificações em tempo real

 * Remove a necessidade de realizar um processamento em loop, prejudicial a ambos os sistema.

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

 * Possibilita receber notificações para todos os documentos ou apenas documentos específicos

 * Interface amigável para gerir webhooks, configurando quais eventos deseja ser notificado

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. (LINK README SWAGGER)

Necessário autenticar na api com Bearer token do usuário administrador da empresa. (Gerado na rota de login LINK API IDENTITY)

Image Added

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

Image Added

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

Image Added

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.

Image Added

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}

Image Added

Image Added

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.

Image Added

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

Image Added

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

Image Added

A api retornará sucesso.

Image Added

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

Callback recebido pela integração:

Image Added

Obs: Um documento pode ter N callbacks.
        Um callback pode estar vinculado a N documentos.

Características da jornada: A integração não precisa implementar os recursos de visualizar e assinar o documento. O assinante acessará o documento pelo próprio portal do TAE e fará a assinatura.

https://excalidraw.com/#json=osSYZga9irrgR9cmcyFjw,PngksyWNw09SgiwGqAzJGg

Características da jornada: Uso da autenticação por envio de token por e-mail (sem cadastro de usuário)

https://excalidraw.com/#json=Hbn_rAGadqVK0Le3QQ5z6,_YZ1VBwV7UIoJRR2ywhauA