Descargar un archivo para el F30-1 de Previred

Entrega un enlace firmado de vida corta a UN archivo ya sincronizado para el Certificado F30-1, identificado por período, nómina y centro de costo, para bajarlo y subirlo al sitio de la Dirección del Trabajo.


Tool ID	`previred.f301.descargar`
Nombre MCP	`previred__f301__descargar`
Conector	`previred`
Plano	`action`
Lee el alcance	`f301` (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

Los datos de cada archivo vienen en 'previred.f301.consultar', y su campo 'archivoDisponible' dice si está guardado. Si la conexión no tiene ese documento, o todavía no se ha descargado, responde 'previred_documento_not_found'.

Entrada

Campo	Tipo	Requerido	Descripción
`periodo`	string `^\d{4}-\d{2}$`	sí	El período del archivo, en formato AAAA-MM.
`nomina`	string	sí	La nómina, tal como la trae 'previred.f301.consultar'.
`centroCosto`	string	no · default `"total"`	El centro de costo, tal como lo trae 'previred.f301.consultar'. Si se omite, 'total'.

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 período del archivo, en formato AAAA-MM."
    },
    "nomina": {
      "type": "string",
      "minLength": 1,
      "description": "La nómina, tal como la trae 'previred.f301.consultar'."
    },
    "centroCosto": {
      "default": "total",
      "description": "El centro de costo, tal como lo trae 'previred.f301.consultar'. Si se omite, 'total'.",
      "type": "string",
      "minLength": 1
    }
  },
  "required": [
    "periodo",
    "nomina"
  ]
}

Ejemplo

curl

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

SDK TypeScript

const data = await connect.tools.previred.f301.descargar({ periodo: "2026-06", nomina: "Junio 2026" }, { connectionId: "conn_9tKfR2mQx4Vb" });

MCP · meta-tool execute

{
  "tool": "previred.f301.descargar",
  "params": {
    "periodo": "2026-06",
    "nomina": "Junio 2026"
  },
  "connectionId": "conn_9tKfR2mQx4Vb"
}

Salida esperada (200):

{
  "data": {
    "periodo": "2026-06",
    "nomina": "Junio 2026",
    "centroCosto": "total",
    "url": "https://connect.emisso.ai/storage/v1/object/sign/comprobantes/previred-f301/...",
    "venceEn": "2026-10-07T19:05:00.000Z"
  },
  "meta": {
    "request_id": "req_…",
    "tool_id": "previred.f301.descargar",
    "plane": "action",
    "latency_ms": 24,
    "audit_status": "recorded"
  }
}

El enlace caduca a los cinco minutos: pídelo justo antes de abrirlo.

Salida

Campo	Tipo	Requerido	Descripción
`periodo`	string	sí	El período del archivo, en formato AAAA-MM.
`nomina`	string	sí	La nómina del archivo.
`centroCosto`	string	sí	El centro de costo del archivo.
`url`	string	sí	Enlace firmado de vida corta para bajar el documento. No sirve para compartir: el documento trae datos personales de los trabajadores.
`venceEn`	string	sí	Cuándo caduca el enlace (ISO 8601, UTC). Son pocos minutos: pídelo justo antes de usarlo y no lo guardes.

JSON Schema de salida

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "type": "object",
  "properties": {
    "periodo": {
      "type": "string",
      "description": "El período del archivo, en formato AAAA-MM."
    },
    "nomina": {
      "type": "string",
      "description": "La nómina del archivo."
    },
    "centroCosto": {
      "type": "string",
      "description": "El centro de costo del archivo."
    },
    "url": {
      "type": "string",
      "description": "Enlace firmado de vida corta para bajar el documento. No sirve para compartir: el documento trae datos personales de los trabajadores."
    },
    "venceEn": {
      "type": "string",
      "description": "Cuándo caduca el enlace (ISO 8601, UTC). Son pocos minutos: pídelo justo antes de usarlo y no lo guardes."
    }
  },
  "required": [
    "periodo",
    "nomina",
    "centroCosto",
    "url",
    "venceEn"
  ],
  "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.