# Consultar archivos para el F30-1 de Previred

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



{/* AUTO-GENERATED by @emisso/codegen. DO NOT EDIT. */}

|                     |                                                                    |
| ------------------- | ------------------------------------------------------------------ |
| **Tool ID**         | `previred.f301.consultar`                                          |
| **Nombre MCP**      | `previred__f301__consultar`                                        |
| **Conector**        | `previred`                                                         |
| **Plano**           | `action`                                                           |
| **Lee el alcance**  | `f301` (debe estar habilitado en la conexión)                      |
| **Scope (permiso)** | `previred:read`                                                    |
| **Auth**            | `none`                                                             |
| **Versión**         | `2`                                                                |
| **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`](/docs/referencia/conexiones/estado-consultar).

## Qué hace [#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 los archivos ya sincronizados con que la Dirección del Trabajo emite el Certificado F30-1 de Cumplimiento de Obligaciones Laborales y Previsionales, el que una empresa contratista tiene que entregarle a su mandante para que le paguen. Cada fila es el archivo de 106 campos de un período y una nómina; 'archivoDisponible' dice si ya está guardado, y 'previred.f301.descargar' entrega el enlace para bajarlo y subirlo al sitio de la Dirección del Trabajo. Emisso NO emite el certificado: entrega el archivo con que se pide. 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 [#entrada]

| Campo     | Tipo                   | Requerido          | Descripción                                                                                                                                                                                       |
| --------- | ---------------------- | ------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `periodo` | string `^\d{4}-\d{2}$` | no                 | Filtra por un mes, en formato AAAA-MM. Sin él, la consulta trae todas las filas guardadas de esta conexión.                                                                                       |
| `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.                                                                                                                                 |

<details>
  <summary>
    JSON Schema de entrada
  </summary>

  ```json
  {
    "$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."
      },
      "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
      }
    }
  }
  ```
</details>

## Ejemplo [#ejemplo]

```bash title="curl"
curl -X POST https://connect.emisso.ai/api/v1/tools/previred.f301.consultar/execute \
  -H "Authorization: Bearer connect_sk_…" \
  -H "X-Connect-Connection: conn_9tKfR2mQx4Vb" \
  -H "Content-Type: application/json" \
  -d '{"input":{"periodo":"2026-06"}}'
```

```json title="MCP · meta-tool execute"
{
  "tool": "previred.f301.consultar",
  "params": {
    "periodo": "2026-06"
  },
  "connectionId": "conn_9tKfR2mQx4Vb"
}
```

**Salida esperada (200):**

```json
{
  "data": {
    "archivos": [
      {
        "periodo": "2026-06",
        "nomina": "Junio 2026",
        "centroCosto": "total",
        "trabajadores": 12,
        "bytes": 3288,
        "archivoDisponible": true,
        "archivoUrl": null,
        "syncedAt": "2026-08-11T14:02:11.000Z"
      }
    ],
    "cursor": null
  },
  "meta": {
    "request_id": "req_…",
    "tool_id": "previred.f301.consultar",
    "plane": "action",
    "latency_ms": 24,
    "audit_status": "recorded"
  }
}
```

> Un período puede traer varias filas si la empresa carga más de una nómina. Para bajar un archivo, llama a 'previred.f301.descargar' con su período, nómina y centro de costo. 'archivoUrl' está deprecado y se retira el 2026-10-14.

## Salida [#salida]

