Guia da API e do MCP para ligações de partilha do Drive

As ligações de partilha permitem entregar um ficheiro do Drive fora da sua conta TrekMail sem enviar um anexo de correio eletrónico de grandes dimensões. A API e as ferramentas MCP podem criar ligações, listar as ligações de um ficheiro e revogar ligações quando o acesso tiver de terminar.

Utilize ligações de partilha para materiais destinados a clientes, faturas, ficheiros de vídeo, pacotes de exportação e qualquer ficheiro demasiado grande ou temporário para ser anexado a uma mensagem.

Âmbitos necessários

Para ficheiros do Drive da conta, utilize drive:account:share. Para ficheiros do Drive da caixa de correio, utilize drive:mailbox:share. Um âmbito de leitura também é útil, porque a maioria dos fluxos de trabalho precisa de encontrar o ficheiro antes de o partilhar.

Os âmbitos de partilha não permitem carregar, mudar o nome, mover, enviar para o lixo, restaurar ou eliminar definitivamente. Mantenha-os separados quando a única tarefa do agente for a entrega.

Criar uma ligação com REST

curl -s -X POST "https://trekmail.net/api/v1/drive/files/{FILE_ID}/share-links" \
  -H "Authorization: Bearer tm_live_your_token" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: share-{FILE_ID}-client-a" \
  -d '{"expires_at":"2026-06-01T00:00:00Z","max_downloads":25}'

A resposta inclui o URL público. O token de partilha em bruto só é devolvido no momento da criação. Se o perder, revogue a ligação e crie uma nova.

Criar uma ligação com MCP

drive_share_create(file_id=123, expires_at="2026-06-01T00:00:00Z", max_downloads=25)

Peça ao agente que devolva o URL na resposta final e que indique a validade e o limite de transferências.

Listar e revogar ligações

Utilize o endpoint de listagem ou drive_share_list para ver as ligações ativas e históricas de um ficheiro. Utilize a revogação quando uma ligação tiver sido enviada à pessoa errada, um contrato já não for válido ou um período de entrega temporário tiver terminado.

drive_share_revoke(link_id=456)

A revogação é imediata. Crie uma nova ligação se for necessário restaurar o acesso.

Predefinições recomendadas

As ligações ilimitadas são práticas, mas tornam-se mais difíceis de avaliar posteriormente. Se optar por não definir uma validade, adicione uma nota no seu próprio sistema que explique o motivo.

Comportamento de segurança

Uma ligação de partilha é pública para qualquer pessoa que tenha o URL. É protegida por um token impossível de adivinhar, não por um início de sessão no TrekMail. Não envie ligações públicas para ficheiros que exijam acesso de destinatários identificados, a menos que a sua organização aceite esse modelo.

A página de transferência não revela detalhes desnecessários da conta. As ligações expiradas, revogadas ou que tenham atingido o limite falham sem expor o contexto privado do ficheiro.

Registo de auditoria

A criação e a revogação de ligações de partilha são auditadas com a identidade do token da API. Se um agente criar ligações para clientes, reveja periodicamente o registo de auditoria e substitua os tokens quando as responsabilidades da equipa mudarem.