🏛️ Cendoj - Buscador de sentencias

Actor de Apify que automatiza la búsqueda de jurisprudencia en el CENDOJ (Centro de Documentación Judicial del Consejo General del Poder Judicial). Permite buscar sentencias, autos y acuerdos por término de texto y filtrarlos por jurisdicción, tipo de órgano, tipo de resolución, comunidad autónoma y rango de fechas.

Para cada resolución encontrada, el actor extrae sus metadatos (ECLI, ROJ, ponente, municipio, número de recurso, etc.), un resumen automático y la URL del PDF oficial. Además, en una segunda ejecución puedes pedirle que descargue y extraiga el texto completo de sentencias concretas (campo pdfUrls) para analizarlas.

✨ Características

• 🔎 Búsqueda por múltiples términos en una sola ejecución (hasta 200).
• � Operadores booleanos en el término de búsqueda (Y, O, NO, PROXn).
• 🧰 Filtros avanzados: jurisdicción, tipo de órgano, tipo de resolución, comunidad autónoma y fechas.
• ↕️ Ordenación de resultados (relevancia, fecha, órgano).
• 📄 Extracción de metadatos completos (ECLI, ROJ, ponente, municipio, número de resolución y recurso).
• 📝 Resumen automático de cada sentencia.
• 🔗 URL de descarga del PDF oficial de cada resolución.
• 📑 Extracción bajo demanda del texto completo de sentencias concretas (campo pdfUrls).

📥 Entrada (Input)

La entrada se define mediante un objeto JSON. Debes indicar al menos uno de estos dos campos: searchTerms (para buscar jurisprudencia) o pdfUrls (para extraer el texto de sentencias concretas).

Campo	Tipo	Obligatorio	Descripción
searchTerms	array<string>	✅ Uno de los dos	Lista de términos a buscar en la jurisprudencia (máx. 50). Admite operadores booleanos.
pdfUrls	array<string>	✅ Uno de los dos	Lista de URLs de PDF (campo pdfUrl de resultados anteriores) de las que extraer el texto completo (máx. 50). Úselo en una segunda ejecución tras una búsqueda. Ver Extracción de texto.
jurisdictions	array<string>	No	Jurisdicciones: CIVIL, PENAL, CONTENCIOSO, SOCIAL, MILITAR, ESPECIAL. Por defecto, todas.
organoTypes	array<string>	No	Tipos de órgano judicial (Tribunal Supremo, Audiencia Nacional, Audiencia Provincial, etc.). Por defecto, todos.
resolutionTypes	array<string>	No	Tipos de resolución: SENTENCIA, AUTO, ACUERDO. Por defecto, todos.
locations	array<string>	No	Comunidades autónomas (ej. MADRID, CATALUÑA). Por defecto, todas. Solo aplica en la vía HTTP.
dateFrom	string	No	Fecha de resolución inicial (YYYY-MM-DD o DD/MM/YYYY).
dateTo	string	No	Fecha de resolución final (YYYY-MM-DD o DD/MM/YYYY).
sortOrder	string	No	Criterio de ordenación: Relevance (coincidencia, por defecto), IN_FECHARESOLUCION:increasing (fecha asc.), IN_FECHARESOLUCION:decreasing (fecha desc.), IN_FECHAENTRADA:numberdecreasing (lo más nuevo), IP_TIPOORGANO:alphabetical (órgano a–z), IP_TIPOORGANO:reversealphabetical (órgano z–a).
maxResults	integer	No	Máximo de sentencias por término (1–200). Por defecto, 10.
proxyConfiguration	object	No	Configuración de proxy. Por defecto, proxy residencial de España.

🧮 Operadores de búsqueda

El campo searchTerms admite operadores booleanos para construir consultas precisas. Puedes escribirlos tanto en su sintaxis nativa de CENDOJ (español) como en la estándar en inglés: el actor traduce automáticamente la versión en inglés a la que entiende el buscador.

Operador (escribe)	Equivalente CENDOJ	Significado	Ejemplo
AND	Y	Ambos términos deben aparecer.	abogacía AND responsabilidad
OR	O	Basta con que aparezca uno de los términos.	"Real Decreto 135/2021" OR "Real Decreto 658/2001"
NOT	NO	Excluye las resoluciones con ese término.	costas NOT "Ley 22/1988"
NEARn	PROXn	Los términos están a menos de n palabras de distancia.	estatuto NEAR5 abogacía

