Aprovação e assinatura de documentos

O contrato gerado no sistema comercial precisa do aval do jurídico e depois da assinatura do cliente. No GED, isso são dois mecanismos: a aprovação, decidida por um colaborador responsável, e a assinatura eletrônica, feita por qualquer pessoa — de dentro ou de fora da empresa — por um link enviado por e-mail. Os dois se pedem pela API, e cada passo — decisão, assinatura, recusa — publica um evento que um webhook leva ao seu sistema.

Quando usar	Um documento precisa de aval interno ou da assinatura de alguém antes de valer
Porta	REST · Webhook (eventos de aprovação e assinatura) · Automação (ações de GED nos fluxos) · página pública de assinatura
Você vai precisar	módulo GESTAO_DOCUMENTOS; permissão DOCUMENTO; Escrita no documento para pedir aprovação; Gerenciar no documento para pedir assinatura (quem enviou o arquivo tem acesso total); DOCUMENTO_ASSINATURA para acompanhar e cancelar pedidos de assinatura; JWT de um usuário vinculado a um colaborador

Como funciona

APROVAÇÃO
seu sistema ──► PUT /ged/documento/{id}/enviar-aprovacao {aprovadorId} ──► documento PENDENTE_APROVACAO
aprovador   ──► tela (Documentos → Aprovações Pendentes) ou PUT …/workflow/{id}/aprovar | /rejeitar
TAI         ──► evento GED_WORKFLOW_DECIDIDO (workflowId, documentoId, resultado) ──► webhook ──► seu sistema

ASSINATURA
seu sistema ──► POST /ged/documento/solicitar-assinatura ──► e-mail com link a cada signatário
signatário  ──► página de assinatura (CPF, nome, nascimento, aceite)
TAI         ──► GED_DOCUMENTO_ASSINADO a cada assinatura (todosAssinaram) · GED_ASSINATURA_RECUSADA ──► webhook
seu sistema ──► GET /ged/documento/{id}/assinaturas   (detalhe: PENDENTE → PARCIAL → CONCLUIDA)

Aprovação

1. Envie para aprovação. aprovadorId é o id do colaborador que decide:

   curl -s -X PUT https://api.taitecnologia.com/ged/documento/4410/enviar-aprovacao \
     -H "Authorization: Bearer $TAI_TOKEN" \
     -H "Content-Type: application/json" \
     -d '{ "aprovadorId": 88, "comentario": "Contrato CT-2026-0187, revisar cláusula 7." }'

   A resposta é a solicitação (workflow), com id e status PENDENTE; o documento passa a PENDENTE_APROVACAO. O aprovador ganha leitura do documento e o vê em Documentos → Aprovações Pendentes.

2. Decida — na tela ou, com o JWT do aprovador, pela API:

   # aprovar (comentário opcional)
   curl -s -X PUT "https://api.taitecnologia.com/ged/documento/workflow/702/aprovar?comentario=De%20acordo" \
     -H "Authorization: Bearer $TAI_TOKEN"
   
   # rejeitar (motivo obrigatório)
   curl -s -X PUT "https://api.taitecnologia.com/ged/documento/workflow/702/rejeitar?motivo=Cl%C3%A1usula%207%20sem%20prazo" \
     -H "Authorization: Bearer $TAI_TOKEN"

   O documento fica APROVADO ou REJEITADO. Quem pediu pode desistir antes da decisão com PUT /ged/documento/workflow/{workflowId}/cancelar. A fila do aprovador: GET /ged/documento/workflow/pendentes/page.

3. Leia o histórico. GET /ged/documento/{id}/workflow/historico traz cada pedido, com solicitante, aprovador, datas, comentário e motivo.

4. Avise o seu sistema. Toda decisão publica o evento Um documento é aprovado ou reprovado (GED_WORKFLOW_DECIDIDO). Crie um webhook em Processos › Central de Automações › Webhooks assinando esse evento:

   {
     "id": "evt_68120",
     "tipo": "GED_WORKFLOW_DECIDIDO",
     "descricao": "Um documento é aprovado ou reprovado",
     "versao": 1,
     "ocorridoEm": "2026-10-07T14:03:55.290Z",
     "empresa": { "id": 12, "nome": "Sua Empresa Ltda" },
     "dados": { "workflowId": 702, "documentoId": 4410, "resultado": "APROVADO" }
   }

   resultado é APROVADO ou REJEITADO. O seu sistema casa pelo documentoId que guardou e busca o resto — título, comentário, motivo — em GET /ged/documento/{id} e no histórico do passo 3. Assine também Um documento é enviado para aprovação (GED_WORKFLOW_ENVIADO) e Um pedido de aprovação de documento é cancelado (GED_WORKFLOW_CANCELADO) se o seu sistema acompanha o pedido do começo ao fim.

Assinatura eletrônica

1. Peça as assinaturas.

   curl -s -X POST https://api.taitecnologia.com/ged/documento/solicitar-assinatura \
     -H "Authorization: Bearer $TAI_TOKEN" \
     -H "Content-Type: application/json" \
     -d '{
       "documentoId": 4410,
       "mensagemConvite": "Por favor, assine o contrato de prestação de serviços.",
       "signatarios": [
         { "nome": "Paula Mendes", "email": "paula@cliente.com.br" },
         { "colaboradorId": 88 }
       ]
     }'

   Cada signatário é uma pessoa de fora (nome + email) ou um colaborador (colaboradorId — vale o e-mail do cadastro). Cada um recebe por e-mail um link próprio, válido por 7 dias. A resposta (201) é a solicitação, com id, status e uma assinaturas[] por signatário.

