API Audiencias

Introducción

La API Pública de Audiencias es un servicio web desarrollado por el Poder Judicial que permite consultar información sobre audiencias judiciales programadas de manera programática. Esta API proporciona acceso a datos de audiencias utilizando el Número Único de Caso (NUC) como identificador principal.

Información General

Requisitos Previos

Para utilizar esta API, necesitará:

• Conexión a Internet: Acceso estable a la red
• Cliente HTTP: Cualquier herramienta capaz de realizar peticiones HTTP (curl, Postman, navegador web, etc.)
• Número Único de Caso (NUC): El identificador del caso judicial cuyas audiencias desea consultar
• Conocimientos básicos de:
  • Peticiones HTTP GET
  • Formato JSON
  • Manejo de respuestas de API REST

Endpoint Disponible

Parámetros de Consulta

Los parámetros se envían como query parameters en la URL.

Descripción Detallada de Parámetros

nuc (Número Único de Caso)

• Identificador único del caso judicial asignado por el sistema
• Formato: Cadena de texto alfanumérica
• Ejemplo: "199-2020-ELAB-00094"
• Sensible a mayúsculas y minúsculas

Estructura de Respuesta

Respuesta Exitosa (200 OK)

La API devuelve un objeto que contiene un array de audiencias en el campo data:

{
  "data": [
    {
      "nuc": "199-2020-ELAB-00094",
      "numeroTramite": "2020-001234",
      "asunto": "Demanda Laboral",
      "tribunal": "Tribunal de Trabajo",
      "sala": "Sala 1",
      "salon": "Salón A",
      "tipoAudiencia": "Audiencia Preliminar",
      "estado": "Programada",
      "urlAudiencia": "https://audiencias.poderjudicial.gob.do/audiencia/12345",
      "urlCelebracion": "https://meet.poderjudicial.gob.do/audiencia/12345",
      "fechaAudiencia": "2024-11-15T09:00:00",
      "horaAudiencia": "09:00 AM",
      "modalidad": "Virtual",
      "fechaAudienciaLetra": "15 de Noviembre de 2024",
      "tipoResultado": "Pendiente"
    }
  ]
}

Campos de la Respuesta

Ejemplos de Uso

Ejemplo 1: Consulta Básica con curl

curl -X GET "https://api.poderjudicial.gob.do/Audiencias/Audiencias/ObtenerAudienciasPorNuc?nuc=199-2020-ELAB-00094"

Ejemplo 2: Consulta con JavaScript (Fetch API)

const obtenerAudiencias = async (nuc) => {
  const url = `https://api.poderjudicial.gob.do/Audiencias/Audiencias/ObtenerAudienciasPorNuc?nuc=${nuc}`;

  try {
    const response = await fetch(url);

    if (!response.ok) {
      throw new Error(`Error HTTP: ${response.status}`);
    }

    const result = await response.json();

    console.log('Total de audiencias:', result.data.length);
    console.log('Audiencias:', result.data);

    return result.data;

  } catch (error) {
    console.error('Error al consultar audiencias:', error);
  }
};

// Uso
obtenerAudiencias('199-2020-ELAB-00094');

Ejemplo 3: Consulta con Python (requests)

import requests

def obtener_audiencias(nuc):
    url = "https://api.poderjudicial.gob.do/Audiencias/Audiencias/ObtenerAudienciasPorNuc"

    params = {
        'nuc': nuc
    }

    try:
        response = requests.get(url, params=params)
        response.raise_for_status()

        result = response.json()
        audiencias = result.get('data', [])

        print(f"Total de audiencias: {len(audiencias)}")

        for audiencia in audiencias:
            print(f"Fecha: {audiencia['fechaAudienciaLetra']}")
            print(f"Tipo: {audiencia['tipoAudiencia']}")
            print(f"Estado: {audiencia['estado']}")
            print(f"Modalidad: {audiencia['modalidad']}")
            print("---")

        return audiencias

    except requests.exceptions.RequestException as e:
        print(f"Error al consultar la API: {e}")
        return None

# Uso
audiencias = obtener_audiencias('199-2020-ELAB-00094')

Ejemplo 4: Consulta con C# (.NET)

using System;
using System.Net.Http;
using System.Text.Json;
using System.Threading.Tasks;
using System.Collections.Generic;

public class AudienciasClient
{
    private readonly HttpClient _httpClient;
    private const string BaseUrl = "https://api.poderjudicial.gob.do/Audiencias";

    public AudienciasClient()
    {
        _httpClient = new HttpClient();
    }

