Token API: collega il tuo negozio o sito web, rinnova e revoca
Usa l'API di Acatudy per creare studenti e dare loro accesso dal tuo negozio online o da un sito esterno. Come ottenere un token, cosa può fare, quando scade e come rinnovarlo o revocarlo.
In questa pagina
In questo argomento 7
- Il tuo abbonamento ad Acatudy: piani, prezzi, fatture e disdetta
- Archiviazione e limiti del piano: cosa conta, dove vederlo e come liberare spazio
- Proteggi il tuo account: password, sessioni e disconnessione
- Privacy, cookie e dati degli studenti (GDPR): cosa fa Acatudy per te
- Token API: collega il tuo negozio o sito web, rinnova e revoca
- Backup: cosa include il tuo piano e come ripristinare la tua accademia
- Cestino: ripristina domande, argomenti, unità ed esami eliminati
In questa guida
- A cosa serve l'API e come ottenere un token.
- Permessi e scadenza.
- Rinnovare un token prima che scada, oppure revocarlo.
- Endpoint, limiti e codici di errore per il tuo sviluppatore.
A cosa serve l'API
L'API permette a un sistema esterno di agire sulla tua accademia senza che nessuno debba digitare nel pannello. Il caso tipico: vendi un corso nel tuo negozio online e, quando il pagamento va a buon fine, il negozio crea lo studente in Acatudy e gli dà accesso al corso o alle materie giuste. Se vendi solo con il checkout di Acatudy, non ti serve l'API: vedi Vendi l'accesso ai tuoi corsi con Stripe.
Ottenere un token
-
Apri un ticket di assistenza
I token li emette il nostro team, così che ciascuno abbia un titolare e uno scopo chiari. In Aiuto → Assistenza indicaci per quale integrazione serve e se deve solo leggere dati oppure anche creare studenti e iscrizioni.
-
Copia il token quando te lo consegniamo
Un token viene mostrato una sola volta. Incollalo subito nel tuo negozio o nella tua integrazione e custodiscilo come una password: mai nel codice pubblico del tuo sito, in un documento condiviso o in una catena di email.
-
Trovalo in Token API
Vai a La mia accademia → Generale → Dettagli e dominio e apri la scheda API. Vedrai Nome, Permessi, Scadenza e Ultimo utilizzo di ogni token, con i pulsanti Rinnova e Revoca.
Token API: scadenza e ultimo utilizzo a colpo d'occhio.
Solo il titolare dell'accademia e gli amministratori possono aprire questa pagina. I docenti non vedono i token.
Permessi e scadenza
| Permesso | Consente |
|---|---|
| read | Verificare la connessione, leggere l'accademia, il suo piano e il suo utilizzo, le sue materie, e cercare uno studente per email. |
| write | Tutto quanto sopra, più creare studenti e creare o annullare iscrizioni. |
Ogni token scade dopo 1 anno (consigliato), 90 giorni oppure, su tua richiesta, mai. I token che scadono impongono una rotazione periodica: se uno viene divulgato, smette di funzionare da solo.
Promemoria di scadenza
- Inviamo un'email ai titolari e agli amministratori dell'accademia 30, 7 e 1 giorno prima della scadenza di un token.
- Da 30 giorni prima, ogni pagina del pannello mostra un banner con Rinnova e Vedi i token.
- Una volta scaduto, l'integrazione riceve un errore (
token_expired) finché non lo rinnovi.
Rinnovare o revocare un token
-
Clicca su Rinnova
Viene creato un nuovo token con lo stesso nome, gli stessi permessi e la stessa durata (1 anno se quello vecchio non scadeva mai). Viene mostrato una sola volta, con un pulsante Copia: «Nuovo token creato. Copialo ora: non verrà mostrato di nuovo.»
-
Incollalo nella tua integrazione
Nel frattempo il vecchio token continua a funzionare, quindi nulla si interrompe mentre fai il cambio.
-
Revoca il vecchio token
Quando hai verificato che l'integrazione funziona con il nuovo token, clicca su Revoca il vecchio token (oppure su Revoca nella sua riga). La revoca è immediata: «Revocare questo token? Le integrazioni che lo usano smetteranno di funzionare.»
Se un token viene divulgato, revocalo subito
Se un token è finito in un luogo pubblico, o se uno sviluppatore che lo aveva lascia il progetto, revocalo e chiedici un nuovo token.
Per il tuo sviluppatore
URL di base: https://acatudy.com/api/v1. Autenticazione: Authorization: Bearer <token>. Il token identifica l'accademia.
| Richiesta | Permesso | Cosa fa |
|---|---|---|
GET /ping | read | Verifica della connessione |
GET /tenant | read | Dati dell'accademia |
GET /plans | read | Piano, limiti, utilizzo e spazio di archiviazione |
GET /courses | read | Materie (id, titolo, stato) |
GET /users?email= | read | Cerca uno studente per email |
POST /users | write | Crea uno studente o collega un account esistente |
POST /enrollments | write | Iscrive dopo un acquisto esterno e dà accesso; le chiamate ripetute con lo stesso external_purchase_id non creano duplicati |
POST /enrollments/{external_purchase_id}/cancel | write | Annulla quell'iscrizione |
Limite: 60 richieste al minuto per token. Gli errori sono in JSON con un code:
| HTTP | code | Significato |
|---|---|---|
| 401 | unauthenticated / token_expired | Token mancante, errato, revocato o scaduto |
| 403 | forbidden | Il token non ha il permesso (per esempio, un token read che prova a creare uno studente) |
| 403 | quota_exceeded | Hai raggiunto il limite di studenti del tuo piano |
| 403 | tenant_inactive / tenant_payment_suspended | L'accademia è scaduta, sospesa o in pausa per mancato pagamento |
| 404 | not_found, course_not_found, user_not_found | Il record non esiste |
| 422 | validation_failed | Dati non validi; fields elenca ogni problema |
| 429 | rate_limited | Troppe richieste; attendi i secondi indicati in Retry-After |
Domande frequenti
Quali piani includono l'API?
Tutti. Il piano conta solo per il limite di studenti.
Posso elencare tutti i miei studenti tramite l'API?
No. L'API cerca uno studente per email, crea studenti e gestisce le iscrizioni.
Acatudy invia webhook al mio sistema?
No. Il tuo sistema chiama l'API quando succede qualcosa dalla sua parte.
Segui questa guida nella tua accademia
Creala gratis in un paio di minuti e tieni aperto il tuo pannello di amministrazione accanto a questa guida.
Apri un ticket da Aiuto → Assistenza nel tuo pannello: rispondiamo entro 24-48 ore a seconda del tuo piano.