UC-015 — Upload e Gestione Media

Campo	Valore
ID	UC-015
Obiettivo	Caricare, elencare e rimuovere file media dalla libreria
Canale	RCS, WhatsApp
Complessità	Base
Tempo stimato	10 minuti
API coinvolte	`POST /api/partner-gateway/v1/media`, `GET /api/partner-gateway/v1/media`, `DELETE /api/partner-gateway/v1/media/{id}`

Scenari reali

Caricare immagine per RCS: L'azienda FashionOutlet carica le immagini della nuova collezione per inviarle tramite Rich Card RCS.
Gestire libreria media: Il team marketing di TravelDream organizza la propria libreria di immagini promozionali, verificando quali sono ancora in uso.
Eliminare media obsoleti: A fine campagna, il team rimuove le immagini stagionali per mantenere la libreria ordinata.

Flusso di gestione media

Il diagramma mostra il ciclo di vita di un file media: upload, consultazione e rimozione.

Prerequisiti

API Key attiva con permessi di gestione media
File immagine in formato supportato (JPEG, PNG, GIF — max 5 MB)
Per RCS: dimensioni consigliate 1440x1440 px (immagini quadrate) o 1440x720 px (landscape)

Step 1 — Carica un file media

Invia il file tramite multipart form-data.

curl -X POST https://api.qlara.ai/api/partner-gateway/v1/media \
  -H "X-Api-Key: YOUR_API_KEY" \
  -F "file=@/path/to/promo-estate-2026.jpg" \
  -F "name=promo-estate-2026" \
  -F "description=Banner promozione estate 2026 - Collezione mare"

Response — Media caricato

La risposta è un array con il media creato:

[
  {
    "id": 5821,
    "key": "5b0e72c4/3f9a1d7e6c2b48a59e0d1f7c8b6a4e21.jpg",
    "thumbnailKey": "5b0e72c4/a7c4e19b2d5f40c3961e8b0d2f4a6c13.jpg",
    "companyId": 1287,
    "userId": 3410,
    "name": "promo-estate-2026",
    "description": "Banner promozione estate 2026 - Collezione mare",
    "filename": "promo-estate-2026.jpg",
    "size": 245760,
    "type": "IMAGE",
    "mimeType": "image/jpeg",
    "source": 1,
    "metadata": null,
    "folderId": null,
    "userEmail": null,
    "userFirstName": null,
    "userMiddleName": null,
    "userLastName": null,
    "url": "https://storage.example.com/5b0e72c4/3f9a1d7e6c2b48a59e0d1f7c8b6a4e21.jpg?X-Amz-Date=20260409T090000Z&X-Amz-Expires=3600&X-Amz-Signature=2bbf02e2c8274379a166bb6eb376bcbdb161455399b552eabd3c566b31777738",
    "thumbnailUrl": "https://storage.example.com/5b0e72c4/a7c4e19b2d5f40c3961e8b0d2f4a6c13.jpg?X-Amz-Date=20260409T090000Z&X-Amz-Expires=3600&X-Amz-Signature=e9c171c6c46a3a250b4e2ba18f76cb7950e31017e7d87092c7cde91d4540d08b",
    "cdnUrl": null,
    "cdnThumbnailUrl": null,
    "public": false,
    "creationDate": "2026-04-09 09:00:00.000+0000",
    "lastUpdateDate": "2026-04-09 09:00:00.000+0000"
  }
]

Usa l'URL nei messaggi RCS

Il campo url è un link firmato al file: usalo subito come mediaUrl di una Rich Card RCS, ma non salvarlo nel tuo CMS, perché scade. Salva invece l'id: quando ti serve di nuovo il link, prendi l'url dello stesso media da GET /media, che ne firma uno nuovo a ogni chiamata.

Dietro le quinte — Elaborazione del file

Validazione: Il gateway verifica tipo MIME, dimensioni del file e risoluzione dell'immagine.
Ottimizzazione: L'immagine viene compressa mantenendo la qualita visiva (JPEG quality 85%) e convertita in formati ottimali per ogni canale.
Storage: Il file viene salvato nello storage dei media con la chiave key. I file caricati tramite API sono privati: url e thumbnailUrl sono link firmati che scadono, e cdnUrl resta null.
Thumbnail: Viene generata automaticamente una versione ridotta (300x300 px) per le anteprime nella dashboard.
Scansione: Il file viene analizzato per verificare l'assenza di contenuti malevoli (malware scan).

