Consultar inventario y preparación de causas

Distingue referencias encontradas en Mis Causas, selección de seguimiento y expedientes recuperados.


Tool ID	`pjud.cartera.consultar`
Nombre MCP	`pjud__cartera__consultar`
Conector	`pjud`
Plano	`action`
Lee el alcance	`expedientes` (debe estar habilitado en la conexión)
Scope (permiso)	`pjud:read`
Auth	`none`
Versión	`1`
Sensible	sí
Deprecado	no
Comportamiento	readOnly=true, destructive=false, idempotent=true, openWorld=false

Requiere conexión. Indica cuál en cada llamada: header X-Connect-Connection en REST y campo connectionId en el execute de MCP. No hay resolución implícita, ni siquiera con una sola conexión activa: la conexión es la empresa. El id sale de conexiones.estado.consultar.

Qué hace

Una referencia pendiente no incluye una cabecera inventada. El progreso de Civil y Laboral es independiente; un fallo o un límite de descubrimiento no acredita una cartera vacía. Una selección manual no requiere importación automática. Lee exclusivamente datos ya sincronizados de la conexión. Para actualizarlos usa pjud.conexion.sincronizar. Revisa estadoDatos, observadoHasta y cobertura antes de interpretar una lista vacía.

Entrada

Campo	Tipo	Requerido	Descripción
`cursor`	string	no	Cursor opaco de la respuesta anterior. Reenvíalo sin construirlo ni modificarlo.
`limit`	entero 1-100	no · default `50`	Máximo de filas por página; conserva el cursor para continuar en el mismo corte.
`competencia`	`"suprema"` · `"apelaciones"` · `"civil"` · `"laboral"` · `"penal"` · `"cobranza"` · …	no	Competencia judicial de la causa. Su presencia en el contrato no implica que todas las competencias estén implementadas.
`busqueda`	string	no	Texto de búsqueda entre los datos persistidos de la conexión.
`enSeguimiento`	booleano	no	Filtra por selección actual; omite el campo para ver también referencias descubiertas retiradas.

JSON Schema de entrada

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "type": "object",
  "properties": {
    "cursor": {
      "type": "string",
      "minLength": 1,
      "maxLength": 4096,
      "description": "Cursor opaco de la respuesta anterior. Reenvíalo sin construirlo ni modificarlo."
    },
    "limit": {
      "default": 50,
      "description": "Máximo de filas por página; conserva el cursor para continuar en el mismo corte.",
      "type": "integer",
      "minimum": 1,
      "maximum": 100
    },
    "competencia": {
      "type": "string",
      "enum": [
        "suprema",
        "apelaciones",
        "civil",
        "laboral",
        "penal",
        "cobranza",
        "familia",
        "disciplinario"
      ],
      "description": "Competencia judicial de la causa. Su presencia en el contrato no implica que todas las competencias estén implementadas."
    },
    "busqueda": {
      "type": "string",
      "minLength": 1,
      "maxLength": 200,
      "description": "Texto de búsqueda entre los datos persistidos de la conexión."
    },
    "enSeguimiento": {
      "description": "Filtra por selección actual; omite el campo para ver también referencias descubiertas retiradas.",
      "type": "boolean"
    }
  },
  "additionalProperties": false
}

Salida

