Guía de API de subida de archivos: arquitectura, seguridad y selección de proveedores

Define la tarea de subida antes de elegir un widget

Una subida en producción comienza antes de que se mueva el primer byte. La aplicación identifica al usuario, decide qué operación está permitida, especifica la cantidad y el tamaño aceptables de los archivos y crea un registro que puede persistir más que una pestaña del navegador. La transferencia es solo una etapa. La validación, el procesamiento, la exportación, la notificación y la conciliación determinan si después el producto puede usar el archivo de forma segura.

Redacta un contrato de finalización en términos del producto. «La solicitud devolvió 200» es una condición débil; «el original y las versiones derivadas requeridas están almacenados bajo este inquilino, el registro del recurso identifica sus versiones y un callback duplicado no cambia nada» es verificable. Registra qué fallos pueden volver a intentar los usuarios, cuáles requieren una nueva subida y cuáles dejan un estado visible para el operador que permita la recuperación.

Elige una de las cuatro rutas explícitas para los bytes

En una retransmisión mediante la aplicación, el navegador envía el archivo a tu servidor y este lo reenvía o lo almacena. Es un modelo fácil de entender y ofrece a la aplicación control inmediato, pero cada byte consume tu capacidad de entrada, memoria o disco temporal, tiempo de conexión y salida de datos. Es adecuado para archivos pequeños y poco frecuentes cuando el servidor existente puede aplicar límites y transmitirlos de forma segura sin guardar cuerpos completos en búfer.

«Directo a la nube» es ambiguo, así que especifica el destino. Un navegador puede subir directamente al almacenamiento de objetos con credenciales de corta duración, subir directamente a un servicio de procesamiento como Transloadit o solicitar a un servicio que importe una URL remota existente. El almacenamiento directo minimiza los saltos cuando la persistencia es la única tarea. El procesamiento directo mantiene los bytes de los archivos fuera del servidor de la aplicación mientras un flujo de trabajo valida, transforma y almacena los archivos en el destino elegido.

Diseña la reanudación por separado de los reintentos

Un reintento vuelve a iniciar una operación; una transferencia reanudable continúa una subida existente desde un desplazamiento de bytes confirmado por el servidor. Con el protocolo tus, el cliente conserva la URL de subida, solicita al servidor el valor de Upload-Offset y envía únicamente los bytes restantes. Conserva esa URL fuera del estado transitorio del componente si debe ser posible recuperarse tras una actualización o un fallo, y genera con cuidado las huellas digitales de los archivos para que el archivo local de un usuario nunca se vincule al recurso de subida de otro.

La reanudación no hace que el tiempo sea ilimitado ni que el procesamiento sea idempotente. Una Assembly de Transloadit sigue teniendo ocho horas desde su creación para terminar la subida, y crear una Assembly de reemplazo puede duplicar el trabajo a menos que la aplicación concilie el identificador anterior. Define cómo gestiona el cliente las pausas, el tiempo sin conexión, los recursos vencidos, los archivos modificados, las subidas abandonadas y la pérdida de una respuesta de finalización después de que el servidor haya aceptado los últimos bytes.

Autoriza la intención en el servidor y desconfía de los bytes

El código del navegador puede contener una Auth Key pública, pero nunca debe contener el Auth Secret de Transloadit ni credenciales permanentes de almacenamiento. Autentica al usuario en tu aplicación, selecciona en el servidor un Template guardado y devuelve parámetros firmados de corta duración con un nonce único. Establece allow_steps_override en false cuando el navegador no tenga un motivo legítimo para sustituir Steps, porque, de lo contrario, un grafo de Steps seleccionado por el cliente podría cambiar el comportamiento del procesamiento o la exportación.

Una firma válida demuestra que se autorizó el payload de parámetros; no demuestra que los bytes subidos coincidan con un nombre de archivo, una extensión, un tipo MIME declarado, un inquilino o una política de moderación. Limita el cuerpo de las solicitudes antes de realizar tareas costosas, inspecciona las propiedades observadas de los archivos, rechaza el contenido no compatible, analízalo cuando lo exija el modelo de amenazas y mantén los resultados no confiables fuera del almacenamiento público hasta que el flujo de trabajo alcance un estado aprobado.

Elige dónde se almacenan los archivos después del procesamiento