Step 2 — Elenca i media caricati

Recupera la lista dei file presenti nella tua libreria media. La lista è paginata (page, limit, 10 elementi di default) e ordinata per id crescente, a meno che tu non passi sortBy e sortOrder.

curl -X GET https://api.qlara.ai/api/partner-gateway/v1/media \
  -H "X-Api-Key: YOUR_API_KEY"

Response — Lista media

{
  "data": [
    {
      "id": 5478,
      "key": "5b0e72c4/c2e8f05a7d3b41f69a8e0c5d7b2f9e14.png",
      "thumbnailKey": "5b0e72c4/e91b4d7c0a3f42e8b6d5c1a9f0e7d3b2.png",
      "companyId": 1287,
      "userId": 3410,
      "name": "logo-brand-2026",
      "description": null,
      "filename": "logo-brand-2026.png",
      "size": 52480,
      "type": "IMAGE",
      "mimeType": "image/png",
      "source": 1,
      "metadata": null,
      "folderId": 214,
      "userEmail": "chiara.verdi@example.it",
      "userFirstName": "Chiara",
      "userMiddleName": null,
      "userLastName": "Verdi",
      "url": "https://storage.example.com/5b0e72c4/c2e8f05a7d3b41f69a8e0c5d7b2f9e14.png?X-Amz-Date=20260409T093000Z&X-Amz-Expires=3600&X-Amz-Signature=6a23f4aaac740c71ca1c46aff614fe18db294e3fbbf2358db3a5a2c71d9ed24c",
      "thumbnailUrl": "https://storage.example.com/5b0e72c4/e91b4d7c0a3f42e8b6d5c1a9f0e7d3b2.png?X-Amz-Date=20260409T093000Z&X-Amz-Expires=3600&X-Amz-Signature=ab09a190584dbfe3036f6817bab4c3ee15b5b5c3d878e63ddea5ab3098700ed6",
      "cdnUrl": null,
      "cdnThumbnailUrl": null,
      "public": false,
      "creationDate": "2026-03-15 08:30:00.000+0000",
      "lastUpdateDate": "2026-03-15 08:30:00.000+0000"
    },
    {
      "id": 5821,
      "key": "5b0e72c4/3f9a1d7e6c2b48a59e0d1f7c8b6a4e21.jpg",
      "thumbnailKey": "5b0e72c4/a7c4e19b2d5f40c3961e8b0d2f4a6c13.jpg",
      "companyId": 1287,
      "userId": 3410,
      "name": "promo-estate-2026",
      "description": "Banner promozione estate 2026 - Collezione mare",
      "filename": "promo-estate-2026.jpg",
      "size": 245760,
      "type": "IMAGE",
      "mimeType": "image/jpeg",
      "source": 1,
      "metadata": null,
      "folderId": null,
      "userEmail": "chiara.verdi@example.it",
      "userFirstName": "Chiara",
      "userMiddleName": null,
      "userLastName": "Verdi",
      "url": "https://storage.example.com/5b0e72c4/3f9a1d7e6c2b48a59e0d1f7c8b6a4e21.jpg?X-Amz-Date=20260409T093000Z&X-Amz-Expires=3600&X-Amz-Signature=a475228f13f075b0f51ce1615bc4eb5c3b8a46eb56551701cc70d82af0e15898",
      "thumbnailUrl": "https://storage.example.com/5b0e72c4/a7c4e19b2d5f40c3961e8b0d2f4a6c13.jpg?X-Amz-Date=20260409T093000Z&X-Amz-Expires=3600&X-Amz-Signature=a3ac2131d57c6d2fcc79029fe246d9604f13e35c13711a19bcf689bc5f856c5e",
      "cdnUrl": null,
      "cdnThumbnailUrl": null,
      "public": false,
      "creationDate": "2026-04-09 09:00:00.000+0000",
      "lastUpdateDate": "2026-04-09 09:00:00.000+0000"
    }
  ],
  "page": 0,
  "limit": 10,
  "totalCount": 2,
  "totalPages": 1
}

