Initial commit — Pedrito Hechakuaa v0
Bot de Telegram para monitoreo de notificaciones judiciales del PJ Paraguay. Multi-tenant con onboarding conversacional, audit log, y polling automático. Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
This commit is contained in:
markosbenitez
323
MANUAL_USUARIO.md
Normal file
323
MANUAL_USUARIO.md
Normal file
@@ -0,0 +1,323 @@
|
||||
# Pedrito Hechakuaa — Manual de usuario
|
||||
|
||||
**Pedrito Hechakuaa** es un bot de Telegram que revisa tu cuenta del sistema judicial del Poder Judicial de Paraguay (`apps.csj.gov.py`) y te avisa cuando aparecen notificaciones nuevas. También podés consultar el estado de cualquier expediente directamente desde Telegram.
|
||||
|
||||
---
|
||||
|
||||
## ¿Qué hace exactamente?
|
||||
|
||||
- Revisa tus notificaciones pendientes en el PJ cada hora, de lunes a viernes entre las 7:00 y las 18:00 (hora de Asunción).
|
||||
- Te manda un mensaje por Telegram cuando aparece algo nuevo.
|
||||
- Te deja consultar el detalle de cualquier expediente por número o por carátula.
|
||||
- **No acusa notificaciones.** Pedrito Hechakuaa es de solo lectura — nunca toca nada que tenga efecto procesal. Para acusar, entrás vos directamente a `apps.csj.gov.py`.
|
||||
|
||||
---
|
||||
|
||||
## Instalación y configuración
|
||||
|
||||
### Lo que necesitás antes de empezar
|
||||
|
||||
- Python 3.12 o superior instalado
|
||||
- Una cuenta en Telegram
|
||||
- Un bot de Telegram creado (lo creás vos, gratis, en 2 minutos)
|
||||
- Tu chat ID de Telegram
|
||||
- Las credenciales del sistema del PJ (cédula y contraseña)
|
||||
|
||||
---
|
||||
|
||||
### Paso 1 — Verificar Python
|
||||
|
||||
Abrí la terminal y ejecutá:
|
||||
|
||||
```bash
|
||||
python3 --version
|
||||
```
|
||||
|
||||
Tiene que decir `3.12.x` o superior. Si dice `3.11` o menos, instalá Python 3.12 desde [python.org](https://www.python.org) o con `brew install python@3.12` en Mac.
|
||||
|
||||
> Si no tenés Python 3.12 pero sí tenés `uv` instalado, no hay problema — `uv` descarga la versión correcta automáticamente.
|
||||
|
||||
---
|
||||
|
||||
### Paso 2 — Instalar uv
|
||||
|
||||
`uv` es el gestor de dependencias que usa el proyecto. Si no lo tenés:
|
||||
|
||||
```bash
|
||||
pip install uv
|
||||
```
|
||||
|
||||
Verificar que quedó instalado:
|
||||
|
||||
```bash
|
||||
uv --version
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### Paso 3 — Instalar dependencias
|
||||
|
||||
Dentro de la carpeta del proyecto:
|
||||
|
||||
```bash
|
||||
uv sync
|
||||
```
|
||||
|
||||
Esto crea un entorno virtual e instala todo. Tarda entre 30 y 60 segundos la primera vez.
|
||||
|
||||
---
|
||||
|
||||
### Paso 4 — Configurar el archivo .env
|
||||
|
||||
```bash
|
||||
cp .env.example .env
|
||||
```
|
||||
|
||||
Abrí el `.env` con cualquier editor de texto y completá los cuatro valores obligatorios:
|
||||
|
||||
**4a. Generar la FERNET_KEY**
|
||||
|
||||
Esta clave cifra tus credenciales del PJ. Ejecutá esto en la terminal y copiá el resultado:
|
||||
|
||||
```bash
|
||||
uv run python -c "from cryptography.fernet import Fernet; print(Fernet.generate_key().decode())"
|
||||
```
|
||||
|
||||
Pegalo en el `.env` en la línea `FERNET_KEY=`.
|
||||
|
||||
> Guardala también en un lugar seguro (gestor de contraseñas, por ejemplo). Si perdés esta clave, tendrás que volver a cifrar las credenciales del PJ.
|
||||
|
||||
**4b. Crear el bot de Telegram y obtener el token**
|
||||
|
||||
1. Abrí Telegram y buscá **@BotFather**
|
||||
2. Mandále `/newbot`
|
||||
3. Seguí las instrucciones: te va a pedir un nombre y un username para el bot
|
||||
4. Al final te da un token con este formato: `123456789:AAFxxx...`
|
||||
5. Pegalo en el `.env` en la línea `TELEGRAM_BOT_TOKEN=`
|
||||
|
||||
**4c. Obtener tu chat ID**
|
||||
|
||||
1. En Telegram buscá **@userinfobot**
|
||||
2. Mandále cualquier mensaje
|
||||
3. Te responde con tu ID numérico (algo como `98765432`)
|
||||
4. Pegalo en el `.env` en la línea `TELEGRAM_CHAT_ID=`
|
||||
|
||||
El `.env` debería quedar así (los demás valores podés dejarlos comentados):
|
||||
|
||||
```
|
||||
FERNET_KEY=tu-clave-generada
|
||||
TELEGRAM_BOT_TOKEN=123456789:AAFxxx...
|
||||
TELEGRAM_CHAT_ID=98765432
|
||||
PJ_USUARIO_ENC=
|
||||
PJ_PASSWORD_ENC=
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### Paso 5 — Cifrar las credenciales del PJ
|
||||
|
||||
```bash
|
||||
uv run python scripts/cifrar_credenciales.py
|
||||
```
|
||||
|
||||
El script te pide:
|
||||
|
||||
- Tu **cédula de identidad** (la que usás para entrar a `apps.csj.gov.py`)
|
||||
- Tu **contraseña del PJ** (no se muestra mientras escribís)
|
||||
|
||||
Las cifra con tu FERNET_KEY y actualiza automáticamente `PJ_USUARIO_ENC` y `PJ_PASSWORD_ENC` en tu `.env`. La contraseña en texto plano nunca se guarda en ningún lado.
|
||||
|
||||
---
|
||||
|
||||
### Paso 6 — Arrancar el bot
|
||||
|
||||
```bash
|
||||
uv run python main.py
|
||||
```
|
||||
|
||||
Lo que debería pasar:
|
||||
|
||||
1. El bot se conecta al PJ y revisa tus notificaciones actuales
|
||||
2. Abrís Telegram, buscás tu bot por su username, y le mandás `/start`
|
||||
3. El bot responde con el estado inicial
|
||||
4. A partir de ahí, te avisa automáticamente cuando aparezca algo nuevo
|
||||
|
||||
---
|
||||
|
||||
## Comandos disponibles
|
||||
|
||||
| Comando | Qué hace |
|
||||
|---------|---------|
|
||||
| `/start` | Muestra el estado del bot y los comandos disponibles |
|
||||
| `/notif` | Revisa las notificaciones ahora mismo, sin esperar la próxima hora |
|
||||
| `/estado` | Muestra el último chequeo y cuántas notificaciones tiene registradas |
|
||||
| `/ayuda` | Lista todos los comandos |
|
||||
| `/exp 198` | Busca el expediente número 198 (sin filtrar por año) |
|
||||
| `/exp 198/2026` | Busca el expediente 198 del año 2026 |
|
||||
| `/exp carlos` | Busca expedientes que tengan "carlos" en la carátula |
|
||||
|
||||
---
|
||||
|
||||
## Cómo se ven las notificaciones
|
||||
|
||||
Cuando aparece una notificación nueva, el bot te manda esto:
|
||||
|
||||
```
|
||||
📋 Nueva notificación judicial
|
||||
|
||||
Rodríguez c/ Municipalidad Capital
|
||||
Exp. 1234/2024 — 1er Juzgado Civil Capital
|
||||
|
||||
Tipo: Auto Interlocutorio
|
||||
Fecha: 20/05/2026
|
||||
|
||||
⚠️ Para acusar esta notificación entrá directamente
|
||||
en https://apps.csj.gov.py
|
||||
```
|
||||
|
||||
El botón **"Ir al sistema del PJ"** te lleva directo a la pantalla de notificaciones.
|
||||
|
||||
---
|
||||
|
||||
## Cómo se ve la consulta de expediente
|
||||
|
||||
**Con un único resultado** (`/exp 198/2026`):
|
||||
|
||||
```
|
||||
📂 Exp. 198/2026
|
||||
Rodríguez c/ Municipalidad Capital
|
||||
1era Circunscripción | Activo
|
||||
|
||||
Últimas actuaciones:
|
||||
• 20/05/2026 — Auto Interlocutorio: Resolución N° 123
|
||||
• 15/05/2026 — Providencia: Autos y vistos
|
||||
• 10/05/2026 — Notificación: Cédula de notificación
|
||||
|
||||
(15 actuaciones en total)
|
||||
```
|
||||
|
||||
**Con múltiples resultados** (`/exp rodriguez`):
|
||||
|
||||
```
|
||||
Se encontraron 3 expedientes para "rodriguez":
|
||||
|
||||
1. Exp. 198/2026 — Rodríguez c/ Municipalidad Capital
|
||||
1era Circunscripción | Activo
|
||||
|
||||
2. Exp. 456/2025 — Rodríguez Díaz c/ Empresa SA
|
||||
1era Circunscripción | Archivado
|
||||
|
||||
3. ...
|
||||
|
||||
Para ver detalle: /exp {numero}/{anio}
|
||||
```
|
||||
|
||||
**Sin resultados** (`/exp 999999/1900`):
|
||||
|
||||
```
|
||||
No encontré expedientes para "999999/1900".
|
||||
Probá con la carátula o con número/año.
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Horario de monitoreo automático
|
||||
|
||||
El bot revisa el PJ **cada hora**, pero solo en horario hábil:
|
||||
|
||||
- **Días**: lunes a viernes
|
||||
- **Horario**: 7:00 a 18:00 (hora de Asunción, UTC-4)
|
||||
|
||||
Fuera de ese horario, el bot no molesta. Si querés revisar en cualquier momento (finde, feriado, madrugada), usá `/notif`.
|
||||
|
||||
---
|
||||
|
||||
## Correr como servicio en segundo plano
|
||||
|
||||
Si no querés tener la terminal abierta todo el tiempo:
|
||||
|
||||
**Con screen (la opción más simple):**
|
||||
|
||||
```bash
|
||||
screen -S pedrito
|
||||
uv run python main.py
|
||||
# Presioná Ctrl+A y luego D para dejar el bot corriendo en segundo plano
|
||||
# Para volver: screen -r pedrito
|
||||
```
|
||||
|
||||
**Con systemd (en un servidor Linux):**
|
||||
|
||||
```ini
|
||||
# /etc/systemd/system/pedrito.service
|
||||
[Unit]
|
||||
Description=Pedrito Hechakuaa — monitor judicial
|
||||
After=network.target
|
||||
|
||||
[Service]
|
||||
Type=simple
|
||||
WorkingDirectory=/ruta/al/proyecto
|
||||
ExecStart=/usr/bin/python3 main.py
|
||||
Restart=on-failure
|
||||
RestartSec=30
|
||||
|
||||
[Install]
|
||||
WantedBy=multi-user.target
|
||||
```
|
||||
|
||||
```bash
|
||||
sudo systemctl enable pedrito
|
||||
sudo systemctl start pedrito
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Solución de problemas comunes
|
||||
|
||||
### El bot no arranca
|
||||
|
||||
| Error | Causa | Solución |
|
||||
|-------|-------|---------|
|
||||
| `ModuleNotFoundError` | Faltan dependencias | Correr `uv sync` de nuevo en la carpeta del proyecto |
|
||||
| `ValidationError` o campo vacío | `.env` incompleto | Verificar que `FERNET_KEY`, `TELEGRAM_BOT_TOKEN`, `TELEGRAM_CHAT_ID`, `PJ_USUARIO_ENC` y `PJ_PASSWORD_ENC` estén completos |
|
||||
| `FERNET_KEY inválida` | La clave tiene espacios o fue copiada mal | Regenerar con `python -c "from cryptography.fernet import Fernet; print(Fernet.generate_key().decode())"` |
|
||||
| `PJ_USUARIO_ENC no se pudo descifrar` | Cambiaste la `FERNET_KEY` después de cifrar | Volver a correr `scripts/cifrar_credenciales.py` con la key actual |
|
||||
|
||||
### El bot arranca pero no responde en Telegram
|
||||
|
||||
- Verificar que `TELEGRAM_CHAT_ID` sea **tu** ID personal (el de la cuenta que va a usar el bot), no el ID del bot.
|
||||
- Asegurate de haberle mandado `/start` primero desde tu cuenta de Telegram.
|
||||
|
||||
### El bot arranca pero falla al conectarse al PJ
|
||||
|
||||
- **Login fallido (401):** las credenciales están incorrectas. Volver a correr `scripts/cifrar_credenciales.py`.
|
||||
- **Password temporal:** la contraseña del PJ es temporal. Entrá a `apps.csj.gov.py`, cambiala, y reiniciá el bot.
|
||||
- **Error de red:** el sistema del PJ tiene intermitencias. El bot va a reintentar automáticamente en la próxima ronda.
|
||||
|
||||
### Los campos de una notificación aparecen vacíos o con valores raros
|
||||
|
||||
El formato exacto de los responses del PJ puede diferir de lo documentado (el sistema tiene actualizaciones frecuentes). En ese caso, copiá el mensaje de error del log y consultá con el equipo técnico — se resuelve en minutos.
|
||||
|
||||
---
|
||||
|
||||
## Seguridad — lo que hace el sistema para proteger tus datos
|
||||
|
||||
- Las credenciales del PJ se cifran con AES-128 (Fernet) antes de guardarse. Nunca quedan en texto plano.
|
||||
- El `.env` con las credenciales cifradas está excluido del repositorio de código (`.gitignore`).
|
||||
- El bot solo responde a tu `TELEGRAM_CHAT_ID`. Si alguien más encuentra el bot por su nombre, no puede usarlo.
|
||||
- Pedrito Hechakuaa nunca acusa notificaciones ni ejecuta ninguna acción con efecto procesal. Es un lector.
|
||||
|
||||
---
|
||||
|
||||
## Actualizaciones de credenciales del PJ
|
||||
|
||||
Si cambiás la contraseña del PJ, simplemente volvés a correr:
|
||||
|
||||
```bash
|
||||
uv run python scripts/cifrar_credenciales.py
|
||||
```
|
||||
|
||||
Y reiniciás el bot. No hace falta tocar nada más.
|
||||
|
||||
---
|
||||
|
||||
*Pedrito Hechakuaa — uso personal, single-tenant.*
|
||||
Reference in New Issue
Block a user