| Campo                          | Tipo            | Requerido | Descripción                                                                                                                                                                                         |                                                                                                                                                                                                                                                                                                                                                                                                                                                 |
| ------------------------------ | --------------- | --------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `archivos`                     | lista de objeto | sí        | Los archivos guardados. Cada uno cubre UNA nómina de un período, así que un período con dos nóminas trae dos filas.                                                                                 |                                                                                                                                                                                                                                                                                                                                                                                                                                                 |
| `archivos[].periodo`           | string          | sí        | El período que cubre el archivo, en formato AAAA-MM.                                                                                                                                                |                                                                                                                                                                                                                                                                                                                                                                                                                                                 |
| `archivos[].nomina`            | string          | sí        | El nombre que la nómina tiene en Previred. Es lo que distingue dos archivos del mismo período.                                                                                                      |                                                                                                                                                                                                                                                                                                                                                                                                                                                 |
| `archivos[].centroCosto`       | string          | sí        | 'total' significa Total Empresa, que es lo único que este conector emite hoy. Está en la respuesta porque Previred también permite emitir el archivo por centro de costo, y ese sería otro archivo. |                                                                                                                                                                                                                                                                                                                                                                                                                                                 |
| `archivos[].trabajadores`      | entero          | sí        | Cuántos trabajadores informa el archivo, una línea por cada uno.                                                                                                                                    |                                                                                                                                                                                                                                                                                                                                                                                                                                                 |
| `archivos[].bytes`             | entero          | sí        | Tamaño del archivo en bytes.                                                                                                                                                                        |                                                                                                                                                                                                                                                                                                                                                                                                                                                 |
| `archivos[].archivoDisponible` | booleano        | sí        | true cuando el archivo ya está guardado en Emisso: pídelo con 'previred.f301.descargar' y su período, nómina y centro de costo. false cuando todavía no se ha descargado.                           |                                                                                                                                                                                                                                                                                                                                                                                                                                                 |
| `archivos[].archivoUrl`        | string          | null      | sí                                                                                                                                                                                                  | **Deprecado.** Se retira el 2026-10-14. Usa 'archivoDisponible' para saber si el documento existe y pide el enlace con 'previred.f301.descargar' solo cuando lo necesites. Enlace firmado de vida corta para descargar el archivo y subirlo al sitio de la Dirección del Trabajo, o null si todavía no se ha descargado. Caduca a los pocos minutos y no sirve para compartir: el archivo trae el RUT, el nombre y la renta de cada trabajador. |
| `archivos[].syncedAt`          | string          | sí        | Cuándo se guardó esta fila en Emisso (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í                                                                                                                                                                                                  | 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.                                                                                                                                                                                                                                                                                                    |

<details>
  <summary>
    JSON Schema de salida
  </summary>

  ```json
  {
    "$schema": "https://json-schema.org/draft/2020-12/schema",
    "type": "object",
    "properties": {
      "archivos": {
        "type": "array",
        "items": {
          "type": "object",
          "properties": {
            "periodo": {
              "type": "string",
              "description": "El período que cubre el archivo, en formato AAAA-MM."
            },
            "nomina": {
              "type": "string",
              "description": "El nombre que la nómina tiene en Previred. Es lo que distingue dos archivos del mismo período."
            },
            "centroCosto": {
              "type": "string",
              "description": "'total' significa Total Empresa, que es lo único que este conector emite hoy. Está en la respuesta porque Previred también permite emitir el archivo por centro de costo, y ese sería otro archivo."
            },
            "trabajadores": {
              "type": "integer",
              "minimum": -9007199254740991,
              "maximum": 9007199254740991,
              "description": "Cuántos trabajadores informa el archivo, una línea por cada uno."
            },
            "bytes": {
              "type": "integer",
              "minimum": -9007199254740991,
              "maximum": 9007199254740991,
              "description": "Tamaño del archivo en bytes."
            },
            "archivoDisponible": {
              "type": "boolean",
              "description": "true cuando el archivo ya está guardado en Emisso: pídelo con 'previred.f301.descargar' y su período, nómina y centro de costo. false cuando todavía no se ha descargado."
            },
            "archivoUrl": {
              "anyOf": [
                {
                  "type": "string"
                },
                {
                  "type": "null"
                }
              ],
              "deprecated": true,
              "description": "Se retira el 2026-10-14. Usa 'archivoDisponible' para saber si el documento existe y pide el enlace con 'previred.f301.descargar' solo cuando lo necesites. Enlace firmado de vida corta para descargar el archivo y subirlo al sitio de la Dirección del Trabajo, o null si todavía no se ha descargado. Caduca a los pocos minutos y no sirve para compartir: el archivo trae el RUT, el nombre y la renta de cada trabajador."
            },
            "syncedAt": {
              "type": "string",
              "description": "Cuándo se guardó esta fila en Emisso (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": [
            "periodo",
            "nomina",
            "centroCosto",
            "trabajadores",
            "bytes",
            "archivoDisponible",
            "archivoUrl",
            "syncedAt"
          ],
          "additionalProperties": false
        },
        "description": "Los archivos guardados. Cada uno cubre UNA nómina de un período, así que un período con dos nóminas trae dos filas."
      },
      "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": [
      "archivos",
      "cursor"
    ],
    "additionalProperties": false
  }
  ```
</details>

## 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_not_found` | 404  | no           | Usa uno de los connectionId que lista el error, o revisa la conexión en /connections. No hace falta reactivar nada. |
| `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](/docs/referencia/errores).

## Próximos pasos [#próximos-pasos]

* [`previred.conexion.sincronizar`](/docs/referencia/previred/conexion-sincronizar): la tool que escribe los datos que esta lectura devuelve.
* [Sincronizar y consultar](/docs/conceptos/sincronizar-consultar): por qué leer datos reales son dos pasos.


---

Esta página es parte de la documentación de Emisso. El índice completo, con cada página y su descripción, está en https://connect.emisso.ai/llms.txt. Esta misma página en HTML: https://connect.emisso.ai/docs/referencia/previred/f301-consultar.