Notas:

• Los operadores deben escribirse en MAYÚSCULAS como palabra completa; los términos en minúsculas se tratan como texto literal.
• Puedes usar comillas para frases exactas: "condena en costas".
• Si escribes directamente los operadores en español (Y, O, NO, PROX20), se envían tal cual.
• Exclusión de frases con NOT/NO: el buscador de CENDOJ solo excluye la palabra inmediatamente siguiente al operador. Por eso, para excluir una frase de varias palabras, enciérrala entre comillas: el actor la expande automáticamente a una exclusión por cada palabra (por ejemplo, NOT "defectos constructivos" se envía como NO defectos NO constructivos). Las palabras vacías (de, la, el...) se omiten para no vaciar los resultados.

🤖 Uso con Claude Code / MCP de Apify (lenguaje natural)

Este actor está pensado para integrarse en Claude Code a través del MCP de Apify. La idea es que el usuario describa su necesidad en lenguaje natural y el asistente construya automáticamente el valor de searchTerms con los operadores adecuados, sin que el usuario tenga que conocerlos.

📖 Guía de integración: Cómo enlazar Claude Code con Apify (MCP).

Directrices para que el asistente (LLM) genere la query:

• Cuando el usuario quiera varias alternativas equivalentes (sinónimos, varias normas, varios nombres), únelas con OR.
• Cuando el usuario exija que aparezcan varios conceptos a la vez, únelos con AND.
• Cuando el usuario quiera descartar ruido (un tema, una ley o un sentido no deseado), usa NOT. Si lo que se excluye es una frase de varias palabras, ponla entre comillas (NOT "defectos constructivos") para que el actor la expanda correctamente; de lo contrario CENDOJ solo excluiría la primera palabra.
• Cuando dos conceptos deban referirse a lo mismo (estar próximos en el texto), usa NEARn (por defecto NEAR5–NEAR10).
• Encierra entre comillas las expresiones de varias palabras que deban buscarse literalmente.

Ejemplos de traducción de lenguaje natural a query:

El usuario pide...	searchTerms generado
"Sentencias sobre gastos hipotecarios pero que no traten de temas penales"	"gastos hipotecarios" NOT penal
"Obra nueva, pero excluyendo defectos constructivos y derecho de superficie"	"obra nueva" NOT "defectos constructivos" NOT "derecho de superficie"
"Casos del Real Decreto 135/2021 o del 658/2001"	"Real Decreto 135/2021" OR "Real Decreto 658/2001"
"Resoluciones sobre responsabilidad del abogado en relación con las costas"	abogado AND costas
"Que hablen del estatuto de la abogacía, no del de los trabajadores"	estatuto NEAR5 abogacía

🗂️ Mapeo de filtros desde lenguaje natural

Además del término de búsqueda, el asistente debe rellenar automáticamente los filtros estructurados cuando el usuario los menciona en lenguaje natural:

• Jurisdicción (jurisdictions): "civil" → CIVIL, "penal" → PENAL, "contencioso" / "contencioso-administrativo" → CONTENCIOSO, "social" / "laboral" → SOCIAL, "militar" → MILITAR, "especial" → ESPECIAL.
• Tipo de resolución (resolutionTypes): "sentencias" → SENTENCIA, "autos" → AUTO, "acuerdos" → ACUERDO.
• Tipo de órgano (organoTypes): ⚠️ los códigos son opacos y NO siguen el orden alfabético; NO los adivines, cópialos de la tabla de abajo. Errores típicos: usar 12 (Sala Penal) para asuntos civiles, o 31 (TSJ) creyendo que es el Juzgado de Primera Instancia (que es 42). Consulta la tabla de referencia de órganos.
• Comunidad autónoma (locations): "Madrid" → MADRID, "Cataluña" → CATALUÑA, "Andalucía" → ANDALUCÍA, etc. (solo aplica en la vía HTTP).
• Fechas (dateFrom / dateTo): "desde 2020" → dateFrom: "2020-01-01", "el último año", "entre enero y marzo de 2024", etc. Formato YYYY-MM-DD.
• Ordenación (sortOrder): "las más recientes" → IN_FECHARESOLUCION:decreasing, "las más antiguas" → IN_FECHARESOLUCION:increasing, "las más relevantes" → Relevance (por defecto).
• Número de resultados (maxResults): por defecto 10. Súbelo (hasta 200) cuando el usuario pida "todas", "un listado amplio", "un análisis exhaustivo" o similar.
• Texto completo (pdfUrls): cuando el usuario pida "descarga/analiza el texto de estas sentencias" tras una búsqueda, relanza el actor pasando en pdfUrls los pdfUrl de las sentencias elegidas (ver Extracción de texto). No uses fetch ni otros actores para bajar el PDF.

