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.

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

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

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

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.

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}

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

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.
        Um callback pode estar vinculado a N documentos.

Em construção

Ao criar uma publicação, ou ao adicionar um destinatário em uma publicação existente, o autor define os dados do destinatário. Sendo eles:

Image Added

Para definir um destinatário para não precisar se cadastrar no TAE e utilizar a assinatura sem cadastro (por envio de código por e-mail), o destinatário deverá ser configurado com:

tipoAutenticacao : 2  
nomeCompleto:  string
tipoIdentificacao:  (1,2 ou 3)
identificacao (opcional): (cpf, cnpj, id internacional ou vazio para ser preenchido pelo usuário)

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