Servidor MCP del Gestor de archivos
Conecta tu asistente al Gestor de archivos: buscar, leer por páginas, crear documentos, ordenar carpetas y crear enlaces públicos aprobados en el móvil.
Actualizado el . 56 min de lectura
Incluido en todos los planes. Ver precios
El servidor MCP del Gestor de archivos (utilia-files) conecta tu asistente de IA con los archivos y las carpetas de la empresa: encontrarlos, leerlos por páginas, mirar sus imágenes y sus hojas de cálculo, crear documentos, traerlos de internet, ordenarlos, vincularlos a una ficha y crear enlaces públicos que la persona aprueba en su móvil. Ve exactamente lo que la persona ve en la aplicación, ni un archivo más. Sustituye a las herramientas fm_* que estaban en el servidor del CRM: cómo pasar de unas a otras está en Si tu integración llamaba desde el CRM.
La guía de uso está en Usar el gestor de archivos.
| Dato | Valor |
|---|---|
| Dirección | https://os.utilia.ai/api/mcp/files |
| Nombre en «Conecta tu IA» | Gestor de archivos |
| Metadatos de descubrimiento | GET /.well-known/mcp-files.json |
| Scopes | files:*, los acompañantes de las fichas y los del plan, los avisos y el soporte |
Cómo se conecta
Desde Conecta tu IA, necesitas entrar con tu cuenta autorizas tu cliente MCP con OAuth o generas una clave de conexión para este servidor. En Claude Code:
claude mcp add --transport http utilia-files https://os.utilia.ai/api/mcp/filesEl token se emite para /api/mcp/files y solo sirve ahí: un token del CRM no entra por esta dirección, ni uno de archivos por la del CRM. El proceso completo, con el descubrimiento y la primera llamada, está en Primeros pasos con MCP.
Qué comprueba en cada operación
Qué comprueba el servidor de archivos
Tu organización
Gestor de archivos en el plan
Con una ficha, además el aplicativo de esa ficha.Si no: MODULE_NOT_ENABLED; ningún permiso lo abre.
El token
Scope de la operación
Una escritura nunca se ejecuta con un scope de lectura.Si no: INSUFFICIENT_SCOPE, con grantUrl para concederlo.
La capacidad
Archivos avanzados, si lo pide
Versiones, vínculos a fichas y enlaces públicos.Si no: CAPABILITY_NOT_ENABLED, o el bloque se omite.
Tu usuario
Permiso de la operación
El mismo que pide la pantalla equivalente.Si no: PERMISSION_DENIED con el permiso que falta.
El archivo
Está en el Gestor para ti
Carpetas que ves, lo tuyo en Inicio y lo vinculado a fichas que ves.Si no: FILE_NOT_FOUND, igual que si no existiera.
El último paso es el perímetro del servidor, y es el mismo para el listado y para cada operación por id. Un archivo está en el Gestor para la persona si está en una carpeta que ve (también por herencia o por su departamento), si es suyo y está en Inicio, o si está vinculado a una ficha que ve y la conexión lleva el acompañante de esa ficha.
Lo que solo se alcanza desde otro módulo queda fuera aunque la persona lo abra en la aplicación: los justificantes de gastos y de ausencias, los adjuntos de tickets y de mensajes directos y los documentos de RRHH. Responden FILE_NOT_FOUND, con una pista que dice dónde se leen. Los adjuntos de un ticket o de un elemento de trabajo se leen con el mismo lector desde su herramienta, con read_attachment: tickets (o my_tickets, si el ticket es tuyo, también desde este servidor), utilia_support para un ticket al soporte de UTILIA OS e issues, en utilia-work. Lo compartido en una conversación se lee con chat_conversations get_file, en utilia-chat, y el justificante de un gasto se descarga con expenses document_get, en utilia-finance. Lo que tiene bloqueado el acceso de la IA y las claves privadas responden también como si no existieran.
Herramientas
| Herramienta | Para qué sirve |
|---|---|
files | Encontrar, leer y mirar archivos: el listado con filtros, la ficha del archivo, el texto por páginas, buscar dentro, las páginas de un PDF, las hojas de cálculo, las versiones, «Eliminados recientemente», las etiquetas y los enlaces de un archivo. Solo lectura. |
files_manage | Subir, crear, traer de internet, descargar, renombrar, mover, copiar, editar, eliminar, recuperar, etiquetar, vincular a una ficha y crear o anular enlaces públicos. |
folders | El árbol de carpetas, lo que hay en una carpeta, encontrar una carpeta por su ruta y quién tiene acceso. Solo lectura. |
folders_manage | Crear carpetas y rutas, cambiarlas, moverlas, eliminarlas y dar o quitar acceso. |
search | Encontrar un archivo o una carpeta por su nombre o por lo que dice dentro, con el fragmento. |
users | El identificador de una persona, para darle acceso a una carpeta. |
org_plan, notifications, my_tickets y utilia_support | El plan, los avisos, los tickets propios y el soporte de UTILIA OS, como en los demás servidores. |
files y folders se anuncian como solo lectura, así que los clientes no piden permiso en cada consulta. La descarga temporal (download_url) está en files_manage a propósito: es una llave para bajar el archivo, y tu cliente pide confirmación antes de usarla. files_manage se ve con cualquiera de los cinco scopes, y descargar pide uno de los tres de archivos (files:items:view, files:items:manage o files:items:delete).
Scopes
Son cinco, separados por lo que hacen. La columna central es el texto que ve la persona en la pantalla de consentimiento.
| Scope | Lo que consiente la persona | Segundo paso al concederlo |
|---|---|---|
files:items:view | Ver los archivos y carpetas del Gestor de archivos y su contenido | No |
files:items:manage | Subir, crear, traer de internet, editar, mover, copiar y organizar archivos y carpetas, vincularlos a fichas y crear enlaces para que alguien suba archivos | No |
files:items:delete | Eliminar archivos y carpetas, también para siempre | Sí |
files:folders:share | Dar y quitar a personas y departamentos el acceso a carpetas | Sí |
files:links:share | Crear enlaces públicos a archivos, que abre cualquiera sin iniciar sesión; cada uno se aprueba en tu móvil | Sí |
- Ninguno entra en un conjunto (
crm:full,dev:full,admin:full...): se piden por su nombre. files:links:shareno va nunca en una clave de conexión ni en los conectores de los directorios de Claude y ChatGPT: solo en una autorización por navegador.- Quién puede concederlos.
files:items:managelo concede quien tenga cualquiera de estos permisos: «Subir archivos», «Crear carpetas», «Editar carpetas», «Gestionar etiquetas», «Restaurar versiones» o «Vincular CRM».files:items:delete, «Eliminar carpetas» o «Gestionar lo que eliminan otros». Concederlo no abre nada más: cada operación sigue pidiendo su propio permiso. - Operaciones que piden dos scopes. Editar sin conservar la versión anterior, quitar la última carpeta o el último vínculo de un archivo y eliminar una versión piden además
files:items:delete, porque el archivo o la versión se pierden.
Acompañantes de las fichas
Para filtrar por una ficha, guardar en su carpeta o vincular un archivo a ella, la conexión de archivos lleva además el scope que ya pide esa ficha en su propio servidor. Viajan por /api/mcp/files como acompañantes, por una lista cerrada, y solo sirven para eso: no abren ninguna otra herramienta del otro dominio.
Ficha (entity.type) | Para ver | Para escribir |
|---|---|---|
client, contact, lead, project, opportunity, budget, interaction | crm:files:view | crm:files:upload |
supplier | finance:suppliers:view | finance:suppliers:update |
supplier_contact | finance:supplier-contacts:view | finance:supplier-contacts:manage |
dev_project (cuenta o proyecto de trabajo) | dev:projects:view | dev:projects:update |
dev_issue (elemento de trabajo) | dev:issues:view | dev:issues:update |
Sin el acompañante, la llamada responde INSUFFICIENT_SCOPE con requiredScopes y, en una conexión OAuth, grantUrl, el enlace para que la persona lo conceda sin volver a conectar.
files: encontrar, leer y mirar
| Operación | Qué hace | Permiso | Capacidad |
|---|---|---|---|
search | El listado con filtros. | Ver archivos; con entity, además ver la ficha | Los vínculos de una ficha, Archivos avanzados |
get | La ficha técnica del archivo (tamaño, páginas, resolución, duración y códecs), de uno o de varios (ids, hasta 20). | Ver archivos | Las versiones y los vínculos, Archivos avanzados |
read | El texto por páginas; una imagen, para verla. | Ver archivos; con version, además «Ver versiones» | Con version, Archivos avanzados |
find | Dónde sale una palabra o una frase dentro del archivo. | Igual que read | Igual que read |
view | Páginas de un PDF como imagen. | Ver archivos | — |
table | Hojas de cálculo XLSX, CSV, XLS y ODS. | Ver archivos | — |
versions | Las versiones, con quién y cuándo. | «Ver versiones» | Archivos avanzados |
compare | Lo que cambió entre dos versiones. | «Ver versiones» | Archivos avanzados |
trash | «Eliminados recientemente», con sus propios filtros. | Ver archivos; lo de otras personas, «Gestionar lo que eliminan otros» | — |
tags | Las etiquetas que ve la persona. | Ver archivos | — |
share_links | Los enlaces públicos de un archivo, sin la dirección. | «Compartir con un enlace» | — |
favorites | Los favoritos de la persona, archivos y carpetas, en el orden de su barra lateral, con su ruta. | Ver archivos | — |
Todas aceptan cualquiera de los cinco scopes, y todas pasan por el perímetro.
Encontrar un archivo
Dos herramientas, para dos preguntas distintas:
files search o search
El listado con filtros
files search
Encontrar
search
files search admite query (hasta 200 caracteres; casa también con el nombre que tiene el archivo en cada carpeta que la persona ve), folderId o path con includeSubfolders (por defecto true), entity con includeRelated, kinds (image, pdf, document, spreadsheet, presentation, video, audio, archive y other), extensions, mimeTypes (exactos, como image/png), owner (me u others: no se filtra por una persona concreta), tags (hasta 10, por nombre o id), from y to (fechas incluidas) con dateField (modified o uploaded), largerThan y smallerThan en bytes, orphan (los sueltos de Inicio, sin carpeta ni ficha), sort y order. Devuelve 20 por página, 50 como mucho.
{
"name": "files",
"arguments": {
"operation": "search",
"query": "contrato marco",
"path": "Clientes/Acme",
"kinds": ["pdf", "document"],
"from": "2026-01-01"
}
}{
"items": [
{ "id": "cmf1a2b3c", "name": "Contrato marco Acme.pdf", "kind": "pdf", "size": 2483011, "modifiedAt": "2026-10-20T16:40:00Z", "path": "Clientes/Acme/Contratos", "matchedBy": "name" }
],
"pageInfo": { "nextCursor": "eyJvIjoyMH0", "hasMore": true, "pageSize": 20, "responseFormat": "concise" },
"totalAtLeast": 21
}matchedBydice si casó por el nombre del archivo (name) o solo por el de una carpeta (folder, con la carpeta enmatchedFoldery el avisoMATCHED_BY_FOLDER); los que casan por el nombre van primero.pathes la primera ubicación visible, onull.totalsolo llega cuando es exacto; si no,totalAtLeast. Una página solo llega vacía connextCursorsi se agotó la exploración sin nada que la persona pueda ver, y entonces lo dice el avisoSCAN_LIMIT: sigue con el cursor o afina la búsqueda. Fuera de ese caso,hasMoresolo es cierto si queda algo: la página siguiente nunca llega vacía.- Con
response_format: "detailed", cada fila añade el tipo, quién lo subió, la versión, las etiquetas y, si ya se conocen,totalPagesyranges.
Con entity, la búsqueda trae lo vinculado a esa ficha y lo que la ficha tiene como propio (el logotipo, la foto, el PDF del presupuesto, los adjuntos de la interacción, los documentos del proyecto); cada fila dice de dónde sale en source. Los vínculos necesitan Archivos avanzados: sin la capacidad llega solo lo propio, con el aviso OMITTED_BY_PLAN. includeRelated suma las fichas relacionadas (los contactos, proyectos, oportunidades, presupuestos e interacciones de un cliente; los presupuestos e interacciones de una oportunidad; los elementos de una cuenta de trabajo...), cada una con su permiso y su acompañante. La que no los tiene, no entra, sin error.
La ficha del archivo
get es la ficha técnica: los datos comunes (nombre, tipo, tamaño, quién lo subió y cuándo, ubicaciones visibles), dónde se usa, si el cliente lo ve en su portal, las etiquetas, si está en los favoritos de la persona (favorite), los enlaces activos, cómo se lee y los datos de su tipo: dimensiones, resolución y espacio de color de una imagen; duración, resolución y códecs de un vídeo o un audio; páginas, tamaño de página y si está cifrado un PDF; palabras, caracteres y tablas de un Word; diapositivas de una presentación, y hojas con sus filas y columnas de un libro. Esta es una respuesta real:
{
"file": {
"id": "cmw8gxq6o008ph1yvhhtwz7xl",
"name": "contrato-marco-acme.pdf",
"extension": "pdf",
"kind": "pdf",
"mimeType": "application/pdf",
"size": 66994,
"sizeLabel": "65,4 KB",
"uploadedBy": { "id": "cmvnvgh1r005sufyvletsr4kn", "name": "Prueba Alta" },
"uploadedAt": "2026-11-08T23:33:41.712Z",
"modifiedAt": "2026-11-08T23:34:03.109Z",
"paths": ["Pruebas MCP archivos/Contratos"],
"versionsCount": 0,
"portalVisible": false,
"activeShareLinks": 0,
"reading": { "method": "text", "totalPages": 40, "totalChars": 88944, "scanned": false, "ranges": ["1-12", "13-24", "25-36", "37-40"] },
"pdf": { "pages": 40, "encrypted": false }
},
"openInApp": "https://os.utilia.ai/dashboard/file-manager/files/cmw8gxq6o008ph1yvhhtwz7xl",
"nextSteps": [
{ "tool": "files", "operation": "read", "why": "Para resumirlo, lee todas sus partes a la vez, una llamada por rango.", "args": "id: 'cmw8gxq6o008ph1yvhhtwz7xl' y pages: \"1-12\", \"13-24\", \"25-36\", \"37-40\", una llamada por rango" },
{ "tool": "files", "operation": "find", "why": "Para una pregunta concreta, busca dentro y lee solo las páginas donde sale.", "args": "id: 'cmw8gxq6o008ph1yvhhtwz7xl', query y, si quieres, terms con sinónimos" }
]
}- Cada bloque sale solo con su permiso: dónde se usa (
usedIn), con el de cada ficha y su acompañante; lo de Finanzas, solo como señal (usedIn.finance, sin datos) con el paso autilia-finance;portalVisible, con el de ver al cliente;activeShareLinks, con «Compartir con un enlace», comoshare_links; las versiones (versionsCount), con «Ver versiones». Un archivo sin cambios tieneversionsCount: 0. - Sin Archivos avanzados, las versiones y los vínculos se omiten y la respuesta lo dice en
omittedByPlan, con el plan que los incluye yupgradeUrl. locations([{ path, name }]) llega cuando el archivo se llama distinto en alguna de sus carpetas.- Hojas de cálculo:
office.sheetListda cada hoja conname,rows,columnsyhiddensi está oculta.rowscuenta filas de datos, sin la de títulos, igual que elrowCountdetable, yheaderRow: truedice que la hay; lo mismotext.rowsde un CSV. Solo las 20 primeras hojas de un libro traen filas y columnas; las demás, su nombre. - Word y OpenDocument:
office.wordsyoffice.characters(con espacios) se cuentan aunque el documento no los guarde, sin lo borrado con control de cambios, los códigos de campo ni los comentarios.office.tablessale siempre, también con 0.office.pagessolo llega si el propio documento la guarda. - Lo que no se puede leer desde aquí lo dice
reading:method: "none", el motivo enreasony qué hacer ennote. Un documento o un libro de más de 20 MB da sus cifras y sus hojas conreason: "too_large"; una imagen que el servidor no sabe abrir (un BMP o un PSD),reason: "unsupported", y sunotepropone que la persona la abra en la aplicación o descargarla. Una foto HEIC o HEIF del iPhone se puede ver (method: "image") siempre que el servidor pueda convertirla en ese momento; si no, sale conreason: "unsupported"y la ficha se vuelve a calcular en unos minutos. - Un escaneado lleva
reading.scanned: true; en un PDF con páginas escaneadas y páginas con texto,reading.scannedPagesdice cuáles gastan el cupo de OCR («12-40»). Si sus páginas ya se han leído enteras hace poco, volver a leerlas no gasta cupo y la ficha lo dice conalreadyRead: truey sutotalChars; sigue diciendoscanned: true, porque el documento sigue siendo un escaneado. - Con
ids, la ficha técnica se calcula para el primero y para los que ya la tenían; los demás llevantechnicalPending: truey el avisoTECHNICAL_INFO_DEFERREDdice cuáles: pídeles suget. antivirusllega en la ficha solo cuando hay algo que saber, igual que enversions:infected(en cuarentena: no se lee, ni se descarga, ni se restaura),pending(se está analizando: su ficha sale sin lectura, conreading: { method: "none" }, y leerlo o descargarlo respondeFILE_SCAN_PENDING) ounverified(el antivirus no ha podido analizarlo y lo volverá a intentar: se lee y se descarga, pero no sale de la empresa por un enlace público, el portal del cliente ni el correo de un presupuesto hasta que se analice).openInAppes la ficha del archivo en la aplicación y va junto afile, no dentro. Llega enget, en lo recién guardado (create,import_url,confirm_upload,move,copyyadd_to_folder) y en los errores cuyo siguiente paso es de la persona. Enfolders getes la carpeta en la aplicación.
Leer un documento largo
La primera lectura da el mapa del documento y el resto se pide a la vez:
Leer un PDF largo en paralelo
Participan: Tu asistente, utilia-files.
De Tu asistente a utilia-files:
files get · id
Antes de leer, la ficha.De utilia-files a Tu asistente:
reading: totalPages y ranges (respuesta)
Tramos que caben en una lectura cada uno.De Tu asistente a utilia-files:
files read · pages 1-14, 15-28 y 29-42
Tres llamadas a la vez, una por tramo.De utilia-files a Tu asistente:
Dos bloques por lectura (respuesta)
Los datos de la lectura y el texto, entre sus marcas y con «— Página N —».
read admite pages ("3", "3-7" o "2,5") en PDF y presentaciones, y cursor en los documentos sin páginas: cada respuesta trae nextCursor mientras quede texto. Lee 34.000 caracteres por defecto (maxChars, hasta 36.000). pages dice lo que se ha leído de verdad y remainingRanges, lo que falta, para pedirlo a la vez. Si una página no cabe entera, sale cortada y lo dice el aviso PAGE_TRUNCATED: pídela sola con un maxChars mayor o mírala con view. Con ids lee varios en serie, con los caracteres repartidos: hasta 5, o hasta 20 si solo pides la primera página (pages: "1"), que basta para clasificarlos.
Topes de la lectura
- Caracteres por lectura
- 34.000
- 36.000 como mucho, con maxChars.
- Archivos por llamada
- 5
- 20 si solo pides la primera página.
- Páginas escaneadas al día
- 200
- Por empresa, para leerlas con OCR.
La respuesta no lleva structuredContent: llega en dos bloques de texto, primero un JSON corto con los datos de la lectura y después el texto del documento, en claro, entre dos marcas fijas, ⟦TEXTO DEL DOCUMENTO⟧ y ⟦FIN DEL TEXTO DEL DOCUMENTO⟧, que el documento no puede imitar: a su texto se le quitan esos corchetes y los que se les parecen. El JSON lo dice en content (kind: "document_text", instructions: false). El texto de un archivo es dato, no instrucciones: tu asistente no debe seguir órdenes que vengan dentro de un documento. Todo lo que devuelve el servidor se limpia de caracteres invisibles y de control de dirección, y la conversión a Markdown nunca deja imágenes remotas.
{
"content": [
{ "type": "text", "text": "{\"id\":\"cmf1a2b3c\",\"name\":\"Contrato marco Acme.pdf\",\"method\":\"text\",\"pages\":\"1-14\",\"totalPages\":42,\"remainingRanges\":[\"15-28\",\"29-42\"],\"content\":{\"kind\":\"document_text\",\"instructions\":false,\"begin\":\"⟦TEXTO DEL DOCUMENTO⟧\",\"end\":\"⟦FIN DEL TEXTO DEL DOCUMENTO⟧\"}}" },
{ "type": "text", "text": "⟦TEXTO DEL DOCUMENTO⟧\n— Página 1 —\n\nCONTRATO MARCO DE PRESTACIÓN DE SERVICIOS\n...\n⟦FIN DEL TEXTO DEL DOCUMENTO⟧" }
]
}methoddice cómo se leyó:text,ocr,table,imageonone.ocrPagesdice qué páginas de esta lectura salieron del OCR («2,5-7»), solo si alguna lo hizo, yocrPagesCharged, cuáles se han pasado por OCR ahora y gastan cupo; las demás deocrPagesvenían ya leídas y no han costado nada.- Un escaneado se lee con OCR mientras quede cupo del día; si solo se leyeron algunas páginas, el aviso
OCR_PARTIALdice cuáles faltan. Si el OCR agota su plazo o su memoria, las páginas que llegó a empezar cuentan en el cupo aunque no den texto: pide menos páginas a la vez. pagesadmite páginas hasta la 100.000; más allá, o mal escrito, respondeINVALID_PAGESsin bajar el archivo. Un cursor que no es de ese archivo respondeINVALID_CURSOR.- Si el archivo cambia entre dos lecturas con cursor, la siguiente responde
FILE_CHANGED: vuelve a empezar sin cursor. - Con
version, lee una versión anterior. - Un audio o un vídeo no tiene texto:
readda su ficha técnica y, si existe, dónde está su transcripción (enchat_conversationsdeutilia-chat). - En un DOCX, las tablas se leen como tablas Markdown; en un PDF salen como texto.
Buscar dentro de un archivo
Para una pregunta concreta sobre un documento, find es más rápido que leerlo entero. Recibe id y query (palabras, o una "frase exacta", sin tildes), y si quieres terms con sinónimos, y devuelve dónde sale, con su página y la frase en que aparece:
{
"id": "cmf1a2b3c",
"name": "Contrato marco Acme.pdf",
"totalMatches": 12,
"shownMatches": 10,
"matchedPages": "1-6",
"matches": [
{ "page": 1, "offset": 1420, "context": "…la duración del contrato será de doce meses, prorrogables…" }
],
"complete": true,
"_notices": {
"items": [
{ "code": "MORE_MATCHES", "message": "Hay 12 coincidencias y aquí van 10. Las páginas donde salen todas están en matchedPages: léelas con read o sube maxMatches (hasta 30).", "totalMatches": 12, "shownMatches": 10 }
]
}
}matchedPagestrae todas las páginas con alguna coincidencia, también las de las que no se enseñan. Para responder «¿en qué páginas sale?», usamatchedPages, no las páginas dematches.shownMatchesy el avisoMORE_MATCHESsolo llegan si hay más coincidencias de las que se enseñan: 10 por defecto y 30 como mucho (maxMatches).complete: truequiere decir que se ha buscado en todo el documento.- Cada
contextes la frase de la coincidencia; dos coincidencias seguidas de la misma página no repiten texto. - Busca en el mismo texto que lee
read, ynextStepspropone leer enteras las páginas dematchedPages.
Ver imágenes y páginas
- Una imagen se ve con
read: devuelve un bloqueimagecon la variante de 1.440 px (variant: "md", por defecto), la miniatura (thumb) o el original si pesa menos de 1,5 MB, y un JSON con lo que se devuelve (preview: anchura, altura, formato y variante) y las medidas de la imagen real (original). - Una foto HEIC o HEIF del iPhone se ve igual, con su variante
mdothumb, en WebP, derecha y sin los datos de la cámara ni la ubicación: el servidor la convierte. Su original no se entrega por aquí (variant: "original"respondeNOT_READABLE); para el archivo tal cual,files_managedownload_url. Si el servidor está ocupado convirtiendo otra, respondeEXTRACTOR_BUSYconretryAfterSeconds. - Las páginas de un PDF, como planos o escaneados, se ven con
view: hasta 5 por llamada enthumbnailomedium(por defecto) y 2 enhigh.
Hojas de cálculo
table lee XLSX, CSV (con el separador y la codificación que tenga), XLS y ODS. Sin mode, da en una sola llamada las hojas, las columnas con su tipo (number, date, text o boolean), las 20 primeras filas y el recuento.
mode | Qué devuelve |
|---|---|
sheets | Las hojas con sus dimensiones. |
rows | Filas, con columns, filters (todas se cumplen), sortBy y order, offset y limit (100 por defecto, 500 como mucho). |
aggregate | Agrupado por groupBy (hasta 5: una columna, o { "column": "Fecha", "by": "month" } para agrupar fechas por day, month, quarter o year), con metrics: sum, avg, min, max, count (sin column, cuenta filas) y count_distinct. Admite limit y offset. |
stats | Por cada columna numérica, el mínimo, el máximo, la media, la suma y las vacías. |
Los filtros admiten eq, ne, contains, not_contains, starts_with, ends_with, gt, gte, lt, lte, between (con [mínimo, máximo]), empty y not_empty. Un filtro con un valor que no es del tipo de su columna (un texto contra una cifra o una fecha) no casa con nada y lo dice el aviso FILTER_VALUE_INVALID. La hoja se pide por su nombre o por su posición desde 0 (sheet). Las columnas se nombran sin importar tildes ni mayúsculas (una que no existe responde COLUMN_NOT_FOUND con missing y las que hay), y los números con formato español (coma decimal y punto de miles) llegan como números. Todas las salidas llevan arriba el id y el name del archivo. Las filas viajan en formato compacto, con la cabecera una sola vez, y shownRows y hasMore dicen cuántas van y si quedan:
{ "columns": ["Fecha", "Cliente", "Importe"], "rows": [["2026-10-01", "Acme", 1250.5]], "rowCount": 412, "shownRows": 1, "hasMore": true }Una hoja XLS u ODS muy grande puede llegar cortada: truncated: true (solo entonces) y el aviso TABLE_TRUNCATED. Sobre ella, aggregate y stats se niegan, porque darían cifras falsas. De cualquier hoja se leen como mucho 200 columnas, con nombres de hasta 100 letras. Cada respuesta tiene un tope de 36.000 caracteres: si no caben las filas pedidas, salen las que caben, con hasMore: true y el aviso TABLE_CHARS_LIMIT.
Versiones, Eliminados recientemente, etiquetas y enlaces
versionslista los contenidos que ha tenido el archivo, con quién, cuándo, la nota del cambio que produjo cada uno y el tamaño (20 por página, hasta 50, conpageInfoytotal). Es el mismo historial que ve la persona en la aplicación. Lo vivo puede salir como entrada propia (version: "current"),currentmarca dónde están los bytes vivos,originalel contenido con que se subió (solo la versión 1, o lo vivo si nunca cambió), con la fecha de alta y quién lo subió; si ese contenido se sustituyó antes sin guardar historial, ya no llevaoriginalni fecha, persona o nota, porque no se sabe quién lo cambió;sameAsotra versión con los mismos bytes ysameAsCurrentuna que guarda lo mismo que lo vivo (restaurarla no cambiaría nada).antivirussolo llega cuando hay algo que saber, con los mismos tres valores que enget:infected, en cuarentena (no se lee, ni se descarga, ni se restaura);pending, se está analizando (leerla o descargarla respondeFILE_SCAN_PENDING), ounverified, el antivirus no ha podido analizarla y lo volverá a intentar (se lee y se descarga). Si se borró la versión anterior a una, esa va sin nota, fecha ni persona: no se sabe qué cambio la produjo y no se inventa. Un archivo sin versiones guardadas respondeitems: [],total: 0ynote: «Este archivo no tiene versiones anteriores: solo su contenido actual.».compareda las líneas añadidas y quitadas, con su página, entreversionytoVersion(por defecto, lo vivo,to: "current"); sinversion, compara lo vivo con la versión más reciente que es distinta. Hasta 200 líneas. Si no hay diferencias, responde{ id, name, from, to, identical: true }. Las dos piden Archivos avanzados. La guía de uso del historial está en Historial de versiones.trashrecorre «Eliminados recientemente», de lo más reciente a lo más antiguo: lo de la persona siempre y lo de otras con «Gestionar lo que eliminan otros», dentro de su alcance. Filtra porquery(el nombre),kind(fileofolder),fromyto(cuándo se eliminó) yowner(quién lo eliminó:meuothers); los filtros desearchydateFieldno valen aquí y respondenVALIDATION. Cada fila dice cuándo se eliminó y quién, cuántos días le quedan y de dónde salió, con la ruta entera. ConhasMore, la página siguiente trae algo seguro.tagsda las etiquetas que la persona ve, las suyas y las de toda la empresa, con cuántos archivos llevan de los que ella ve (files).favoritesda los favoritos de la persona, archivos y carpetas, en el orden de su barra lateral: los que sigue viendo en el Gestor. Cada uno traekind(fileofolder),id,nameypath, la ruta visible de la carpeta o de la carpeta donde está el archivo (nullsi está en Inicio o solo en una ficha); un archivo, además,mimeTypeysize. Admitekindpara pedir solo archivos o solo carpetas (otro valor respondeVALIDATION), ylimit(20 por defecto, 50 como mucho) concursor. Recorre hasta 500 favoritos: con más,truncated: trueytotales un mínimo. Si un archivo está en favoritos lo dice tambiénfavoriteenget.share_linksda los enlaces públicos de un archivo, activos y terminados en los últimos 30 días, sin la dirección: solo se entrega al crearlo. Arriba, elidy elnamedel archivo. Si no se puede crear uno,createBlockedReasondice por qué y, si es del plan, cuál lo incluye yupgradeUrl.
files_manage: guardar y cambiar
| Operaciones | Qué hacen | Scope | Permiso |
|---|---|---|---|
request_upload, confirm_upload, abort_upload | Subir desde el disco en dos pasos. | files:items:manage | «Subir archivos» |
create_upload_link | Un enlace para que la persona suba desde su navegador. | files:items:manage | «Subir archivos» y editar la carpeta |
create, import_url | Un archivo nuevo desde texto o desde internet. | files:items:manage | «Subir archivos» |
download_url | Una descarga temporal. | files:items:view, files:items:manage o files:items:delete | Ver archivos |
rename, move | Cambiar el nombre y mover. | files:items:manage | «Editar carpetas» |
copy, add_to_folder, remove_from_folder | «Hacer una copia», «Añadir también a…» y «Quitar de esta carpeta». | files:items:manage | «Subir archivos» |
edit, patch | «Editar contenido»: el texto entero o un fragmento. | files:items:manage | «Editar carpetas» |
restore_version, delete_version | Volver a una versión o eliminarla. | files:items:manage; eliminarla, files:items:delete | «Restaurar versiones» |
delete, restore, purge | Eliminar, recuperar y «Eliminar definitivamente». | files:items:delete; recuperar, files:items:manage o files:items:delete | «Eliminar carpetas»; recuperar, ver archivos |
tag, untag, tag_update, tag_delete | Etiquetas. | files:items:manage | «Gestionar etiquetas» |
link, unlink | Vincular a una ficha o quitar el vínculo. | files:items:manage y el acompañante | «Vincular CRM» y editar la ficha |
share_link_create, share_link_revoke | Crear un enlace público o «Anular el enlace». | files:links:share | «Compartir con un enlace» |
favorite, unfavorite | Marcar o quitar favoritos, archivos y carpetas, por id o ids (el servidor sabe si cada uno es un archivo o una carpeta) o con items: [{ kind, id }]. Cada fila dice outcome: added, already, removed o not_favorite; marcar lo que ya lo está, o quitar lo que no, no es un fallo. | files:items:manage | Ver archivos |
Los lotes admiten hasta 50 elementos (ids o items) y 20 en las subidas. Todos responden igual: un resultado por elemento, en el orden en que los pediste, y el resumen, así que un fallo no tumba el resto:
{
"results": [
{ "index": 0, "id": "cmf1a2b3c", "ok": true, "outcome": "trashed" },
{ "index": 1, "id": "cmf9z8y7x", "ok": false, "errorCode": "FILE_NOT_FOUND", "message": "No hay ningún archivo con ese id en el Gestor de archivos a tu alcance.", "hint": "Comprueba el id con files search." }
],
"summary": { "total": 2, "ok": 1, "failed": 1 },
"_notices": {
"items": [
{ "code": "NOT_FOUND_ELSEWHERE", "message": "Si es un adjunto de un ticket, léelo con read_attachment de tickets (utilia-crm o utilia-work) o, si el ticket es tuyo, de my_tickets; …", "ids": ["cmf9z8y7x"] }
]
}
}indexes la posición del elemento en tu petición; un id repetido cuenta una vez.idsolo llega si el elemento existe: un documento o una carpeta que no se ha podido crear no tieneid, y lo reconoces por suindexy suname.- Una fila que falla trae siempre
errorCode,messageyhint, y su pista dice «repite solo este elemento»: reintenta solo esas filas, nunca el lote entero. - Los avisos de una fila (un
renameque conservó la extensión, por ejemplo) llegan en_notices.items, con elindexy elidde su fila. - La pista de «no encontrado»: cada fila
FILE_NOT_FOUNDdice «Comprueba el id con files search.». En los lotes de lectura (getyread), dónde se lee lo que no es del Gestor llega una sola vez en el avisoNOT_FOUND_ELSEWHERE, con susids. createdFolders(idypath) llega arriba siempre queensurePathha creado carpetas: enrequest_upload,create,import_url,move,copyyadd_to_folder.
La forma de los lotes cambió el 9 de noviembre
Las filas ya no traen success ni fileId, y las respuestas ya no traen succeeded, failedItems ni operation. Lee ok e id en cada fila, y summary arriba. El detalle está en Cambios de las integraciones.
request_upload, create, import_url, copy y folders_manage create admiten idempotencyKey: la misma clave con los mismos datos devuelve el resultado de la primera vez, y con otros datos responde IDEMPOTENCY_KEY_REUSED. Repetir con confirm: true y la misma clave es la misma alta, y una respuesta que no ha escrito nada (pedir confirmación, un argumento que no vale) no gasta la clave. Para reintentar solo las filas que fallaron de un lote, usa una clave nueva.
Dónde va un archivo
Las operaciones que guardan (create, import_url, request_upload y move) reciben el destino de una de tres formas. Con la persona se habla con rutas; con la herramienta, con identificadores:
¿Cómo le dices dónde va?
¿Va a la carpeta de una ficha, como un cliente o un presupuesto?
Sí:
entity
{ type, id }
La carpeta de esa ficha, creada si falta; además, el archivo queda vinculado a ella.No:
¿Te ha dado la persona una ruta?
Sí:
path
Clientes/Acme
Con ensurePath crea lo que falte de la ruta.No:
folderId
El identificador de la carpeta, o null en move para Inicio.
- Las rutas van por tramos con «/» (
Clientes/Acme/Contratos); al entrar se acepta también « › ». Las respuestas las dan siempre con «/». ensurePathadmiteallowSimilar: true, en la llamada o dentro de cadato(files[].to,documents[].toymoves[].to), para crear la ruta pedida aunque haya una carpeta casi igual.ensurePathcrea lo que falte de la ruta solo si la persona tiene el permiso «Crear carpetas» y, dentro de otra carpeta, el nivel «Gestionar» en ella; si no, respondePERMISSION_DENIEDsin crear nada. Cada tramo se valida como un nombre de carpeta en la aplicación: sin caracteres de control ni invisibles, sin: * ? " < > | #y sin punto al final. Donde la operación admiteensurePath, la pista dePATH_NOT_FOUNDdice que repitas conensurePath: truesi la persona quiere crear la ruta.entityes{ type, id }o{ type, name }. Con un nombre que casa con varias fichas respondeENTITY_AMBIGUOUScon las candidatas, para que preguntes cuál.- Con
entityypath, la ruta va dentro de la carpeta de la ficha. Los clientes, los contactos, los proyectos comerciales, los presupuestos y las interacciones tienen carpeta propia; en las demás fichas el archivo queda vinculado sin carpeta, con el avisoENTITY_HAS_NO_FOLDER. - Guardar con
entitypide Archivos avanzados, «Vincular CRM», poder editar la ficha y el acompañante de escritura. - Si el destino lo ve más gente que el origen (también por el departamento dueño de la carpeta o por la ficha de una carpeta anclada), alguien con un rol externo o el cliente en su portal, la operación pide
confirm: true, y sin él dice quién lo vería («Lo verán además 12 personas del departamento Ventas y el cliente en su portal»).
Subir desde el disco
La subida es en dos pasos y el archivo nunca viaja dentro de la llamada:
-
request_uploadconfiles(hasta 20), cada uno confilenameyfileSize, el tamaño exacto en bytes, y opcionalmentemimeType,to(cada archivo a su sitio, también una ruta; conensurePathcrea las carpetas que falten) yversionOf. Cada archivo puede pesar hasta 2 GB. Devuelve una fila por archivo con suid(el de la reserva, que se pasa a los pasos siguientes),uploadUrl,relayUploadUrly las cabeceras, válidos 15 minutos. SiensurePathha creado carpetas, la respuesta las trae encreatedFolders(idypath) con el avisoFOLDERS_CREATED. -
Un
PUTde cada archivo a suuploadUrl, con suContent-Type. Si falla por la red, el mismoPUTarelayUploadUrl. -
confirm_uploadconids, o confiles: [{ id, sha256 }]para comprobar además la huella (fileIdsigue valiendo en lugar deid; si mandas los dos y no coinciden, respondeVALIDATION). Verifica el tamaño y el tipo real y deja el archivo en su carpeta; si no cuadra, lo descarta. Cada fila trae el nombre, el tipo, el tamaño yopenInApp(yplaced: false,linkedToolinkErrorsegún el caso); arriba, el resumen y el siguiente paso. Si era una versión nueva,ides el archivo,uploadIdla reserva,versionel número que ha quedado, y el tamaño y el tipo son los de lo que acabas de subir. Una subida que ya se está confirmando respondeUPLOAD_IN_PROGRESS. Una fila conok: truequiere decir que el archivo está guardado y terminado: es la que te deja borrar tu copia. Si la confirmación no lo deja terminado, o no se puede comprobar, la fila respondeok: falseconUPLOAD_NOT_FINISHED: no borres tu copia y confirma eseidotra vez pasados unos segundos, sin volver a hacer elPUT. Una fila conok: falseySTORAGE_UNAVAILABLE(«El archivo todavía se está guardando») quiere decir que el archivo ya llegó y su reserva sigue: repiteconfirm_uploadcon eseidpasados unos segundos, sin volver a hacer elPUTni reservarlo otra vez.Lo que se acaba de subir pasa por el antivirus, que suele tardar unos segundos. Mientras tanto la fila lleva
antivirus: "pending"y la respuesta trae el avisoSCAN_PENDINGcon susidsyretryAfterSeconds: hasta que termine, ese archivo no se puede leer, descargar ni compartir. Espera ese tiempo antes de usarlo y, si tras tres intentos sigue igual, no insistas: díselo a la persona. El análisis sigue solo y no hace falta volver a subir el archivo.
Mientras no se confirma, la reserva ya está en su carpeta como subida sin terminar: solo la ve quien la subió, la aplicación la enseña atenuada con «Continuar» y «Descartar», y files get, files search y folders list la marcan con uploadPending: true. No tiene contenido: leerla o descargarla responde FILE_UPLOAD_PENDING. Cada reserva sin confirmar ocupa uno de 20 huecos durante 24 horas: abort_upload los libera, y un id que no es una reserva tuya pendiente responde UPLOAD_NOT_FOUND en su fila. Si las carpetas a las que iba la subida se quedan vacías, también las de encima que se crearon para ella, la respuesta las nombra en emptyFolders con el aviso FOLDERS_LEFT_EMPTY, para que las elimines si se crearon solo para la subida. Si no quedan huecos, las filas que no se llegaron a reservar responden TOO_MANY_UPLOAD_RESERVATIONS. Con versionOf, lo subido es una versión nueva de ese archivo: pide Archivos avanzados, «Restaurar versiones» con un alcance que llegue a quien subió el archivo y poder editarlo, lo mismo que restaurar; si no, PERMISSION_DENIED antes de reservar nada. Si tu entorno no puede hacer peticiones, como ChatGPT en la web, create_upload_link con folderId o path da un enlace de 24 horas para que la persona suba desde su navegador. Las dos salidas y sus errores están en Subir un archivo cuando el PUT no llega. Para subir a la ficha que pide un fileId en otro servidor (un gasto, una factura, un elemento de trabajo), está file_uploads de ese servidor.
Crear un documento
create guarda un archivo nuevo desde texto: name con su extensión y content, hasta 2 MB; o varios a la vez con documents: [{ name, content, to? }] (hasta 10). Los .md, .txt, .csv, .json, .html, .xml, .yaml y los de código se guardan tal cual. En .docx y .pdf, content es Markdown y UTILIA OS genera el documento. Lo que vaya a leer una persona, mejor en .docx; en .md, solo si lo pide.
{
"name": "files_manage",
"arguments": {
"operation": "create",
"name": "Resumen de la reunión con Acme.docx",
"path": "Clientes/Acme/Reuniones",
"content": "# Reunión con Acme\n\n## Acuerdos\n\n- Entrega el 15 de diciembre.\n- Revisión quincenal.",
"idempotencyKey": "resumen-acme-2026-11-08"
}
}Devuelve el archivo con su ruta, openInApp y el siguiente paso. En .docx y .pdf, content admite hasta 300.000 caracteres; el autor del .docx es la empresa. Crear un .pdf o un .docx y traer de internet van de uno en uno por persona (y tres a la vez por empresa): con otro en curso responde FILES_MANAGE_BUSY, con retryAfterSeconds. Lo creado pasa por las mismas comprobaciones que una subida (antivirus, almacenamiento, tipos de riesgo), queda marcado como creado por un asistente de IA, así que tu asistente puede leerlo después, y no suma puntos de gamificación.
Traer de internet
import_url guarda en el Gestor un archivo de una dirección https pública, hasta 25 MB, con name opcional. El tipo se decide por el contenido, no por la extensión ni por la cabecera. Una dirección que no es https, con credenciales o con un puerto que no es el 443, o un tipo de riesgo, responde IMPORT_URL_BLOCKED; una que no responde, pasa de 25 MB o lleva a una red interna, IMPORT_URL_UNREACHABLE. Con versionOf, lo traído es una versión nueva de ese archivo, con las mismas puertas que restaurar comprobadas antes de descargarlo. El asistente de la aplicación no trae archivos de internet.
Ordenar
rename:idyname(o varios conrenames: [{ id, name }], hasta 50), como «Renombrar» en la web: dentro de una carpeta cambia el nombre que tiene ahí y, fuera de carpetas, el del archivo. Si está en varias carpetas,fromFolderIddice en cuál; sin él,AMBIGUOUS_SOURCE. Sin extensión se conserva la real (avisoEXTENSION_KEPT); con otra extensión,EXTENSION_MISMATCH. Responde el nombre guardado, releído.move:idsy el destino, omoves: [{ ids, to }]para varios destinos (to, una carpeta onullpara Inicio). Si un archivo está en varias carpetas,fromFolderIddice de cuál sale; sin él respondeAMBIGUOUS_SOURCEcon sus rutas. CondryRun: truedevuelve lo que haría sin tocar nada (ycreatesFolderssi crearía carpetas); si algo llegaría a más gente, la fila llevawidensAudiencey arriba vaconfirmReason, por qué al hacerlo pediráconfirm: true. SinfromFolderId, el origen es una carpeta del Gestor de la persona, nunca una del sistema ni de una conversación. Cada elemento responde su nombre, de dónde salió, adónde fue yopenInApp.copy: «Hacer una copia» en el destino, solo de lo que está en el Gestor para la persona. Cada fila trae la copia (copy: { id, name }) y suopenInApp.add_to_folderyremove_from_folder:idsy la carpeta ento,folderIdopath. Quitar de una ficha no es esto: esunlink. Quitar la última carpeta de un archivo lo lleva a «Eliminados recientemente»: pideconfirm: trueyfiles:items:delete, y la fila respondeoutcome: "trashed"en vez de"removed".dryRunsolo existe enmovey enfolders_manageensure_path. En cualquier otra escritura respondeVALIDATIONy no hace nada: para saber qué pasaría, llama sinconfirm.
Editar el contenido
edit sustituye el texto entero (content). patch cambia un trozo: old_string es el texto exacto, copiado de read; new_string, lo que lo sustituye; y replace_all: true lo cambia todas las veces que sale. Un edit con old_string responde VALIDATION y manda a patch. Solo en archivos de texto de hasta 5 MB: todo lo que se edita se lee, pero no todo lo que se lee se edita. Se conservan la codificación (UTF-8, UTF-16 o Windows-1252), la marca BOM y los saltos de línea; si el cambio trae un carácter que no cabe en la codificación del archivo, NOT_EDITABLE dice cuál. Los dos admiten expectedVersion, la versión que leíste: si alguien la cambió después, responden VERSION_CONFLICT. También lo responden, sin expectedVersion, si otra persona cambia el archivo mientras se guarda: vuelve a leerlo y aplica el cambio sobre lo nuevo.
Editar con o sin Archivos avanzados
Se conserva la anterior
Con Archivos avanzados
No se conserva
Sin Archivos avanzados
Si el cliente ve el archivo en su portal, la edición pide confirm: true y la respuesta lo avisa con PORTAL_VISIBLE. restore_version vuelve a una versión por su número sin perder lo vivo: si ninguna versión lo guarda, antes lo guarda como «Antes de restaurar la versión N», y su undo vuelve a ello. La web hace lo mismo. Responde restoredFrom, la versión de la que es copia lo vigente; si la pedida ya era lo vigente, unchanged: true y no cambia nada. Una versión en cuarentena no se restaura: FILE_INFECTED. delete_version elimina una que no sea la vigente (la marcada current en versions), con confirm: true; su contenido se borra para siempre si ningún otro archivo ni otra versión lo usa. Las dos piden Archivos avanzados.
Eliminar y recuperar
delete(ids,confirm: true) lleva los archivos a «Eliminados recientemente» durante 30 días. Cada elemento respondeoutcome:trashedoin_use. Si el archivo sigue en uso en un sitio que la persona no puede editar, no se toca yreferencedBydice dónde.restore(items: [{ kind, id }], conkindfileofolder, hasta 50) devuelve cada elemento a su carpeta o a su ficha si siguen existiendo y la persona puede editarlas; si no, a Inicio. Cada fila respondeoutcome: "restored"conrestoredTo(la ruta entera o «Inicio») yalsoRestoredTosi vuelve a más carpetas, ooutcome: "failed"con su código. Bastafiles:items:manageofiles:items:delete: quien puede eliminar puede deshacerlo.purge(«Eliminar definitivamente»,itemsyconfirm: true) no se puede deshacer. Sinconfirm, el ensayo dice cuánto se borra para siempre (subcarpetas, archivos y versiones anteriores, sin contar la vigente), qué va dentro de otra carpeta del lote y qué no se eliminará y por qué. Cada fila respondepurged,queued(se borra en segundo plano) ofailed. Lo que va dentro de una carpeta del mismo lote se borra con ella y su fila sale bien, conwithFolder(el id de esa carpeta).
Eliminar todo, el botón que vacía «Eliminados recientemente», no está por MCP: lo hace una persona en la aplicación. La guía de uso está en Eliminar y recuperar archivos.
errorCode | Cuándo |
|---|---|
TRASH_ITEM_NOT_FOUND | No está en «Eliminados recientemente» o la persona no puede verlo. Responde igual en los dos casos, también en el ensayo, sin nombre. |
TRASH_ITEM_EXPIRED | Se le acabó el plazo y se está borrando. |
TRASH_ITEM_INSIDE_FOLDER | Se eliminó con su carpeta: restaura o borra la carpeta (si la carpeta va en el mismo purge, se borra con ella). |
TRASH_ITEM_CONTENT_GONE | Su contenido ya no existe y no se puede restaurar. |
TRASH_RESTORE_NO_DESTINATION | Su carpeta ya no existe o no se puede editar, y la persona no puede crear carpetas en Inicio. |
TRASH_RESTORE_CONFLICT | Otro archivo activo usa ya el mismo contenido. |
TRASH_PURGE_FORBIDDEN | Solo quien lo subió, el Super Administrador o quien gestiona lo que eliminan otros lo borra antes de tiempo. |
Etiquetas y fichas
tagpone etiquetas (idsytags, por nombre o id) y crea como personales las que falten; las de toda la empresa se crean en la aplicación. Un id que no es de una etiqueta que la persona ve, también uno mal copiado, no crea nada: respondeTAG_NOT_FOUNDcon las de id parecido.untaglas quita.tag_updatecambia el nombre o el color (#RRGGBB) de una, ytag_delete, conconfirm: true, la quita de todos los archivos que la llevan; sin él, dice cuántos y cuáles la llevan de los que ve la persona.linkyunlinkvinculanidsa unaentityo quitan el vínculo. Piden Archivos avanzados, «Vincular CRM», poder editar la ficha y el acompañante de escritura. Quitar el último vínculo de un archivo sin carpeta lo lleva a «Eliminados recientemente», conconfirm: trueyfiles:items:delete.
Descargar
download_url da una dirección para que tu asistente baje el archivo ahora: de un solo uso, caduca a los 5 minutos (expiresInMinutes, hasta 15) y admite version, que entrega siempre esa versión. fileName es el nombre que ve la persona. No sirve para dársela a una persona: para eso, openInApp o un enlace público. Las claves privadas y los certificados no se descargan por aquí. Tiene la misma puerta del antivirus que leer: un archivo (o la versión pedida) que aún se está analizando responde FILE_SCAN_PENDING y uno en cuarentena, FILE_INFECTED.
Lo que pide confirmación
Lo que borra o expone, sin confirm: true, no hace nada y responde qué pasaría, con lo afectado (hasta 20 nombres) y su recuento. Enséñaselo a la persona y repite la misma llamada con confirm: true solo si lo confirma:
{
"error": {
"code": "VALIDATION",
"message": "Eliminar 3 archivos los lleva a Eliminados recientemente durante 30 días. Cuéntaselo a la persona y, si lo confirma, repite la llamada con confirm:true.",
"retryable": true,
"details": {
"errorCode": "CONFIRMATION_REQUIRED",
"operationKey": "files_manage:delete",
"affectedCount": 3,
"affected": [{ "id": "cmf1a2b3c", "name": "Contrato marco Acme.pdf" }]
}
}
}Lo piden delete, purge, delete_version, tag_delete, quitar la última carpeta o el último vínculo, share_link_revoke, las ediciones sin versión conservada o visibles en el portal, todo lo que manda un archivo a un destino con más público y, en folders_manage, delete, share, unshare y mover una carpeta a una madre con más público. En share y move de carpetas, details.affectedPeople nombra a quienes la verían y hoy no. share_link_create no lo pide: lo aprueba la persona en el móvil.
Enlaces públicos aprobados en el móvil
share_link_create crea un enlace a un archivo que abre cualquiera con la dirección, sin iniciar sesión, en una página con el nombre y el logotipo de la empresa. Es lo mismo que «Compartir con un enlace…» en la aplicación, con dos diferencias: cada enlace lo aprueba la persona en su móvil, y por aquí caduca como mucho a los 30 días.
Crear un enlace público
Participan: Tu asistente, UTILIA OS, La persona.
De Tu asistente a UTILIA OS:
share_link_create · id y expiresInDays
Comprueba todo antes de pedir nada.De UTILIA OS a Tu asistente:
APPROVAL_REQUIRED con approvalId y number (respuesta)
Aún no hay enlace.De Tu asistente a La persona:
«Elige el número 42 en tu móvil»
Y termina su turno.Nota en La persona:
Ve el archivo, su carpeta y las condiciones, y elige el número.De Tu asistente a UTILIA OS:
La misma llamada con twoFactorApprovalId
Cuando la persona avisa.De UTILIA OS a Tu asistente:
link con url, status y expiresAt (respuesta)
La dirección, solo esta vez.
Los parámetros son los del diálogo de la aplicación: id del archivo, expiresInDays (1, 7 o 30), allowDownload, password opcional (de 8 a 64 caracteres, nunca se devuelve) y label, una nota para reconocerlo (120 caracteres) que no sale en la página pública. No lleva confirm: la aprobación en el móvil es la confirmación. Pide el enlace solo cuando la persona te lo haya pedido.
- La aprobación cubre ese archivo con esas condiciones. Si cambia algo entre la petición y el canje (el archivo, su versión, su nombre, su carpeta, la caducidad, la descarga, la contraseña o la nota), responde
APPROVAL_MISMATCHy hay que pedir otra. - La dirección se entrega una sola vez, en la respuesta del alta.
share_linksla omite siempre; para volver a copiarla, la persona en la aplicación. - La persona recibe un aviso en la aplicación cada vez que se crea un enlace por esta vía, con «Anular el enlace» a un toque. Si el archivo es de otra persona, también lo recibe ella.
No se crea un enlace por MCP:
- de un archivo que una IA ha creado, cambiado, movido o renombrado en las últimas 24 horas, desde cualquier servidor (
AI_RECENTLY_CHANGED): la persona puede crearlo en la aplicación, desdeopenInApp. La misma regla, yconfirm: truecon el nombre del archivo, valen para poner una imagen del Gestor como portada de la página de reservas o en los correos de Marketing; - con una clave de conexión (
SHARE_LINK_NEEDS_OAUTH: conecta el asistente por OAuth y cada enlace se aprobará en el móvil) ni desde el copiloto de UTILIA OS (PERSONAL_SESSION_REQUIRED); - si la persona no tiene un móvil al que preguntar o no tiene activada la verificación en dos pasos (
APPROVAL_UNAVAILABLE); - pasado el cupo diario de enlaces creados por MCP (
SHARE_LINK_DAILY_LIMIT), además de los topes de la aplicación; - sin Archivos avanzados contratada, ni durante la prueba (esto se dice primero, antes que cualquier problema de la conexión, con el plan que lo incluye), ni en una sesión de soporte, ni de lo que la aplicación tampoco deja compartir (adjuntos de chat y tickets, justificantes, grabaciones de llamadas, documentos protegidos, claves privadas y tipos de riesgo).
Mientras un archivo tiene un enlace activo, por MCP no se cambia su contenido ni su nombre: edit, patch, rename, restore_version y las subidas o importaciones con versionOf responden FILE_HAS_PUBLIC_LINKS. Quien abre el enlace ve siempre lo que la persona aprobó.
share_link_revoke («Anular el enlace», linkId y confirm: true) lo corta al momento, también las descargas empezadas. Ver y anular enlaces no piden Archivos avanzados: tras bajar de plan se siguen pudiendo revisar y cortar.
errorCode | Cuándo | Qué hacer |
|---|---|---|
APPROVAL_REQUIRED | Se ha pedido la aprobación; details.approval trae approvalId, number y expiresAt. | Termina el turno pidiendo a la persona que elija el número y te avise; después repite la misma llamada con twoFactorApprovalId. |
APPROVAL_PENDING | Se ha repetido antes de que la persona respondiera. | Lo mismo: pídele que elija el número y espera a que te avise. |
APPROVAL_REJECTED | La persona la ha rechazado. | No la vuelvas a pedir salvo que ella te lo diga. |
APPROVAL_EXPIRED | Caducó sin respuesta. | Si la persona sigue queriéndolo, repite sin twoFactorApprovalId para pedir otra. |
APPROVAL_MISMATCH | El archivo o las condiciones han cambiado desde que se pidió. | Enséñaselo a la persona y, si quiere, pide otra. |
APPROVAL_UNAVAILABLE | No hay móvil al que preguntar o falta la verificación en dos pasos. | Que la persona lo cree en la aplicación: menú del archivo › «Compartir con un enlace…». |
AI_RECENTLY_CHANGED | Una IA tocó el archivo en las últimas 24 horas. | Que lo cree la persona en la aplicación (details.openInApp). |
SHARE_LINK_DAILY_LIMIT | Se ha llegado al cupo del día. | Al día siguiente se puede de nuevo. |
SHARE_LINK_NEEDS_OAUTH | La llamada viene de una clave de conexión. | Conectar el asistente por OAuth, o que lo cree la persona en la aplicación (details.openInApp). |
PERSONAL_SESSION_REQUIRED | La llamada viene del copiloto. | Que lo cree la persona en la aplicación. |
FILE_SHARE_LINK_* | Los mismos rechazos que en la aplicación: tipo bloqueado, antivirus, contraseña débil, prueba gratuita, sesión de soporte, demasiados enlaces en el archivo o un enlace que ya no existe o no está activo. | Sigue la pista de la respuesta. |
folders: ver cómo está organizado
| Operación | Qué hace |
|---|---|
tree | El árbol desde id, path o las raíces, con depth 2 por defecto (hasta 5) y 150 carpetas como mucho (maxNodes). Cada nodo trae id, name, cuántas carpetas y archivos tiene, sus hijas y truncated si se cortó. |
list | Lo que hay en una carpeta (id, path o entity) o, sin nada, en Inicio: arriba la carpeta listada (folder, con su ruta), y después primero las subcarpetas y luego los archivos, con sort (name, modified o size), kinds y 50 por página (hasta 100). |
get | La carpeta: ruta, descripción, dueño, departamento, recuentos, la ficha a la que está anclada y qué puede hacer la persona en ella (can: subir, editar, eliminar y compartir), con openInApp. |
resolve | Una ruta a su carpeta: found, ambiguous con las candidatas (nunca elige una) o not_found, que trae candidates si hay carpetas que se llaman así o casi. |
permissions | Quién tiene acceso: quién la creó, su departamento, de dónde hereda y, por cada persona o departamento, su nivel, su fecha de fin (expiresAt, y expired si ya pasó) y si llega a las subcarpetas (inheritToChildren), con una frase (summary) de quién la ve. |
Todo lo que la persona no ve queda fuera, también de las rutas y de los recuentos: resolve no atraviesa una carpeta intermedia oculta, y lo oculto responde igual que lo que no existe. Las carpetas del sistema, las de conversaciones y las que tienen bloqueado el acceso de la IA no salen en el árbol.
folders_manage: crear y organizar
| Operación | Qué hace | Scope | Permiso | confirm |
|---|---|---|---|---|
create | Una carpeta (name y parentId o parentPath) o un lote en folders, hasta 20, con parentIndex para colgar una de otra anterior del lote. Admite description, color, entity (anclarla a una ficha), departmentId (departamento dueño) e inheritPermissions (por defecto true); en un lote, llegan a todas. | files:items:manage | «Crear carpetas» | No |
ensure_path | Crea lo que falte de una ruta (path, o paths hasta 20) y devuelve, como un lote, una fila por ruta con el id de la carpeta final, su path y lo que ha creado (created); en el ensayo, sin id y con existing, la carpeta más honda de la ruta que ya existe. Con entity, dentro de la carpeta de la ficha; con dryRun, sin crear nada; con allowSimilar: true, crea el nombre pedido aunque haya uno casi igual. | files:items:manage | «Crear carpetas» | No |
update | Nombre, descripción y color; o varias carpetas con updates (hasta 20). | files:items:manage | «Editar carpetas» | No |
move | A parentId (null, la raíz) o parentPath; varias a la vez con ids (hasta 20). | files:items:manage | «Editar carpetas» | Si la nueva madre la ve más gente |
delete | A «Eliminados recientemente» 30 días, con cascade lo que contiene; varias a la vez con ids (hasta 20), con una sola confirmación. Sin cascade, una carpeta con algo dentro no se elimina (FOLDER_NOT_EMPTY), y el ensayo lo avisa antes. La devuelve files_manage restore con kind: "folder". | files:items:delete | «Eliminar carpetas» | Sí |
share, unshare | Dar o quitar acceso a userIds (hasta 50) o a un departmentId. Al dar, level, y opcionales expiresAt e inheritToChildren. unshare quita el acceso directo, no el heredado. | files:folders:share | «Compartir» | Sí |
ensure_path no duplica carpetas por una mayúscula o una tilde: si ya existe «contratos» y pides «Contratos», usa la que hay y lo avisa con PATH_REUSED. Si hay una casi igual, responde PATH_SIMILAR_EXISTS, con la carpeta en el mensaje y todas en items, para que preguntes: si la persona quería esa, usa su ruta o su id; si quiere el nombre nuevo, repite con allowSimilar: true. Lo que numera no cuenta como errata: «2025» y «2026», «Fase 1» y «Fase 2», «v1» y «v2» o «Enero» y «Febrero» son carpetas distintas y se crean sin preguntar. Si la ruta casa con varias, PATH_AMBIGUOUS, sin crear nada.
Anclar carpetas a una ficha pide Archivos avanzados. create y ensure_path con entity, o dentro de una carpeta que ya está anclada a una ficha, necesitan la capacidad: sin ella no se crea ninguna y la respuesta es CAPABILITY_NOT_ENABLED, con el plan que la incluye y upgradeUrl. Con carpeta madre y entity, la madre tiene que ser de esa ficha.
Dar acceso. Los niveles son VIEW (ver: abrir y descargar), EDIT (editar: además subir, cambiar, renombrar y quitar archivos), MANAGE (gestionar: además crear subcarpetas, mover y eliminar) y FULL (control total: además dar y quitar acceso a otras personas). Sin level responde VALIDATION con esa explicación. expiresAt es una fecha AAAA-MM-DD (vale hasta el final de ese día, en la zona de la empresa), una fecha y hora, o null para quitar la fecha de fin; inheritToChildren: false deja el acceso solo en esta carpeta. Si no los pasas, quien ya tenía acceso directo conserva su fecha de fin y su herencia. Sin confirm: true, la respuesta dice qué cambia o se conserva de cada acceso, si había caducado y quién la vería que hoy no.
El acceso de la IA y la Búsqueda por dentro de una carpeta no se cambian por MCP: solo una persona en la aplicación.
Avisos y siguiente paso
Los avisos que cambian lo que debe hacer tu asistente llegan en _notices.items, cada uno con su code y su message, junto a los de siempre (ignoredFields, deprecatedOperation, reauthorization). Nunca citan texto del archivo.
code | Cuándo |
|---|---|
OCR_PARTIAL | Del escaneado solo se leyeron algunas páginas (pagesRead, pagesPending). |
OCR_DAILY_QUOTA | Se acabó el cupo de páginas escaneadas del día a mitad de la lectura. |
OMITTED_BY_PLAN | Una parte del resultado necesita Archivos avanzados; trae el plan que la incluye y upgradeUrl. |
ENTITY_HAS_NO_FOLDER | La ficha no tiene carpeta: el archivo queda vinculado a ella, sin carpeta. |
PATH_REUSED | ensure_path usó una carpeta que ya existía con otra grafía (requested, used). |
PORTAL_VISIBLE | Lo editado o movido lo ve el cliente en su portal. |
PREVIOUS_VERSION_NOT_KEPT | Se editó sin Archivos avanzados y no se guardó la versión anterior; trae el plan que las conserva y upgradeUrl. |
TABLE_TRUNCATED | La hoja llegó cortada. |
EXTENSION_KEPT | rename sin extensión: se ha conservado la real (extension). |
TECHNICAL_INFO_DEFERRED | get de varios: la ficha técnica de los de ids está pendiente; pídela con get de cada uno. |
PAGE_TRUNCATED | Una página no cabía entera y falta su final (page, charsRead). |
FILTER_VALUE_INVALID | Un filtro de table compara con algo que no es del tipo de su columna (column). |
TABLE_CHARS_LIMIT | table da menos filas de las pedidas para no pasar de 36.000 caracteres (maxChars); si ni una cabe entera, sus textos largos acaban en «…» (cellsShortened). Pide las siguientes con offset o menos columnas con columns. |
MATCHED_BY_FOLDER | Algunos resultados de search casan solo por estar en una carpeta con ese nombre. |
SCAN_LIMIT | Se agotó la exploración y quedan más sin revisar: la página sale vacía o, en trash, con lo encontrado. Sigue con nextCursor. |
MORE_MATCHES | find encontró más coincidencias de las que enseña (totalMatches, shownMatches): las páginas de todas están en matchedPages. |
NOT_FOUND_ELSEWHERE | En un lote de get o read, dónde se lee lo que no es del Gestor, una vez para todas las filas FILE_NOT_FOUND (ids). |
FOLDERS_CREATED | request_upload creó carpetas con ensurePath (están en createdFolders): si no subes nada, se quedan vacías. |
FOLDERS_LEFT_EMPTY | abort_upload dejó vacías las carpetas de la subida y las que se crearon encima para ella (emptyFolders): si se crearon solo para la subida, elimínalas con folders_manage delete. |
SCAN_PENDING | confirm_upload: el antivirus aún está analizando lo recién subido (ids, retryAfterSeconds). Hasta que termine no se lee, ni se descarga, ni se comparte; si tras tres intentos sigue igual, díselo a la persona. |
nextSteps sugiere el paso siguiente, también en otro servidor (por ejemplo, preparar un presupuesto con crm_budgets de utilia-crm), solo si el plan y los permisos lo permiten. Llega en get y en lo recién guardado (confirm_upload, create, import_url), tras find (leer esas páginas), en la ficha de un escaneado (mirarlo con view) o de un vídeo o un audio (descargarlo).
Errores
Todos llegan como resultado de la herramienta, con error.details.errorCode y una hint que dice qué hacer ahora. Ningún mensaje cita texto del archivo ni nombra lo que la persona no ve. Los de plan, permiso y scope son los comunes, en Errores con motivo. El límite de peticiones de la conexión es la excepción: llega como HTTP 429 con RATE_LIMITED y retryAfterSeconds, en Límite de peticiones.
Al encontrar
errorCode | Cuándo | Qué hacer |
|---|---|---|
FILE_NOT_FOUND | No existe, no se ve, tiene bloqueado el acceso de la IA o es de otro módulo. | Comprueba el id con files search. Si es un adjunto de un ticket, léelo con read_attachment de tickets (utilia-crm o utilia-work) o, si el ticket es tuyo, de my_tickets; el de un ticket al soporte de UTILIA OS, con read_attachment de utilia_support, y el de un elemento de trabajo, con read_attachment de issues (utilia-work). Lo compartido en una conversación se lee con chat_conversations (utilia-chat); del justificante de un gasto, expenses (utilia-finance) da su enlace de descarga con document_get, y los documentos de RRHH se abren en la aplicación. |
FOLDER_NOT_FOUND | Igual, con una carpeta. | Comprueba la carpeta con folders resolve o folders tree. |
PATH_NOT_FOUND | Ninguna carpeta visible tiene esa ruta; si hay alguna que se llama así o casi, trae las candidatas (details.items). | Pregunta si es alguna de ellas; si no, enseña las carpetas que hay o crea la ruta con ensure_path si te lo piden. |
PATH_AMBIGUOUS | Varias rutas visibles casan (details.items). | Pregunta cuál es y repite con su id. |
PATH_SIMILAR_EXISTS | ensure_path o ensurePath encuentran una carpeta casi igual (el mensaje la nombra; todas, en items). | Pregunta a la persona: si es esa, repite con su id; si quiere la nueva tal cual, repite con allowSimilar: true. No elijas tú. |
ENTITY_NOT_FOUND, ENTITY_AMBIGUOUS | La ficha no existe, no se ve o casa con varias (details.candidates). | Compruébala con search, o pregunta cuál es y repite con su id. |
TAG_NOT_FOUND | Una etiqueta pedida no existe entre las visibles; trae las parecidas. | Usa una de ellas o pide el nombre exacto. |
WRONG_TOOL | La operación es de otra herramienta del servidor: «La operación X es de Y, no de Z.» (details.operationKey). | Repite con esa herramienta y los mismos datos. |
Al leer
errorCode | Cuándo | Qué hacer |
|---|---|---|
NOT_READABLE | details.reason: scanned (sin texto y sin cupo de OCR), encrypted, unsupported o too_large. | Un escaneado, míralo con view; uno con contraseña, que lo abra la persona; uno demasiado grande, léelo por pages. |
PAGE_OUT_OF_RANGE | pages fuera del documento. | Pide páginas entre 1 y el totalPages de files get. |
INVALID_PAGES | pages mal escrito o con una página por encima de 100.000. | Repite con pages como "3", "3-7" o "2,5". |
INVALID_CURSOR | El cursor no es de ese archivo o ya no vale. | Vuelve a leerlo desde el principio, sin cursor. |
INVALID_QUERY | find sin query ni terms. | Repite con unas palabras o una "frase exacta". |
FILE_CHANGED | El archivo cambió desde que se emitió el cursor. | Vuelve a leerlo desde el principio, sin cursor. |
NOT_COMPARABLE | compare con versiones sin texto o de tipos distintos. | Enseña sus fichas con versions. |
SHEET_NOT_FOUND, COLUMN_NOT_FOUND | La hoja o la columna no existen; trae las que hay (y missing, las columnas que fallaron). | Usa uno de esos nombres. |
TABLE_TRUNCATED | aggregate o stats sobre una hoja cortada. | Lee filas con mode: "rows" o que la abra la persona. |
EXTRACTOR_BUSY, EXCEL_READ_BUSY | El lector está ocupado (retryAfterSeconds). | Reintenta una vez pasado ese tiempo. |
EXTRACTOR_UNAVAILABLE | Ahora no se puede leer (con retryAfterSeconds si es un escaneado y no se puede contar su cupo). | Reintenta pasado ese tiempo; si la persona lo necesita ya, que lo abra en la aplicación. |
STORAGE_UNAVAILABLE | El almacenamiento de archivos no responde (retryAfterSeconds). El archivo existe. | Reintenta pasado ese tiempo; si sigue sin responder, díselo a la persona. |
OCR_DAILY_QUOTA | El escaneado necesita OCR y no queda cupo hoy. | Míralo con view o vuelve a intentarlo mañana. |
READ_RATE_LIMITED | Ya hay una lectura en curso en la empresa o se ha pasado el cupo de la hora (retryAfterSeconds). | Espera y lee menos a la vez. |
FILE_SCAN_PENDING | El antivirus aún lo está analizando (retryAfterSeconds). También en download_url. | Vuelve a intentarlo pasado ese tiempo; si tras tres intentos sigue igual, no insistas y díselo a la persona: el análisis sigue solo y no hace falta volver a subir el archivo. |
FILE_INFECTED | Está en cuarentena: el antivirus ha encontrado una amenaza. También en download_url. | No se puede leer, descargar ni reenviar, y no sirve reintentarlo. Díselo a la persona; en la ficha del archivo verá qué puede hacer con él. |
FILE_UPLOAD_PENDING | Es una subida sin terminar: la reserva está en su carpeta, pero el contenido no llegó. También en download_url. | Dile a la persona que la continúe o la descarte en su carpeta, o súbelo otra vez con request_upload si tienes el fichero. |
PRIVATE_KEY_RESTRICTED | Es una clave privada o un certificado. | La persona lo descarga desde la aplicación. |
Al cambiar
errorCode | Cuándo | Qué hacer |
|---|---|---|
CONFIRMATION_REQUIRED | Falta confirm: true. | Enseña lo que va a pasar y repite la misma llamada si la persona lo confirma. |
NAME_CONFLICT | Ya hay algo con ese nombre en el destino. | Elige otro nombre con la persona y repite con él. |
NOT_EDITABLE | edit o patch sobre algo que no es texto, pasa de 5 MB o no se puede reescribir en su codificación sin estropearlo. | Sube una versión nueva con request_upload o import_url y versionOf; si es un carácter que no cabe, escribe el cambio sin él. |
PATCH_NO_MATCH, PATCH_MULTIPLE_MATCHES | old_string no aparece, o aparece varias veces. | Vuelve a leer y cópialo exacto, amplíalo para que sea único o usa replace_all. |
AMBIGUOUS_SOURCE | move o rename de un archivo que está en varias carpetas, sin fromFolderId. | Pregunta de qué carpeta sale (o en cuál se renombra) y repite con fromFolderId. |
EXTENSION_MISMATCH | rename a un nombre con otra extensión que la real. | Usa la extensión real, o ninguna; para otro formato, crea una copia con create. |
FILES_MANAGE_BUSY | Ya se está creando un .pdf o un .docx, o trayendo un archivo de internet (retryAfterSeconds). | Espera y repite; de uno en uno. |
UPLOAD_NOT_PREPARED, UPLOAD_IN_PROGRESS, VERSION_UPLOAD_FAILED | No se pudo preparar la subida (nada reservado), ya se está confirmando, o no se pudo guardar como versión nueva. | Pide la subida otra vez en unos minutos; o espera y confírmala de nuevo; o sigue la pista. |
STORAGE_UNAVAILABLE en una fila de confirm_upload | El archivo ha llegado, pero todavía se está guardando o el almacenamiento no responde. La reserva sigue. | Repite confirm_upload con ese id pasados unos segundos. No hagas otra vez el PUT ni reserves de nuevo. |
UPLOAD_NOT_FINISHED en una fila de confirm_upload | La confirmación no ha dejado la subida terminada (el archivo seguiría como subida sin terminar), o no se ha podido comprobar. El contenido ya llegó. | No borres tu copia. Repite confirm_upload con ese id pasados unos segundos, sin volver a hacer el PUT; si vuelve a pasar, díselo a la persona. |
VERSION_CONFLICT | expectedVersion no es la vigente (details.currentRevision), u otra persona lo ha cambiado mientras se guardaba. | Vuelve a leerlo y aplica el cambio sobre la versión nueva. |
FILE_INFECTED | restore_version de una versión en cuarentena. | Elige otra versión: versions marca las que están en cuarentena con antivirus: "infected". |
FOLDER_NOT_EMPTY | folders_manage delete sin cascade de una carpeta con algo dentro. | Cuéntale a la persona lo que contiene y, si quiere eliminarlo también, repite con cascade: true. |
TOO_MANY_UPLOAD_RESERVATIONS, UPLOAD_NOT_FOUND | No quedan huecos para reservar más subidas, o el id no es una reserva tuya pendiente. | Termina o libera las reservas con abort_upload y repite solo esas filas; o comprueba el id que dio request_upload. |
PERMISSION_DENIED en path | ensurePath tendría que crear carpetas y la persona no tiene «Crear carpetas» o el nivel «Gestionar» donde irían. | Guárdalo en una carpeta que ya exista o díselo a la persona; no repitas con ensurePath. |
FILE_HAS_PUBLIC_LINKS | El archivo tiene un enlace público activo. | Que la persona anule el enlace o haga el cambio en la aplicación. |
FILE_IS_WORM_PROTECTED, FILE_IS_SYSTEM_GENERATED, FOLDER_IS_SYSTEM, FILE_IS_ISSUED_INVOICE_ORIGINAL, FILE_IS_VAT_ACCREDITATION_EVIDENCE, HR_SYSTEM_FILE_PROTECTED, FILE_PROTECTED | El archivo está protegido: se conserva sin cambios por ley, lo mantiene UTILIA OS, es el original de una factura emitida (se corrige con una rectificativa en utilia-finance), es la prueba de una acreditación fiscal, es un documento de RRHH (en utilia-rrhh) o está en retención. | No se cambia por aquí; díselo a la persona. |
IMPORT_URL_BLOCKED, IMPORT_URL_UNREACHABLE | La dirección no es https, lleva credenciales o un puerto raro, el tipo es de riesgo, o no se alcanza. | Usa una dirección pública; si el archivo está en el disco, súbelo con request_upload. |
QUOTA_EXCEEDED_STORAGE | No queda espacio. | La persona puede liberar espacio o pedir más con org_plan. |
Si conecta alguien de la asesoría
Una persona de la asesoría entra en este servidor solo si la empresa le comparte el área «Documentos», y su asistente tiene las mismas reglas que ella en la aplicación:
La asesoría por MCP, según su nivel
| Acción | Ver y descargar | También subir |
|---|---|---|
| Leer, mirar y descargar | Sí | Sí |
| Subir, crear, ordenar y editarSolo en su carpeta compartida | No | Sí |
| Eliminar y recuperarSolo lo que subió o metió ella | No | Propios: Lo que ha creado |
| Dar acceso a carpetas | No | No |
| Crear o anular enlaces públicos | No | No |
- Leer, mirar y descargarSí
- Subir, crear, ordenar y editarSolo en su carpeta compartidaNo
- Eliminar y recuperarSolo lo que subió o metió ellaNo
- Dar acceso a carpetasNo
- Crear o anular enlaces públicosNo
- Leer, mirar y descargarSí
- Subir, crear, ordenar y editarSolo en su carpeta compartidaSí
- Eliminar y recuperarSolo lo que subió o metió ellaPropios: Lo que ha creado
- Dar acceso a carpetasNo
- Crear o anular enlaces públicosNo
- Propios:
- Lo que ha creado
Nada sale de su carpeta compartida: mover fuera, o a Inicio, se niega. ADVISOR_DELETE_NOT_ALLOWED y ADVISOR_FILE_READ_ONLY explican la negativa sobre lo que ella ve; lo de la empresa que no ve responde como si no existiera.
Si tu integración llamaba desde el CRM
Las herramientas fm_* y fm_virtual_folders salen del servidor utilia-crm. Por su nombre viejo responden MOVED_TO_FILES, con la sustituta exacta en details.replacement (server, path, tool y operation). Las conexiones del CRM autorizadas antes del cambio que llevan dev:files:* siguen pudiendo llamarlas, lecturas y escrituras, hasta el 31 de diciembre de 2026, sin anunciarse y con el aviso _notices.reauthorization; después se retiran. Mientras tanto se comportan como este servidor en lo que importa: solo alcanzan lo que está en el Gestor para la persona, también al escribir, y no cambian el contenido ni el nombre de un archivo con un enlace público activo. Las escrituras que aceptaban las herramientas de lectura (fm_files, fm_folders, fm_organization) responden MOVED_TO_FILES desde el primer día.
| Herramienta del CRM | Sustituta en utilia-files |
|---|---|
fm_files | get → files get; get_content → files read; get_download_url → files_manage download_url; get_versions → files versions; search → files search (por dentro, search); list_trash → files trash |
fm_files_manage | Las subidas (también las batch_*) → request_upload, confirm_upload y abort_upload con files; upload_version → import_url con versionOf; edit_content → edit; share_links_list → files share_links; restore_version va por número de versión. El resto se llama igual en files_manage, sin el prefijo batch_. |
fm_folders | list_root y get_contents → folders list; get_tree → folders tree; get y get_breadcrumb → folders get; get_permissions → folders permissions |
fm_folders_manage | create y batch_create → folders_manage create; delete_cascade → delete con cascade; unshare va por persona o departamento. El resto se llama igual. |
fm_organization, fm_organization_manage | Las etiquetas → files tags y files_manage tag, untag, tag_update y tag_delete. Los favoritos → files favorites y files_manage favorite y unfavorite; el orden, en la aplicación. |
fm_excel_query | files table, con mode sheets, rows o stats |
fm_pdf_visual | get_info → files get; render_page y render_pages → files view |
fm_virtual_folders | Los árboles y get_entity_files → files search con entity; link_files → files_manage link; unlink_file y unlink_files → files_manage unlink |
En utilia-crm se quedan crm_files, crm_files_management y crm_budget_files, para los archivos de las fichas del CRM. crm:files:view, crm:files:upload y crm:files:delete cubren desde ahora solo esas fichas, y sus rótulos lo dicen: «Ver los archivos de las fichas del CRM», «Subir y vincular archivos a las fichas del CRM» y «Eliminar archivos de las fichas del CRM». El servidor del CRM deja de anunciar dev:files:*. Para el Gestor entero, conecta este servidor y autoriza los files:* que necesites.
Siguiente paso
Ponlo en práctica
Lo encontrarás en Conecta tu IA. Para abrirlo, entra con tu cuenta de UTILIA OS.