Consultar planillas pagadas de Previred

Antes de pedir datos nuevos, consulta atenciones en conexiones.estado.consultar.

Tool IDprevired.planillas.consultar
Nombre MCPprevired__planillas__consultar
Conectorprevired
Planoaction
Lee el alcanceplanillas (debe estar habilitado en la conexión)
Scope (permiso)previred:read
Authnone
Versión2
Sensiblesí
Deprecadono
ComportamientoreadOnly=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

Si sincronizarSirve es false, sigue hacer: las indicaciones para pedir datos nuevos que siguen no aplican hasta resolver esa atención. La consulta de datos ya guardados sigue disponible según el plan. Lee las planillas de cotizaciones ya sincronizadas de esta conexión, de la más reciente a la más antigua, filtrables por período (AAAA-MM) y por institución. Un pago de un período se abre en VARIAS planillas, una por cada institución previsional (AFP, Fonasa o Isapre, AFC, mutual, CCAF): por eso un mismo período trae varias filas y eso es lo normal, no una duplicación. Cada fila trae su 'folio', que es el identificador con que Previred la direcciona, y 'comprobanteDisponible' dice si el PDF del comprobante ya está guardado; el PDF se pide aparte con 'previred.comprobante.descargar'. Lectura pura: NO contacta a Previred ni dispara una sincronización. Si el período nunca se sincronizó devuelve una lista vacía, que NO significa que no haya datos en Previred. Para traer datos nuevos, usa 'previred.conexion.sincronizar' primero. Pagina con 'cursor': cuando la respuesta trae 'cursor' distinto de null hay más filas, reenvía ese valor tal cual; nunca lo construyas a mano.

Entrada

CampoTipoRequeridoDescripción
periodostring ^\d{4}-\d{2}$noFiltra por un mes, en formato AAAA-MM. Sin él, la consulta trae todas las filas guardadas de esta conexión.
institucionstringnoFiltra por institución previsional, con el nombre exacto que trae el campo 'institucion' de las filas. Sin él, trae todas.
cursorstringnoContinúa desde donde quedó la página anterior: reenvía tal cual el 'cursor' que vino en la respuesta. Es opaco, así que nunca lo construyas a mano. Sin él, la consulta empieza por el principio.
limitentero 1-500no · default 100Cuántas filas traer como máximo, entre 1 y 500. Si se omite, 100.
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": "Filtra por un mes, en formato AAAA-MM. Sin él, la consulta trae todas las filas guardadas de esta conexión."
    },
    "institucion": {
      "type": "string",
      "description": "Filtra por institución previsional, con el nombre exacto que trae el campo 'institucion' de las filas. Sin él, trae todas."
    },
    "cursor": {
      "description": "Continúa desde donde quedó la página anterior: reenvía tal cual el 'cursor' que vino en la respuesta. Es opaco, así que nunca lo construyas a mano. Sin él, la consulta empieza por el principio.",
      "type": "string"
    },
    "limit": {
      "default": 100,
      "description": "Cuántas filas traer como máximo, entre 1 y 500. Si se omite, 100.",
      "type": "integer",
      "minimum": 1,
      "maximum": 500
    }
  }
}

Ejemplo

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

Salida esperada (200):

{
  "data": {
    "planillas": [
      {
        "folio": "2055260600000004",
        "periodo": "2026-06",
        "institucion": "Instituto de Seguridad Laboral (ISL)",
        "tipoInstitucion": "MUTUAL",
        "idNomina": "75128352",
        "montoPagado": 17585,
        "fechaPago": "2026-07-13",
        "afiliadosInformados": 1,
        "comprobanteDisponible": true,
        "comprobanteUrl": null
      }
    ],
    "cursor": null
  },
  "meta": {
    "request_id": "req_…",
    "tool_id": "previred.planillas.consultar",
    "plane": "action",
    "latency_ms": 24,
    "audit_status": "recorded"
  }
}

Para bajar el PDF, llama a 'previred.comprobante.descargar' con el folio de una fila que traiga 'comprobanteDisponible' en true. 'comprobanteUrl' está deprecado y se retira el 2026-10-14.

Salida