    public async Task<List<AudienciaResponse>> ObtenerAudienciasPorNuc(string nuc)
    {
        var url = $"{BaseUrl}/Audiencias/ObtenerAudienciasPorNuc?nuc={nuc}";

        try
        {
            var response = await _httpClient.GetAsync(url);
            response.EnsureSuccessStatusCode();

            var content = await response.Content.ReadAsStringAsync();
            var resultado = JsonSerializer.Deserialize<ApiResponse>(content);

            Console.WriteLine($"Total de audiencias: {resultado.Data.Count}");

            foreach (var audiencia in resultado.Data)
            {
                Console.WriteLine($"Fecha: {audiencia.FechaAudienciaLetra}");
                Console.WriteLine($"Tipo: {audiencia.TipoAudiencia}");
                Console.WriteLine($"Estado: {audiencia.Estado}");
                Console.WriteLine("---");
            }

            return resultado.Data;
        }
        catch (Exception ex)
        {
            Console.WriteLine($"Error: {ex.Message}");
            return null;
        }
    }
}

public class ApiResponse
{
    public List<AudienciaResponse> Data { get; set; }
}

public class AudienciaResponse
{
    public string Nuc { get; set; }
    public string NumeroTramite { get; set; }
    public string Asunto { get; set; }
    public string Tribunal { get; set; }
    public string Sala { get; set; }
    public string Salon { get; set; }
    public string TipoAudiencia { get; set; }
    public string Estado { get; set; }
    public string UrlAudiencia { get; set; }
    public string UrlCelebracion { get; set; }
    public DateTime? FechaAudiencia { get; set; }
    public string HoraAudiencia { get; set; }
    public string Modalidad { get; set; }
    public string FechaAudienciaLetra { get; set; }
    public string TipoResultado { get; set; }
}

Ejemplo 5: Consulta con PHP

<?php
function obtenerAudiencias($nuc) {
    $url = "https://api.poderjudicial.gob.do/Audiencias/Audiencias/ObtenerAudienciasPorNuc?nuc=" . urlencode($nuc);

    $ch = curl_init();
    curl_setopt($ch, CURLOPT_URL, $url);
    curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
    curl_setopt($ch, CURLOPT_SSL_VERIFYPEER, true);

    $response = curl_exec($ch);
    $httpCode = curl_getinfo($ch, CURLINFO_HTTP_CODE);

    curl_close($ch);

    if ($httpCode === 200) {
        $result = json_decode($response, true);
        $audiencias = $result['data'] ?? [];

        echo "Total de audiencias: " . count($audiencias) . "\n";

        foreach ($audiencias as $audiencia) {
            echo "Fecha: " . $audiencia['fechaAudienciaLetra'] . "\n";
            echo "Tipo: " . $audiencia['tipoAudiencia'] . "\n";
            echo "Estado: " . $audiencia['estado'] . "\n";
            echo "---\n";
        }

        return $audiencias;
    } else {
        echo "Error HTTP: " . $httpCode . "\n";
        return null;
    }
}

// Uso
$audiencias = obtenerAudiencias('199-2020-ELAB-00094');
?>

Códigos de Estado HTTP

La API utiliza los siguientes códigos de estado HTTP estándar:

Limitación de Peticiones

La API implementa un sistema de limitación de peticiones (Rate Limiting) para garantizar un uso equitativo del servicio y proteger la infraestructura.

Comportamiento al Exceder el Límite

Cuando se excede el límite de peticiones:

1. Código de respuesta: 429 Too Many Requests
2. Mensaje de error:

{
  "error": "Ha superado el límite de peticiones permitidas."
}

Recomendaciones

• Implemente lógica de reintento con retroceso exponencial (exponential backoff)
• Distribuya sus peticiones a lo largo del tiempo en lugar de ráfagas
• Cache los resultados cuando sea posible para reducir llamadas repetidas
• Monitoree el código de respuesta 429 en sus aplicaciones
• Si necesita límites más altos, contacte al equipo de soporte para obtener un API Key personalizado

Ejemplo de Implementación con Reintento

async function obtenerAudienciasConReintentos(nuc, maxReintentos = 3) {
  for (let intento = 0; intento < maxReintentos; intento++) {
    try {
      const response = await fetch(
        `https://api.poderjudicial.gob.do/Audiencias/Audiencias/ObtenerAudienciasPorNuc?nuc=${nuc}`
      );

      if (response.status === 429) {
        // Esperar antes de reintentar (retroceso exponencial)
        const espera = Math.pow(2, intento) * 1000;
        console.log(`Límite excedido. Reintentando en ${espera}ms...`);
        await new Promise(resolve => setTimeout(resolve, espera));
        continue;
      }

      if (!response.ok) {
        throw new Error(`Error HTTP: ${response.status}`);
      }

      return await response.json();

    } catch (error) {
      if (intento === maxReintentos - 1) throw error;
    }
  }
}

Manejo de Errores

Error 400 - Parámetro Faltante o Inválido

{
  "message": "Debe verificar los parametros suministrados 'nuc'"
}

Error 404 - Sin Resultados

{
  "message": "No se encontraron resultados para el caso: 199-2020-ELAB-00094"
}

Error 429 - Límite de Peticiones Excedido

{
  "error": "Ha superado el límite de peticiones permitidas."
}

Error 500 - Error Interno del Servidor

{
  "message": "Descripción del error interno"
}