Archivos

Con /external/v1/files tu aplicación sube archivos (por ejemplo, para adjuntarlos a un ticket), consulta cuánto espacio le queda y obtiene direcciones firmadas para descargarlos. Los archivos de cada aplicación se guardan aparte, dentro de tu organización.

Autenticación y plan

Todas las peticiones llevan la clave de API de la aplicación:

X-Api-Key: <api_key_de_la_app>

El plan de tu organización tiene que incluir el aplicativo Gestor de archivos; si no, la respuesta es 403 MODULE_NOT_ENABLED.

Permisos de la API (scopes)

Sin el permiso adecuado, los endpoints responden 403 INSUFFICIENT_SCOPE con un mensaje genérico que pide hablar con el administrador de la organización. El permiso se exige desde la primera llamada, sin periodo de gracia (las versiones antiguas de esta página hablaban de catorce días de tolerancia que no se aplican). El catálogo y las reglas de concesión están en Permisos de la API.

No hay endpoint para borrar archivos desde fuera: no existe DELETE /external/v1/files/:id ni, por tanto, el permiso fm:files:delete, que se retiró del catálogo el 25 de mayo de 2026.

Endpoints

Parámetros

X-Api-Keyheaderobligatorio

Clave de API de la aplicación externa.

filemultipartobligatorio

En la subida: el archivo (campo file). Hasta 50 MB por petición, dentro siempre del tamaño máximo y la cuota configurados para la aplicación.

namemultipart

En la subida: nombre personalizado del archivo.

metadatamultipart

En la subida: metadatos libres del archivo.

idpathobligatorio

En GET /:id/url: identificador del archivo.

Ejemplos

# Subir un archivo
curl -X POST 'https://os.utilia.ai/api/external/v1/files/upload' \
  -H 'X-Api-Key: utl_xxx' \
  -F 'file=@/ruta/local/captura.png'
 
# Consultar la cuota
curl -X GET 'https://os.utilia.ai/api/external/v1/files/quota' \
  -H 'X-Api-Key: utl_xxx'
 
# Obtener la dirección de descarga
curl -X GET 'https://os.utilia.ai/api/external/v1/files/file-uuid/url' \
  -H 'X-Api-Key: utl_xxx'

Errores

• 400 FILE_MISSING: la petición de subida no lleva ningún archivo.
• 400 FILE_INVALID_MIME: ese tipo de archivo no está permitido (solo imágenes, PDF, documentos de Office y texto).
• 400 FILE_TOO_LARGE: el archivo supera el tamaño máximo por archivo configurado para la aplicación.
• 403 FILE_QUOTA_EXCEEDED: la subida superaría la cuota de almacenamiento de la aplicación.
• 403 MODULE_NOT_ENABLED: el plan de tu organización no incluye el Gestor de archivos.
• 403 INSUFFICIENT_SCOPE: la aplicación no tiene concedido el permiso necesario.
• 404 FILE_NOT_FOUND: el archivo no existe o no es de esta aplicación (los archivos son de la aplicación, no de cada usuario externo).

El tamaño máximo por archivo y la cuota de la aplicación se ajustan en la pestaña Avanzado de los ajustes de la aplicación, en Aplicaciones externas, necesitas entrar con tu cuenta.

Seguimiento de peticiones

Envía X-Request-Id en cada petición para poder cruzarla con los registros de UTILIA OS. Si no lo envías, la respuesta trae el que se haya generado.

Siguiente paso

Tras subir un archivo, adjúntalo a un ticket con attachmentIds en el cuerpo de POST /external/v1/tickets o de POST /external/v1/tickets/:id/messages (ver Tickets de soporte). Si algún identificador no es válido o no es de tu aplicación, la respuesta es 400 FILE_INVALID_ATTACHMENTS.