7743919695
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>
324 lines
9.2 KiB
Markdown
324 lines
9.2 KiB
Markdown
# 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.*
|