Organizzazione

Dettaglio organizzazione

Restituisce il profilo, il piano (con i limiti effettivi), l'ID dell'utente principale e i conteggi di membri, modelli e viewer. Accessibile a qualsiasi membro dell'organizzazione tramite token di sessione, oppure a un servizio backend tramite API key.

Parametri del percorso

Esempio di richiesta

GET https://api.spectraholo.it/v1/organization/42

Risposta200

{
  "organization": {
    "id": 42,
    "name": "ACME Corp",
    "description": "Holographic visualization platform",
    "logoUrl": "https://api.spectraholo.it/orgs/42/logo.png",
    "planId": 2,
    "planName": "Business",
    "maxUsers": 50,
    "maxStorageGb": 25,
    "maxViewers": 15,
    "maxModels": 150,
    "mainUserId": "550e8400-e29b-41d4-a716-446655440000",
    "memberCount": 12,
    "modelCount": 25,
    "viewerCount": 8,
    "createdAt": "2026-01-15T10:30:00Z"
  }
}

Errori

• 401Nessun token di sessione valido o backend API key forniti
• 403Il token di sessione è valido ma il livello di authority dell'utente è inferiore a AUTHORITY_VIEW (0)
• 404L'organizzazione con l'ID indicato non esiste
• 502Il server di autenticazione è irraggiungibile o ha restituito un errore

Aggiorna nome/descrizione

Aggiorna il nome e/o la descrizione dell'organizzazione. L'autorizzazione richiede una backend API key (server-to-server) oppure un token di sessione valido di un utente con authority ADMIN (livello 3) all'interno dell'organizzazione. Entrambi i campi sono facoltativi ma almeno uno deve essere fornito.

Parametri del percorso

Corpo della richiesta · application/json

Esempio di corpo (JSON)

{
  "name": "ACME S.r.l.",
  "description": "Vetrine olografiche per il retail"
}

Risposta200

{
  "message": "Organization profile updated."
}

Errori

• 400Il corpo della richiesta non è JSON valido
• 400Il campo 'name' è fornito ma non è una stringa
• 400Il campo 'description' è fornito ma non è una stringa
• 400Il campo 'name' è fornito ma è vuoto o più lungo di 32 caratteri dopo il trim
• 400Il campo 'description' è fornito ma è vuoto o più lungo di 256 caratteri dopo il trim
• 400Né 'name' né 'description' sono forniti nel corpo della richiesta
• 401Nessun token di sessione valido o backend API key fornito, oppure token di sessione non valido/scaduto
• 403Il token di sessione è valido ma il livello di authority dell'utente è inferiore ad ADMIN (3)
• 404L'organizzazione con l'ID indicato non esiste
• 502Il server di autenticazione è irraggiungibile o restituisce un errore durante la validazione della sessione

Logo dell'organizzazione

Recupera l'immagine del logo di un'organizzazione. Il logo viene servito con header di sicurezza (nosniff, CSP sandbox) e con caching abilitato. Restituisce i byte grezzi dell'immagine con l'header Content-Type appropriato, determinato dal contenuto del file e non dalla dichiarazione del client.

Parametri del percorso

Esempio di richiesta

GET https://api.spectraholo.it/v1/organization/42/logo

Risposta200

Raw image bytes (PNG, JPEG, GIF, or WEBP) with headers: Content-Type: image/png (or appropriate MIME type), Content-Disposition: inline, X-Content-Type-Options: nosniff, Content-Security-Policy: default-src 'none'; sandbox, Cache-Control: public, max-age=3600

Errori

• 404Logo non trovato per l'organizzazione indicata
• 500Errore interno del server

Carica il logo

Carica e aggiorna l'immagine del logo di un'organizzazione. Richiede una richiesta multipart/form-data con il file del logo nel campo 'logo'. Il content-type viene verificato dai magic bytes del file (per sicurezza sono consentiti solo i formati raster PNG, JPEG, GIF, WEBP; niente SVG o HTML per prevenire XSS). Richiede authority ADMIN (>= 3) o una backend API key.

Parametri del percorso

Corpo della richiesta · multipart/form-data

Esempio di richiesta

POST https://api.spectraholo.it/v1/organization/42/logo

# Campi del modulo (multipart/form-data)
logo = @logo.png

Risposta200

{
  "success": true,
  "message": "Logo updated.",
  "logoUrl": "https://api.spectraholo.it/logos/org-123-abc123.png"
}

Errori

• 400Richiesta non valida: corpo multipart/form-data mancante o non valido, campo logo assente, oppure formato immagine non supportato (sono ammessi solo PNG, JPEG, GIF, WEBP)
• 401Autenticazione richiesta: nessun token di sessione valido o backend API key fornito
• 403Authority insufficiente: l'utente della sessione ha un livello di authority < 3 (ADMIN)
• 413Logo troppo grande: il file supera il limite di 5 MB
• 502Servizio backend (server di autenticazione) irraggiungibile durante la validazione della sessione
• 500Errore interno del server

Elimina l'organizzazione

Rimuove definitivamente l'organizzazione e propaga l'eliminazione a tutti i membri, modelli e viewer. I dati vengono rimossi dal database locale e propagati al server di autenticazione e al server delle risorse. L'operazione è idempotente dal punto di vista del client: restituisce 200 anche se l'organizzazione non esiste più. Sono supportate due modalità di autenticazione: backend API key oppure la sessione dell'utente principale dell'organizzazione.

Parametri del percorso

Esempio di richiesta

DELETE https://api.spectraholo.it/v1/organization/42

Risposta200

{
  "message": "Organization successfully deleted!"
}

Errori

• 401Nessuna backend API key valida o token di sessione fornito
• 403Il token di sessione è valido ma l'utente non è l'utente principale dell'organizzazione
• 404L'organizzazione non esiste (nota: idempotente; restituisce comunque 200 dal punto di vista del client)
• 502Il server di autenticazione o il server delle risorse è irraggiungibile o ha restituito un errore durante la propagazione