# Médias

Les endpoints Media permettent d’organiser, stocker, téléverser et récupérer des ressources (images, vidéos et documents) dans le tenant.

Tradly prend en charge les hiérarchies structurées de dossiers et de fichiers, les téléversements directs vers S3 par URL pré-signées, les liens de téléchargement pré-signés sécurisés pour les ressources privées et les téléversements multiparties en blocs pour les fichiers volumineux.

## Types de médias

- **`1` (média / fichier)** : ressource fichier individuelle (par exemple `image/jpeg`, `image/png`, `video/mp4`, `application/pdf`).
- **`2` (dossier)** : nœud de répertoire regroupant des fichiers et sous-dossiers. Les éléments racine utilisent `parent: 0`.

## Méthodes de téléversement

1. **URL S3 pré-signée (`/v1/utils/S3signedUploadURL`)** : demande des URL PUT temporaires pour téléverser un ou plusieurs fichiers directement du navigateur ou de l’application mobile vers S3, sans faire transiter les fichiers binaires par le serveur applicatif.
2. **Téléversement multipartie S3 (`/v1/utils/S3multipart/...`)** : adapté aux fichiers volumineux et aux vidéos. Gère l’initialisation, la signature des parties, la finalisation ou l’annulation du téléversement en blocs.
3. **Création d’un enregistrement Media Manager (`/v1/media`)** : enregistre les URL des ressources et les métadonnées des dossiers dans la bibliothèque média du tenant après le stockage des fichiers.

## Important : signature de téléversement et signature de téléchargement

Ces endpoints ont des objectifs et des corps de requête différents. N’utilisez pas le champ `urls` pour téléverser :

| Endpoint | Objectif | Corps de la requête |
|---|---|---|
| `POST /v1/utils/S3signedUploadURL` | Obtenir une URL S3 `PUT` temporaire pour téléverser un nouveau fichier | `{"files":[{"name":"video.mp4","type":"video/mp4"}]}` |
| `POST /v1/utils/S3signedGetURL` | Obtenir une URL temporaire pour télécharger un fichier privé existant | `{"urls":[{"url":"https://..."}]}` |

L’endpoint de téléchargement accepte également `downloadable: true` pour demander au navigateur de télécharger le fichier. Le champ `mime` ne sert ni à choisir l’endpoint ni à créer un téléversement.

### Processus de téléversement

1. Appelez `S3signedUploadURL` avec des entrées `files[]` contenant `name` et le type MIME `type`.
2. Envoyez les octets bruts du fichier par `PUT` à l’URL `signedUrl` renvoyée. Utilisez le type de contenu transmis lors de la demande de l’URL ; n’envoyez pas le jeton Bearer Tradly à S3.
3. Enregistrez le `fileUri` renvoyé dans les champs média de l’annonce. Vous pouvez aussi créer un enregistrement `/v1/media` pour organiser le fichier dans Media Manager.

### Télécharger un fichier privé

Appelez `S3signedGetURL` avec des entrées `urls[]` contenant l’URL du fichier privé existant. Cet endpoint signe un `GET` pour un fichier déjà téléversé ; il ne téléverse, ne copie ni n’enregistre le fichier.

### Lorsque les téléversements hébergés ne sont pas disponibles

Les champs média des annonces peuvent également contenir des URL d’images ou de vidéos hébergées ailleurs. Cette méthode n’utilise pas la signature S3 et convient lorsque les téléversements hébergés ne sont pas disponibles. Une annonce renvoyant une URL externe ne signifie pas que les octets du fichier sont stockés chez Tradly.

Si `S3signedUploadURL` renvoie une erreur serveur (5xx) après validation de la requête, il s’agit d’un problème côté service de téléversement ou serveur, et non d’un périmètre média manquant. Vérifiez la réponse et les journaux du serveur API ; utilisez des URL média externes en solution de repli. Ne réessayez pas la même requête avec `S3signedGetURL` : cet endpoint signe uniquement les téléchargements de fichiers privés.