Planifier et suivre des visios certifiées
Cette API vous permet de planifier des visios certifiées depuis votre propre outil, de retrouver celles de votre entreprise et de les re-planifier, sans passer par l'interface Certificall.
Une visio est menée par une personne en charge : un utilisateur de votre entreprise (ou de l'une de ses filiales) qui la lancera depuis Certificall. L'invité est la personne qui rejoint la visio.
Prérequis
Avant de commencer, assurez-vous que :
- Vous disposez d'un token d'authentification JWT (voir Authentification).
- Votre compte API porte les droits visio nécessaires (planifier, consulter, re-planifier). Si ce n'est pas le cas, contactez votre administrateur Certificall.
- La visio est activée pour votre entreprise (ou héritée de votre entreprise mère).
Toutes les requêtes portent l'en-tête :
Authorization: Bearer <votre_token>
Les routes de cette page partagent l'URL de base du reste de l'API Certificall : https://admin.certificall.app/v2/certificall/api.
Périmètre : votre entreprise et ses filiales
Vous voyez, planifiez et re-planifiez les visios de votre entreprise et de toute sa descendance (filiales, filiales de filiales, et ainsi de suite). Une visio d'une autre entreprise est introuvable pour vous (404).
La personne en charge doit elle aussi appartenir à ce périmètre.
Cycle de vie d'une visio
| Statut | Signification | Re-planifiable |
|---|---|---|
READY | Planifiée, pas encore lancée | Oui |
CREATED | Lancée par la personne en charge | Non |
INITIATED | L'invité a rejoint la visio | Non |
COMPLETED | Visio terminée | Non |
ERROR | Visio en erreur | Non |
Une visio ne fait qu'avancer dans ce cycle : elle ne revient jamais à un statut précédent.
1. Planifier une visio
- Endpoint :
POST /v2/certificall/api/visio-sessions - Droit requis : planifier une visio
Corps de la requête :
| Champ | Type | Requis | Description |
|---|---|---|---|
assigneeEmail | String | oui | E-mail de la personne en charge : un utilisateur de votre entreprise ou de l'une de ses filiales |
firstName | String | oui | Prénom de l'invité (100 caractères max.) |
lastName | String | oui | Nom de l'invité (100 caractères max.) |
phoneNumber | String | oui | Téléphone de l'invité (30 caractères max.) |
email | String | non | E-mail de l'invité |
scheduledAt | String | non | Date et heure de la visio, au format ISO 8601 (ex. 2026-11-02T09:00:00Z) |
reportToken | String | non | Identifiant de rapport auquel rattacher le dossier de la visio (100 caractères max.) |
expectedAddress | String | non | Adresse attendue du lieu de la visio : voie, code postal à 5 chiffres et commune |
expectedLatitude | String | non | Latitude de l'adresse attendue |
expectedLongitude | String | non | Longitude de l'adresse attendue |
expectedLatitude et expectedLongitude se donnent ensemble, et seulement avec expectedAddress.
Exemple de requête :
curl -X POST https://admin.certificall.app/v2/certificall/api/visio-sessions \
-H "Authorization: Bearer $TOKEN" \
-H "Content-Type: application/json" \
-d '{
"assigneeEmail": "operateur@votre-entreprise.fr",
"firstName": "Jeanne",
"lastName": "Martin",
"phoneNumber": "+33612345678",
"email": "jeanne.martin@example.com",
"scheduledAt": "2026-11-02T09:00:00Z",
"expectedAddress": "12 Rue de la Paix, 75002 Paris"
}'
Exemple de réponse (201 Created) :
{
"id": "VIS-1761210000000-6f1c2b9e-3d4a-4f5b-8c7d-1e2f3a4b5c6d",
"status": "READY",
"companyId": 123,
"caseId": null,
"guest": {
"firstName": "Jeanne",
"lastName": "Martin",
"phoneNumber": "+33612345678",
"email": "jeanne.martin@example.com"
},
"assigneeEmail": "operateur@votre-entreprise.fr",
"scheduledAt": "2026-11-02T09:00:00.000Z",
"expectedAddress": "12 Rue de la Paix, 75002 Paris",
"expectedLatitude": null,
"expectedLongitude": null,
"createdAt": "2026-10-23T09:00:00.000Z",
"updatedAt": null
}
Conservez l'id : il sert à consulter et re-planifier la visio. assigneeEmail est l'e-mail de la personne en charge ; il vaut null si cet utilisateur n'existe plus.
Quand la visio est datée, l'invité reçoit une invitation (s'il a un e-mail) et la personne en charge reçoit une confirmation avec un fichier calendrier (.ics).
Codes de réponse :
201 Created: visio planifiée400 Bad Request: champ manquant ou invalide (dontassigneeEmailabsent)403 Forbidden: droit de planification manquant422 Unprocessable Entity: personne en charge introuvable dans votre entreprise ou ses filiales, ou visio non activée pour votre entreprise
2. Lister les visios
- Endpoint :
GET /v2/certificall/api/visio-sessions - Droit requis : consulter les visios
Les visios sont triées de la plus récemment créée à la plus ancienne.
Paramètres de requête (tous optionnels) :
| Nom | Type | Description |
|---|---|---|
status | String | Filtre sur un statut (READY, CREATED, INITIATED, COMPLETED, ERROR) |
scheduledFrom | String | Visios prévues à partir de cette date (ISO 8601, incluse) |
scheduledTo | String | Visios prévues jusqu'à cette date (ISO 8601, incluse) |
limit | Number | Nombre de visios par page, de 1 à 200 (défaut : 50) |
offset | Number | Nombre de visios à sauter (défaut : 0) |
Exemple de requête :
curl "https://admin.certificall.app/v2/certificall/api/visio-sessions?status=READY&limit=20&offset=0" \
-H "Authorization: Bearer $TOKEN"
Exemple de réponse :
{
"items": [
{
"id": "VIS-1761210000000-6f1c2b9e-3d4a-4f5b-8c7d-1e2f3a4b5c6d",
"status": "READY",
"companyId": 123,
"caseId": null,
"guest": {
"firstName": "Jeanne",
"lastName": "Martin",
"phoneNumber": "+33612345678",
"email": "jeanne.martin@example.com"
},
"assigneeEmail": "operateur@votre-entreprise.fr",
"scheduledAt": "2026-11-02T09:00:00.000Z",
"expectedAddress": "12 Rue de la Paix, 75002 Paris",
"expectedLatitude": null,
"expectedLongitude": null,
"createdAt": "2026-10-23T09:00:00.000Z",
"updatedAt": null
}
],
"total": 1
}
total est le nombre total de visios correspondant aux filtres, toutes pages confondues.
Codes de réponse :
200 OK: liste retournée400 Bad Request: paramètre invalide (dontscheduledFrompostérieur àscheduledTo)403 Forbidden: droit de consultation manquant
3. Consulter une visio
- Endpoint :
GET /v2/certificall/api/visio-sessions/:id - Droit requis : consulter les visios
Exemple de requête :
curl https://admin.certificall.app/v2/certificall/api/visio-sessions/VIS-1761210000000-6f1c2b9e-3d4a-4f5b-8c7d-1e2f3a4b5c6d \
-H "Authorization: Bearer $TOKEN"
La réponse a la même forme qu'une visio de la liste.
Codes de réponse :
200 OK: visio retournée403 Forbidden: droit de consultation manquant404 Not Found: visio inconnue, ou appartenant à une entreprise hors de votre périmètre
4. Re-planifier une visio
- Endpoint :
PATCH /v2/certificall/api/visio-sessions/:id - Droit requis : re-planifier une visio
Change la date et/ou la personne en charge d'une visio qui n'a pas encore été lancée (statut READY).
Corps de la requête (au moins un champ) :
| Champ | Type | Description |
|---|---|---|
scheduledAt | String ou null | Nouvelle date (ISO 8601), ou null pour retirer la date |
assigneeEmail | String | E-mail de la nouvelle personne en charge (votre entreprise ou ses filiales) |
La personne en charge ne peut pas être retirée : assigneeEmail: null est refusé.
Exemple de requête :
curl -X PATCH https://admin.certificall.app/v2/certificall/api/visio-sessions/VIS-1761210000000-6f1c2b9e-3d4a-4f5b-8c7d-1e2f3a4b5c6d \
-H "Authorization: Bearer $TOKEN" \
-H "Content-Type: application/json" \
-d '{
"scheduledAt": "2026-11-03T14:30:00Z",
"assigneeEmail": "autre.operateur@filiale.fr"
}'
La réponse est la visio mise à jour.
Une nouvelle date envoie une invitation mise à jour à l'invité et une confirmation à la personne en charge. Un changement de personne en charge sur une visio datée envoie une confirmation à la nouvelle personne en charge.
Codes de réponse :
200 OK: visio re-planifiée400 Bad Request: aucun champ à modifier, ou champ invalide403 Forbidden: droit de re-planification manquant404 Not Found: visio inconnue, ou hors de votre périmètre409 Conflict: visio déjà lancée ; elle reste inchangée422 Unprocessable Entity: personne en charge introuvable dans votre entreprise ou ses filiales
Erreurs communes à toutes les routes
| Code | Cause |
|---|---|
401 Unauthorized ou 403 Forbidden | Token absent, invalide ou expiré |
403 Forbidden | Droit visio manquant pour cette route |
423 Locked | Accès à l'API suspendu pour votre entreprise (impayé) : contactez votre administrateur |
429 Too Many Requests | Limite d'appels atteinte (voir ci-dessous) |
Extrait du corps d'une erreur :
{
"statusCode": 409,
"message": "Session VIS-… en statut CREATED : plus modifiable une fois la visio lancée",
"codeError": "visioSession.notEditable",
"requestId": "b3f1c2e4-...",
"details": {
"header": "Error on request: b3f1c2e4-..."
}
}
Le message est rédigé dans la langue de l'en-tête Accept-Language (français, anglais ou espagnol). Pour réagir à une erreur dans votre code, appuyez-vous sur statusCode et codeError, jamais sur le texte du message. Communiquez le requestId au support si vous avez besoin d'aide.
Limites de requêtes
Chaque route accepte 60 requêtes par minute et par entreprise. Le comptage et les en-têtes (Retry-After, X-RateLimit-*) suivent les mêmes règles que le reste de l'API : voir Limites de requêtes.
Résumé des Endpoints
| Méthode | Endpoint | Description |
|---|---|---|
POST | /v2/certificall/api/visio-sessions | Planifier une visio |
GET | /v2/certificall/api/visio-sessions | Lister les visios de votre entreprise et de ses filiales |
GET | /v2/certificall/api/visio-sessions/:id | Consulter une visio |
PATCH | /v2/certificall/api/visio-sessions/:id | Re-planifier une visio (date et/ou personne en charge) |