API et webhooks

Créer une clé API, et ce que l'API publique permet sur un examen papier : copies, import des scans, inscrits et notes.

Écrit par Florian Barral

Dernière mise à jour Il y a environ 16 heures

L'API publique permet à vos outils (système d'information, scripts, ENT) de lire vos examens papier, de télécharger les copies, d'envoyer les scans et de récupérer les notes. Elle est réservée aux administrateurs de l'organisation.

Créer une clé API

Cliquez sur votre nom en bas de la barre latérale, puis sur Paramètres.
Dans la rubrique Administration, ouvrez API.
Dans Clés API, cliquez sur Nouvelle clé.
Donnez-lui un Nom de la clé qui vous aide à la reconnaître, puis cliquez sur Créer la clé.
Copiez le Client ID et le Client secret, puis cliquez sur J'ai copié mes identifiants.

Le client secret ne s'affiche qu'une fois. Conservez-le dans un gestionnaire de secrets. Si vous le perdez, supprimez la clé et créez-en une nouvelle.

Une clé donne accès à toutes les données de l'organisation. Pour couper un accès, cliquez sur Supprimer : les intégrations qui l'utilisent cessent aussitôt de fonctionner.

S'authentifier

Votre outil échange le client ID et le client secret contre un jeton d'accès (OAuth 2.0, client_credentials), puis l'envoie à chaque appel. Le lien En savoir plus de la carte Clés API ouvre la documentation complète de l'API : adresses, paramètres et exemples.

Ce que l'API permet sur un examen papier

Besoin	Avec l'API
Retrouver vos examens papier	Lister les examens en filtrant sur le type `paper`.
Inscrire les participants	Ajouter, modifier ou retirer des inscrits, jusqu'à 50 par appel. Aucun email ne leur est envoyé.
Suivre la préparation des copies	Lire le mode de copies (nominatives ou anonymes), le nombre de copies et l'état de la génération.
Télécharger les copies	Récupérer le PDF de toutes les copies, des copies individuelles, des feuilles de réponse ou des feuilles d'énoncé, une fois générées.
Importer les scans	Envoyer un PDF de scans (20 Mo maximum par fichier). Les imports s'ajoutent les uns aux autres, et l'analyse se fait comme dans l'application.
Récupérer les notes	Lire la note finale de chaque participant.

Créez l'examen, configurez les copies et lancez leur génération dans Papeez : l'API lit cet état et sert les fichiers, mais ne crée pas d'examen papier. Les pages que l'analyse n'a pas pu associer à un participant se traitent dans Papeez : voir Importer les scans.

Webhooks

Sur la même page, la carte Webhooks envoie à vos serveurs les événements de votre organisation au moment où ils se produisent : Nouveau webhook, puis l'URL de destination (en https) et les Événements à recevoir. Pour un examen papier, les événements utiles concernent les emails envoyés aux participants (envoi, réception, ouverture…). Il n'y a pas encore d'événement pour les scans ou les notes : interrogez l'API pour suivre l'analyse des scans.

Les clés API sont disponibles avec toutes les formules. Les webhooks ne sont pas inclus dans toutes les formules : si c'est le cas de la vôtre, Papeez l'indique à la création.

Questions fréquentes

Je ne vois pas la page API

La rubrique Administration des paramètres est réservée aux administrateurs de l'organisation.

L'import d'un scan est refusé sur un examen anonyme

Sur un examen à copies anonymes, inscrivez d'abord les participants : Papeez a besoin de la liste des inscrits pour retrouver chaque copie. Voir Copies nominatives ou anonymes.

Le téléchargement des copies renvoie une erreur

Les fichiers n'existent qu'une fois les copies générées dans Papeez. Voir Générer les copies à imprimer.

Cela a-t-il été utile ?

Besoin d'aide supplémentaire ? Demander à l'équipe