# Consultar adjuntos de Compra Ágil
> Entrega los adjuntos conservados de una Compra Ágil.
{/* AUTO-GENERATED by @emisso/codegen. DO NOT EDIT. */}
| | |
| ------------------- | ------------------------------------------------------------------ |
| **Tool ID** | `mercadopublico.compra_agil.consultar` |
| **Nombre MCP** | `mercadopublico__compra_agil__consultar` |
| **Conector** | `mercadopublico` |
| **Plano** | `action` |
| **Scope (permiso)** | `mercadopublico:read` |
| **Auth** | `none` |
| **Versión** | `1` |
| **Sensible** | no |
| **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]
Trae enlaces temporales; no abre el portal ni inicia una descarga: no\_solicitada, pendiente y fallido no significan que la Compra Ágil carezca de adjuntos. Mientras una actualización está en curso, o si falla, entrega la lectura anterior con resultadoAnterior en true.
## Entrada [#entrada]
| Campo | Tipo | Requerido | Descripción |
| -------- | ------------------------------------- | --------- | -------------------------------------------------------------------------------- |
| `codigo` | string `^\d{1,10}-\d{1,10}-COT\d{2}$` | sí | Código público de la Compra Ágil, por ejemplo 1057539-228-COT26. No acepta URLs. |
JSON Schema de entrada
```json
{
"$schema": "https://json-schema.org/draft/2020-12/schema",
"type": "object",
"properties": {
"codigo": {
"type": "string",
"maxLength": 40,
"pattern": "^\\d{1,10}-\\d{1,10}-COT\\d{2}$",
"description": "Código público de la Compra Ágil, por ejemplo 1057539-228-COT26. No acepta URLs."
}
},
"required": [
"codigo"
]
}
```
## Salida [#salida]
| Campo | Tipo | Requerido | Descripción | |
| ------------------------- | ----------------------------------------------------------------------------------------------- | --------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------- |
| `codigo` | string | sí | Código o ID público consultado, canonizado en mayúsculas. | |
| `estado` | `"no_solicitada"` · `"pendiente"` · `"procesando"` · `"disponible"` · `"parcial"` · `"fallido"` | sí | Estado de la descarga solicitada a Connect. | |
| `solicitadoEn` | string | null | sí | Instante ISO 8601 de la última solicitud, o null si no existe. |
| `finalizadoEn` | string | null | sí | Instante ISO 8601 en que terminó la descarga, si corresponde. |
| `errorCodigo` | string | null | sí | Código acotado de fallo, sin datos de sesión ni URLs del portal. |
| `consultarEnSegundos` | entero | null | sí | Mientras la descarga está pendiente o en proceso, cuántos segundos esperar antes de consultar de nuevo. null cuando ya terminó o no hay solicitud. |
| `observadoEn` | string | null | sí | Instante ISO 8601 de la última lectura del portal conservada. |
| `completo` | booleano | sí | Se leyó el listado entero y se conservaron todos los adjuntos admitidos dentro de los límites. | |
| `motivosIncompletitud` | lista de string | sí | Razones por las que el listado o las descargas requieren revisión. | |
| `resultadoAnterior` | booleano | sí | true si los datos son de una lectura anterior: hay una actualización en curso o la última falló. observadoEn dice de cuándo son. | |
| `totalAdjuntos` | entero | sí | Cantidad de adjuntos listados por Mercado Público. | |
| `documentos` | lista de objeto | sí | Todos los adjuntos listados, sin clasificar: los descargados llevan enlace firmado; el resto indica su estado. | |
| `documentos[].idPortal` | string | sí | Identificador (UUID, en minúsculas) del adjunto en Mercado Público. Es su identidad natural. | |
| `documentos[].nombre` | string | sí | Nombre del archivo declarado por el comprador. | |
| `documentos[].estado` | `"descargado"` · `"omitido_formato"` · `"omitido_tamano"` · `"no_descargado"` | sí | 'descargado': hay archivo conservado (lleva archivoUrl). 'omitido\_formato': no es PDF, Word, Excel ni PNG/JPEG, o su contenido no corresponde a su extensión. 'omitido\_tamano': supera el tope. 'no\_descargado': se observó pero no se conserva (error o límite). | |
| `documentos[].formato` | `"pdf"` · `"docx"` · `"doc"` · `"xlsx"` · `"xls"` · `"png"` · … | null | sí | Formato del archivo conservado; null si no se descargó. |
| `documentos[].bytes` | entero | null | sí | Tamaño en bytes del archivo conservado; null si no se descargó. |
| `documentos[].sha256` | string | null | sí | Huella SHA-256 del archivo conservado; null si no se descargó. |
| `documentos[].archivoUrl` | string | null | sí | Enlace temporal al archivo conservado por Connect; null si no se descargó o no pudo firmarse. Nunca es una URL del portal. |
| `documentos[].urlVenceEn` | string | null | sí | Instante ISO 8601 en que caduca archivoUrl, si se firmó. |
JSON Schema de salida
```json
{
"$schema": "https://json-schema.org/draft/2020-12/schema",
"type": "object",
"properties": {
"codigo": {
"type": "string",
"description": "Código o ID público consultado, canonizado en mayúsculas."
},
"estado": {
"type": "string",
"enum": [
"no_solicitada",
"pendiente",
"procesando",
"disponible",
"parcial",
"fallido"
],
"description": "Estado de la descarga solicitada a Connect."
},
"solicitadoEn": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"description": "Instante ISO 8601 de la última solicitud, o null si no existe."
},
"finalizadoEn": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"description": "Instante ISO 8601 en que terminó la descarga, si corresponde."
},
"errorCodigo": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"description": "Código acotado de fallo, sin datos de sesión ni URLs del portal."
},
"consultarEnSegundos": {
"anyOf": [
{
"type": "integer",
"exclusiveMinimum": 0,
"maximum": 9007199254740991
},
{
"type": "null"
}
],
"description": "Mientras la descarga está pendiente o en proceso, cuántos segundos esperar antes de consultar de nuevo. null cuando ya terminó o no hay solicitud."
},
"observadoEn": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"description": "Instante ISO 8601 de la última lectura del portal conservada."
},
"completo": {
"type": "boolean",
"description": "Se leyó el listado entero y se conservaron todos los adjuntos admitidos dentro de los límites."
},
"motivosIncompletitud": {
"type": "array",
"items": {
"type": "string"
},
"description": "Razones por las que el listado o las descargas requieren revisión."
},
"resultadoAnterior": {
"type": "boolean",
"description": "true si los datos son de una lectura anterior: hay una actualización en curso o la última falló. observadoEn dice de cuándo son."
},
"totalAdjuntos": {
"type": "integer",
"minimum": 0,
"maximum": 9007199254740991,
"description": "Cantidad de adjuntos listados por Mercado Público."
},
"documentos": {
"type": "array",
"items": {
"type": "object",
"properties": {
"idPortal": {
"type": "string",
"description": "Identificador (UUID, en minúsculas) del adjunto en Mercado Público. Es su identidad natural."
},
"nombre": {
"type": "string",
"description": "Nombre del archivo declarado por el comprador."
},
"estado": {
"type": "string",
"enum": [
"descargado",
"omitido_formato",
"omitido_tamano",
"no_descargado"
],
"description": "'descargado': hay archivo conservado (lleva archivoUrl). 'omitido_formato': no es PDF, Word, Excel ni PNG/JPEG, o su contenido no corresponde a su extensión. 'omitido_tamano': supera el tope. 'no_descargado': se observó pero no se conserva (error o límite)."
},
"formato": {
"anyOf": [
{
"type": "string",
"enum": [
"pdf",
"docx",
"doc",
"xlsx",
"xls",
"png",
"jpg"
],
"description": "Formato del archivo conservado, verificado por su contenido: 'pdf'; Word ('docx', 'doc'); Excel ('xlsx', 'xls'); imagen ('png', 'jpg')."
},
{
"type": "null"
}
],
"description": "Formato del archivo conservado; null si no se descargó."
},
"bytes": {
"anyOf": [
{
"type": "integer",
"minimum": 0,
"maximum": 9007199254740991
},
{
"type": "null"
}
],
"description": "Tamaño en bytes del archivo conservado; null si no se descargó."
},
"sha256": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"description": "Huella SHA-256 del archivo conservado; null si no se descargó."
},
"archivoUrl": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"description": "Enlace temporal al archivo conservado por Connect; null si no se descargó o no pudo firmarse. Nunca es una URL del portal."
},
"urlVenceEn": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"description": "Instante ISO 8601 en que caduca archivoUrl, si se firmó."
}
},
"required": [
"idPortal",
"nombre",
"estado",
"formato",
"bytes",
"sha256",
"archivoUrl",
"urlVenceEn"
],
"additionalProperties": false
},
"description": "Todos los adjuntos listados, sin clasificar: los descargados llevan enlace firmado; el resto indica su estado."
}
},
"required": [
"codigo",
"estado",
"solicitadoEn",
"finalizadoEn",
"errorCodigo",
"consultarEnSegundos",
"observadoEn",
"completo",
"motivosIncompletitud",
"resultadoAnterior",
"totalAdjuntos",
"documentos"
],
"additionalProperties": false
}
```
## 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. |
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).