Step 3 — Elimina un media obsoleto

Rimuovi un file dalla libreria quando non è più necessario, usando il suo id.

curl -X DELETE https://api.qlara.ai/api/partner-gateway/v1/media/5478 \
  -H "X-Api-Key: YOUR_API_KEY"

Response — Media eliminato

L'API risponde 204 No Content, con body vuoto.

Dietro le quinte — Eliminazione

Eliminazione definitiva: Il file viene rimosso dalla libreria e dallo storage dei media. L'operazione non è reversibile.
Messaggi già inviati: Non subiscono conseguenze, perché il contenuto del media è stato consegnato al momento dell'invio.
Riferimenti futuri: Ogni messaggio o campagna che fa ancora riferimento al media eliminato non riuscirà a recuperare il file. Prima di eliminarlo, verifica che non sia usato da una campagna programmata o da un template non ancora inviato.
Eliminazioni rifiutate: 404 se l'id non è nella tua libreria, 409 se il media è pubblico o ancora usato da un post social, 400 se il file è ancora in fase di caricamento.

Risultato atteso

Step	Azione	Risultato
1	`POST /media`	File caricato, `id`, `key` e `url` restituiti
2	`GET /media`	Lista paginata dei media con metadati
3	`DELETE /media/{id}`	Media rimosso, `204 No Content`

Esempio completo end-to-end

Scenario FashionOutlet: carica immagine e usala in una Rich Card RCS.

# 1. Carica l'immagine promozionale
MEDIA_URL=$(curl -s -X POST https://api.qlara.ai/api/partner-gateway/v1/media \
  -H "X-Api-Key: YOUR_API_KEY" \
  -F "file=@./summer-collection.jpg" \
  -F "name=summer-collection-2026" | jq -r '.[0].url')

echo "Media URL: $MEDIA_URL"

# 2. Verifica che sia nella libreria (dal più recente)
curl -s -X GET "https://api.qlara.ai/api/partner-gateway/v1/media?sortBy=id&sortOrder=desc" \
  -H "X-Api-Key: YOUR_API_KEY" | jq '.data[] | select(.name == "summer-collection-2026")'

# 3. Usa subito l'URL nella Rich Card RCS (vedi UC-002): il link è firmato e scade
echo "Pronto per l'invio RCS con mediaUrl: $MEDIA_URL"

Varianti

Upload di un video

Per i canali che supportano video (RCS), carica file MP4 (max 10 MB):

curl -X POST https://api.qlara.ai/api/partner-gateway/v1/media \
  -H "X-Api-Key: YOUR_API_KEY" \
  -F "file=@/path/to/promo-video.mp4" \
  -F "name=promo-video-estate" \
  -F "description=Video promozionale 15 secondi"

Errori comuni

413 Payload Too Large — File troppo grande

{
  "status": "fail",
  "data": {
    "file": "File size exceeds maximum allowed (5 MB for images, 10 MB for videos)"
  }
}

Soluzione: Comprimi l'immagine o riducine la risoluzione. Per le Rich Card RCS, 1440px di larghezza e sufficiente.

415 Unsupported Media Type — Formato non supportato

{
  "status": "fail",
  "data": {
    "file": "Unsupported media type. Allowed: image/jpeg, image/png, image/gif, video/mp4"
  }
}

Soluzione: Converti il file in uno dei formati supportati prima dell'upload.

Prossimi passi

UC-002 — Invio RCS Rich Card: Usa il media caricato in una Rich Card RCS
UC-003 — Invio WhatsApp Template: Associa media a template WhatsApp
UC-014 — API Key Management: Gestisci le chiavi di accesso

Riferimenti

API Reference — Media

Scenari reali​

Flusso di gestione media​

Prerequisiti​

Step 1 — Carica un file media​

Response — Media caricato​

Step 2 — Elenca i media caricati​

Response — Lista media​

Step 3 — Elimina un media obsoleto​

Response — Media eliminato​

Risultato atteso​

Esempio completo end-to-end​

Varianti​

Upload di un video​

Errori comuni​

413 Payload Too Large — File troppo grande​

415 Unsupported Media Type — Formato non supportato​

Prossimi passi​

Riferimenti​