Un endpoint de subida no es automáticamente un sistema de registro. Decide qué bucket o base de datos de recursos conserva el original, cómo se relacionan los derivados con él, qué identificadores sobreviven a los cambios de nombre y quién elimina cada copia. Transloadit normalmente conserva los resultados temporales durante 24 horas, salvo que la opción «No guardar» esté activada, mientras que sus URL de acceso pueden vencer después de unas horas. Añade un Step de almacenamiento para los archivos que quieras conservar: /transloadit/store para Transloadit Storage (beta), u otro Robot de exportación como /s3/store para tu propio almacenamiento. Las URL temporales se limitan a la recuperación a corto plazo, no a incrustar ni a entregar repetidamente en el producto.

Incluye la exportación en la Assembly cuando el éxito del flujo de trabajo requiera tanto el procesamiento como la persistencia. Un Robot de exportación puede usar credenciales de Template almacenadas para escribir los resultados en el destino elegido como parte del flujo de trabajo. Como alternativa, primero sube directamente a un almacenamiento propio e inicia el procesamiento mediante un evento controlado. Esa ruta proporciona una copia persistente desde una etapa temprana, pero añade tareas de orquestación y otra transferencia al procesador.

Con Transloadit Storage (beta), no necesitas tu propio bucket de S3. También puedes guardar archivos en tu propio proveedor de almacenamiento compatible. La File Library (vista previa) es la interfaz de gestión de recursos digitales (DAM) de Transloadit para explorar, organizar, previsualizar y descargar archivos en Transloadit Storage. El acceso a la File Library se habilita por Workspace; contáctanos para consultar la disponibilidad. Los ejemplos de S3 de esta guía demuestran la opción de traer tu propio almacenamiento.

Decide entre desarrollar o comprar en el límite de responsabilidad

Desarrolla la ruta de transferencia cuando los requisitos sean específicos y el equipo esté preparado para asumir todo el ciclo de vida. Un formulario pequeño y autenticado que transmita archivos cortos a un bucket existente quizá no justifique otra plataforma. Aun así, la estimación debe incluir el análisis multipart, la contrapresión, la aplicación de límites de tamaño, la reanudación o su ausencia deliberada, la limpieza, los controles contra abusos, la observabilidad, las actualizaciones y el soporte para fallos que ocurran después de que finalice la solicitud.

Un servicio gestionado resulta más atractivo a medida que el flujo de trabajo combina redes poco confiables, archivos grandes, experiencia de usuario en el navegador, fuentes remotas, inspección multimedia, transformación o varios destinos de almacenamiento. Comprar no elimina la responsabilidad de las comprobaciones de inquilinos, la autorización, los registros de recursos, la política de retención y las reglas de publicación de tu aplicación. Elige almacenamiento alojado cuando quieras que el proveedor lo opere, o un diseño híbrido cuando importe conservar tu bucket existente.

Evalúa el flujo de trabajo completo de Uppy + Transloadit. Uppy aporta la interfaz de subida y se conecta con la infraestructura de subida y procesamiento de Transloadit. Transloadit Storage está en beta; sus archivos pueden gestionarse mediante la File Library (vista previa), con acceso a la File Library habilitado por Workspace. Consúltanos sobre la disponibilidad de Transloadit Storage y la File Library. También puedes conservar tu almacenamiento actual. Tu aplicación sigue autenticando a los usuarios, conservando los registros de recursos y controlando la entrega. Para los archivos en Transloadit Storage, tu servidor firma las URL de Smart CDN. No necesitas operar los servidores de subida y de procesamiento multimedia.

Compara proveedores con pruebas de fallos, no por cantidad de funciones

Crea una matriz de evaluación basada en la carga de trabajo real del producto. Compara clientes web y móviles, soporte para protocolos abiertos, tamaño máximo de archivo, comportamiento de concurrencia, endpoints geográficos, importaciones remotas, amplitud de procesamiento, destinos de almacenamiento, aislamiento de la credencial, verificación de webhooks, conservación de estados, soporte y opciones de salida. Marca cada función como obligatoria, opcional o irrelevante antes de consultar las páginas de los proveedores.

Ejecuta los mismos casos de prueba con cada candidato serio. Interrumpe una subida grande, recarga la página, envía un evento de finalización duplicado, revoca las credenciales de almacenamiento, rechaza un archivo después de recibirlo, supera un límite y pierde la respuesta final. Mide la recuperación visible para el usuario, los bytes retransmitidos, el tiempo hasta obtener un resultado persistente, la evidencia para el operador y la limpieza. Un selector de archivos bien diseñado dice poco sobre estas propiedades en producción.

Implementa una subida firmada con Uppy y Transloadit

