Início rápido da API do Drive para programadores

Este guia mostra o caminho mais seguro desde "Quero uma integração" até uma chamada funcional à API do Drive. Vai criar um token restrito, listar espaços do Drive, carregar um ficheiro e criar uma ligação pública de partilha com data de expiração.

1. Criar um token do Drive

Abra Agentes de IA e API → Tokens → Criar token. Dê ao token um nome claro, como drive-report-uploader. Selecione apenas os âmbitos necessários para o seu fluxo de trabalho.

Para este guia, use:

• drive:account:read
• drive:account:write
• drive:account:share

Não inclua âmbitos de purga numa primeira integração. Mantenha a eliminação permanente num token de manutenção separado.

Copie o token imediatamente após a criação. O TrekMail mostra o texto simples uma vez e armazena apenas um hash seguro.

2. Definir o URL base e o token

export TREKMAIL_BASE_URL="https://trekmail.net"
export TREKMAIL_API_TOKEN="tm_live_your_token"

Cada pedido usa o mesmo cabeçalho bearer:

-H "Authorization: Bearer $TREKMAIL_API_TOKEN"

3. Listar os espaços do Drive disponíveis

curl -s "$TREKMAIL_BASE_URL/api/v1/drive/spaces" \
  -H "Authorization: Bearer $TREKMAIL_API_TOKEN"

A resposta inclui o Drive da conta e quaisquer espaços do Drive de caixas de correio que o token possa ver. Use account para o Drive da conta nos exemplos seguintes.

4. Criar uma pasta

As operações de escrita devem incluir uma chave de idempotência. Se a rede repetir o pedido, o TrekMail pode devolver o resultado original em vez de criar duplicados.

curl -s -X POST "$TREKMAIL_BASE_URL/api/v1/drive/spaces/account/folders" \
  -H "Authorization: Bearer $TREKMAIL_API_TOKEN" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: folder-$(date +%s)" \
  -d '{"name":"API Uploads","color":"#2563eb"}'

Guarde o ID da pasta devolvido.

5. Carregar um ficheiro

A API REST separa a negociação do carregamento da transferência do ficheiro. Primeiro, inicie:

curl -s -X POST "$TREKMAIL_BASE_URL/api/v1/drive/spaces/account/uploads:initiate" \
  -H "Authorization: Bearer $TREKMAIL_API_TOKEN" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: upload-report-001" \
  -d '{"name":"report.pdf","size_bytes":123456,"folder_id":42,"client_mime":"application/pdf"}'

O TrekMail devolve instruções de carregamento. Envie os bytes para o URL de carregamento devolvido e depois chame:

curl -s -X POST "$TREKMAIL_BASE_URL/api/v1/drive/uploads/{FILE_ID}:complete" \
  -H "Authorization: Bearer $TREKMAIL_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{}'

Se usar MCP, prefira drive_file_upload. A ferramenta reúne os passos de início, transferência, conclusão e cancelamento.

6. Criar uma ligação de partilha

curl -s -X POST "$TREKMAIL_BASE_URL/api/v1/drive/files/{FILE_ID}/share-links" \
  -H "Authorization: Bearer $TREKMAIL_API_TOKEN" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: share-report-001" \
  -d '{"expires_at":"2026-06-01T00:00:00Z","max_downloads":25}'

O URL público devolvido é a única ocasião em que o token bruto da ligação é mostrado. Guarde-o agora se precisar de o enviar mais tarde.

7. Verificar o histórico de auditoria

Abra Agentes de IA e API → Registo de auditoria e filtre por token. Deverá ver a criação da pasta, o carregamento, a conclusão e a criação da ligação de partilha. Esta é a forma mais rápida de confirmar que a integração usa o token e os âmbitos esperados.

Lista de verificação para produção

• Use um token por integração.
• Conceda leitura, escrita e partilha separadamente; exclua a purga dos fluxos diários.
• Adicione expiração e limites de transferências às ligações públicas.
• Use uma chave de idempotência quando a documentação do endpoint ou a especificação OpenAPI a exigir. Neste fluxo, isso inclui a criação da pasta, o início do carregamento e a criação da ligação de partilha.
• Revogue os tokens de teste após o desenvolvimento.