Campo	Tipo	Requerido	Descripción
`causas`	lista de objeto	sí	Referencias de esta página del inventario y selección manual.
`causas[].referencia`	objeto	sí	Identificación de la referencia; no inventa carátula ni estado de un expediente pendiente.
`causas[].referencia.competencia`	`"suprema"` · `"apelaciones"` · `"civil"` · `"laboral"` · `"penal"` · `"cobranza"` · …	sí	Competencia judicial de la causa. Su presencia en el contrato no implica que todas las competencias estén implementadas.
`causas[].referencia.tribunal`	objeto	sí	Tribunal resuelto para mantener la identidad de la causa.
`causas[].referencia.rol`	string `^(?:[A-Z]6-)?(?:0	[1-9]\d14)-\d4$`	sí
`causas[].referencia.anio`	entero 1800-9999	null	sí
`causas[].referencia.causaId`	string `^pjc_[a-zA-Z0-9_-]{16,80}$`	sí	ID obtenido de pjud.causas.consultar. No es el rol escrito en el portal.
`causas[].encontrado`	booleano	sí	La referencia aparece en el inventario importado de Mis Causas.
`causas[].enSeguimiento`	booleano	sí	Connect tiene seleccionada esta causa para mantenerla al día.
`causas[].expedienteDisponible`	booleano	sí	Existe un expediente guardado y autorizado para leer; puede tener cobertura parcial.
`causas[].estadoDatos`	`"sin_sincronizar"` · `"disponibles"` · `"incompletos"`	sí	Disponibilidad de este expediente y sus secciones.
`causas[].observadoEn`	string `^(?:(?:\d\d[2468][048]	\d\d[13579][26]	\d\d0[48]
`modo`	`"sin_inicializar"` · `"manual"` · `"automatico"`	sí	Origen de la preparación visible; una cartera manual se conserva aunque no exista inventario importado.
`progreso`	lista de objeto	sí	Progreso independiente por competencia. En modo manual conserva historia de importación y no condiciona la selección vigente.
`progreso[].competencia`	`"civil"` · `"laboral"`	sí	Competencia cuyo descubrimiento se informa.
`progreso[].estado`	`"pendiente"` · `"completada"` · `"fallida"`	sí	Resultado del descubrimiento en esta competencia, separado de leer sus expedientes.
`progreso[].encontradas`	entero	sí	Referencias únicas encontradas en esta competencia.
`progreso[].observadoEn`	string `^(?:(?:\d\d[2468][048]	\d\d[13579][26]	\d\d0[48]
`progreso[].codigoIncidencia`	string `^pjud_[a-z0-9_]+$`	null	sí
`progreso[].alcance`	string	sí	Superficie y filtros que delimitan el inventario encontrado.
`contadores`	objeto	sí	Totales de la conexión antes de filtrar o paginar; disponibles significa que existe lectura autorizada y puede ser parcial.
`contadores.encontradas`	entero	sí	Referencias distintas en el inventario importado.
`contadores.enSeguimiento`	entero	sí	Causas seleccionadas actualmente.
`contadores.expedientesDisponibles`	entero	sí	Expedientes legibles entre todas las referencias, incluidas las retiradas.
`contadores.pendientesDeExpediente`	entero	sí	Causas en seguimiento que aún no ofrecen una lectura autorizada.
`contadores.expedientesIncompletos`	entero	sí	Expedientes legibles cuya cobertura contiene secciones pendientes.
`contadores.causasRestringidas`	entero	sí	Expedientes con restricción explícita; se omiten sus referencias en la página.
`cursor`	string	null	sí
`estadoDatos`	`"sin_sincronizar"` · `"disponibles"` · `"incompletos"`	sí	Una lista vacía con sin_sincronizar o incompletos no acredita ausencia de actividad judicial.
`observadoHasta`	string `^(?:(?:\d\d[2468][048]	\d\d[13579][26]	\d\d0[48]
`cobertura`	lista de objeto	sí	Secciones efectivamente revisadas y sus límites, para las causas de esta consulta.
`cobertura[].causaId`	string `^pjc_[a-zA-Z0-9_-]{16,80}$`	sí	ID obtenido de pjud.causas.consultar. No es el rol escrito en el portal.
`cobertura[].cuadernoId`	string `^pjq_[a-zA-Z0-9_-]{16,80}$`	null	sí
`cobertura[].seccion`	`"cabecera"` · `"historia"` · `"litigantes"` · `"notificaciones"` · `"escritos_por_resolver"` · `"exhortos"` · …	sí	Sección concreta cuya cobertura se informa.
`cobertura[].estado`	`"con_datos"` · `"sin_registros"` · `"parcial"` · `"fallida"` · `"no_accesible"` · `"no_implementada"`	sí	Solo con_datos y sin_registros acreditan revisión completa de esta sección. Los otros valores indican información pendiente o inaccesible.
`cobertura[].revisadaEn`	string `^(?:(?:\d\d[2468][048]	\d\d[13579][26]	\d\d0[48]
`cobertura[].registrosObservados`	entero	null	sí
`cobertura[].codigoIncidencia`	string `^pjud_[a-z_]+$`	null	sí

JSON Schema de salida

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "type": "object",
  "properties": {
    "causas": {
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "referencia": {
            "type": "object",
            "properties": {
              "competencia": {
                "type": "string",
                "enum": [
                  "suprema",
                  "apelaciones",
                  "civil",
                  "laboral",
                  "penal",
                  "cobranza",
                  "familia",
                  "disciplinario"
                ],
                "description": "Competencia judicial de la causa. Su presencia en el contrato no implica que todas las competencias estén implementadas."
              },
              "tribunal": {
                "type": "object",
                "properties": {
                  "codigo": {
                    "type": "string",
                    "minLength": 1,
                    "maxLength": 40,
                    "pattern": "^[A-Za-z0-9_-]+$",
                    "description": "Código oficial del tribunal dentro de la competencia."
                  },
                  "nombre": {
                    "type": "string",
                    "minLength": 1,
                    "maxLength": 200,
                    "description": "Nombre publicado del tribunal."
                  }
                },
                "required": [
                  "codigo",
                  "nombre"
                ],
                "additionalProperties": false,
                "description": "Tribunal resuelto para mantener la identidad de la causa."
              },
              "rol": {
                "type": "string",
                "pattern": "^(?:[A-Z]{1,6}-)?(?:0|[1-9]\\d{0,14})-\\d{4}$",
                "description": "Rol o RIT canónico de la referencia encontrada o seleccionada."
              },
              "anio": {
                "anyOf": [
                  {
                    "type": "integer",
                    "minimum": 1800,
                    "maximum": 9999
                  },
                  {
                    "type": "null"
                  }
                ],
                "description": "Año de la referencia judicial; null si no está disponible."
              },
              "causaId": {
                "type": "string",
                "pattern": "^pjc_[a-zA-Z0-9_-]{16,80}$",
                "description": "ID obtenido de pjud.causas.consultar. No es el rol escrito en el portal."
              }
            },
            "required": [
              "competencia",
              "tribunal",
              "rol",
              "anio",
              "causaId"
            ],
            "additionalProperties": false,
            "description": "Identificación de la referencia; no inventa carátula ni estado de un expediente pendiente."
          },
          "encontrado": {
            "type": "boolean",
            "description": "La referencia aparece en el inventario importado de Mis Causas."
          },
          "enSeguimiento": {
            "type": "boolean",
            "description": "Connect tiene seleccionada esta causa para mantenerla al día."
          },
          "expedienteDisponible": {
            "type": "boolean",
            "description": "Existe un expediente guardado y autorizado para leer; puede tener cobertura parcial."
          },
          "estadoDatos": {
            "type": "string",
            "enum": [
              "sin_sincronizar",
              "disponibles",
              "incompletos"
            ],
            "description": "Disponibilidad de este expediente y sus secciones."
          },
          "observadoEn": {
            "anyOf": [
              {
                "type": "string",
                "format": "date-time",
                "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$",
                "description": "Instante ISO 8601 con zona horaria."
              },
              {
                "type": "null"
              }
            ],
            "description": "Última observación de este expediente; null cuando sigue pendiente."
          }
        },
        "required": [
          "referencia",
          "encontrado",
          "enSeguimiento",
          "expedienteDisponible",
          "estadoDatos",
          "observadoEn"
        ],
        "additionalProperties": false
      },
      "description": "Referencias de esta página del inventario y selección manual."
    },
    "modo": {
      "type": "string",
      "enum": [
        "sin_inicializar",
        "manual",
        "automatico"
      ],
      "description": "Origen de la preparación visible; una cartera manual se conserva aunque no exista inventario importado."
    },
    "progreso": {
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "competencia": {
            "type": "string",
            "enum": [
              "civil",
              "laboral"
            ],
            "description": "Competencia cuyo descubrimiento se informa."
          },
          "estado": {
            "type": "string",
            "enum": [
              "pendiente",
              "completada",
              "fallida"
            ],
            "description": "Resultado del descubrimiento en esta competencia, separado de leer sus expedientes."
          },
          "encontradas": {
            "type": "integer",
            "minimum": 0,
            "maximum": 9007199254740991,
            "description": "Referencias únicas encontradas en esta competencia."
          },
          "observadoEn": {
            "anyOf": [
              {
                "type": "string",
                "format": "date-time",
                "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$",
                "description": "Instante ISO 8601 con zona horaria."
              },
              {
                "type": "null"
              }
            ],
            "description": "Instante del descubrimiento; null cuando está pendiente."
          },
          "codigoIncidencia": {
            "anyOf": [
              {
                "type": "string",
                "pattern": "^pjud_[a-z0-9_]+$"
              },
              {
                "type": "null"
              }
            ],
            "description": "Código saneado del fallo; null cuando no hay incidencia."
          },
          "alcance": {
            "type": "string",
            "description": "Superficie y filtros que delimitan el inventario encontrado."
          }
        },
        "required": [
          "competencia",
          "estado",
          "encontradas",
          "observadoEn",
          "codigoIncidencia",
          "alcance"
        ],
        "additionalProperties": false
      },
      "description": "Progreso independiente por competencia. En modo manual conserva historia de importación y no condiciona la selección vigente."
    },
    "contadores": {
      "type": "object",
      "properties": {
        "encontradas": {
          "type": "integer",
          "minimum": 0,
          "maximum": 9007199254740991,
          "description": "Referencias distintas en el inventario importado."
        },
        "enSeguimiento": {
          "type": "integer",
          "minimum": 0,
          "maximum": 9007199254740991,
          "description": "Causas seleccionadas actualmente."
        },
        "expedientesDisponibles": {
          "type": "integer",
          "minimum": 0,
          "maximum": 9007199254740991,
          "description": "Expedientes legibles entre todas las referencias, incluidas las retiradas."
        },
        "pendientesDeExpediente": {
          "type": "integer",
          "minimum": 0,
          "maximum": 9007199254740991,
          "description": "Causas en seguimiento que aún no ofrecen una lectura autorizada."
        },
        "expedientesIncompletos": {
          "type": "integer",
          "minimum": 0,
          "maximum": 9007199254740991,
          "description": "Expedientes legibles cuya cobertura contiene secciones pendientes."
        },
        "causasRestringidas": {
          "type": "integer",
          "minimum": 0,
          "maximum": 9007199254740991,
          "description": "Expedientes con restricción explícita; se omiten sus referencias en la página."
        }
      },
      "required": [
        "encontradas",
        "enSeguimiento",
        "expedientesDisponibles",
        "pendientesDeExpediente",
        "expedientesIncompletos",
        "causasRestringidas"
      ],
      "additionalProperties": false,
      "description": "Totales de la conexión antes de filtrar o paginar; disponibles significa que existe lectura autorizada y puede ser parcial."
    },
    "cursor": {
      "anyOf": [
        {
          "type": "string",
          "minLength": 1,
          "maxLength": 4096,
          "description": "Cursor opaco de la respuesta anterior. Reenvíalo sin construirlo ni modificarlo."
        },
        {
          "type": "null"
        }
      ],
      "description": "null cuando no quedan filas en este corte; no acredita que OJV esté completamente revisada."
    },
    "estadoDatos": {
      "type": "string",
      "enum": [
        "sin_sincronizar",
        "disponibles",
        "incompletos"
      ],
      "description": "Una lista vacía con sin_sincronizar o incompletos no acredita ausencia de actividad judicial."
    },
    "observadoHasta": {
      "anyOf": [
        {
          "type": "string",
          "format": "date-time",
          "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$",
          "description": "Instante ISO 8601 con zona horaria."
        },
        {
          "type": "null"
        }
      ],
      "description": "Corte de observación de los datos persistidos. No es la fecha de la consulta ni la de una resolución."
    },
    "cobertura": {
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "causaId": {
            "type": "string",
            "pattern": "^pjc_[a-zA-Z0-9_-]{16,80}$",
            "description": "ID obtenido de pjud.causas.consultar. No es el rol escrito en el portal."
          },
          "cuadernoId": {
            "anyOf": [
              {
                "type": "string",
                "pattern": "^pjq_[a-zA-Z0-9_-]{16,80}$",
                "description": "Identificador estable de cuaderno, obtenido de causas.detallar."
              },
              {
                "type": "null"
              }
            ],
            "description": "Cuaderno al que corresponde la información; null para una sección de toda la causa."
          },
          "seccion": {
            "type": "string",
            "enum": [
              "cabecera",
              "historia",
              "litigantes",
              "notificaciones",
              "escritos_por_resolver",
              "exhortos",
              "remisiones",
              "documentos",
              "diligencias",
              "liquidacion",
              "materias"
            ],
            "description": "Sección concreta cuya cobertura se informa."
          },
          "estado": {
            "type": "string",
            "enum": [
              "con_datos",
              "sin_registros",
              "parcial",
              "fallida",
              "no_accesible",
              "no_implementada"
            ],
            "description": "Solo con_datos y sin_registros acreditan revisión completa de esta sección. Los otros valores indican información pendiente o inaccesible."
          },
          "revisadaEn": {
            "anyOf": [
              {
                "type": "string",
                "format": "date-time",
                "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$",
                "description": "Instante ISO 8601 con zona horaria."
              },
              {
                "type": "null"
              }
            ],
            "description": "Instante ISO 8601 de revisión; null si esa sección no se revisó."
          },
          "registrosObservados": {
            "anyOf": [
              {
                "type": "integer",
                "minimum": 0,
                "maximum": 9007199254740991
              },
              {
                "type": "null"
              }
            ],
            "description": "Filas observadas en la sección; null significa que no se pudo contar, no cero."
          },
          "codigoIncidencia": {
            "anyOf": [
              {
                "type": "string",
                "pattern": "^pjud_[a-z_]+$"
              },
              {
                "type": "null"
              }
            ],
            "description": "Código saneado; nunca mensajes, cookies o HTML del proveedor."
          }
        },
        "required": [
          "causaId",
          "cuadernoId",
          "seccion",
          "estado",
          "revisadaEn",
          "registrosObservados",
          "codigoIncidencia"
        ],
        "additionalProperties": false
      },
      "description": "Secciones efectivamente revisadas y sus límites, para las causas de esta consulta."
    }
  },
  "required": [
    "causas",
    "modo",
    "progreso",
    "contadores",
    "cursor",
    "estadoDatos",
    "observadoHasta",
    "cobertura"
  ],
  "additionalProperties": false
}

Errores de esta tool

Código	HTTP	Reintentable	Qué hacer
`connection_disabled`	403	no	Reactívala en /connections o usa otra conexión del mismo sistema.
`alcance_not_enabled`	403	no	Habilita el alcance en /connections o quítalo del input de la sincronización.

Toda llamada puede devolver además los códigos transversales (validation_error, unauthorized, scope_not_granted, rate_limited, entre otros): el detalle vive en el catálogo de errores.

Próximos pasos

pjud.conexion.sincronizar: la tool que escribe los datos que esta lectura devuelve.
Sincronizar y consultar: por qué leer datos reales son dos pasos.