hechakuaa_bot/MANUAL_USUARIO.md

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á:

python3 --version

Tiene que decir 3.12.x o superior. Si dice 3.11 o menos, instalá Python 3.12 desde 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:

pip install uv

Verificar que quedó instalado:

uv --version

---

Paso 3 — Instalar dependencias

Dentro de la carpeta del proyecto:

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

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:

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

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

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):

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):

# /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

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:

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.