API REST — Referencia de Endpoints¶

GexCom expone una API REST con FastAPI en el puerto :8000. Todos los endpoints (excepto /health, /ready y /auth/login) requieren autenticacion JWT.

Autenticacion¶

Obtener Token¶

POST /auth/login
Content-Type: application/json

{
  "email": "admin@csj.gov.co",
  "password": "Admin2026!"
}

Respuesta 200 OK:

{
  "access_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
  "token_type": "bearer"
}

El token tiene una validez de 480 minutos (8 horas). Incluirlo en el header:

Authorization: Bearer <access_token>

Politica de Lockout¶

Despues de 5 intentos fallidos consecutivos, la cuenta queda bloqueada durante 15 minutos (TTL persistente en base de datos).

Endpoints de Salud¶

Metodo	Ruta	Descripcion	Auth
GET	`/health`	Liveness probe — app corriendo	No
GET	`/ready`	Readiness probe — DB alcanzable	No

GET /health
→ {"status": "ok"}

GET /ready
→ {"status": "ready"} | {"status": "not_ready"}

Procesos¶

Metodo	Ruta	Descripcion	Rol minimo
GET	`/procesos`	Listar todos los procesos (paginado)	NOTIFICADOR
POST	`/procesos`	Crear proceso	NOTIFICADOR
GET	`/procesos/{id}`	Obtener proceso por ID	NOTIFICADOR

GET /procesos¶

GET /procesos?page=1&page_size=20
Authorization: Bearer <token>

Respuesta 200 OK:

{
  "items": [
    {
      "id": "uuid",
      "radicado": "2024-001234",
      "descripcion": "Proceso ordinario laboral",
      "estado": "ACTIVO",
      "juzgado_id": "uuid",
      "fecha_creacion": "2026-04-01T10:00:00"
    }
  ],
  "total": 45,
  "page": 1,
  "page_size": 20
}

POST /procesos¶

POST /procesos
Authorization: Bearer <token>
Content-Type: application/json

{
  "radicado": "2026-000123",
  "descripcion": "Tutela por vulneracion derecho a la salud",
  "juzgado_id": "uuid-del-juzgado"
}

Notificaciones¶

Metodo	Ruta	Descripcion	Rol minimo
GET	`/notificaciones`	Listar notificaciones (paginado)	NOTIFICADOR
POST	`/notificaciones`	Crear notificacion	NOTIFICADOR
GET	`/notificaciones/{id}`	Obtener notificacion por ID	NOTIFICADOR
PATCH	`/notificaciones/{id}/estado`	Cambiar estado	NOTIFICADOR

POST /notificaciones¶

POST /notificaciones
Authorization: Bearer <token>
Content-Type: application/json

{
  "id_proceso": "uuid-proceso",
  "id_sujeto": "uuid-sujeto",
  "canal": "EMAIL",
  "observacion": "Primera notificacion del proceso"
}

Canales validos: EMAIL, WHATSAPP, PRESENCIAL, TELEFONO, CORREO_FISICO

PATCH /notificaciones/{id}/estado¶

PATCH /notificaciones/uuid/estado
Authorization: Bearer <token>
Content-Type: application/json

{
  "nuevo_estado": "EN_PROCESO",
  "observacion": "Iniciando gestion de notificacion"
}

Estados validos: PENDIENTE, EN_PROCESO, ENVIADA, RECIBIDA, FALLIDA, CANCELADA

Sujetos¶

Metodo	Ruta	Descripcion	Rol minimo
GET	`/sujetos`	Listar sujetos	NOTIFICADOR
POST	`/sujetos`	Crear sujeto	NOTIFICADOR
GET	`/sujetos/{id}`	Obtener sujeto por ID	NOTIFICADOR

Usuarios¶

Metodo	Ruta	Descripcion	Rol minimo
GET	`/usuarios`	Listar usuarios	ADMINISTRADOR
POST	`/usuarios`	Crear usuario	ADMINISTRADOR

Solo ADMINISTRADOR

Los endpoints de /usuarios requieren el rol ADMINISTRADOR. Devuelven 403 Forbidden si el token tiene rol NOTIFICADOR.

Codigos de Error¶

Codigo	Descripcion
`400`	Bad Request — datos invalidos o regla de negocio violada
`401`	Unauthorized — token ausente, invalido o expirado
`403`	Forbidden — rol insuficiente
`404`	Not Found — recurso no encontrado
`422`	Unprocessable Entity — validacion Pydantic fallida
`500`	Internal Server Error — error inesperado

Documentacion Interactiva¶

Con el servidor corriendo:

Swagger UI: http://localhost:8000/docs
ReDoc: http://localhost:8000/redoc
OpenAPI JSON: http://localhost:8000/openapi.json

Backlog P03

API-DOCS: El endpoint /docs (Swagger UI) esta expuesto sin autenticacion. En produccion se recomienda restringir el acceso o deshabilitar con docs_url=None en el constructor de FastAPI.

Ejemplo: Flujo completo con curl¶

# 1. Login
TOKEN=$(curl -s -X POST http://localhost:8000/auth/login \
  -H "Content-Type: application/json" \
  -d '{"email":"admin@csj.gov.co","password":"Admin2026!"}' \
  | python -c "import sys,json; print(json.load(sys.stdin)['access_token'])")

# 2. Crear proceso
curl -X POST http://localhost:8000/procesos \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"radicado":"2026-TEST-001","descripcion":"Proceso de prueba","juzgado_id":"<uuid>"}'

# 3. Listar notificaciones
curl http://localhost:8000/notificaciones \
  -H "Authorization: Bearer $TOKEN"