2. Acompanhe as assinaturas.

   curl -s https://api.taitecnologia.com/ged/documento/4410/assinaturas \
     -H "Authorization: Bearer $TAI_TOKEN"

   Nível	Status
   Solicitação	PENDENTE, PARCIAL (parte assinou), CONCLUIDA (todos assinaram), CANCELADA, EXPIRADA
   Cada signatário	PENDENTE, ASSINADO, RECUSADO (com motivoRecusa), EXPIRADO, CANCELADO

   Quem pediu também recebe e-mail quando todos assinam ou alguém recusa.

3. Receba cada assinatura na hora. Em vez de consultar de tempos em tempos, crie um webhook assinando Alguém assina um documento (GED_DOCUMENTO_ASSINADO) e Alguém recusa assinar um documento (GED_ASSINATURA_RECUSADA):

   {
     "id": "evt_68377",
     "tipo": "GED_DOCUMENTO_ASSINADO",
     "descricao": "Alguém assina um documento",
     "versao": 1,
     "ocorridoEm": "2026-10-08T09:41:17.602Z",
     "empresa": { "id": 12, "nome": "Sua Empresa Ltda" },
     "dados": {
       "assinaturaId": 3391,
       "solicitacaoId": 1204,
       "documentoId": 4410,
       "colaboradorId": null,
       "email": "paula@cliente.com.br",
       "todosAssinaram": true
     }
   }

   Cada signatário gera um evento; todosAssinaram é true no que completa o pedido — o sinal para o sistema comercial dar o contrato por fechado. A recusa traz o motivo. Com Enviar também o registro completo, o pedido inteiro, com todas as assinaturas, chega em registro. Também existem Um documento é enviado para assinatura (GED_ASSINATURA_SOLICITADA) e Um pedido de assinatura é cancelado (GED_ASSINATURA_CANCELADA).

4. Reenvie ou cancele, se precisar. POST /ged/documento/assinatura/{assinaturaId}/reenviar manda o convite de novo a um signatário; DELETE /ged/documento/assinatura/solicitacao/{solicitacaoId} cancela um pedido pendente.

O signatário assina na página da TAI, informando CPF, nome completo e data de nascimento e marcando o aceite. A TAI registra como evidência o CPF validado, o IP, o navegador, o hash SHA-256 do documento e a data e hora — esses dados aparecem completos só para quem pediu, para quem gerencia o documento e para os administradores.

Nos fluxos de Processos

Os fluxos de Processos usam o GED pelos campos do tipo Arquivo (cada arquivo é um documento do GED) e por quatro ações de automação:

Ação (na tela)	Código	O que faz
Enviar para Aprovação GED	ENVIAR_PARA_APROVACAO_GED	Envia o documento de um campo do card para a aprovação de um colaborador escolhido; quem pede é o criador do card
Solicitar Assinatura GED	SOLICITAR_ASSINATURA_GED	Registra no card, como comentário, o pedido de assinatura e os signatários. Não envia o convite: o pedido se completa no GED (ou pela API acima)
Mover Documento GED	MOVER_DOCUMENTO_GED	Move o documento de um campo do card para outra pasta
Criar Documento GED	CRIAR_DOCUMENTO_GED	Cria um registro de documento (sem arquivo, em rascunho) ligado ao card, com título que aceita variáveis, na pasta escolhida ou na do fluxo

As quatro exigem o módulo Documentos na empresa; sem documento no campo configurado, a execução termina com falha e o motivo.

Aprovar o card pela decisão do documento

Uma fase de aprovação pode abrir sozinha a aprovação no GED dos arquivos do card e aprovar ou reprovar o card pela decisão do documento. A opção não aparece na tela de configuração; liga-se na fase pela API, com três campos de /phase:

Campo	Conteúdo
criarGedWorkflowAutomatico	true liga a aprovação automática no GED
fieldSchemaAprovacaoGedId	O campo de arquivo cujo documento vai para aprovação
aprovadorGedColaboradorId	O colaborador que aprova no GED

Leia a fase com GET /phase/{id}, ajuste os três campos e envie o objeto inteiro de volta em PUT /phase — o PUT substitui o registro.

Quando um card entra na fase, a TAI envia para aprovação o documento do campo indicado (sem fieldSchemaAprovacaoGedId, todos os campos de arquivo do card). O aprovador é o de aprovadorGedColaboradorId; sem ele, o aprovador designado para o card ou o primeiro aprovador da fase. A decisão no GED vale como decisão do card — aprovado, ele avança — e fica comentada no card.

Pelo seu agente de IA

“Quais documentos esperam a minha aprovação? E o contrato CT-2026-0187, já foi assinado por todos?”

É leitura: o agente lista as pendências e consulta as assinaturas. Aprovar e assinar são ações de confirmação forte: nenhum agente externo as executa — elas se fazem na plataforma ou pela Tali. Veja Escrita e segurança.

Cuidados

• Só o aprovador decide: outra pessoa recebe 403; um pedido já decidido, 400. Uma aprovação aberta por automação de fluxo só é cancelada por administrador.
• Aprovação tem um aprovador por pedido. Para mais de uma pessoa, envie um pedido para cada uma.
• A assinatura vale para a versão do pedido. Uma versão nova do documento depois do pedido não está assinada: peça de novo.
• Signatário colaborador sem e-mail no cadastro, ou colaborador de outra empresa, é recusado com 400 antes de gravar o pedido.
• Link vencido (7 dias) não assina: reenvie o convite ou faça um pedido novo.
• O evento GED_WORKFLOW_DECIDIDO sai uma vez por decisão; cada automação roda uma vez para ele.
• Assinatura por evento, reconciliação pela API. As novas tentativas do webhook cobrem horas, não dias: um sistema que depende do contrato assinado também confere GET /ged/documento/{id}/assinaturas dos pedidos ainda em aberto de tempos em tempos.