API de monitoreo judicial.
Manual de referencia para autenticación, consulta de cuenta, catálogos, gestión de expedientes y búsqueda de acuerdos. Esta versión sustituye al handbook en PDF y se entrega directamente en web.
Introducción
La API de monitoreo judicial permite registrar expedientes bajo una cuenta autenticada y consultar los acuerdos asociados a esos expedientes en jurisdicción federal y estatal. Está pensada para integraciones con sistemas internos, dashboards operativos y aplicaciones que necesitan consumir datos judiciales en JSON.
Esta API
- Expone endpoints JSON para autenticación, catálogos, expedientes y acuerdos.
- Permite decidir cuándo consultar y con qué filtros.
- Está orientada a integraciones y automatización de procesos.
API de alertas
- Envía notificaciones automáticas por correo.
- Opera como mecanismo de aviso, no como API de consulta operativa.
- Sirve cuando el objetivo es recibir alertas, no integrar resultados en tiempo real.
Inicio rápido
El flujo base para operar la API es siempre el mismo: autenticar, consultar catálogos, crear expedientes válidos y luego consultar acuerdos sobre los expedientes ya registrados.
curl -X POST https://monitoreo.buholegal.com/api/v1/users/login/ \
-H "Content-Type: application/json" \
-d '{
"username": "usuario@ejemplo.com",
"password": "mi-contraseña-segura"
}'
curl -H "Authorization: Bearer <token>" \
https://monitoreo.buholegal.com/api/v1/fuentes/
curl -X POST https://monitoreo.buholegal.com/api/v1/expedientes/create/federal/ \
-H "Authorization: Bearer <token>" \
-H "Content-Type: application/json" \
-d '{
"expediente": "123/2025",
"nombre": "Mi expediente federal",
"juzgado_id": 1533,
"tipo_expediente": "60"
}'
curl -H "Authorization: Bearer <token>" \
"https://monitoreo.buholegal.com/api/v1/mis-acuerdos/?tipo=ordenados&limit=20"
Autenticación
El endpoint de login usa el campo username. Internamente acepta tanto nombre de usuario como correo electrónico y devuelve un token de acceso y un token de refresh.
Login
{
"username": "usuario@ejemplo.com",
"password": "mi-contraseña-segura"
}
{
"refresh": "eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9...",
"access": "eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9..."
}
Refresh
{
"refresh": "eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9..."
}
Headers
Authorization: Bearer eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9...
Cuenta de usuario
El endpoint de estado de cuenta muestra límites, uso actual y disponibilidad para crear expedientes o hacer consultas. Es la referencia operativa para saber si una cuenta todavía puede trabajar.
{
"success": true,
"message": "Estado de cuenta obtenido exitosamente",
"data": {
"buhouser_id": 583574,
"limite_expedientes": 10,
"expedientes_registrados": 3,
"expedientes_disponibles": 7,
"limite_consultas_diarias": 50,
"consultas_hoy": 12,
"consultas_disponibles": 38,
"puede_crear_expediente": true,
"puede_consultar": true
}
}
Gestión de expedientes
Los expedientes se registran por entidad y quedan asociados al usuario autenticado. El alta ya no se limita a validar formato: ahora también valida existencia real del expediente en la fuente judicial.
Crear expediente
{
"expediente": "123/2025",
"nombre": "Mi expediente federal",
"juzgado_id": 1533,
"tipo_expediente": "60",
"asunto": "Amparo indirecto",
"notas": "Seguimiento interno"
}
{
"success": true,
"message": "Expediente creado exitosamente",
"data": {
"id": 127,
"expediente": "123/2025",
"nombre": "Mi expediente federal",
"entidad": "federal"
}
}
Listar expedientes
GET https://monitoreo.buholegal.com/api/v1/expedientes/list/?entidad=federal
Editar y eliminar
- Campos mínimos de alta: expediente, nombre y juzgado_id.
- tipo_expediente puede volverse obligatorio según la entidad.
- Si el expediente ya existe para el usuario, la API responde 409.
- Si el expediente no existe en la fuente, la API responde 404.
Catálogos
Antes de crear expedientes conviene resolver primero la jurisdicción y sus catálogos auxiliares. La API expone entidades, juzgados, circuitos, organismos federales y tipos de expediente.
| Método | Endpoint | Uso |
|---|---|---|
| GET | /fuentes/ | Lista de entidades o fuentes disponibles. |
| GET | /circuitos-federales/ | Catálogo de circuitos federales. |
| GET | /organismos-federales/<id_circuito>/ | Organismos o juzgados dentro de un circuito federal. |
| GET | /juzgados/<entidad>/ | Juzgados estatales por entidad. |
| GET | /tipos/expedientes/<entidad>/ | Tipos de expediente por entidad. |
curl -H "Authorization: Bearer <token>" \
https://monitoreo.buholegal.com/api/v1/tipos/expedientes/federal/
Mis acuerdos
/mis-acuerdos/ consulta acuerdos solo para los expedientes que ya están guardados en la cuenta autenticada. El endpoint admite filtros por expediente, entidad, tipo de consulta y rango de fechas.
| Parámetro | Tipo | Descripción |
|---|---|---|
| expediente | string | Filtra por número de expediente registrado. |
| entidad | string | Restringe la búsqueda a una entidad específica. |
| limit | integer | Límite de resultados. El endpoint aplica corte durante la búsqueda. |
| tipo | string | hoy, ordenados, recientes o rango_fechas. |
| fecha_desde | date | Fecha inicial para rango_fechas. |
| fecha_hasta | date | Fecha final para rango_fechas. |
GET https://monitoreo.buholegal.com/api/v1/mis-acuerdos/?tipo=ordenados&limit=50
GET https://monitoreo.buholegal.com/api/v1/mis-acuerdos/?entidad=federal&limit=50
GET https://monitoreo.buholegal.com/api/v1/mis-acuerdos/?expediente=123/2025&tipo=hoy
GET https://monitoreo.buholegal.com/api/v1/mis-acuerdos/?tipo=rango_fechas&fecha_desde=2025-09-01&fecha_hasta=2025-09-05
{
"success": true,
"tipo_busqueda": "ordenados",
"filtro_expediente": null,
"total_mis_expedientes": 2,
"total_encontrados": 3,
"limite_aplicado": 50,
"acuerdos": [
{
"id": 19430,
"expediente": "123/2025",
"fecha": "2025-09-08",
"juzgado_fk": 1533,
"acuerdo": "Se tiene por presentado...",
"entidad": "federal",
"tipo": "federal",
"mi_expediente_id": 127,
"mi_expediente_nombre": "Mi expediente federal"
}
]
}
Manejo de errores
La API utiliza códigos HTTP estándar y, en la mayoría de los casos, entrega un cuerpo con success, error_type y message.
| Código | Significado | Cuándo aparece |
|---|---|---|
| 200 | OK | Consulta o actualización exitosa. |
| 201 | Created | Expediente creado exitosamente. |
| 400 | Bad Request | Parámetros faltantes o inválidos. |
| 401 | Unauthorized | Token faltante o inválido. |
| 404 | Not Found | Recurso inexistente o expediente no encontrado en fuente. |
| 409 | Conflict | Alta duplicada del mismo expediente para el usuario. |
| 429 | Too Many Requests | Límite de expedientes o de consultas alcanzado. |
| 500 | Internal Server Error | Error interno no controlado. |
| 503 | Service Unavailable | No fue posible validar contra la fuente judicial. |
{
"success": false,
"error": true,
"error_type": "expediente_no_encontrado",
"message": "El expediente no existe en la fuente judicial seleccionada",
"status_code": 404
}
Referencia rápida
| Método | Endpoint | Descripción |
|---|---|---|
| POST | /users/login/ | Autenticación con username o email en el campo username. |
| POST | /users/refresh/ | Renueva el token de acceso. |
| GET | /users/me/ | Devuelve información básica del usuario autenticado. |
| GET | /cuenta/estado/ | Consulta límites y uso de la cuenta. |
| GET | /fuentes/ | Lista de entidades soportadas. |
| GET | /circuitos-federales/ | Catálogo de circuitos federales. |
| GET | /organismos-federales/<id_circuito>/ | Organismos por circuito federal. |
| GET | /juzgados/<entidad>/ | Juzgados por entidad estatal. |
| GET | /tipos/expedientes/<entidad>/ | Tipos de expediente por entidad. |
| POST | /expedientes/create/<entidad>/ | Alta de expediente para monitoreo. |
| GET | /expedientes/list/ | Lista de expedientes del usuario. |
| PATCH | /expedientes/edit/<id>/ | Actualización parcial del expediente. |
| DELETE | /expedientes/delete/<id>/ | Eliminación del expediente. |
| GET | /mis-acuerdos/ | Búsqueda de acuerdos sobre expedientes guardados. |
| GET | /help/endpoints/ | Resumen JSON de endpoints y ejemplos. |
Ejemplos completos
Python
import requests
class MonitoreoAPI:
def __init__(self, base_url="https://monitoreo.buholegal.com/api/v1"):
self.base_url = base_url
self.token = None
def login(self, username, password):
response = requests.post(
f"{self.base_url}/users/login/",
json={"username": username, "password": password},
timeout=30,
)
response.raise_for_status()
payload = response.json()
self.token = payload["access"]
return payload
def headers(self):
return {"Authorization": f"Bearer {self.token}"}
def listar_expedientes(self):
return requests.get(
f"{self.base_url}/expedientes/list/",
headers=self.headers(),
timeout=30,
).json()
def mis_acuerdos(self, **params):
return requests.get(
f"{self.base_url}/mis-acuerdos/",
params=params,
headers=self.headers(),
timeout=30,
).json()
JavaScript
class MonitoreoAPIClient {
constructor(baseUrl = 'https://monitoreo.buholegal.com/api/v1') {
this.baseUrl = baseUrl;
this.token = null;
}
async login(username, password) {
const response = await fetch(`${this.baseUrl}/users/login/`, {
method: 'POST',
headers: { 'Content-Type': 'application/json' },
body: JSON.stringify({ username, password })
});
if (!response.ok) {
throw new Error('No fue posible iniciar sesión');
}
const data = await response.json();
this.token = data.access;
return data;
}
authHeaders() {
return { Authorization: `Bearer ${this.token}` };
}
async misAcuerdos(filtros = {}) {
const params = new URLSearchParams(filtros);
const response = await fetch(
`${this.baseUrl}/mis-acuerdos/?${params.toString()}`,
{ headers: this.authHeaders() }
);
return await response.json();
}
}
Soporte y recursos
- Si el objetivo es una integración, usa este handbook junto con Swagger.
- Si el objetivo es monitoreo visual o pruebas rápidas, usa el dashboard.
- Si el expediente no existe en la fuente o no coincide con juzgado y tipo, no debe guardarse.