💡 Para construir tablas, los campos más útiles de la salida son organo, jurisdiction, resolutionDateISO, roj, ecli, title, ponente, summary y pdfUrl.

🏛️ Tabla de referencia (organoTypes)

Mapea el órgano que pide el usuario a su código exacto de esta tabla (son los valores oficiales del <select> de CENDOJ). Para órganos con varias salas, usa el código combinado (primera fila de cada grupo) salvo que el usuario precise una sala concreta.

Código (organoTypes)	Órgano (título oficial)
11|12|13|14|15|16	Tribunal Supremo (todas las salas)
11	Tribunal Supremo. Sala de lo Civil
12	Tribunal Supremo. Sala de lo Penal
13	Tribunal Supremo. Sala de lo Contencioso
14	Tribunal Supremo. Sala de lo Social
15	Tribunal Supremo. Sala de lo Militar
16	Tribunal Supremo. Sala de lo Especial
22|2264|23|24|25|26|27|28|29	Audiencia Nacional (todas las salas)
22	Audiencia Nacional. Sala de lo Penal
2264	Sala de Apelación de la Audiencia Nacional
23	Audiencia Nacional. Sala de lo Contencioso
24	Audiencia Nacional. Sala de lo Social
27	Audiencia Nacional. Juzgados Centrales de Instrucción / Tribunal Central Instancia Sec. Instr.
26	Audiencia Nacional. Juzgado Central de Menores
25	Audiencia Nacional. Juzgado Central de Vigilancia Penitenciaria
29	Audiencia Nacional. Juzgados Centrales de lo Contencioso / Tribunal Central Instancia Sec. Contencioso
28	Audiencia Nacional. Juzgados Centrales de lo Penal
31|31201202|33|34	Tribunal Superior de Justicia (todas las salas)
31	Tribunal Superior de Justicia. Sala de lo Civil y Penal
31201202	Sección de Apelación Penal. TSJ Sala de lo Civil y Penal
33	Tribunal Superior de Justicia. Sala de lo Contencioso
34	Tribunal Superior de Justicia. Sala de lo Social
37	Audiencia Provincial
38	Audiencia Provincial. Tribunal Jurado
1001	Tribunal de Marca de la UE
42	Juzgado de Primera Instancia / Tribunal Instancia Sec. Civil
43	Juzgado de Instrucción
45	Juzgado de lo Contencioso Administrativo / Tribunal Instancia Sec. Contencioso-Administrativo
53	Juzgado de Menores / Tribunal Instancia Sec. Menores
41	Juzgado de 1ª Inst. Instr. / Tribunal Instancia Sec. Civil Instr.
47	Juzgado de lo Mercantil / Tribunal Instancia Sec. Mercantil
1002	Juzgados de Marca de la UE
51	Juzgado de lo Penal / Tribunal Instancia Sec. Penal
44	Juzgado de lo Social / Tribunal Instancia Sec. Social
52	Juzgado de Vigilancia Penitenciaria / Tribunal Instancia Sec. Vigilancia Penitenciaria
48	Juzgado de Violencia sobre la Mujer
83	Tribunal Militar Territorial
85	Tribunal Militar Central
75	Consejo Supremo de Justicia Militar
36	Audiencia Territorial

⚠️ "Juzgado de Primera Instancia" = 42, NO 31 (que es el Tribunal Superior de Justicia). "Sala de lo Civil del Supremo" = 11, NO 12 (que es Penal). "Audiencia Provincial" = 37, NO 42. Verifica siempre el código contra esta tabla antes de llamar al actor.

📤 Salida (Output)

Los resultados se almacenan en el dataset del actor. Cada elemento corresponde a una resolución con la siguiente estructura:

