Preparación documental

La preparación documental convierte los archivos de una licitación en material disponible para consulta. Es distinta del catálogo: buscar o abrir una ficha solo muestra metadata y nunca inicia esta etapa.

Estado de preparación documental

Estado de una licitación mientras los documentos se preparan para consulta.

Una acción explícita y reutilizable

La preparación comienza solo cuando eliges prepararla desde la web, REST o MCP. Abrir la ficha, buscar por ID, actualizar metadata, agregar la oportunidad al seguimiento o abrir el chat no la inicia.

Antes de una preparación nueva, LicitaIQ valida la capacidad de preparación de la cuenta. Ese es el único paywall: la autorización cubre descarga, procesamiento e indexación de la misma licitación; no hay un segundo paywall entre esas etapas.

Una preparación ya autorizada se reutiliza. Si está en curso, una nueva solicitud informa que el flujo ya está activo en vez de iniciar trabajo duplicado. Si falla un archivo persistido, el reintento trabaja solo sobre ese archivo y no vuelve a descargar los que ya quedaron disponibles.

El mismo contrato en web, REST y MCP

La web no decide el acceso por el nombre del plan: muestra la matriz de capacidades que devuelve el backend. REST y MCP aplican la misma matriz y devuelven el mismo estado agregado, manifiesto y acciones posibles.

Necesidad	Web	REST	MCP	Efecto sobre el cupo
Ver el manifiesto o actualizar su estado	Actualizar	GET /tenders/:tenderId/preparation o POST /tenders/:tenderId/preparation/refresh	refresh_tender_preparation	No inicia trabajo ni consume.
Iniciar una preparación	Acción explícita de preparar	POST /tenders/:tenderId/preparation	download_tender_files o prepare_tender_for_agent	Puede consumir una preparación solo al finalizar correctamente.
Reintentar un archivo fallido	Acción sobre el archivo marcado	POST /tenders/:tenderId/preparation/retry con file_ref	retry_tender_processing con file_ref	No consume una preparación adicional.

refresh_tender en MCP actualiza la metadata de Mercado Público; no sustituye la lectura del manifiesto ni inicia la preparación documental.

Estados de la preparación

El estado agregado resume la situación de la licitación. Las acciones sugeridas dependen también de las capacidades de la cuenta y del manifiesto por archivo.

Estado	Significado	Siguiente paso seguro
not_found	La licitación no fue encontrada en Mercado Público.	Revisa el ID y vuelve a buscar.
details_not_loaded	La licitación existe, pero su metadata aún no está cargada en LicitaIQ.	Carga o actualiza la ficha; no prepara archivos.
fetching_details	La metadata está cargándose.	Espera y actualiza el estado.
files_not_started	La metadata está lista, pero aún no se ha solicitado preparar documentos.	Inicia la preparación explícita si tu cuenta la permite.
downloading_files	LicitaIQ está obteniendo los documentos.	Actualiza el estado; no inicies otro flujo.
processing_files	Los documentos están siendo transformados e indexados.	Actualiza el estado o revisa el manifiesto.
ready_for_retrieval	Los documentos ya se pueden consultar con retrieval.	Usa búsqueda documental o el chat si tu capacidad lo permite.
enriched	Hay documentos listos y análisis IA disponible.	Consulta documentos o análisis según tus cupos.
partial	Hay documentos disponibles y otros archivos siguen procesándose o fallaron.	Consulta los disponibles con ready_for_retrieval; revisa cada archivo y reintenta solo los fallidos reintentables.
failed	La preparación no dejó documentos listos para consulta.	Revisa el diagnóstico y el manifiesto antes de reintentar.

Manifiesto por archivo

El manifiesto expone una entrada pública por archivo. Incluye el nombre, tipo, estado, resultado, si se puede reintentar y la siguiente acción. Para reintentar se usa file_ref, una referencia opaca: la interfaz, REST y MCP no exponen IDs internos, claves de almacenamiento ni IDs de proveedores.

Estado del archivo	Significado
waiting	Está registrado y espera una etapa del flujo.
processing	Se está extrayendo, transformando, leyendo o indexando.
available	Quedó disponible para consulta documental.
failed	Falló una etapa; el manifiesto indica si es reintentable.
skipped	No entra al análisis, por ejemplo por un formato no soportado o un límite de anidamiento de archivos.

Un fallo puede categorizarse como archivo comprimido, procesamiento o indexación. Esta clasificación sirve para decidir el siguiente paso sin exponer detalles internos de infraestructura.

Actualizar y reintentar con seguridad

• Actualizar es seguro en cualquier momento en que el manifiesto esté disponible: solo vuelve a consultar su estado y no lanza una nueva preparación.
• Reintentar requiere una preparación ya autorizada y un archivo persistido con retryable: true. Usa su file_ref; no se aplica a archivos disponibles, omitidos o que todavía están en curso.
• Si el flujo completo sigue activo, el sistema conserva ese flujo en vez de ejecutar un reintento competidor.
• Si la acción devuelve file_not_retryable, file_not_found, invalid_file_reference o una capacidad bloqueada, revisa el manifiesto o el estado de cuenta antes de repetirla.

Actualizar o reintentar no agrega un nuevo consumo. Una licitación preparada se descuenta una sola vez al completarse con los archivos descubiertos descargados, procesados e indexados para consulta documental. Si el estado luego es partial y ready_for_retrieval es verdadero, los documentos disponibles se pueden consultar, pero no se agrega ni revierte ese consumo. Si la preparación termina sin documentos utilizables, no se descuenta el cupo.

Disponibilidad de Mercado Público

LicitaIQ depende de que Mercado Público permita consultar metadata y obtener los archivos publicados. Un bloqueo de acceso, como una verificación de bot o CAPTCHA, puede impedir la preparación automática. LicitaIQ no promete eludir ni resolver CAPTCHAs; en ese caso el manifiesto y el estado muestran el fallo de forma segura y no se descuenta una preparación que no produjo documentos utilizables.

Consulta Resolución de problemas si Mercado Público bloquea una preparación o si un archivo sigue fallando.

Formatos considerados para análisis

LicitaIQ intenta preparar para consulta asistida los siguientes tipos de archivo, siempre que estén disponibles, sean legibles y el procesamiento se complete correctamente:

• Archivos comprimidos: .zip, .rar, .7z, .tar, .gz
• PDF: .pdf
• Office y OpenDocument: .doc, .docx, .xls, .xlsx, .ppt, .pptx, .odt, .ods, .odp
• Imágenes: .png, .jpg, .jpeg, .gif, .bmp, .tiff, .tif
• Texto y marcado: .txt, .md, .html, .htm

Un archivo listado no está garantizado para el análisis. Puede quedar omitido por formato, dañado, protegido, ilegible, antiguo o por límites de archivos comprimidos. Los archivos comprimidos multipart no están soportados.