# Sincronizar cartera de Poder Judicial
> Lee la cartera elegida con ClaveÚnica y guarda causas, actuaciones y documentos disponibles.
{/* AUTO-GENERATED by @emisso/codegen. DO NOT EDIT. */}
| | |
| ------------------- | ------------------------------------------------------------------ |
| **Tool ID** | `pjud.conexion.sincronizar` |
| **Nombre MCP** | `pjud__conexion__sincronizar` |
| **Conector** | `pjud` |
| **Plano** | `read` |
| **Alcances** | `expedientes` |
| **Scope (permiso)** | `pjud:read` |
| **Auth** | `connection_credentials` |
| **Versión** | `2` |
| **Sensible** | sí |
| **Deprecado** | no |
| **Comportamiento** | readOnly=false, destructive=false, idempotent=true, openWorld=true |
> **Requiere conexión.** Indica cuál en cada llamada: header `X-Connect-Connection` en REST, campo `connectionId` en el `execute_write` de MCP y en las opciones del SDK. 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`](../conexiones/estado-consultar).
## Qué hace [#qué-hace]
El piloto incorpora causas civiles y laborales accesibles al titular; conserva el ámbito de historia y declara anexos y secciones pendientes. No presenta escritos ni calcula plazos legales. El período organiza la ejecución de Connect: no filtra la historia judicial.
## Entrada [#entrada]
| Campo | Tipo | Requerido | Descripción | |
| ---------- | ------------------------ | ------------------------------ | -------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------- |
| `periodo` | string \`^\d{4}-(0\[1-9] | 1\[0-2])$\` | no | Período de ejecución en AAAA-MM; si se omite, usa el mes actual en Santiago al ejecutar. No filtra la historia de las causas. |
| `alcances` | lista de string | no · default `["expedientes"]` | Módulo judicial que se sincroniza en esta llamada. | |
JSON Schema de entrada
```json
{
"$schema": "https://json-schema.org/draft/2020-12/schema",
"type": "object",
"properties": {
"periodo": {
"description": "Período de ejecución en AAAA-MM; si se omite, usa el mes actual en Santiago al ejecutar. No filtra la historia de las causas.",
"type": "string",
"pattern": "^\\d{4}-(0[1-9]|1[0-2])$"
},
"alcances": {
"default": [
"expedientes"
],
"description": "Módulo judicial que se sincroniza en esta llamada.",
"minItems": 1,
"maxItems": 1,
"type": "array",
"items": {
"type": "string",
"const": "expedientes"
}
}
},
"additionalProperties": false
}
```
## Salida [#salida]
| Campo | Tipo | Requerido | Descripción | |
| --------------------------------- | ----------------------------- | --------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `periodo` | string | sí | Período de ejecución en AAAA-MM. | |
| `estado` | `"encolado"` · `"completado"` | sí | 'encolado' = la sincronización quedó en cola y va a empezar enseguida; esta respuesta NO trae datos todavía, y el trabajo se sigue por 'jobId'. 'completado' = la sincronización ya corrió y su resumen por alcance viene en 'results'. Un cliente recibe siempre 'encolado': un sync abre una sesión real contra el sistema externo y puede tardar minutos, así que no se te hace esperar por él. | |
| `jobId` | string | null | no | El identificador de la sincronización encolada. Por la API REST, el avance se consulta en 'GET /v1/syncs/\{jobId}'; por MCP, búscalo en 'trabajos' de 'conexiones.estado.consultar' y revisa 'datosListos' ahí mismo. Es el mismo id que viaja en el webhook 'sync.completed' o 'sync.failed' si tu plan los incluye. Es null cuando 'estado' es 'completado': ahí el resultado ya está en la respuesta y no hay nada que seguir. |
| `yaEnCurso` | booleano | no | 'true' significa que ya había una sincronización viva para esa conexión y ese período, y que 'jobId' es la de ella. No es un error ni un rechazo: pedir dos veces el mismo período es inofensivo y te devuelve el trabajo que ya está andando. Ojo con el otro lado: 'false' NO garantiza que la hayas creado tú: dos llamadas a la vez pueden recibir las dos 'false' y el MISMO 'jobId'. Lo que sí vale siempre es que hay una sola sincronización activa por conexión y período, así que el 'jobId' que recibes es el trabajo que cubre tu pedido, lo hayas encolado tú o no. | |
| `results` | lista de objeto | no | El resumen por alcance, una fila por alcance sincronizado. AUSENTE cuando 'estado' es 'encolado': el trabajo todavía no corrió. Ausente no es lo mismo que vacío: un arreglo vacío significaría que se miró y no había nada. | |
| `results[].alcance` | string | sí | Módulo de expedientes judiciales. | |
| `results[].status` | `"ok"` · `"partial"` | sí | Partial indica que se guardaron avances con cobertura pendiente; no equivale a una revisión completa. | |
| `results[].recordsSynced` | entero | sí | Registros entregados a persistencia por esta ejecución; no es el total histórico de la conexión. | |
| `results[].causasRevisadas` | entero | sí | Causas con una observación recuperada, aun cuando alguna sección quedó pendiente. | |
| `results[].causasPendientes` | entero | sí | Causas elegidas cuya lectura no pudo completarse en esta ejecución. | |
| `results[].documentosDescargados` | entero | sí | Originales recuperados e incluidos en el guardado de esta ejecución. | |
| `results[].detalle` | string | sí | Explicación de la cobertura o de una cartera sin selección. | |
JSON Schema de salida
```json
{
"$schema": "https://json-schema.org/draft/2020-12/schema",
"type": "object",
"properties": {
"periodo": {
"type": "string",
"description": "Período de ejecución en AAAA-MM."
},
"estado": {
"type": "string",
"enum": [
"encolado",
"completado"
],
"description": "'encolado' = la sincronización quedó en cola y va a empezar enseguida; esta respuesta NO trae datos todavía, y el trabajo se sigue por 'jobId'. 'completado' = la sincronización ya corrió y su resumen por alcance viene en 'results'. Un cliente recibe siempre 'encolado': un sync abre una sesión real contra el sistema externo y puede tardar minutos, así que no se te hace esperar por él."
},
"jobId": {
"description": "El identificador de la sincronización encolada. Por la API REST, el avance se consulta en 'GET /v1/syncs/{jobId}'; por MCP, búscalo en 'trabajos' de 'conexiones.estado.consultar' y revisa 'datosListos' ahí mismo. Es el mismo id que viaja en el webhook 'sync.completed' o 'sync.failed' si tu plan los incluye. Es null cuando 'estado' es 'completado': ahí el resultado ya está en la respuesta y no hay nada que seguir.",
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
},
"yaEnCurso": {
"description": "'true' significa que ya había una sincronización viva para esa conexión y ese período, y que 'jobId' es la de ella. No es un error ni un rechazo: pedir dos veces el mismo período es inofensivo y te devuelve el trabajo que ya está andando. Ojo con el otro lado: 'false' NO garantiza que la hayas creado tú: dos llamadas a la vez pueden recibir las dos 'false' y el MISMO 'jobId'. Lo que sí vale siempre es que hay una sola sincronización activa por conexión y período, así que el 'jobId' que recibes es el trabajo que cubre tu pedido, lo hayas encolado tú o no.",
"type": "boolean"
},
"results": {
"description": "El resumen por alcance, una fila por alcance sincronizado. AUSENTE cuando 'estado' es 'encolado': el trabajo todavía no corrió. Ausente no es lo mismo que vacío: un arreglo vacío significaría que se miró y no había nada.",
"type": "array",
"items": {
"type": "object",
"properties": {
"alcance": {
"type": "string",
"const": "expedientes",
"description": "Módulo de expedientes judiciales."
},
"status": {
"type": "string",
"enum": [
"ok",
"partial"
],
"description": "Partial indica que se guardaron avances con cobertura pendiente; no equivale a una revisión completa."
},
"recordsSynced": {
"type": "integer",
"minimum": 0,
"maximum": 9007199254740991,
"description": "Registros entregados a persistencia por esta ejecución; no es el total histórico de la conexión."
},
"causasRevisadas": {
"type": "integer",
"minimum": 0,
"maximum": 9007199254740991,
"description": "Causas con una observación recuperada, aun cuando alguna sección quedó pendiente."
},
"causasPendientes": {
"type": "integer",
"minimum": 0,
"maximum": 9007199254740991,
"description": "Causas elegidas cuya lectura no pudo completarse en esta ejecución."
},
"documentosDescargados": {
"type": "integer",
"minimum": 0,
"maximum": 9007199254740991,
"description": "Originales recuperados e incluidos en el guardado de esta ejecución."
},
"detalle": {
"type": "string",
"description": "Explicación de la cobertura o de una cartera sin selección."
}
},
"required": [
"alcance",
"status",
"recordsSynced",
"causasRevisadas",
"causasPendientes",
"documentosDescargados",
"detalle"
],
"additionalProperties": false
}
}
},
"required": [
"periodo",
"estado"
],
"additionalProperties": false
}
```
## Errores de esta tool [#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. |
| `connection_credential_required` | 428 | no | Crea un enlace con conexiones.enlace.crear (modo reconectar si la conexión ya existe) y pide a la persona que entregue la credencial de nuevo. No reintentes con la credencial anterior. |
| `connection_busy` | 409 | sí | Espera unos segundos y reintenta. Es una espera transitoria: no necesitas volver a conectar ni ingresar la credencial otra vez. |
| `upstream_error` | 502 | sí | Reintenta más tarde. Si persiste, el problema está en el sistema externo, no en tu integración. |
| `timeout` | 504 | sí | Reintenta. Para sincronizaciones largas usa la vía asíncrona y consulta el estado del trabajo. |
| `connection_session_pending` | 409 | sí | Ejecuta la sincronización de esa conexión (ella acuña la sesión) o espera la programada, y reintenta. |
| `connection_sync_in_progress` | 409 | sí | Espera a que termine y reintenta, o consulta directamente: puede que ya haya datos. |
| `too_many_pending` | 429 | sí | Deja terminar los trabajos en curso antes de encolar más. |
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](../errores).
## Próximos pasos [#próximos-pasos]
* [`pjud.causas.consultar`](./causas-consultar): lee el alcance `expedientes` que esta sincronización escribe.
* [`pjud.causas.detallar`](./causas-detallar): lee el alcance `expedientes` que esta sincronización escribe.
* [`pjud.actuaciones.consultar`](./actuaciones-consultar): lee el alcance `expedientes` que esta sincronización escribe.
* [`pjud.documentos.consultar`](./documentos-consultar): lee el alcance `expedientes` que esta sincronización escribe.
* [`pjud.documentos.detallar`](./documentos-detallar): lee el alcance `expedientes` que esta sincronización escribe.
* [`pjud.novedades.consultar`](./novedades-consultar): lee el alcance `expedientes` que esta sincronización escribe.