Descargar un archivo para el F30-1 de Previred
Antes de pedir datos nuevos, consulta atenciones en conexiones.estado.consultar.
| 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-Connectionen REST y campoconnectionIden elexecutede MCP. No hay resolución implícita, ni siquiera con una sola conexión activa: la conexión es la empresa. El id sale deconexiones.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. 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. 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 -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"}}'{
"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. |
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.
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.