Automatización de cargas de archivos con la API de Drive

La automatización de cargas es uno de los flujos de trabajo más útiles de la API de Drive. Informes, facturas, exportaciones generadas, PDF firmados y adjuntos de soporte pueden llegar a la carpeta correcta de TrekMail Drive sin arrastrarlos y soltarlos manualmente.

El patrón seguro es sencillo: comprueba el almacenamiento, crea o elige una carpeta, inicia la carga, transfiere los bytes, completa la carga y escribe un registro de auditoría útil.

Alcances recomendados

Para cargar en el Drive de la cuenta, comienza con:

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

Para cargar en el Drive de un buzón, usa:

• drive:mailbox:read
• drive:mailbox:write

Evita los alcances de compartir y borrado permanente, salvo que el mismo flujo de trabajo realmente los necesite. Si la tarea de carga también crea enlaces públicos, añade el alcance de uso compartido correspondiente.

Comprobaciones previas

Antes de cargar un archivo grande, consulta el endpoint de resumen de almacenamiento o de uso del espacio. Tu integración debe tratar "cuota superada" como un resultado normal del negocio, no como un fallo de la aplicación.

Una buena automatización también comprueba si existe la carpeta de destino. Si no existe, créala con una clave de idempotencia para que los reintentos no generen carpetas duplicadas.

Flujo de carga REST

1. Envía POST /api/v1/drive/spaces/{space}/uploads:initiate con el nombre y tamaño del archivo, el ID de carpeta opcional y el tipo MIME.
2. Envía los bytes del archivo a la URL de carga o a las URL de carga multiparte devueltas.
3. Envía POST /api/v1/drive/uploads/{file}:complete cuando la transferencia finalice correctamente.
4. Si la transferencia falla, llama a POST /api/v1/drive/uploads/{file}:abort para liberar la reserva rápidamente.

Usa una Idempotency-Key en la solicitud de inicio, que reserva capacidad de carga. Usa una clave estable para cada archivo lógico, como invoice-2026-05-001-upload. No des por hecho que todos los endpoints de carga posteriores reproducen resultados idempotentes; conserva el ID de archivo devuelto y comprueba su estado antes de reintentar la finalización o cancelar una transferencia.

Flujo de carga MCP

Para los agentes, utiliza preferentemente una herramienta:

drive_file_upload(space="account", local_path="/exports/report.pdf", folder_id=42)

El contenedor MCP gestiona la negociación de la carga, la transferencia, la finalización y la cancelación en caso de error. Hay herramientas de bajo nivel para lógicas de transferencia personalizadas, pero la mayoría de los flujos de trabajo no las necesitan.

Convenciones de nombres y carpetas

Usa nombres predecibles para que las personas puedan explorar Drive más adelante:

• Reports/2026/05/monthly-summary.pdf
• Clients/Acme/contracts/acme-renewal-2026.pdf
• Invoices/2026/INV-2026-0042.pdf

Si un agente carga versiones repetidas, incluye marcas de tiempo o etiquetas de versión. No ocultes el significado sobrescribiendo final.pdf cada semana.

Gestión de errores

Planifica estos casos:

Después de la carga

Si el archivo está destinado a entrega externa, crea un enlace para compartir con fecha de caducidad y límite de descargas. Si es interno, déjalo como un archivo normal de Drive. En ambos casos, consulta Agentes de IA y API → Registro de auditoría para confirmar el token y la secuencia de acciones.