API multi-usuario para sincronizar progreso de lectura desde KOReader a Goodreads automáticamente.
- ✅ Multi-usuario: Soporta múltiples usuarios simultáneos con sesiones independientes
- ✅ Búsqueda inteligente: Fuzzy matching avanzado para títulos y autores
- ✅ Manejo de sagas: Detecta y diferencia libros de series automáticamente
- ✅ Auto-ping: Mantiene el servidor activo en Render Free Tier
- ✅ Sincronización en background: No bloquea las peticiones HTTP
- ✅ Plugin KOReader: Integración completa con interfaz gráfica
El servidor ya está desplegado y listo para usar en:
https://tracker-reader.onrender.com
Solo necesitas configurar el plugin de KOReader (ver sección Plugin KOReader).
-
Clonar el repositorio
git clone <tu-repositorio> cd api-tracker-reader
-
Instalar dependencias
pip install -r requirements.txt playwright install chromium
-
Ejecutar el servidor
python main.py
-
Verificar que funciona
curl http://localhost:8000/ping
Inicia sesión en Goodreads y obtiene un token de usuario.
Request:
{
"username": "tu-email@ejemplo.com",
"password": "tu-contraseña"
}Response:
{
"user_id": "abc123def456",
"status": "success",
"message": "Login exitoso. Guarda el user_id para futuras peticiones."
}Sincroniza el progreso de lectura con Goodreads.
Request:
{
"user_id": "abc123def456",
"titulo": "El Señor de los Anillos",
"autor": "J.R.R. Tolkien",
"pagina_actual": 150,
"total_paginas": 500
}Response:
{
"status": "received",
"book": "El Señor de los Anillos",
"user_id": "abc123def456",
"message": "Sincronización iniciada en segundo plano"
}Health check para verificar que el servidor está activo.
Response:
{
"status": "alive",
"timestamp": "2026-01-23T16:19:22.123456",
"message": "Server is running"
}Documentación interactiva de la API (Swagger UI).
- Descarga la carpeta
tracker_hector.koplugin - Cópiala a la carpeta de plugins de KOReader:
- Android:
/sdcard/koreader/plugins/ - Kobo/Kindle:
.adds/koreader/plugins/
- Android:
- Reinicia KOReader
- Abre cualquier libro
- Menú superior → Hector's Tracker → Configurar Servidor
- Ingresa la URL:
https://tracker-reader.onrender.com - Guarda la configuración
- Ve a Login en Goodreads
- Ingresa tu email y contraseña de Goodreads
Sincronización Manual:
- Menú → Hector's Tracker → Sincronizar Ahora
Sincronización Automática:
- Se sincroniza automáticamente al cerrar un libro
┌─────────────────┐
│ KOReader │
│ (Plugin Lua) │
└────────┬────────┘
│ HTTP POST
▼
┌─────────────────────────────────┐
│ FastAPI Server │
│ ┌─────────────────────────┐ │
│ │ /login /sync /ping │ │
│ └───────────┬─────────────┘ │
│ │ │
│ ┌───────────▼─────────────┐ │
│ │ ThreadPoolExecutor │ │
│ │ (Playwright Sync API) │ │
│ └───────────┬─────────────┘ │
│ │ │
│ ┌───────────▼─────────────┐ │
│ │ Scraper Logic │ │
│ │ - Login │ │
│ │ - Search (Fuzzy) │ │
│ │ - Update Progress │ │
│ └─────────────────────────┘ │
└─────────────────────────────────┘
│
▼
┌─────────────────┐
│ Goodreads │
│ (Web Scraping)│
└─────────────────┘
- FastAPI: Framework web moderno y rápido
- Playwright: Automatización de navegador para scraping
- Rapidfuzz: Fuzzy matching de strings
- Pydantic: Validación de datos
- httpx: Cliente HTTP asíncrono
api-tracker-reader/
├── main.py # Punto de entrada de FastAPI
├── scraper.py # Lógica de Playwright (login, búsqueda, actualización)
├── auth.py # Manejo de sesiones y user_id
├── models.py # Modelos Pydantic
├── utils.py # Funciones auxiliares (JS injection)
├── requirements.txt # Dependencias Python
├── Procfile # Configuración para Render
├── DEPLOY.md # Guía de despliegue
├── README.md # Este archivo
└── tracker_hector.koplugin/
├── _meta.lua # Metadatos del plugin
├── main.lua # Lógica del plugin KOReader
└── README.md # Documentación del plugin
Consulta la Guía de Despliegue para instrucciones detalladas.
Resumen rápido:
-
Build Command:
pip install -r requirements.txt && playwright install chromium && playwright install-deps
-
Start Command:
uvicorn main:app --host 0.0.0.0 --port $PORT -
Variables de Entorno:
HEADLESS=TruePYTHON_VERSION=3.11.0
El servidor incluye un sistema de auto-ping que:
- Hace ping a sí mismo cada 10 minutos
- Evita que Render Free Tier suspenda el servidor (timeout de 15 min)
- Se activa automáticamente al iniciar
- Configurable mediante la variable
RENDER_EXTERNAL_URL
Logs esperados:
✅ Auto-ping activado - El servidor se mantendrá activo
🏓 Auto-ping exitoso: 200 - 2026-01-23T16:19:22.123456
-
Sin persistencia de archivos: Las sesiones se pierden al reiniciar el servidor
- Solución temporal: Los usuarios deben hacer login nuevamente
- Solución futura: Migrar a base de datos externa (MongoDB Atlas)
-
Timeout de 30 segundos: Las peticiones HTTP tienen límite de 30s
- La sincronización se ejecuta en background para evitar timeouts
-
Suspensión por inactividad: Sin auto-ping, el servidor se suspende en 15 min
- El auto-ping lo mantiene activo indefinidamente
Solución: Verifica que el auto-ping esté funcionando en los logs de Render.
Causa: Render Free Tier no tiene persistencia de disco.
Solución: Realiza login nuevamente desde el plugin de KOReader.
Solución: Ejecuta el login nuevamente desde KOReader.
- Migrar sesiones a MongoDB Atlas (persistencia)
- Implementar caché de búsquedas
- Añadir métricas de uso
- Dockerizar la aplicación
- Soporte para otros servicios (LibraryThing, StoryGraph)
MIT License - Siéntete libre de usar y modificar este proyecto.
Las contribuciones son bienvenidas! Por favor:
- Fork el proyecto
- Crea una rama para tu feature (
git checkout -b feature/AmazingFeature) - Commit tus cambios (
git commit -m 'Add some AmazingFeature') - Push a la rama (
git push origin feature/AmazingFeature) - Abre un Pull Request
Si encuentras problemas:
- Revisa la Guía de Despliegue
- Consulta la documentación del Plugin KOReader
- Abre un issue en GitHub
Hecho con ❤️ para la comunidad de KOReader