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 la aplicación fuera de la ruta de los datos mientras un flujo de trabajo valida, transforma y exporta los archivos a un almacenamiento propio.

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.

Separa el almacenamiento persistente del procesamiento de subidas

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 conserva los resultados temporales durante al menos 24 horas, mientras que sus URLs de acceso pueden vencer después de unas horas. Exporta los archivos que deban conservarse. Las URLs temporales solo sirven para recuperaciones a corto plazo, no para incrustar archivos ni entregarlos 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.

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 se vuelve 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 un servicio no elimina la responsabilidad de la aplicación: las comprobaciones de inquilinos, la autorización, los registros de recursos, la retención, la publicación y la gestión de incidentes siguen bajo tu responsabilidad. Un diseño híbrido suele funcionar mejor, con almacenamiento y estado de negocio propios alrededor de una capa gestionada de transferencia y procesamiento.

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 de Node transloadit en el servidor. Inicializa 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 de firma. Rechaza las solicitudes no autenticadas o no autorizadas; la función auxiliar no es un endpoint de autenticación.

El ejemplo permite una imagen de hasta 10 MiB en formato JPEG, PNG o WebP. Las restricciones de Uppy ofrecen información inmediata, mientras que los límites firmados auth.max_size y auth.max_number_of_files y el filtro del Template en el servidor hacen cumplir la política. 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.

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: 10 * 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'

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 el tamaño del archivo y 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}", ">", 10485760]],
      "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 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 IAM de /s3/store para los permisos s3:ListBucket y s3:GetBucketLocation a nivel de bucket; no hace falta consultar la región cuando la credencial de Template incluye bucket_region. Sustituye YOUR_AUTH_KEY por la Auth Key del workspace (no su 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 en el 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 instancia de Uppy. Los límites del Template de 256 MiB y un archivo son reglas de ejemplo. Refleja esos límites en la opción restrictions de Uppy core (maxFileSize, maxNumberOfFiles) para dar aviso temprano en el selector; las comprobaciones del servidor siguen siendo necesarias. Para esta prueba de video, sustituye la restricción de imágenes por allowedFileTypes: ["video/*"] y establece tanto maxFileSize en el navegador como auth.max_size en los parámetros firmados en 256 * 1024 * 1024; conserva ambos límites de número de archivos en 1. Comprueba los límites de subida del workspace y los formatos de origen compatibles antes de la prueba. El Template detecta la familia MIME de video, crea una versión MP4 de dimensiones limitadas y exporta esa versión y el original aceptado. No es una política completa de protección frente a malware o contenido inapropiado.

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/"]],
      "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}"
    }
  }
}