Avvertenza: questa documentazione è stata ricavata tramite analisi del traffico di rete del sito ufficiale nuvola.madisoft.it. Non esiste documentazione pubblica ufficiale. I dettagli potrebbero cambiare senza preavviso in seguito ad aggiornamenti di Madisoft.

• Panoramica
• Autenticazione
• Convezioni comuni
• Endpoint
  • Studenti
  • Frazioni temporali (quadrimestri)
  • Voti
  • Assenze
  • Compiti
  • Note disciplinari
  • Notifiche
  • Pagamenti
  • Argomenti lezione
  • Eventi
• Modelli di risposta
• Gestione errori

L'autenticazione avviene in 5 fasi sequenziali. Non esiste un endpoint OAuth standard: Nuvola usa una sessione web tradizionale dalla quale viene poi ricavato un JWT.

GET /login

Risposta: pagina HTML. Estrarre il valore dell'input nascosto:

<input name="_csrf_token" value="TOKEN_QUI" />

POST /login_check
Content-Type: application/x-www-form-urlencoded

Body (form-urlencoded):

Risposta attesa: HTTP 302 (redirect) o 200. Un HTTP 401/403 indica credenziali errate.

I cookie di sessione vengono impostati automaticamente in questa fase e devono essere mantenuti per le richieste successive.

GET /area-studente

Necessario per stabilire il contesto di sessione lato server. Non restituisce dati utili.

GET /api-studente/v1/login-from-web

Risposta:

"eyJhbGciOiJSUzI1NiJ9..."

Il token può essere restituito come stringa diretta oppure come oggetto:

{ "token": "eyJhbGciOiJSUzI1NiJ9..." }

Il JWT ha una scadenza effettiva di circa 28 minuti.

Tutte le successive chiamate API devono includere l'header:

Authorization: Bearer <jwt_token>

Il parametro query contextAlunno=<alunnoId> è richiesto dalla maggior parte degli endpoint.

La maggior parte degli endpoint restituisce un oggetto con la chiave valori:

{
  "listeValori": null,
  "opzioni": [],
  "valori": [ ... ],
  "paginatore": null
}

In alcuni casi i dati sono restituiti come array diretto [...].

GET /api-studente/v1/alunni

Restituisce gli studenti associati all'account autenticato (di solito uno solo per account famiglia).

Risposta:

{
  "valori": [
    {
      "id": 12345,
      "nome": "Mario",
      "cognome": "Rossi",
      "nomeCompleto": "Mario Rossi",
      "classe": "3A",
      "scuola": "Istituto Esempio"
    }
  ]
}

GET /api-studente/v1/alunno/{id}/frazioni-temporali
     ?contextAlunno={id}

Restituisce i periodi dell'anno scolastico (trimestri, quadrimestri, intero anno).

Risposta:

{
  "valori": [
    { "id": 258, "nome": "1° QUADRIMESTRE", "corrente": false },
    { "id": 259, "nome": "2° QUADRIMESTRE", "corrente": true },
    { "id": 260, "nome": "INTERO ANNO",     "corrente": false }
  ]
}

GET /api-studente/v1/alunno/{id}/frazione-temporale/{frazioneId}/voti/materie
     ?contextAlunno={id}

Restituisce le materie con i rispettivi voti e la media calcolata per il periodo selezionato.

Risposta:

{
  "valori": [
    {
      "id": 101,
      "materia": "MATEMATICA",
      "media": "7,50",
      "voti": [
        {
          "id": 9001,
          "data": "2025-11-10",
          "valutazione": "8",
          "valore": "8",
          "tipo": "S",
          "descrizione": "Verifica algebra",
          "docente": "Prof. Bianchi",
          "visibile": true
        }
      ]
    }
  ]
}

Campi materia:

Campi voto:

GET /api-studente/v1/alunno/{id}/frazione-temporale/{frazioneId}/voti/materia/{materiaId}
     ?contextAlunno={id}

Restituisce i voti dettagliati di una sola materia.

Risposta: medesima struttura di un singolo elemento valori dell'endpoint precedente, con eventuali campi aggiuntivi.

GET /api-studente/v1/alunno/{id}/voti
     ?contextAlunno={id}

Endpoint alternativo per ottenere tutti i voti senza raggruppamento per materia.

GET /api-studente/v1/alunno/{id}/assenze
     ?contextAlunno={id}

Query parameter opzionale:

Risposta:

{
  "valori": [
    {
      "id": 5001,
      "data": "2025-10-15",
      "tipo": "assenza",
      "giustificata": true,
      "dataGiustificazione": "2025-10-17",
      "motivazione": "Malattia"
    }
  ]
}

Campo tipo:

GET /api-studente/v1/alunno/{id}/compito/elenco/{date}
     ?contextAlunno={id}

Il parametro {date} deve essere nel formato DD-MM-YYYY (es. 10-03-2026).

Restituisce i compiti assegnati per la data specificata.

Risposta:

{
  "valori": [
    {
      "id": 7001,
      "materia": "ITALIANO",
      "descrizione": ["Leggere capitolo 5", "Rispondere alle domande"],
      "dataConsegna": "2026-03-12",
      "docente": "Prof.ssa Verdi"
    }
  ]
}

⚠️ Il campo descrizione può essere sia una string che un List<String>. Il parsing deve gestire entrambi i casi.

GET /api-studente/v1/alunno/{id}/note
     ?contextAlunno={id}

Query parameter opzionale:

Risposta:

{
  "valori": [
    {
      "id": 3001,
      "data": "2025-12-01",
      "tipo": "nota",
      "testo": "Comportamento scorretto durante la lezione",
      "docente": "Prof. Neri"
    }
  ]
}

Campo tipo:

GET /api-studente/v1/alunno/{id}/notifiche/conteggio
     ?contextAlunno={id}

Risposta:

{ "count": 3 }

GET /api-studente/v1/alunno/{id}/pagamenti
     ?contextAlunno={id}

Restituisce i pagamenti (contributi scolastici, gite, ecc.) associati allo studente.

Endpoint definito ma non ancora implementato nell'interfaccia dell'app.

GET /api-studente/v1/alunno/{id}/argomento-lezione/elenco/{date}
     ?contextAlunno={id}

Restituisce gli argomenti trattati in classe per la data specificata (formato DD-MM-YYYY).

Endpoint definito ma non ancora implementato nell'interfaccia dell'app.

GET /api-studente/v1/alunno/{id}/eventi-classe
     ?contextAlunno={id}

GET /api-studente/v1/alunno/{id}/eventi-classe-materia
     ?contextAlunno={id}

GET /api-studente/v1/alunno/{id}/eventi-alunno
     ?contextAlunno={id}

Questi endpoint sono definiti nelle costanti ma non ancora implementati nell'interfaccia dell'app.

Quasi tutti gli endpoint restituiscono:

{
  "listeValori": null,
  "opzioni": [],
  "valori": [ ... ],
  "paginatore": null
}

Alcuni endpoint (specialmente per strutture dati semplici) restituiscono direttamente un array [...] o un oggetto singolo.

Il campo paginatore è presente ma risulta null nella maggior parte delle risposte osservate. Non è chiaro se la paginazione sia implementata o meno.

In caso di token JWT scaduto, ripetere le fasi 1–5 del flusso di autenticazione con le credenziali salvate per ottenere un nuovo token.

Documentazione redatta tramite analisi del traffico di rete. Ultimo aggiornamento: marzo 2026.