# Contenido multimedia

Los endpoints Media permiten organizar, almacenar, subir y recuperar recursos como imágenes, vídeos y documentos dentro del tenant.

Tradly admite jerarquías estructuradas de carpetas y archivos, cargas directas a S3 mediante URL firmadas, enlaces de descarga firmados para recursos privados y cargas multipartes por bloques para archivos grandes.

## Tipos de contenido multimedia

- **`1` (medio / archivo)**: recurso de archivo individual (por ejemplo, `image/jpeg`, `image/png`, `video/mp4`, `application/pdf`).
- **`2` (carpeta)**: nodo de directorio para agrupar archivos y subcarpetas. Los elementos de nivel raíz usan `parent: 0`.

## Métodos de carga

1. **URL firmada directa de S3 (`/v1/utils/S3signedUploadURL`)**: solicita URL PUT temporales para cargar uno o varios recursos directamente desde el navegador o la aplicación móvil del cliente a S3, sin pasar los datos binarios por el servidor de la aplicación.
2. **Carga multipartes de S3 (`/v1/utils/S3multipart/...`)**: ideal para archivos grandes o vídeos. Gestiona cargas por bloques mediante inicialización, firma de partes, finalización o cancelación.
3. **Crear un registro en Media Manager (`/v1/media`)**: registra las URL de los recursos y los metadatos de carpetas en la biblioteca multimedia del tenant después de subir los archivos al almacenamiento.

## Importante: firma de carga y firma de descarga

Estos endpoints tienen cuerpos y propósitos distintos. No uses el campo `urls` para cargar archivos:

| Endpoint | Propósito | Cuerpo de la solicitud |
|---|---|---|
| `POST /v1/utils/S3signedUploadURL` | Obtener una URL S3 `PUT` temporal para cargar nuevos bytes de archivo | `{"files":[{"name":"video.mp4","type":"video/mp4"}]}` |
| `POST /v1/utils/S3signedGetURL` | Obtener una URL temporal de descarga para un archivo privado existente | `{"urls":[{"url":"https://..."}]}` |

El endpoint de descarga también admite `downloadable: true` por URL para solicitar que el navegador descargue el archivo. El campo `mime` no se usa para seleccionar el endpoint ni para crear una carga.

### Flujo de carga

1. Llama a `S3signedUploadURL` con elementos `files[]` que incluyan `name` y el tipo MIME `type`.
2. Envía los bytes sin procesar mediante `PUT` a la `signedUrl` devuelta. Usa el tipo de contenido empleado para solicitar la URL; no envíes el token Bearer de Tradly a S3.
3. Guarda el `fileUri` devuelto en los campos multimedia del anuncio. Opcionalmente, crea un registro `/v1/media` para organizar el archivo en Media Manager.

### Descargar archivos privados

Llama a `S3signedGetURL` con elementos `urls[]` que contengan la URL del archivo privado existente. Este endpoint firma una solicitud `GET` para un archivo ya cargado; no carga, copia ni registra el archivo.

### Cuando las cargas alojadas no están disponibles

Los campos multimedia de los anuncios también pueden contener URL externas de imágenes o vídeos. Este método basado en URL no utiliza firma S3 y sirve como alternativa cuando no están disponibles las cargas alojadas. Que la respuesta del anuncio incluya una URL externa no significa que Tradly almacene los bytes del archivo.

Si `S3signedUploadURL` devuelve un error del servidor (5xx) después de validar la solicitud, se trata de un problema del servicio de carga o del backend, no de un ámbito multimedia ausente. Comprueba la respuesta y los registros del servidor API; usa URL multimedia externas como alternativa. No repitas la solicitud con `S3signedGetURL`: ese endpoint solo firma descargas de archivos privados.