El ejemplo del navegador permite que Uppy gestione la selección y la transferencia mediante el protocolo tus, mientras el plugin de Transloadit solicita parámetros de Assembly a tu aplicación. El endpoint del servidor debe autenticar al usuario actual antes de devolver el objeto de calcSignature. Debe seleccionar por sí mismo el Template en lugar de aceptar Steps arbitrarios o un destino de almacenamiento proporcionado por quien realiza la solicitud, y debe limitar la tasa de solicitudes de autorización de forma independiente del tráfico de subida.

Antes de usar este ejemplo, activa «Require a correct Signature» en la Configuración del Workspace, guarda el Template siguiente y configura su ID en TRANSLOADIT_UPLOAD_TEMPLATE_ID en el servidor. Guarda el acceso AWS a tu bucket privado como credenciales de Template con el nombre my_s3_credentials. La Auth Key puede llegar al navegador; el Auth Secret y las credenciales AWS no. El endpoint de firma debe devolver Cache-Control: no-store para que cada operación autorizada reciba parámetros nuevos.

Instala @uppy/core, @uppy/dashboard y @uppy/transloadit en el frontend y el SDK @transloadit/node en el servidor. Monta el ejemplo del navegador después de que exista un elemento como <div id="photo-upload"></div>. Implementa /api/transloadit-params en tu framework con autenticación de sesión y autorización de subida antes de llamar a la función auxiliar de firma. Rechaza las solicitudes no autenticadas o no autorizadas; la función auxiliar no es un endpoint de autenticación.

La política de archivos del ejemplo permite una sola imagen JPEG, PNG o WebP de hasta 9 MiB. maxFileSize de Uppy ofrece información inmediata sobre los bytes del archivo, y el filtro del Template bloqueado aplica en el servidor ese límite de 9 MiB por archivo. El parámetro firmado auth.max_size establece un presupuesto total de 10 MiB para las solicitudes, incluidos los bytes de la solicitud inicial de la Assembly y las subidas reanudables; auth.max_number_of_files limita la Assembly a un solo archivo. Esto deja un margen ilustrativo de 1 MiB para la sobrecarga de las solicitudes. La sobrecarga de las solicitudes varía, por lo que el rechazo del servidor sigue siendo definitivo; la aceptación del navegador no garantiza la creación de la Assembly. waitForEncoding: true espera a la Assembly, incluida la exportación, en lugar de confundir el final de la transferencia con la finalización del flujo de trabajo.

import Uppy from '@uppy/core'
import Dashboard from '@uppy/dashboard'
import Transloadit from '@uppy/transloadit'

import '@uppy/core/css/style.min.css'
import '@uppy/dashboard/css/style.min.css'

// Mount this once after <div id="photo-upload"></div> exists in your page.
const uppy = new Uppy({
  restrictions: {
    maxNumberOfFiles: 1,
    maxFileSize: 9 * 1024 * 1024,
    allowedFileTypes: ['image/jpeg', 'image/png', 'image/webp'],
  },
}).use(Dashboard, { inline: true, target: '#photo-upload' }).use(Transloadit, {
  async assemblyOptions() {
    const response = await fetch('/api/transloadit-params', {
      credentials: 'same-origin',
      cache: 'no-store',
    })
    if (!response.ok) {
      throw new Error('Could not authorize this upload')
    }
    return response.json()
  },
  waitForEncoding: true,
  retryDelays: [0, 1000, 3000, 5000, 10000],
})

uppy.on('transloadit:assembly-created', (assembly) => {
  // Associate this ID with the server-side operation before the user leaves the page.
  console.log('Assembly started:', assembly.assembly_id)
})

uppy.on('transloadit:complete', (assembly) => {
  // Record completion against the ID persisted at transloadit:assembly-created.
  console.log('Processing completed. Assembly:', assembly.assembly_id)
})

uppy.on('transloadit:assembly-error', () => {
  // Show this through the application’s accessible status UI, not raw API errors or URLs.
  console.error('Processing failed. Check the Assembly in your workspace.')
})

uppy.on('upload-error', () => {
  // Transloadit API signature rejections and Assembly errors also reach this event.
  // Failures thrown by assemblyOptions() use Uppy’s general error event instead.
  // Deduplicate application notices.
  console.error('The upload workflow failed. Check its status before retrying.')
})

import { randomUUID } from 'node:crypto'
import { Transloadit } from '@transloadit/node'

