Sincronizar conexión Previred

Sincroniza en una sola pasada los módulos habilitados de Previred: planillas, cotizaciones, deuda, archivo F30-1, certificados, empresas y nóminas actuales.

Tool IDprevired.conexion.sincronizar
Nombre MCPprevired__conexion__sincronizar
Conectorprevired
Planoread
Alcancesplanillas, cotizaciones, deuda, f301, certificados, empresas, nominas
Scope (permiso)previred:read
Authconnection_credentials
Versión2
Sensiblesí
Deprecadono
ComportamientoreadOnly=false, destructive=false, idempotent=true, openWorld=true

Requiere conexión. Indica cuál en cada llamada: header X-Connect-Connection en REST y campo connectionId en el execute_write 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

Los módulos históricos usan el período pedido; 'nominas' consulta una pantalla de estado actual que no acepta historia y conserva el período que declaró el propio portal. Es el ÚNICO camino que trae datos de Previred: las tools '.consultar' leen lo que esto haya guardado. 'deuda' es el estado del momento y no del período, así que solo se sincroniza cuando se pide el período corriente. 'f301' trae el archivo de 106 campos con que la Dirección del Trabajo emite el Certificado F30-1 de ese período. 'certificados' emite el certificado oficial de cotizaciones de CADA trabajador y por eso es el alcance más caro: cuesta una petición al portal por persona. 'empresas' lista las empresas que la credencial administra y no cuesta ninguna petición: ese listado ya llega al iniciar sesión. Del 10 al 13 de cada mes no se pueden cargar meses fuera del alta (Previred está en su cierre de pago): solo se aceptan el mes actual y los dos anteriores; los meses más antiguos se pueden cargar desde el 14.

Entrada

CampoTipoRequeridoDescripción
periodostring ^\d{4}-\d{2}$síEl mes que se va a sincronizar, en formato AAAA-MM y en calendario chileno (por ejemplo '2026-07'). Traer varios meses son varias llamadas, una por mes. El mismo mes de una conexión se puede pedir una vez cada 10 minutos; antes responde 'rate_limited'.
alcanceslista de "planillas" · "cotizaciones" · "deuda" · "f301" · "certificados" · "empresas" · …síQué módulos de datos traer en esta corrida, al menos uno. Todos se traen en la misma sincronización, así que pedir varios en una llamada cuesta menos que llamar una vez por cada uno. Un alcance debe estar habilitado en la conexión; si no lo está, la llamada responde 'alcance_not_enabled'.
JSON Schema de entrada
{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "type": "object",
  "properties": {
    "periodo": {
      "type": "string",
      "pattern": "^\\d{4}-\\d{2}$",
      "description": "El mes que se va a sincronizar, en formato AAAA-MM y en calendario chileno (por ejemplo '2026-07'). Traer varios meses son varias llamadas, una por mes. El mismo mes de una conexión se puede pedir una vez cada 10 minutos; antes responde 'rate_limited'."
    },
    "alcances": {
      "minItems": 1,
      "type": "array",
      "items": {
        "type": "string",
        "enum": [
          "planillas",
          "cotizaciones",
          "deuda",
          "f301",
          "certificados",
          "empresas",
          "nominas"
        ]
      },
      "description": "Qué módulos de datos traer en esta corrida, al menos uno. Todos se traen en la misma sincronización, así que pedir varios en una llamada cuesta menos que llamar una vez por cada uno. Un alcance debe estar habilitado en la conexión; si no lo está, la llamada responde 'alcance_not_enabled'."
    }
  },
  "required": [
    "periodo",
    "alcances"
  ]
}

Ejemplo

curl
curl -X POST https://connect.emisso.ai/api/v1/tools/previred.conexion.sincronizar/execute \
  -H "Authorization: Bearer connect_sk_…" \
  -H "X-Connect-Connection: conn_9tKfR2mQx4Vb" \
  -H "Content-Type: application/json" \
  -d '{"input":{"periodo":"2026-06","alcances":["planillas","cotizaciones"]}}'
