Prácticas recomendadas

Seguridad

Usa Templates

Los Templates te permiten almacenar las Assembly Instructions en nuestros sistemas, cifradas en reposo. Luego, haces referencia a un Template mediante template_id en tu solicitud a la API. Esto es más seguro que enviar todas las instrucciones en cada solicitud, especialmente si estas contienen credenciales de terceros.

El uso de Templates también mejora la operabilidad:

• Puedes cambiar el comportamiento del procesamiento sin volver a implementar tu aplicación.
• Puedes combinar Templates con Assembly Notifications y reejecuciones de Assembly.
• Aun así, puedes sobrescribir valores específicos durante la ejecución cuando sea necesario.

Más información:

• Templates
• Credenciales de Template

Firma las solicitudes provenientes del navegador

Si las solicitudes pueden generarse del lado del cliente, asume que tu Auth Key podría quedar visible. Usa Signature Authentication y endpoints HTTPS (https://api2.transloadit.com).

Esto protege la integridad de las solicitudes y ayuda a evitar el uso no autorizado.

Usa credenciales con privilegios mínimos

Cuando concedas acceso al almacenamiento (por ejemplo, a S3), limita las credenciales a las acciones y rutas mínimas necesarias. Por ejemplo, unas credenciales de exportación con permisos de solo escritura suelen ser suficientes para 🤖/s3/store.

---

Confiabilidad

Prefiere el procesamiento asíncrono

Si los usuarios deben esperar a que termine todo el procesamiento antes de continuar, el tiempo en cola afecta directamente la experiencia de usuario.

Un patrón mejor consiste en lo siguiente:

1. Primero, sube o importa los archivos.
2. Deja que el procesamiento continúe de forma asíncrona.
3. Usa Assembly Notifications para actualizar tu backend cuando se complete la Assembly.

Esto mantiene tu interfaz receptiva y evita que los usuarios tengan que esperar las conversiones.

Más información: Webhooks y Notifications

No dependas del orden de los resultados

No se garantiza que las posiciones de los arrays de resultados coincidan entre los distintos Steps. Si necesitas vincular los archivos procesados con los originales, relaciónalos mediante sus IDs:

• uploads[*].id
• results[*].original_id

Limita los archivos de entrada por Assembly

Los conjuntos de entrada muy grandes en una sola Assembly pueden tener consecuencias negativas:

• Puedes superar los cupos prioritarios disponibles.
• Aumentas el riesgo de alcanzar el tiempo máximo de ejecución de una Assembly, que es de 8 horas.

Como pauta práctica, limita los archivos de entrada subidos e importados a aproximadamente 500 a 1000 archivos por Assembly, según la cantidad de procesamiento que requiera cada archivo.

Usa ignore_errors de manera intencional

El parámetro ignore_errors de Step permite que una Assembly continúe cuando ciertos errores por archivo sean aceptables, lo que resulta útil para trabajos por lotes o para la extracción opcional de metadatos. También hace que los errores sean menos visibles, así que aplícalo deliberadamente:

• Prefiere arrays específicos como ["meta"] en lugar de true, para que solo se ignoren las fases que esperas tolerar.
• Supervisa ignored_errors y ignored_error_count en el Assembly Status para que tu equipo pueda detectar incluso los errores silenciosos.

Más información: El parámetro ignore_errors

Lee la documentación de cada Robot

Las demostraciones son un excelente punto de partida, pero el comportamiento en producción suele depender de opciones, casos extremos y límites documentados para cada Robot.

Antes del lanzamiento, valida tu flujo exacto con la documentación de Robots correspondiente.

---

Rendimiento y costo

Realiza la entrega mediante Smart CDN

Si entregas recursos procesados a los usuarios finales, usa la Smart CDN de Transloadit.

Ventajas principales:

• Menor latencia gracias a la entrega desde ubicaciones perimetrales.
• Mayor confiabilidad bajo carga.
• Menos procesamiento repetido y tráfico de origen gracias al almacenamiento en caché.

Prácticas recomendadas:

• Configura el comportamiento del almacenamiento en caché en 🤖/file/serve.
• Prefiere las transformaciones basadas en URL cuando sean adecuadas.
• Mantén las claves de caché estables y explícitas.

Más información: Entrega de contenido

Agrupa los archivos en menos Assemblies

Las Assemblies requieren más recursos que las operaciones de archivos individuales. Agrupar archivos en menos Assemblies puede mejorar el rendimiento y reducir la sobrecarga, especialmente en importaciones grandes.

Para las importaciones, mantén el tamaño total del lote en un nivel práctico que facilite los reintentos y preserve la seguridad operativa.

Mantén actualizadas las pilas de encoding

Mantenemos disponibles las pilas antiguas para conservar la compatibilidad con versiones anteriores, pero deberías actualizar periódicamente a pilas más recientes para obtener correcciones, mejoras de rendimiento y actualizaciones de códecs y herramientas.

Revisa la configuración de las pilas al menos una vez al año y haz pruebas antes de cambiar el tráfico de producción.

Establece un límite de facturación

Durante la integración pueden producirse bucles accidentales que generen aumentos inesperados en el uso. Un límite de facturación es una medida de protección útil.

Establécelo lo suficientemente alto como para permitir el crecimiento normal, pero lo suficientemente bajo como para limitar un comportamiento descontrolado e inesperado.