function requiredEnvironmentValue(name: string): string {
  const value = process.env[name]
  if (value == null) throw new Error(`Missing environment variable: ${name}`)
  return value
}

const transloadit = new Transloadit({
  authKey: requiredEnvironmentValue('TRANSLOADIT_KEY'),
  authSecret: requiredEnvironmentValue('TRANSLOADIT_SECRET'),
})

export function createAuthorizedUploadParameters(): { params: string; signature: string } {
  // Call this only after the server has authenticated the request and authorized the operation.
  const params = {
    auth: {
      expires: new Date(Date.now() + 5 * 60 * 1000).toISOString(),
      max_size: 10 * 1024 * 1024,
      max_number_of_files: 1,
    },
    nonce: randomUUID(),
    template_id: requiredEnvironmentValue('TRANSLOADIT_UPLOAD_TEMPLATE_ID'),
  }
  return transloadit.calcSignature(params)
}

Conecta la recepción, la validación, el procesamiento y la exportación

Una Assembly conecta toda la ruta: subida autenticada con Uppy → validación con /file/filter → procesamiento con /image/resize → exportación con /s3/store a un bucket del cliente. El Template guardado define el flujo y cada dependencia use determina qué archivos llegan al siguiente Step. Uppy proporciona la experiencia de subida; Transloadit ejecuta el flujo gestionado, no tu servidor de aplicaciones.

El filtro comprueba el tipo MIME detectado y rechaza los archivos de más de 9 MiB; después, solo envía las imágenes aceptadas a los Steps de vista previa y exportación. error_on_decline: true convierte un rechazo en un error de Assembly. Las comprobaciones de MIME y tamaño no son análisis de malware ni moderación de contenido; añade esos Steps antes del procesamiento y la exportación cuando tu política lo requiera.

Usa un bucket S3 privado con Block Public Access activado y credenciales de Template con permisos debidamente limitados. acl: "bucket-default" omite la ACL del objeto y depende de la política de acceso del bucket; no convierte un bucket público en privado. La exportación guarda el original aceptado y una vista previa limitada a 1600 × 1600 píxeles en rutas específicas de la Assembly y del archivo. Ninguna exportación lee directamente de :original sin filtrar.

{
  "allow_steps_override": false,
  "steps": {
    ":original": {
      "robot": "/upload/handle"
    },
    "accepted_images": {
      "use": ":original",
      "robot": "/file/filter",
      "accepts": [
        ["${file.mime}", "regex", "^image/(jpeg|png|webp)$"]
      ],
      "declines": [["${file.size}", ">", 9437184]],
      "error_on_decline": true
    },
    "preview": {
      "use": "accepted_images",
      "robot": "/image/resize",
      "resize_strategy": "fit",
      "width": 1600,
      "height": 1600
    },
    "exported": {
      "use": ["accepted_images", "preview"],
      "robot": "/s3/store",
      "credentials": "my_s3_credentials",
      "acl": "bucket-default",
      "path": "uploads/${assembly.id}/${file.id}/${file.url_name}"
    }
  }
}

Prueba un video grande desde la subida interrumpida hasta la exportación privada

Para un flujo de trabajo de video, crea una credencial de Template llamada large-upload-output con credenciales IAM cuyo permiso s3:PutObject se limite al prefijo privado upload-tests/. Sigue la configuración de IAM de /s3/store, incluido s3:AbortMultipartUpload para el prefijo de salida. Indica el bucket_region real en las credenciales de Template para evitar una búsqueda de ubicación; las credenciales solo de exportación no necesitan s3:ListBucket ni s3:GetBucketLocation en esa configuración. Sustituye YOUR_AUTH_KEY por la Auth Key del Workspace (no el Auth Secret), guarda el siguiente Template y exige Signature Authentication en ese Template. Usa un bucket privado con Block Public Access habilitado y Object Ownership configurado como Bucket owner enforced. El ajuste acl: "bucket-default" omite la ACL del objeto; el acceso sigue controlado por las políticas de tu bucket y de IAM. Para la prueba, asigna a TRANSLOADIT_UPLOAD_TEMPLATE_ID del endpoint de firma autenticado el ID de este Template de video guardado. Reutiliza la integración de Uppy anterior con un archivo seleccionado por el usuario y una sola instancia de Uppy. Esta política ilustrativa permite un solo video de hasta 254 MiB de bytes de archivo dentro del presupuesto total de 256 MiB para las solicitudes del Template. auth.max_size incluye los bytes de la solicitud inicial de la Assembly más las subidas reanudables. El filtro de confianza del Template rechaza los archivos de más de 254 MiB, lo que deja un margen ilustrativo de 2 MiB para la sobrecarga de las solicitudes. Para esta prueba de video, sustituye la restricción solo de imágenes por allowedFileTypes: ["video/*"], establece maxFileSize: 254 * 1024 * 1024 en la opción restrictions de Uppy core y establece el parámetro firmado auth.max_size en 256 * 1024 * 1024; conserva ambos límites de número de archivos en 1 (maxNumberOfFiles y auth.max_number_of_files). La sobrecarga de las solicitudes varía, por lo que el rechazo del servidor sigue siendo definitivo; la aceptación del navegador no garantiza la creación de la Assembly. Comprueba los límites de subida del Workspace y los formatos de fuente compatibles antes de la prueba. El Template detecta la familia MIME de video, crea una variante MP4 de dimensiones limitadas y exporta esa variante y el original aceptado. No es una política completa de protección frente a malware o de seguridad del contenido.

