Vai al contenuto principale
Integrazioni

API e webhook

Crea una chiave API e scopri cosa permette l'API pubblica su un esame cartaceo: copie, import delle scansioni, iscritti e voti.

Scritto da Florian Barral

Ultimo aggiornamento 9 giorni fa

L'API pubblica permette ai tuoi strumenti (sistema informativo, script, ambienti digitali di lavoro) di leggere i tuoi esami cartacei, scaricare le copie, inviare le scansioni e recuperare i voti. È riservata agli amministratori dell'organizzazione.

Creare una chiave API

  1. Clicca sul tuo nome in basso nella barra laterale, poi su Impostazioni.

  2. Nella sezione Amministrazione, apri API.

  3. In Chiavi API, clicca su Nuova chiave.

  4. Dai alla chiave un Nome della chiave che ti aiuti a riconoscerla, poi clicca su Crea la chiave.

  5. Copia il Client ID e il Client secret, poi clicca su Ho salvato le credenziali.

Il client secret viene mostrato una sola volta. Conservalo in un gestore di segreti. Se lo perdi, elimina la chiave e creane una nuova.

Una chiave dà accesso a tutti i dati dell'organizzazione. Per interrompere un accesso, clicca su Elimina: le integrazioni che la usano smettono subito di funzionare.

Autenticarsi

Il tuo strumento scambia il client ID e il client secret con un token di accesso (OAuth 2.0, client_credentials), poi lo invia a ogni chiamata. Il link Scopri di più della scheda Chiavi API apre la documentazione completa dell'API: indirizzi, parametri ed esempi.

Cosa permette l'API su un esame cartaceo

Esigenza

Con l'API

Ritrovare i tuoi esami cartacei

Elencare gli esami filtrando per tipo paper.

Iscrivere i partecipanti

Aggiungere, modificare o rimuovere iscritti, fino a 50 per chiamata. Non viene inviata alcuna email.

Seguire la preparazione delle copie

Leggere la modalità delle copie (nominative o anonime), il numero di copie e lo stato della generazione.

Scaricare le copie

Recuperare il PDF di tutte le copie, delle singole copie, dei fogli delle risposte o dei fogli della prova, una volta generati.

Importare le scansioni

Inviare un PDF di scansioni (20 MB al massimo per file). Gli import si sommano tra loro e l'analisi avviene come nell'applicazione.

Recuperare i voti

Leggere il voto finale di ogni partecipante.

Crea l'esame, configura le copie e avvia la loro generazione in Papeez: l'API legge questo stato e fornisce i file, ma non crea esami cartacei. Le pagine che l'analisi non ha saputo associare a un partecipante si gestiscono in Papeez: vedi Importare le scansioni.

Webhook

Nella stessa pagina, la scheda Webhooks invia ai tuoi server gli eventi della tua organizzazione nel momento in cui si verificano: Nuovo webhook, poi l'URL di destinazione (in https) e gli Eventi da ricevere. Per un esame cartaceo, gli eventi utili riguardano le email inviate ai partecipanti (invio, ricezione, apertura…). Non esiste ancora un evento per le scansioni o i voti: interroga l'API per seguire l'analisi delle scansioni.

Le chiavi API sono disponibili con tutti i piani. I webhook non sono inclusi in tutti i piani: se è il caso del tuo, Papeez lo indica alla creazione.

Domande frequenti

La sezione Amministrazione delle impostazioni è riservata agli amministratori dell'organizzazione.

Su un esame con copie anonime, iscrivi prima i partecipanti: Papeez ha bisogno dell'elenco degli iscritti per ritrovare ogni copia. Vedi Copie nominative o anonime.

I file esistono solo dopo che le copie sono state generate in Papeez. Vedi Generare le copie da stampare.