MCP · meta-tool execute_write
{
  "tool": "previred.conexion.sincronizar",
  "params": {
    "periodo": "2026-06",
    "alcances": [
      "planillas",
      "cotizaciones"
    ]
  },
  "connectionId": "conn_9tKfR2mQx4Vb"
}

Salida esperada (200):

{
  "data": {
    "periodo": "2026-06",
    "estado": "encolado",
    "jobId": "sjb_8t6y4u2i0o9p7a5s3d1f0",
    "yaEnCurso": false
  },
  "meta": {
    "request_id": "req_…",
    "tool_id": "previred.conexion.sincronizar",
    "plane": "read",
    "latency_ms": 58240,
    "audit_status": "recorded"
  }
}

Un pago de un período se abre en varias planillas, una por institución previsional: cuatro registros para un solo trabajador es lo normal.

Salida

CampoTipoRequeridoDescripción
periodostringsíEco del período que se pidió, para poder correlacionar la respuesta sin guardarlo tú.
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 consulta el sistema externo y puede tardar minutos, así que no se te hace esperar por él.
jobIdstringnullno
yaEnCursobooleanono'true' significa que ya había una sincronización viva para esa conexión y ese período, así que no se creó otra. No es un error ni un rechazo. Si esa sincronización sigue en cola, 'jobId' es el suyo; si ya está corriendo, 'jobId' llega null y su avance se ve en 'trabajos' de 'conexiones.estado.consultar'. Cubre el período, no necesariamente los alcances que pediste: si pediste otros, vuelve a pedirlos cuando termine. 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.
resultslista de objetonoEl 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[].alcancestringsíCuál de los alcances pedidos describe esta fila. Hay una fila por alcance solicitado, en el orden canónico del conector, no en el orden en que los pediste.
results[].marcadorstringnoUso interno de Emisso; no se publica. En GET /v1/syncs/{id}, la fila trae en su lugar 'motivo': qué pasó y quién tiene que actuar, de la lista cerrada del catálogo de errores.
results[].status"ok" · "partial" · "failed"sí'ok' = el alcance terminó bien; que 'recordsSynced' sea 0 no lo vuelve un fallo. 'failed' = no terminó bien, y la causa va en 'error'. Ojo con un 'failed': NO garantiza que no se haya escrito nada. Cuando el sistema externo trunca un listado, el alcance queda 'failed' con las filas que alcanzó en 'recordsSynced'. Mira siempre las dos cosas juntas. Y revisa fila por fila: un alcance puede fallar mientras los otros de la misma corrida terminan bien. 'partial' = falta el archivo F30-1 de alguna nómina o la información actual de nóminas quedó incompleta. Se conservan los datos ya guardados y se revisa en la próxima sincronización.
results[].recordsSyncedenterosíCuántos registros de este alcance escribió ESTA corrida. Es el trabajo de esta llamada, no el total acumulado que tienes guardado: para saber cuánto hay, consulta. Un 0 no significa por sí solo «no hay datos»; cuando el cero tiene una explicación, viene en 'detalle'.
results[].errorstringnoPor qué este alcance no terminó bien. Presente solo cuando 'status' es 'failed'. Normalmente es un código del catálogo de errores; cuando el sistema externo truncó el listado es una etiqueta de resultado ('movimientos_truncated', 'cartolas_truncated') que no está en ese catálogo y que significa «se escribió lo que alcanzó a venir». Decide por el valor, nunca por el texto libre.
results[].detallestringnoExplicación en lenguaje llano, presente solo cuando el resultado necesita una. Existe para que un cero se pueda transmitir tal cual en vez de concluir «no hay datos»: transmítelo a quien pregunte en lugar de resumir el número solo.
results[].completobooleanono'false' significa que los datos pedidos siguen pendientes de completar: la empresa todavía no aparece entre las del usuario o la información actual de nóminas quedó incompleta.
JSON Schema de salida
{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "type": "object",
  "properties": {
    "periodo": {
      "type": "string",
      "description": "Eco del período que se pidió, para poder correlacionar la respuesta sin guardarlo tú."
    },
    "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 consulta 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.succeeded' o 'sync.failed' si tu plan los incluye. Es null cuando 'estado' es 'completado', porque ahí el resultado ya está en la respuesta, y cuando 'yaEnCurso' es true y esa sincronización ya está corriendo.",
      "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, así que no se creó otra. No es un error ni un rechazo. Si esa sincronización sigue en cola, 'jobId' es el suyo; si ya está corriendo, 'jobId' llega null y su avance se ve en 'trabajos' de 'conexiones.estado.consultar'. Cubre el período, no necesariamente los alcances que pediste: si pediste otros, vuelve a pedirlos cuando termine. 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.",
      "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",
            "description": "Cuál de los alcances pedidos describe esta fila. Hay una fila por alcance solicitado, en el orden canónico del conector, no en el orden en que los pediste."
          },
          "marcador": {
            "description": "Uso interno de Emisso; no se publica. En GET /v1/syncs/{id}, la fila trae en su lugar 'motivo': qué pasó y quién tiene que actuar, de la lista cerrada del catálogo de errores.",
            "type": "string"
          },
          "status": {
            "type": "string",
            "enum": [
              "ok",
              "partial",
              "failed"
            ],
            "description": "'ok' = el alcance terminó bien; que 'recordsSynced' sea 0 no lo vuelve un fallo. 'failed' = no terminó bien, y la causa va en 'error'. Ojo con un 'failed': NO garantiza que no se haya escrito nada. Cuando el sistema externo trunca un listado, el alcance queda 'failed' con las filas que alcanzó en 'recordsSynced'. Mira siempre las dos cosas juntas. Y revisa fila por fila: un alcance puede fallar mientras los otros de la misma corrida terminan bien. 'partial' = falta el archivo F30-1 de alguna nómina o la información actual de nóminas quedó incompleta. Se conservan los datos ya guardados y se revisa en la próxima sincronización."
          },
          "recordsSynced": {
            "type": "integer",
            "minimum": -9007199254740991,
            "maximum": 9007199254740991,
            "description": "Cuántos registros de este alcance escribió ESTA corrida. Es el trabajo de esta llamada, no el total acumulado que tienes guardado: para saber cuánto hay, consulta. Un 0 no significa por sí solo «no hay datos»; cuando el cero tiene una explicación, viene en 'detalle'."
          },
          "error": {
            "description": "Por qué este alcance no terminó bien. Presente solo cuando 'status' es 'failed'. Normalmente es un código del catálogo de errores; cuando el sistema externo truncó el listado es una etiqueta de resultado ('movimientos_truncated', 'cartolas_truncated') que no está en ese catálogo y que significa «se escribió lo que alcanzó a venir». Decide por el valor, nunca por el texto libre.",
            "type": "string"
          },
          "detalle": {
            "description": "Explicación en lenguaje llano, presente solo cuando el resultado necesita una. Existe para que un cero se pueda transmitir tal cual en vez de concluir «no hay datos»: transmítelo a quien pregunte en lugar de resumir el número solo.",
            "type": "string"
          },
          "completo": {
            "description": "'false' significa que los datos pedidos siguen pendientes de completar: la empresa todavía no aparece entre las del usuario o la información actual de nóminas quedó incompleta.",
            "type": "boolean"
          }
        },
        "required": [
          "alcance",
          "status",
          "recordsSynced"
        ],
        "additionalProperties": false
      }
    }
  },
  "required": [
    "periodo",
    "estado"
  ],
  "additionalProperties": false
}

Errores de esta tool

CódigoHTTPReintentableQué hacer
connection_disabled403noReactívala en /connections o usa otra conexión del mismo sistema.
connection_not_found404noUsa uno de los connectionId que lista el error, o revisa la conexión en /connections. No hace falta reactivar nada.
alcance_not_enabled403noHabilita el alcance en /connections o quítalo del input de la sincronización.
too_many_pending429síDeja terminar los trabajos en curso antes de encolar más.

La llamada solo encola: las fallas del sistema externo (credencial, sesión, caída del portal) no llegan en esta respuesta, sino en el trabajo: en outcomes y last_error de GET /v1/syncs/{jobId}, o en los webhooks sync.succeeded (un alcance que falló junto a otros que terminaron) y sync.failed.

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

En esta página