Inicio rápido de la API de Drive para desarrolladores

Este inicio rápido muestra la ruta más segura desde "Quiero una integración" hasta una llamada funcional a la API de Drive. Crearás un token limitado, enumerarás los espacios de Drive, subirás un archivo y crearás un enlace público con fecha de caducidad.

1. Crea un token de Drive

Abre Agentes de IA y API → Tokens → Crear token. Asigna al token un nombre claro, como drive-report-uploader. Selecciona solo los alcances necesarios para tu flujo de trabajo.

Para esta guía, usa:

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

No incluyas alcances de purga en una primera integración. Mantén la eliminación permanente en un token de mantenimiento independiente.

Copia el token inmediatamente después de crearlo. TrekMail muestra el texto sin formato una sola vez y almacena únicamente un hash seguro.

2. Configura la URL base y el token

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

Cada solicitud usa el mismo encabezado bearer:

-H "Authorization: Bearer $TREKMAIL_API_TOKEN"

3. Enumera los espacios de Drive disponibles

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

La respuesta incluye Drive de la cuenta y los espacios de Drive de buzones que el token puede ver. Usa account para Drive de la cuenta en los ejemplos siguientes.

4. Crea una carpeta

Las operaciones de escritura deben incluir una clave de idempotencia. Si la red reintenta la solicitud, TrekMail puede devolver el resultado original en lugar de crear 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"}'

Guarda el ID de carpeta devuelto.

5. Sube un archivo

La API REST separa la negociación de la carga de la transferencia del archivo. Primero, inicia la carga:

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"}'

TrekMail devuelve instrucciones de carga. Envía los bytes a la URL de carga devuelta y después llama a:

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 '{}'

Si usas MCP, prefiere drive_file_upload. Esta herramienta agrupa los pasos de inicio, transferencia, finalización y cancelación.

6. Crea un enlace compartido

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}'

La URL pública devuelta es la única ocasión en que se muestra el token sin formato del enlace. Guárdala ahora si necesitas enviarla más tarde.

7. Revisa el registro de auditoría

Abre Agentes de IA y API → Registro de auditoría y filtra por token. Deberías ver la creación de la carpeta, la carga, la finalización y la creación del enlace compartido. Es la forma más rápida de confirmar que la integración usa el token y los alcances esperados.

Lista de comprobación para producción

• Usa un token por integración.
• Concede lectura, escritura y uso compartido por separado; excluye la purga de los flujos diarios.
• Añade caducidad y límites de descargas a los enlaces públicos.
• Usa una clave de idempotencia cuando lo exijan la documentación del endpoint o la especificación OpenAPI. En este flujo incluye la creación de carpetas, el inicio de cargas y la creación de enlaces compartidos.
• Revoca los tokens de prueba después del desarrollo.