API partenaires
Reliez la plateforme de votre organisme de formation à Conversa : vous inscrivez vos stagiaires, vous leur ouvrez l'accès en un clic, sans mot de passe, et vous recevez chaque séance avec son évaluation. Le paiement reste chez vous.
Principe
Votre plateforme reste la référence pour vos stagiaires, leurs formations et leurs paiements. Conversa ne connaît d'eux que ce que vous lui transmettez, rattaché à votre identifiant (id_externe).
| Sens | Ce qui passe |
|---|---|
| Vous → Conversa | Inscription et mise à jour du stagiaire, demande d'un lien d'accès, lecture des séances, des évaluations et du solde. |
| Conversa → vous | Un message signé à chaque séance démarrée ou terminée, à chaque évaluation prête, et quand votre solde passe sous le seuil choisi. |
Chaque séance terminée par un stagiaire inscrit par l'API est décomptée une fois du solde de votre organisme. Le stagiaire ne paie rien à Conversa.
Parcours type
- Dans votre espace Conversa, menu Connexion API : créez une clé et indiquez l'adresse qui recevra nos messages.
- À l'inscription d'un stagiaire chez vous :
POST /api/v1/apprenants.php. - Quand il clique sur « S'entraîner à l'oral » :
POST /api/v1/acces.php, puis redirigez-le vers l'urlreçue. - Il fait sa séance sur Conversa, puis consulte son compte rendu.
- Vous recevez
seance.termineepuisevaluation.prete, et vous enregistrez le résultat dans son dossier.
Authentification
Toutes les adresses commencent par https://conversa.fr/api/v1/, en HTTPS. Chaque requête porte votre clé dans l'en-tête X-Api-Key. L'en-tête Authorization: Bearer … est aussi accepté, mais certains serveurs le suppriment en route : préférez X-Api-Key.
La clé s'utilise uniquement depuis votre serveur, jamais dans le navigateur ni dans une application mobile. Limite : 120 requêtes par minute et par clé (au-delà : 429 et l'en-tête Retry-After).
Erreurs
Toute réponse est un objet JSON. En cas d'échec, ok vaut false et erreur donne un code stable et un message lisible.
| HTTP | Signification |
|---|---|
| 400 / 422 | Requête mal formée ou champ invalide : le message dit lequel. |
| 401 | Clé absente, invalide ou révoquée. |
| 403 | Organisme suspendu. |
| 404 | Apprenant ou séance inconnu de votre organisme. |
| 409 | Action impossible en l'état : apprenant suspendu, droits épuisés. |
| 429 | Trop de requêtes : réessayez après le délai de Retry-After. |
| 5xx | Incident de notre côté : réessayez plus tard. |
Apprenants
POST /api/v1/apprenants.php crée l'apprenant s'il n'existe pas, et sinon met à jour seulement les champs envoyés. Rappelez-le autant de fois que nécessaire : le résultat est le même.
| Champ | Obligatoire | Description |
|---|---|---|
id_externe | oui | Votre identifiant du stagiaire. 1 à 100 caractères parmi A-Z a-z 0-9 . _ : @ -. |
langue_cible | à la création | Langue des séances : en, es, de… (liste dans le message d'erreur si le code est inconnu). |
prenom | conseillé | L'avatar s'adresse au stagiaire par son prénom. |
langue_maternelle | conseillé | Le compte rendu traduit le vocabulaire conseillé dans cette langue. |
niveau | conseillé | A1 à C2. |
nb_seances | conseillé | Nombre de séances accordées. null : sans limite (dans la limite du solde de l'organisme). |
acces_jusqu_au | conseillé | Date de fin, AAAA-MM-JJ. L'accès se ferme le lendemain. |
groupe | non | Session ou cohorte, pour vos statistiques. |
scenarios | non | Liste d'identifiants de scénarios autorisés (voir Scénarios). Absent ou vide : tous. |
statut | non | active ou suspended. |
nom, email | non | Inutiles au fonctionnement. Ne les envoyez que si vous en avez besoin. |
Réponse 201 à la création, 200 à la mise à jour :
GET /api/v1/apprenants.php?id_externe=STG-2026-0142 relit l'apprenant et ses compteurs.
DELETE /api/v1/apprenants.php?id_externe=STG-2026-0142 l'efface définitivement, avec ses séances, ses évaluations et ses enregistrements audio.
Lien d'accès
POST /api/v1/acces.php renvoie un lien qui connecte le stagiaire à Conversa, sans mot de passe. Le lien sert une seule fois et expire au bout de 5 minutes : demandez-le au moment du clic, jamais à l'avance, et ne l'envoyez pas par email.
scenario_id est facultatif : il présélectionne un scénario. Si le stagiaire n'a plus de droits (solde de l'organisme épuisé, séances utilisées, date dépassée, scénario non autorisé), la réponse est 409 droits_epuises avec un message que vous pouvez lui afficher.
Lien signé, sans appel d'API
Pour proposer seulement les conversations avec l'avatar IA (ou la voix), votre serveur peut fabriquer lui-même le lien, sans créer le stagiaire au préalable. Le secret et les domaines autorisés se règlent dans l'espace organisme, rubrique Avatar intégré. Le stagiaire est créé à sa première venue, puis mis à jour à chaque lien ; il ne voit que la séance, son résultat et un bouton de retour vers votre plateforme.
o votre numéro d'organisme, e l'identifiant du stagiaire chez vous (obligatoire), p/n prénom et nom, l la langue apprise, m la langue maternelle, niv A1 à C2, s le scénario, ref votre référence (100 caractères), retour une adresse HTTPS sur un domaine déclaré, t l'horodatage Unix (5 minutes de tolérance), nonce 16 à 64 caractères hexadécimaux, jamais réutilisé.
Signature : sig = HMAC-SHA256 en hexadécimal, avec votre secret de lien, de la chaîne formée de tous les autres paramètres triés par nom, encodés en RFC 3986 (%20 pour l'espace) et joints par &. En PHP : ksort($p); hash_hmac('sha256', http_build_query($p, '', '&', PHP_QUERY_RFC3986), $secret). Le secret ne doit jamais apparaître dans une page web : le lien se fabrique sur votre serveur, au moment du clic.
Retour : sur la page de résultat, le stagiaire revient vers retour avec ref, e, seance, statut (termine, en_cours, aucune), score, niveau, t et sig, signés de la même façon. Le détail complet (critères, synthèse) part par message signé : seance.terminee puis evaluation.prete, qui portent la même reference.
Séances et évaluations
GET /api/v1/seances.php?id_externe=STG-2026-0142 : les 100 dernières séances du stagiaire.
GET /api/v1/seances.php?id=… : une séance, avec l'évaluation complète. Ajoutez &transcription=1 pour le texte de la conversation.
evaluation vaut null tant que le compte rendu n'est pas produit : il l'est quand le stagiaire ouvre la page de résultat, à la fin de sa séance.
Crédits
GET /api/v1/credits.php : { "ok": true, "credits_restants": 42, "seuil_alerte": 5 }. Un crédit correspond à une séance terminée. Le rechargement se fait dans votre espace Conversa (menu Acheter des crédits).
Demandes de séances
Un stagiaire ne paie rien sur Conversa. Quand il veut d'autres séances, il les demande depuis son espace (menu Commander des séances). Vous recevez le message seances.demandees, vous validez sur votre plateforme (paiement, accord du responsable…), puis vous répondez :
Acceptée, la demande ajoute nb_seances au droit du stagiaire (nb_seances de sa fiche) : il peut pratiquer aussitôt. Le motif d'un refus s'affiche dans son espace. Une demande ne se traite qu'une fois : une seconde réponse renvoie 409 deja_traitee.
GET /api/v1/demandes.php : les demandes en attente (?statut=toutes pour les 200 dernières, ?id=42 pour une seule).
Sans plateforme reliée, ou si vous préférez, la même demande se traite dans votre espace Conversa (menu Demandes de séances) ; vous recevez alors demande.traitee.
Visio et présences
Les créneaux en Visio Conversa (visio intégrée, avec un intervenant) mesurent le temps de présence de chacun. À la clôture, 15 minutes après la fin, chaque réservation est décomptée selon une règle fixe :
decompte | Situation | Séance décomptée |
|---|---|---|
debite | Présence cumulée d'au moins 50 % de la durée (les reconnexions s'additionnent). | Oui |
partielle | Présence inférieure à 50 %. | Non |
absent / absent_debite | Aucune présence ; décomptée ou non selon votre réglage (menu Créneaux). | Selon réglage |
service | L'intervenant n'est pas venu (moins d'une minute). | Non |
GET /api/v1/visios.php?id_externe=STG-2026-0142 : les visios du stagiaire. GET /api/v1/visios.php?creneau=12 : un créneau et tous ses participants. Chaque réservation porte presence_sec, decompte, decomptee et le détail des passages (entree, sortie, source : serveur_video fait foi, navigateur sert de secours) : de quoi répondre à une réclamation.
Une séance décomptée compte dans seances_faites du stagiaire et consomme un crédit de votre organisme, comme une séance avec le tuteur IA.
Formateurs et comptes rendus
GET /api/v1/formateurs.php (ou ?langue=en, ?id=12) : les formateurs que vous pouvez placer sur vos créneaux en visio, les vôtres et ceux de la bourse partagée de Conversa. L’email et le téléphone ne sont jamais transmis.
Chaque fiche porte aussi id_externe (le vôtre, si vous l’avez créée) et gere_par : votre_plateforme, organisme ou conversa. Une fiche se lit aussi par ?id_externe=F-42.
Gérer vos formateurs depuis votre plateforme
POST /api/v1/formateurs.php crée le formateur, ou le met à jour s’il existe déjà avec ce id_externe (réponse 201 à la création, 200 à la mise à jour). La fiche envoyée remplace la précédente ; seuls email et telephone, s’ils sont absents, sont conservés. Un formateur créé ainsi est en lecture seule dans Conversa : votre plateforme le tient à jour, vos administrateurs le voient sans pouvoir le modifier. Il n’a pas de tarif public : c’est vous qui le rémunérez.
photo_url : une adresse https publique (JPG, PNG ou WEBP, 2 Mo au plus) ; l’image est téléchargée puis recadrée en 400 × 400. En cas d’échec, le formateur est quand même enregistré et la réponse porte avertissement_photo. email sert à lui ouvrir son espace formateur (planning, visio, comptes rendus) : jamais transmis aux apprenants. statut : actif ou suspendu.
DELETE /api/v1/formateurs.php?id_externe=F-42 le retire : supprimé s’il n’a jamais eu de créneau, sinon suspendu (son historique et ses comptes rendus restent).
Dans GET /api/v1/visios.php, chaque créneau porte formateur (même fiche, sans les tarifs) et chaque réservation porte compte_rendu : niveau_observe, points_forts, a_travailler, devoirs, commentaire, redige_le (null tant que le formateur ne l’a pas rempli). Le formateur le remplit après la séance ; vous recevez alors visio.compte_rendu.
Scénarios
GET /api/v1/scenarios.php (ou ?langue=en) : les scénarios disponibles, avec id, titre, langue, cecrl (niveau A1 à C2), difficulte (beginner, intermediate ou advanced, déduite du niveau) et duree_min. Leurs identifiants servent dans scenarios (apprenant) et scenario_id (lien d'accès).
Cours : importer, exporter, SCORM
GET /api/v1/cours.php : les cours que vos apprenants peuvent suivre, c'est-à-dire ceux de la bibliothèque Conversa et les vôtres (proprietaire : conversa ou organisme), avec id, titre, langue, cecrl, theme, statut et le nombre de lecons.
POST /api/v1/cours.php importe un cours. Il vous appartient, seuls vos apprenants le voient, et vous pouvez le récupérer à tout moment avec GET ?id=. Un cours par appel, 2 Mo au plus. Chaque bloc passe par les mêmes contrôles que l'éditeur : un bloc mal formé est écarté et signalé dans rejets, le reste est enregistré. Le format natif :
Les champs de chaque type sont ceux de l'éditeur : choix donne une proposition par ligne, avec une étoile devant chaque bonne réponse ; dans texte, les accolades marquent les trous, et | sépare plusieurs réponses acceptées ; phrase découpe les morceaux par / ; paires donne une paire par ligne, sous la forme gauche = droite. Les sons de la dictée, de la compréhension et de l'oral sont produits à l'import. Tout bloc accepte consigne, explication et points.
Questions Moodle (GIFT) : envoyez {"format": "gift", "titre": "...", "langue": "en", "cecrl": "A2", "gift": "…le texte GIFT…"}. Les choix uniques et multiples, les vrai ou faux, les réponses courtes (qui deviennent des textes à trous) et les associations deviennent une leçon d'exercices.
Tableur (CSV) : {"format": "csv", "titre": "...", "langue": "en", "cecrl": "A2", "csv": "…"}. Une ligne par exercice ; la première ligne porte les en-têtes type;enonce;reponse;autres;explication (séparateur point-virgule, virgule ou tabulation). Types : qcm (reponse = bonnes réponses, autres = mauvaises, séparées par |), vrai_faux (reponse = vrai ou faux), trous (enonce avec ___, reponse = réponses acceptées séparées par |), ordre (morceaux séparés par /), appariement (reponse = gauche = droite | gauche = droite).
QTI : {"format": "qti", "titre": "...", "langue": "en", "cecrl": "A2", "qti": "<?xml …"}, un document XML QTI 2.x (assessmentItem ou assessmentTest avec ses questions) ou QTI 1.2 (questestinterop, export Canvas ou Blackboard). Choix, textes à trous, associations et ordres sont repris ; les autres interactions sont signalées dans rejets. Un paquet .zip s'importe depuis votre espace, rubrique Cours > Importer.
GET /api/v1/cours.php?id=12 renvoie un de vos cours au même format natif (format : conversa-cours-1), réimportable tel quel. Les cours de la bibliothèque Conversa ne s'exportent qu'en SCORM.
GET /api/v1/cours.php?id=12&format=scorm renvoie un paquet SCORM 1.2 (zip) à déposer dans votre LMS (Moodle, etc.). Dans le LMS, l'apprenant clique sur « Ouvrir le cours » : Conversa s'ouvre dans une fenêtre, l'apprenant est créé dans votre organisme à sa première venue (id_externe : scorm-<paquet>-<son identifiant dans le LMS>), et sa progression remonte au LMS (score sur 100, statut incomplete ou completed). Le paquet ne contient pas le cours mais un lanceur : le contenu reste à jour, et la correction par l'IA comme l'oral fonctionnent. Il donne accès à ce seul cours, pour vos seuls apprenants, avec 300 nouveaux apprenants par jour au plus.
DELETE /api/v1/cours.php?id=12 supprime un de vos cours, avec ses leçons et les réponses de vos apprenants.
Devoirs
POST /api/v1/devoirs.php assigne des leçons, à un apprenant ({"apprenant": "ID", "lecons": [4, 5], "echeance": "2026-11-01"}) ou à tout un groupe ({"groupe": "Anglais pro", "lecons": [4]}). La liste envoyée remplace les leçons que vous aviez déjà assignées ; une liste vide les retire. Les leçons recommandées après une conversation ou par un formateur restent. Une leçon que l'apprenant ne peut pas suivre est ignorée et rendue dans lecons_ignorees.
GET /api/v1/devoirs.php?apprenant=ID : tous ses devoirs, avec source (conversation, formateur ou organisme), raison, echeance et fait (leçon terminée).
Résultats des cours
GET /api/v1/resultats.php : par apprenant, lecons_terminees, score_moyen, xp, niveau (1 à 10), serie_jours (jours de suite au défi du jour) et derniere_activite. ?depuis=AAAA-MM-JJ limite le compte des leçons terminées.
GET /api/v1/resultats.php?apprenant=ID : le détail, avec chaque leçon commencée ou terminée, son statut, son score et ses dates. Quand un apprenant termine une leçon pour la première fois, vous recevez lecon.terminee.
Messages signés
Conversa envoie un POST JSON à l'adresse réglée dans votre espace (menu Connexion API). Répondez par un code 2xx en moins de 10 secondes. Sinon, le message est renvoyé 8 fois en environ deux jours (1, 5, 15, 60 minutes, puis 3, 6, 12 et 24 heures).
| Type | Quand | donnees |
|---|---|---|
seance.demarree | Le stagiaire commence une séance. | seance |
seance.terminee | La séance est finie et décomptée. | seance |
evaluation.prete | Le compte rendu est produit. | seance, évaluation comprise |
seances.demandees | Un stagiaire demande des séances supplémentaires. | demande |
demande.traitee | Une demande est acceptée ou refusée depuis votre espace Conversa. | demande |
visio.terminee | Une visio Conversa est clôturée : une fois par stagiaire inscrit. | visio : creneau, id_externe, presence_sec, decompte, decomptee |
lecon.terminee | Un apprenant a terminé une leçon pour la première fois. | lecon : id, titre, cours_id, cours, id_externe, score |
visio.compte_rendu | Le formateur a rempli (ou corrigé) le compte rendu d’un stagiaire. | compte_rendu : creneau, id_externe, formateur_id, niveau_observe, points_forts, a_travailler, devoirs, commentaire |
credits.bas | Le solde atteint le seuil choisi, puis zéro. | credits_restants, seuil_alerte |
test | Bouton « Envoyer un message de test ». | message |
Un même message peut arriver plus d'une fois (par exemple si votre réponse s'est perdue). Enregistrez son id et ignorez un id déjà traité.
Vérifier la signature
Le secret de signature s'affiche une fois, dans votre espace, quand vous enregistrez l'adresse de réception. La signature est un HMAC-SHA256 du texte t + "." + corps brut. Refusez un message dont la signature ne correspond pas, ou dont t a plus de 5 minutes d'écart avec votre horloge.
Données personnelles
Conversa traite pour votre compte la voix de vos stagiaires et leurs évaluations : un contrat de sous-traitance (article 28 du RGPD) s'impose entre votre organisme et Conversa. Seuls id_externe et langue_cible sont nécessaires : n'envoyez ni nom ni email si vous n'en avez pas l'usage. DELETE /api/v1/apprenants.php efface un stagiaire et tout ce qui le concerne, enregistrements audio compris.