API Médias

Objectif

Uploader, lister et supprimer des médias rattachés à un contexte métier.

Périmètre

Médias génériques DMV, documents acteurs et médias PlayLoop.

Acteurs/applications consommatrices

• DMV public.
• Backoffice.
• PlayLoop admin.
• Mairie.
• AssoSuite.

Authentification requise

À confirmer pour une API média générique. Les routes médias PlayLoop et documents acteurs visibles nécessitent une authentification pour l’écriture.

Permissions/RBAC

• Upload et suppression limités au propriétaire ou gestionnaire du périmètre.
• Les droits doivent être vérifiés côté Laravel.

Endpoints actuels visibles si confirmés

Méthode	Route	Statut
POST	/api/v1/acteurs/{id}/documents	Confirmé.
DELETE	/api/v1/acteurs/{id}/documents/{documentId}	Confirmé.
PATCH	/api/v1/acteurs/{id}/documents/{documentId}/pin	Confirmé.
GET	/api/v1/playloop/acteurs/{id}/media	Confirmé PlayLoop.
POST	/api/v1/playloop/acteurs/{id}/media	Confirmé PlayLoop.
DELETE	/api/v1/playloop/media/{id}	Confirmé PlayLoop.

Endpoints cibles proposés si utile

• POST /api/v1/media pour upload générique.
• DELETE /api/v1/media/{id} pour suppression générique.
• POST /api/v1/media/{id}/attach pour rattachement métier.

Ces routes sont proposées, non confirmées.

Exemple de requête

POST /api/v1/playloop/acteurs/acteur-id/media
Authorization: Bearer <token>
X-App-Source: playloop
Content-Type: multipart/form-data

Exemple de réponse succès

{
  "data": {
    "id": "media-id",
    "filename": "video-campagne.mp4",
    "mimetype": "video/mp4",
    "url": "https://xyz.supabase.co/storage/v1/object/public/documents/media-id",
    "duration_s": 30
  }
}

Exemple d’erreur

{
  "error": "invalid_media",
  "message": "Le fichier envoyé n’est pas accepté."
}

Pagination si applicable

Applicable aux listes de médias.

Rate limiting si applicable

Recommandé sur uploads et suppressions.

Audit/logs si applicable

Obligatoire pour suppressions et médias liés à contenus publics ou campagnes.

Sécurité

• Validation MIME, taille et extension côté Laravel.
• Pas de fichier exécutable.
• Accès privé/public à clarifier par contexte.

État actuel vs cible

Sujet	État actuel	Cible
Documents acteur	Routes visibles.	Harmonisation avec service média.
PlayLoop media	Routes visibles.	Contrat media stable et cacheable.
API générique	Non confirmée.	À définir si mutualisation nécessaire.

Points à confirmer

• Stockage cible.
• Taille et formats autorisés.
• API média générique ou APIs par domaine.