El fin de la transferencia no es el final del proceso. Con waitForEncoding: true, el navegador espera al procesamiento, pero tu aplicación sigue necesitando un ID de Assembly persistente y notificaciones verificadas o una consulta del Assembly Status si desaparece la pestaña. Un fallo de exportación no debe marcar el recurso como listo. Confirma ASSEMBLY_COMPLETED, la versión de video requerida y ambos objetos privados en S3; compara la suma de comprobación del original exportado con la entrada antes de registrar el éxito. Estos objetos privados no son automáticamente URL públicas de reproducción.

Ejecuta tres controles sin interrupciones y tres pruebas interrumpidas con el mismo video propio de 100–200 MiB. Registra los bytes exactos y SHA-256 del archivo, duración y códecs, versiones del navegador y los paquetes, Template, región, plan y configuración de red. En Chrome DevTools, aplica un perfil de limitación personalizado y registra sus ajustes, cambia a Offline cerca del 25 % de la subida durante 10 segundos y restaura el perfil sin recargar. Ante fallos de red detectados mientras el navegador está sin conexión y quedan reintentos, el plugin tus de Uppy instalado pausa su cola hasta un evento online. Cada reintento sigue consumiendo un intento; el avance de la subida puede reiniciar el contador. La suma de retryDelays no es un límite de tiempo sin conexión. Verifica que una solicitud HEAD indique el Upload-Offset guardado y que las solicitudes PATCH posteriores continúen con el mismo recurso tus. Esto prueba una interrupción emulada en el navegador, no la conmutación por error del servidor ni todas las condiciones de red.

Mide desde el inicio de la subida hasta la primera Assembly completada con los objetos exportados verificados, no solo hasta el último byte subido. Registra también el tiempo desde la reconexión hasta el final, los bytes retransmitidos cuando sean observables, los fallos, las Assemblies duplicadas y el número real de ejecuciones. Es un procedimiento de prueba reproducible, no un resultado de benchmark publicado. Los reintentos limitados pueden agotarse por fallos repetidos de solicitudes, el plazo de subida de la Assembly de ocho horas sigue vigente y este ejemplo en memoria no restaura el estado tras recargar o cerrar la pestaña. Prueba por separado la cancelación, la autorización vencida, los archivos que superan el límite y las credenciales de exportación revocadas. Consulta la API de subidas reanudables para la transición del protocolo y la demo de video, miniaturas y S3 EN (English) para un ejemplo de procesamiento y exportación pública.

{
  "allow_steps_override": false,
  "auth": {
    "key": "YOUR_AUTH_KEY",
    "max_size": 268435456,
    "max_number_of_files": 1
  },
  "steps": {
    ":original": { "robot": "/upload/handle" },
    "accepted_video": {
      "use": ":original",
      "robot": "/file/filter",
      "accepts": [["${file.mime}", "regex", "^video/"]],
      "declines": [["${file.size}", ">", 266338304]],
      "error_on_decline": true
    },
    "rendition": {
      "use": "accepted_video",
      "robot": "/video/encode",
      "ffmpeg_stack": "v7",
      "preset": "web/mp4/360p",
      "width": 640,
      "height": 360,
      "resize_strategy": "fit",
      "result": true
    },
    "exported": {
      "use": ["accepted_video", "rendition"],
      "robot": "/s3/store",
      "credentials": "large-upload-output",
      "acl": "bucket-default",
      "path": "upload-tests/${assembly.id}/${file.id}/${file.url_name}"
    }
  }
}