{
    "searchTerm": "Gastos hipotecarios",
    "title": "ATIM Madrid, a 10 de junio de 2026 - ROJ: ATIM M 31/2026",
    "roj": "ATIM M 31/2026",
    "reference": "11755479",
    "ecli": "ECLI:ES:TIM:2026:31A",
    "jurisdiction": "Civil",
    "organo": "Tribunal de Instancia Mercantil",
    "resolutionDate": "20260610",
    "resolutionDateISO": "2026-06-10",
    "resolutionNumber": null,
    "municipality": "Madrid",
    "ponente": "NOMBRE_PONENTE",
    "appealNumber": "573/2025",
    "summary": "Resumen automático de la resolución...",
    "pdfUrl": "https://www.poderjudicial.es/search/contenidos.action?action=contentpdf&databasematch=AN&reference=11755479&optimize=20260612&publicinterface=true&tab=AN",
}

Campo	Descripción
searchTerm	Término de búsqueda que originó el resultado.
title	Título de la resolución.
roj	Repositorio Oficial de Jurisprudencia (identificador ROJ).
reference	Referencia interna del documento en CENDOJ.
ecli	Identificador europeo de jurisprudencia (ECLI).
jurisdiction	Jurisdicción de la búsqueda en formato legible (p. ej. Civil). null si no se filtró por jurisdicción.
organo	Órgano judicial legible derivado del ROJ (p. ej. Tribunal Supremo, Audiencia Provincial).
resolutionDate	Fecha de resolución (formato YYYYMMDD).
resolutionDateISO	Fecha de resolución en formato legible YYYY-MM-DD.
resolutionNumber	Número de resolución (si está disponible).
municipality	Municipio del órgano judicial.
ponente	Magistrado ponente.
appealNumber	Número de recurso.
summary	Resumen automático generado por el buscador.
pdfUrl	URL de descarga del PDF oficial (es también el documento online: el visor de CENDOJ muestra ese mismo PDF).

� Extracción de texto de sentencias concretas

El buscador devuelve metadatos y resumen, pero no el texto completo de los PDFs (descargarlos todos sería lento y CENDOJ bloquea las descargas masivas). Para analizar el contenido de sentencias concretas, sigue un flujo en dos pasos:

1. Busca con searchTerms y revisa los resultados. Cada uno incluye su pdfUrl.
2. Vuelve a ejecutar el actor pasando en pdfUrls las URLs (pdfUrl) de las sentencias que te interesen. El actor descargará esos PDFs y extraerá su texto.

Cuando usas pdfUrls, no es necesario rellenar searchTerms. La salida de esta segunda ejecución tiene esta forma:

{
    "pdfUrl": "https://www.poderjudicial.es/search/contenidos.action?action=contentpdf&databasematch=TS&reference=11753648&...",
    "reference": "11753648",
    "databasematch": "TS",
    "text": "Texto completo de la sentencia extraído del PDF..."
}

Campo	Descripción
pdfUrl	URL del PDF procesado (la que pasaste en pdfUrls).
reference	Referencia interna del documento (extraída de la URL).
databasematch	Base de datos de origen (extraída de la URL).
text	Texto completo de la sentencia. Es null (con campo error) si no se pudo extraer.

⚠️ Por qué no se descarga directamente el PDF: CENDOJ protege las URLs de PDF con un control anti-descargas masivas (CAPTCHA "Control Descargas masivas") que bloquea las peticiones sin una sesión de navegador válida. Por eso una descarga directa con fetch/curl o con actores genéricos falla. Este actor abre una sesión real (cookies + aviso legal + proxy residencial de España) y descarga el PDF desde dentro de esa sesión, por lo que es la vía fiable para obtener el texto.

💡 Límite de 50 PDFs por ejecución para no disparar el bloqueo. Si necesitas más, divídelos en varias ejecuciones.

🤖 Uso con Claude Code / MCP

El flujo encaja de forma natural con el MCP: primero el asistente lanza la búsqueda, muestra los resultados y, cuando le pides "descárgame el texto de estas dos sentencias para analizarlas", relanza el actor con el campo pdfUrls rellenado con los pdfUrl correspondientes del paso anterior. No uses fetch ni otros actores para bajar el PDF: usa este mismo actor con pdfUrls.

📝 También existe la variable de entorno EXTRACT_PDF_TEXT=true, que extrae el texto de todas las sentencias durante la propia búsqueda. Es útil para procesos batch, pero más lento; para análisis puntuales se recomienda el campo pdfUrls.

�📝 Notas

• El número máximo de resultados por término es 200 por ejecución.