BuhoLegal Handbook
Documentación operativa

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.

JWT con refresh Expedientes por usuario Acuerdos judiciales

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.
Formato JSON en todas las respuestas
Autenticación JWT con header Authorization: Bearer ...
Documentación interactiva https://monitoreo.buholegal.com/

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.

Paso 1 Haz login y guarda el access
Paso 2 Obtén entidad, juzgado y tipo si aplica
Paso 3 Crea el expediente y consulta /mis-acuerdos/
Flujo mínimo con curl bash
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

POST /users/login/ json
{
  "username": "usuario@ejemplo.com",
  "password": "mi-contraseña-segura"
}
Campo de entrada Aunque el nombre del campo es username, la autenticación acepta correo electrónico o username. Esa es la convención que sigue también el dashboard.
Respuesta exitosa 200
{
  "refresh": "eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9...",
  "access": "eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9..."
}

Refresh

POST /users/refresh/ json
{
  "refresh": "eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9..."
}

Headers

Authorization header
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.

GET /cuenta/estado/ Bearer JWT
{
  "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
  }
}
Límite de expedientes Cada cuenta tiene un máximo de expedientes registrados. Si se alcanza, el alta responde 429.
Límite de consultas Las consultas diarias de acuerdos también están controladas por cuenta y se reinician de forma periódica.

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.

Validación al crear El endpoint de creación impide guardar expedientes que no existan en la fuente consultada. Para algunas entidades, también exige tipo_expediente y lo valida junto con el número y el juzgado.

Crear expediente

POST /expedientes/create/<entidad>/ json
{
  "expediente": "123/2025",
  "nombre": "Mi expediente federal",
  "juzgado_id": 1533,
  "tipo_expediente": "60",
  "asunto": "Amparo indirecto",
  "notas": "Seguimiento interno"
}
Respuesta exitosa 201
{
  "success": true,
  "message": "Expediente creado exitosamente",
  "data": {
    "id": 127,
    "expediente": "123/2025",
    "nombre": "Mi expediente federal",
    "entidad": "federal"
  }
}

Listar expedientes

GET /expedientes/list/ query opcional
GET https://monitoreo.buholegal.com/api/v1/expedientes/list/?entidad=federal

Editar y eliminar

Actualizar PATCH /expedientes/edit/<id>/
Eliminar DELETE /expedientes/delete/<id>/
  • 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.
Ejemplo curl
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 /mis-acuerdos/ ejemplos
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
Respuesta típica 200
{
  "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"
    }
  ]
}
Comportamiento actual El endpoint devuelve acuerdos de los expedientes guardados, no solo los publicados después del alta del monitoreo.

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.
Error de expediente inexistente 404
{
  "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

Cliente básico 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

Cliente web 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

Base URL https://monitoreo.buholegal.com/api/v1/
  • 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.