# Medien

Die Media-Endpunkte ermöglichen das Organisieren, Speichern, Hochladen und Abrufen von Ressourcen wie Bildern, Videos und Dokumenten innerhalb des Tenants.

Tradly unterstützt strukturierte Ordner- und Dateihierarchien, direkte S3-Uploads über vorsignierte URLs, sichere vorsignierte Downloadlinks für private Ressourcen und mehrteilige Block-Uploads für große Dateien.

## Medientypen

- **`1` (Medium / Datei)**: einzelne Dateieressource (z. B. `image/jpeg`, `image/png`, `video/mp4`, `application/pdf`).
- **`2` (Ordner)**: Verzeichnisknoten zum Gruppieren von Dateien und Unterordnern. Elemente auf oberster Ebene verwenden `parent: 0`.

## Upload-Verfahren

1. **Direkte signierte S3-URL (`/v1/utils/S3signedUploadURL`)**: Fordert temporäre vorsignierte PUT-URLs an, damit Browser oder mobile App Dateien direkt zu S3 hochladen können, ohne Binärdaten über den Anwendungsserver zu leiten.
2. **S3-Multipart-Upload (`/v1/utils/S3multipart/...`)**: Geeignet für große Medien und Videos. Verarbeitet Uploads in Blöcken mit Initialisierung, Signierung der Teile, Abschluss oder Abbruch.
3. **Media-Manager-Eintrag erstellen (`/v1/media`)**: Registriert Ressourcen-URLs und Ordnermetadaten nach dem Datei-Upload in der Medienbibliothek des Tenants.

## Wichtig: Signierung für Uploads und Downloads

Diese Endpunkte haben unterschiedliche Zwecke und Anfrageinhalte. Verwenden Sie `urls` nicht für Uploads:

| Endpunkt | Zweck | Anfrageinhalt |
|---|---|---|
| `POST /v1/utils/S3signedUploadURL` | Temporäre S3-`PUT`-URL zum Hochladen neuer Dateidaten abrufen | `{"files":[{"name":"video.mp4","type":"video/mp4"}]}` |
| `POST /v1/utils/S3signedGetURL` | Temporäre Download-URL für eine vorhandene private Datei abrufen | `{"urls":[{"url":"https://..."}]}` |

Der Download-Endpunkt akzeptiert pro URL außerdem optional `downloadable: true`, damit der Browser die Datei herunterlädt. Das Feld `mime` wird weder zur Auswahl des Endpunkts noch für einen Upload verwendet.

### Upload-Ablauf

1. Rufen Sie `S3signedUploadURL` mit `files[]`-Einträgen auf, die `name` und den MIME-Typ `type` enthalten.
2. Senden Sie die unveränderten Dateidaten per `PUT` an die zurückgegebene `signedUrl`. Verwenden Sie denselben Content-Type wie bei der URL-Anfrage und senden Sie das Tradly-Bearer-Token nicht an S3.
3. Speichern Sie die zurückgegebene `fileUri` in den Medienfeldern des Angebots. Optional kann ein `/v1/media`-Eintrag zur Organisation in Media Manager erstellt werden.

### Private Dateien herunterladen

Rufen Sie `S3signedGetURL` mit `urls[]`-Einträgen auf, die die URL der vorhandenen privaten Datei enthalten. Der Endpunkt signiert ein `GET` für eine bereits hochgeladene Datei; er lädt sie nicht hoch, kopiert oder registriert sie nicht.

### Wenn gehostete Uploads nicht verfügbar sind

Medienfelder von Angeboten können auch externe Bild- oder Video-URLs enthalten. Diese URL-basierte Methode nutzt keine S3-Signierung und ist geeignet, wenn gehostete Uploads nicht verfügbar sind. Eine externe URL in einer Angebotsantwort bedeutet nicht, dass Tradly die Dateidaten speichert.

Wenn `S3signedUploadURL` nach erfolgreicher Validierung einen Serverfehler (5xx) zurückgibt, liegt ein Problem beim Uploaddienst oder Backend vor, kein fehlender Medienbereich. Prüfen Sie Antwort und API-Serverprotokolle; externe Medien-URLs können als Ausweichmöglichkeit dienen. Wiederholen Sie die Anfrage nicht mit `S3signedGetURL` – dieser Endpunkt signiert nur Downloads privater Dateien.