Consultar nóminas actuales de Previred

Lee desde la caché el snapshot más reciente del maletín de nóminas de esta empresa: nombre, período observado, códigos crudos de estado y forma de carga, total, cuadratura y las señales operativas que dicen si una nómina requiere actualización o cálculo, está bloqueada o puede seleccionarse.


Tool ID	`previred.nominas.consultar`
Nombre MCP	`previred__nominas__consultar`
Conector	`previred`
Plano	`action`
Lee el alcance	`nominas` (debe estar habilitado en la conexión)
Scope (permiso)	`previred: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, campo connectionId en el execute 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.

Qué hace

Esta pantalla de Previred NO ofrece selector histórico: 'periodo' es lo que el portal declaró al observar el snapshot, no un mes solicitado, y la tool no promete historia. Lectura pura: NO contacta a Previred ni dispara una sincronización. Una lista vacía sin un sync exitoso reciente no demuestra que el portal esté vacío; para refrescarla usa 'previred.conexion.sincronizar'. 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

Campo	Tipo	Requerido	Descripción
`estado`	string `^[^\s&]+$`	no	Filtra por el código de estado crudo que devolvió Previred. Sin él, trae todos los estados actuales.
`seleccionable`	booleano	no	Filtra por si la nómina está actualmente habilitada para selección en Previred.
`cursor`	string	no	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.
`limit`	entero 1-500	no · default `100`	Cuá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": {
    "estado": {
      "type": "string",
      "minLength": 1,
      "maxLength": 32,
      "pattern": "^[^\\s&]+$",
      "description": "Filtra por el código de estado crudo que devolvió Previred. Sin él, trae todos los estados actuales."
    },
    "seleccionable": {
      "type": "boolean",
      "description": "Filtra por si la nómina está actualmente habilitada para selección en Previred."
    },
    "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.nominas.consultar/execute \
  -H "Authorization: Bearer connect_sk_…" \
  -H "X-Connect-Connection: conn_9tKfR2mQx4Vb" \
  -H "Content-Type: application/json" \
  -d '{"input":{"seleccionable":true}}'

SDK TypeScript

const data = await connect.tools.previred.nominas.consultar({ seleccionable: true }, { connectionId: "conn_9tKfR2mQx4Vb" });

MCP · meta-tool execute

{
  "tool": "previred.nominas.consultar",
  "params": {
    "seleccionable": true
  },
  "connectionId": "conn_9tKfR2mQx4Vb"
}

Salida esperada (200):

{
  "data": {
    "nominas": [
      {
        "idNomina": "741",
        "periodo": "2026-08",
        "nombre": "Remuneraciones Agosto",
        "estado": "1",
        "requiereActualizacion": false,
        "formaCarga": "2",
        "requiereCalculo": false,
        "bloqueada": false,
        "seleccionable": true,
        "montoTotal": 12345678,
        "cuadraturaDisponible": true,
        "observadoEn": "2026-09-04T15:30:00.000Z",
        "syncedAt": "2026-09-04T15:30:01.000Z"
      }
    ],
    "cursor": null
  },
  "meta": {
    "request_id": "req_…",
    "tool_id": "previred.nominas.consultar",
    "plane": "action",
    "latency_ms": 24,
    "audit_status": "recorded"
  }
}

Los códigos 'estado' y 'formaCarga' son valores crudos del portal; usa los booleanos para decisiones operativas.

Salida

Campo	Tipo	Requerido	Descripción
`nominas`	lista de objeto	sí	El snapshot vigente del maletín de nóminas de Previred. No es un historial: las filas que dejaron de estar vigentes no se exponen.
`nominas[].idNomina`	string	sí	Identificador opaco y estable que Previred asigna a la nómina. Es su clave natural dentro de esta conexión.
`nominas[].periodo`	string	sí	Período que la propia pantalla de Previred declaró para este snapshot, en formato AAAA-MM. No es un período pedido por quien consulta.
`nominas[].nombre`	string	sí	Nombre de la nómina tal como lo configuró la empresa en Previred.
`nominas[].estado`	string	sí	Código de estado crudo de Previred. Se conserva para trazabilidad; usa los booleanos operativos en vez de inferir significado de este código.
`nominas[].requiereActualizacion`	booleano	sí	true cuando Previred exige actualizar la nómina antes de continuar.
`nominas[].formaCarga`	string	sí	Código de forma de carga crudo de Previred. Se conserva sin inventar una taxonomía no documentada.
`nominas[].requiereCalculo`	booleano	sí	true cuando Previred todavía exige calcular el total a pagar.
`nominas[].bloqueada`	booleano	sí	true cuando el portal marca el estado 16, que su propio JavaScript trata como nómina bloqueada.
`nominas[].seleccionable`	booleano	sí	true cuando la fila tiene su checkbox habilitado y no requiere actualización, cálculo ni está bloqueada.
`nominas[].montoTotal`	número	null	sí
`nominas[].cuadraturaDisponible`	booleano	sí	true cuando Previred habilita la cuadratura de esta nómina en la pantalla actual.
`nominas[].observadoEn`	string	sí	Instante ISO 8601 en que se observó este estado en Previred.
`nominas[].syncedAt`	string	sí	Cuándo se guardó esta fila en Connect (ISO 8601). Dice qué tan fresca está la caché: si la última sincronización es vieja, lo que falta puede existir en Previred y todavía no haberse traído.
`cursor`	string	null	sí

JSON Schema de salida

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "type": "object",
  "properties": {
    "nominas": {
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "idNomina": {
            "type": "string",
            "description": "Identificador opaco y estable que Previred asigna a la nómina. Es su clave natural dentro de esta conexión."
          },
          "periodo": {
            "type": "string",
            "description": "Período que la propia pantalla de Previred declaró para este snapshot, en formato AAAA-MM. No es un período pedido por quien consulta."
          },
          "nombre": {
            "type": "string",
            "description": "Nombre de la nómina tal como lo configuró la empresa en Previred."
          },
          "estado": {
            "type": "string",
            "description": "Código de estado crudo de Previred. Se conserva para trazabilidad; usa los booleanos operativos en vez de inferir significado de este código."
          },
          "requiereActualizacion": {
            "type": "boolean",
            "description": "true cuando Previred exige actualizar la nómina antes de continuar."
          },
          "formaCarga": {
            "type": "string",
            "description": "Código de forma de carga crudo de Previred. Se conserva sin inventar una taxonomía no documentada."
          },
          "requiereCalculo": {
            "type": "boolean",
            "description": "true cuando Previred todavía exige calcular el total a pagar."
          },
          "bloqueada": {
            "type": "boolean",
            "description": "true cuando el portal marca el estado 16, que su propio JavaScript trata como nómina bloqueada."
          },
          "seleccionable": {
            "type": "boolean",
            "description": "true cuando la fila tiene su checkbox habilitado y no requiere actualización, cálculo ni está bloqueada."
          },
          "montoTotal": {
            "anyOf": [
              {
                "type": "number"
              },
              {
                "type": "null"
              }
            ],
            "description": "Total de la nómina en pesos. null cuando el portal todavía muestra 'Calcular Total a Pagar' o no entregó un monto; nunca se convierte en 0."
          },
          "cuadraturaDisponible": {
            "type": "boolean",
            "description": "true cuando Previred habilita la cuadratura de esta nómina en la pantalla actual."
          },
          "observadoEn": {
            "type": "string",
            "description": "Instante ISO 8601 en que se observó este estado en Previred."
          },
          "syncedAt": {
            "type": "string",
            "description": "Cuándo se guardó esta fila en Connect (ISO 8601). Dice qué tan fresca está la caché: si la última sincronización es vieja, lo que falta puede existir en Previred y todavía no haberse traído."
          }
        },
        "required": [
          "idNomina",
          "periodo",
          "nombre",
          "estado",
          "requiereActualizacion",
          "formaCarga",
          "requiereCalculo",
          "bloqueada",
          "seleccionable",
          "montoTotal",
          "cuadraturaDisponible",
          "observadoEn",
          "syncedAt"
        ],
        "additionalProperties": false
      },
      "description": "El snapshot vigente del maletín de nóminas de Previred. No es un historial: las filas que dejaron de estar vigentes no se exponen."
    },
    "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": [
    "nominas",
    "cursor"
  ],
  "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

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