Api-Gsuit/README.md

Google Workspace Hub (FastAPI + SQLite)

Proyecto base en FastAPI para centralizar acciones con Google Workspace (Gmail, Classroom, Calendar/Meet, etc.) y guardar tokens/usuarios en SQLite.

Qué incluye

• FastAPI listo para correr
• SQLite (con SQLModel)
• Flujo OAuth web:
  • GET /auth/google/start genera el link de autorización
  • GET /auth/google/callback recibe el code y guarda el token en SQLite
• Ejemplos de endpoints:
  • Gmail: GET /gmail/profile, POST /gmail/send
  • Classroom: GET /classroom/courses
  • Calendar/Meet: POST /calendar/events (crea evento con Meet)

Nota: Para que funcione necesitas crear un OAuth Client (Web application) en Google Cloud Console y descargar el client_secret.json.

---

Requisitos

• Python 3.11+ (recomendado)
• Una cuenta Google (o Workspace) y un proyecto en Google Cloud con APIs habilitadas:
  • Gmail API
  • Google Classroom API
  • Google Calendar API

1) Setup rápido (Windows PowerShell)

python -m venv .venv
.\.venv\Scripts\Activate.ps1
pip install -r requirements.txt
copy .env.example .env

2) Coloca tus credenciales

1. Crea carpeta: credentials/
2. Copia tu archivo OAuth aquí:
   • credentials/client_secret.json

No lo subas a git (ya está en .gitignore).

3) Configura el .env

Edita .env y pon:

• GOOGLE_REDIRECT_URI (ej: http://127.0.0.1:8000/auth/google/callback)
• GOOGLE_SCOPES (ya viene uno útil por defecto)

4) Corre el servidor

uvicorn app.main:app --reload

Abre:

• http://127.0.0.1:8000/docs

5) Autoriza tu cuenta Google

1. Ve a:
   • GET /auth/google/start
2. Abre el auth_url que te devuelve
3. Acepta permisos
4. Google te redirige a GOOGLE_REDIRECT_URI
5. Eso guarda el token en SQLite (app.db)

6) Probar endpoints

• Gmail profile:
  • GET /gmail/profile?account_email=TU_CORREO@gmail.com
• Enviar correo:
  • POST /gmail/send?account_email=TU_CORREO@gmail.com
• Listar cursos:
  • GET /classroom/courses?account_email=TU_CORREO@gmail.com
• Crear evento con Meet:
  • POST /calendar/events?account_email=TU_CORREO@gmail.com

---

Estructura

app/
  core/      config + DB
  google/    auth + clientes Google
  routers/   endpoints (oauth, gmail, classroom, calendar)
  models.py  tablas SQLite

Notas importantes

• Si tu cuenta es Workspace y quieres administrar usuarios/dominio (acciones “de admin”), eso normalmente se hace con Service Account + Domain-wide delegation. Aquí te dejo el proyecto listo para OAuth (usuario) porque es lo más simple para empezar.
• Si algo “se cae” por permisos: revisa los scopes y vuelve a autorizar (borrando el token del usuario en SQLite).

---

Próximos pasos sugeridos

• Roles/usuarios internos (login propio)
• Cola de tareas (para correos masivos): Celery/RQ/Arq
• Logs en DB (auditoría)