CampoTipoRequeridoDescripción
planillaslista de objetosíLas planillas guardadas, de la más reciente a la más antigua. Un pago de un período se abre en varias planillas, una por institución previsional: varias filas del mismo período es lo normal, no una duplicación.
planillas[].foliostringsíEl identificador que Previred le da a la planilla, y con el que el portal la direcciona. Son 16 dígitos y es opaco: no lo descompongas, porque los folios reales no siguen un patrón parejo.
planillas[].periodostringsíEl mes de remuneraciones que paga esta planilla, en formato AAAA-MM.
planillas[].institucionstringsíLa institución previsional, con el nombre que le da Previred (la AFP, Fonasa o la isapre, el seguro de cesantía, la mutual, la caja de compensación).
planillas[].tipoInstitucionstringnullsí
planillas[].idNominastringnullsí
planillas[].montoPagadonúmeronullsí
planillas[].fechaPagostringnullsí
planillas[].afiliadosInformadosenteronullsí
planillas[].comprobanteDisponiblebooleanosítrue cuando el comprobante de pago en PDF ya está guardado en Emisso: pídelo con 'previred.comprobante.descargar' y este folio. false cuando todavía no se ha descargado (la planilla vale igual y el próximo sync lo reintenta).
planillas[].comprobanteUrlstringnullsí
cursorstringnullsí
JSON Schema de salida
{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "type": "object",
  "properties": {
    "planillas": {
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "folio": {
            "type": "string",
            "description": "El identificador que Previred le da a la planilla, y con el que el portal la direcciona. Son 16 dígitos y es opaco: no lo descompongas, porque los folios reales no siguen un patrón parejo."
          },
          "periodo": {
            "type": "string",
            "description": "El mes de remuneraciones que paga esta planilla, en formato AAAA-MM."
          },
          "institucion": {
            "type": "string",
            "description": "La institución previsional, con el nombre que le da Previred (la AFP, Fonasa o la isapre, el seguro de cesantía, la mutual, la caja de compensación)."
          },
          "tipoInstitucion": {
            "anyOf": [
              {
                "type": "string"
              },
              {
                "type": "null"
              }
            ],
            "description": "La familia de la institución, que es el eje por el que Previred agrupa y filtra (por ejemplo 'AFP' o 'MUTUAL'). null cuando el portal no la informó."
          },
          "idNomina": {
            "anyOf": [
              {
                "type": "string"
              },
              {
                "type": "null"
              }
            ],
            "description": "Identificador de la nómina dentro del período. Una empresa puede tener varias en el mismo mes, así que agrupar solo por período las mezcla."
          },
          "montoPagado": {
            "anyOf": [
              {
                "type": "number"
              },
              {
                "type": "null"
              }
            ],
            "description": "Lo pagado a esa institución, en pesos. null cuando el portal no trajo la celda, nunca 0: un 0 es un monto real y confundirlos mentiría sobre la plata."
          },
          "fechaPago": {
            "anyOf": [
              {
                "type": "string"
              },
              {
                "type": "null"
              }
            ],
            "description": "Cuándo se pagó la planilla, según el comprobante. null cuando el portal no lo informó."
          },
          "afiliadosInformados": {
            "anyOf": [
              {
                "type": "integer",
                "minimum": -9007199254740991,
                "maximum": 9007199254740991
              },
              {
                "type": "null"
              }
            ],
            "description": "Cuántos trabajadores informa esta planilla. null cuando el portal no trajo el dato."
          },
          "comprobanteDisponible": {
            "type": "boolean",
            "description": "true cuando el comprobante de pago en PDF ya está guardado en Emisso: pídelo con 'previred.comprobante.descargar' y este folio. false cuando todavía no se ha descargado (la planilla vale igual y el próximo sync lo reintenta)."
          },
          "comprobanteUrl": {
            "anyOf": [
              {
                "type": "string"
              },
              {
                "type": "null"
              }
            ],
            "deprecated": true,
            "description": "Se retira el 2026-10-14. Usa 'comprobanteDisponible' para saber si el documento existe y pide el enlace con 'previred.comprobante.descargar' solo cuando lo necesites. Enlace firmado de vida corta al comprobante de pago en PDF, o null si todavía no se ha descargado. Caduca a los pocos minutos y no sirve para compartir: el documento trae el RUT, el nombre y la renta de los trabajadores."
          }
        },
        "required": [
          "folio",
          "periodo",
          "institucion",
          "tipoInstitucion",
          "idNomina",
          "montoPagado",
          "fechaPago",
          "afiliadosInformados",
          "comprobanteDisponible",
          "comprobanteUrl"
        ],
        "additionalProperties": false
      },
      "description": "Las planillas guardadas, de la más reciente a la más antigua. Un pago de un período se abre en varias planillas, una por institución previsional: varias filas del mismo período es lo normal, no una duplicación."
    },
    "cursor": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "description": "Cuando no es null quedan más filas: reenvíalo tal cual en 'cursor' para pedir la página siguiente. En null significa que esta fue la última."
    }
  },
  "required": [
    "planillas",
    "cursor"
  ],
  "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.

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