Enviar e versionar documentos

O sistema de contratos gera o PDF assinado, o laboratório emite o laudo, o ERP produz a nota. Em vez de alguém baixar e subir de novo, o sistema de origem envia o arquivo direto para o GED — na pasta certa, com tipo, tags e, se for o caso, ligado ao colaborador ou ao card a que pertence. Quando o arquivo muda, uma nova versão entra no mesmo documento, com o histórico preservado.

Quando usar	Arquivos nascem em outro sistema e precisam viver no acervo da TAI
Porta	REST (multipart) · Agente (MCP) para busca e consulta
Você vai precisar	módulo GESTAO_DOCUMENTOS; permissão DOCUMENTO; permissão Upload na pasta de destino; JWT de um usuário de integração vinculado a um colaborador

Como funciona

seu sistema ──► GET  /ged/pasta/arvore                         (uma vez: id da pasta)
            ──► POST /ged/documento/upload?titulo=…&pastaId=…  (multipart: guarda o id)
            ──► POST /ged/documento/{id}/versao                (arquivo mudou: nova versão)
            ──► GET  /ged/documento/{id}/download              (quando precisar do arquivo)

Passo a passo

1. Ache ou crie a pasta.

   curl -s https://api.taitecnologia.com/ged/pasta/arvore \
     -H "Authorization: Bearer $TAI_TOKEN"

   Para criar uma subpasta (exige Upload na pasta pai):

   curl -s -X POST https://api.taitecnologia.com/ged/pasta/criar \
     -H "Authorization: Bearer $TAI_TOKEN" \
     -H "Content-Type: application/json" \
     -d '{ "nome": "Contratos 2026", "pastaPaiId": 12 }'

2. Envie o documento. Os metadados vão na query string; o arquivo, na parte arquivo:

   curl -s -X POST "https://api.taitecnologia.com/ged/documento/upload?titulo=Contrato%20Cliente%20Exemplo&tipoDocumento=CONTRATO_CLIENTE&pastaId=31&codigo=CT-2026-0187&tags=contrato,comercial,CT-2026-0187" \
     -H "Authorization: Bearer $TAI_TOKEN" \
     -F "arquivo=@contrato-0187.pdf"

   Parâmetro	Conteúdo
   tipoDocumento	Obrigatório. CONTRATO_CLIENTE, NDA, PROPOSTA_COMERCIAL, PROCEDIMENTO, MANUAL, ATESTADO, ASO, OUTROS… — a lista completa está na referência
   titulo, descricao, tags	Para a busca; tags separadas por vírgula
   codigo	Texto livre: a chave do documento no seu sistema. A busca não olha o código — repita a chave em tags para achá-la
   pastaId	Pasta de destino
   tipoEntidadeVinculo + idEntidadeVinculo	Liga o documento a um registro: COLABORADOR, CLIENTE, PROJETO, TAREFA, PATRIMONIO…
   dataValidade	Validade do documento (ASO, certificado)
   comentarioVersao	Comentário da versão 1

   A resposta (201) é o documento, com id, versaoNumero e versaoAtual (nome original, tamanho e hashArquivo, o SHA-256 do arquivo). Guarde o id no seu sistema.

3. Publique uma nova versão quando o arquivo mudar:

   curl -s -X POST "https://api.taitecnologia.com/ged/documento/4410/versao?comentarioVersao=Aditivo%20de%20prazo" \
     -H "Authorization: Bearer $TAI_TOKEN" \
     -F "arquivo=@contrato-0187-v2.pdf"

   Exige permissão Escrita no documento. As versões anteriores continuam disponíveis:

   Rota	O que faz
   GET /ged/documento/{id}/versoes	Lista as versões, com número, comentário, autor, data e hash
   GET /ged/documento/{id}/versao/{n}/download	Baixa uma versão específica
   PUT /ged/documento/{id}/restaurar/{n}	Torna uma versão anterior a atual

4. Baixe e procure. GET /ged/documento/{id}/download devolve o arquivo da versão atual. Para achar documentos:

   curl -s "https://api.taitecnologia.com/ged/documento/buscar/page?termo=CT-2026-0187&page=0&size=20" \
     -H "Authorization: Bearer $TAI_TOKEN"

   A busca procura em título, descrição, tags e no texto lido do arquivo. Os documentos ligados a um registro saem de GET /ged/documento/entidade/{tipoEntidade}/{idEntidade}/page — por exemplo, entidade/COLABORADOR/1043/page.

Arquivos de cards de processo

Arquivos de campos do tipo Arquivo de um card de processo também viram documentos do GED, mas sobem por rotas próprias, que já ligam o arquivo ao campo: POST /bpm/ged/upload/{cardId}/{fieldSchemaId} e /bpm/ged/upload-versao/{cardId}/{fieldSchemaId}. Veja Abrir card de outro sistema.

Automatize

Nos fluxos de Processos, a ação Criar Documento GED cria um registro de documento ligado ao card, e Mover Documento GED move o documento de um campo do card para outra pasta — por exemplo, levar o contrato para “Vigentes” quando o card é concluído. Para aprovação e assinatura, veja Aprovação e assinatura.

Para o seu sistema saber dos documentos que entram no GED da TAI — enviados na tela, pela Tali ou por outra integração —, crie um webhook assinando Um documento é enviado ao GED (GED_DOCUMENTO_ENVIADO), com documentoId, titulo, pastaId, tipoDocumento e colaboradorId (quem enviou), e Um documento muda de pasta (GED_DOCUMENTO_MOVIDO). Os uploads do seu próprio sistema também voltam por esse webhook: descarte os documentoId que você já guardou. Com Enviar também o registro completo, chega o documento como GET /ged/documento/{id} o devolve; o arquivo se baixa em GET /ged/documento/{id}/download. Uma versão nova não publica evento.

Pelo seu agente de IA

“Ache o contrato CT-2026-0187 e me diga quando vence.”

É leitura: o agente busca pelo texto e lê os metadados. Arquivos não trafegam pela conversa — quando o agente precisa entregar um arquivo, ele gera um link temporário. Veja Ferramentas.

Cuidados

• Até 50 MB por arquivo, nas extensões pdf, doc, docx, xls, xlsx, ppt, pptx, txt, csv, jpg, jpeg, png, gif, bmp e webp.
• Não há chave de idempotência. Repetir o upload cria outro documento. Guarde o id; para conferir antes, busque pela sua chave repetida em tags.
• Permissão do GED além da funcionalidade. Enviar exige Upload na pasta; versionar, Escrita no documento; vincular a colaborador, férias, candidato ou PDI exige a permissão de edição do cadastro correspondente. Quem envia é o criador e tem acesso total ao documento.
• Metadados vão na URL. Codifique acentos e espaços (%20) e mantenha os textos curtos.
• Use multipart/form-data com a parte arquivo; o firewall aceita arquivos grandes nas rotas /ged/documento/ e /bpm/ged/. Veja Limites de uso.