Aller au contenu principal

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>
URL de base

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​

StatutSignificationRe-planifiable
READYPlanifiée, pas encore lancéeOui
CREATEDLancée par la personne en chargeNon
INITIATEDL'invité a rejoint la visioNon
COMPLETEDVisio terminéeNon
ERRORVisio en erreurNon

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 :

ChampTypeRequisDescription
assigneeEmailStringouiE-mail de la personne en charge : un utilisateur de votre entreprise ou de l'une de ses filiales
firstNameStringouiPrénom de l'invité (100 caractères max.)
lastNameStringouiNom de l'invité (100 caractères max.)
phoneNumberStringouiTéléphone de l'invité (30 caractères max.)
emailStringnonE-mail de l'invité
scheduledAtStringnonDate et heure de la visio, au format ISO 8601 (ex. 2026-11-02T09:00:00Z)
reportTokenStringnonIdentifiant de rapport auquel rattacher le dossier de la visio (100 caractères max.)
expectedAddressStringnonAdresse attendue du lieu de la visio : voie, code postal à 5 chiffres et commune
expectedLatitudeStringnonLatitude de l'adresse attendue
expectedLongitudeStringnonLongitude 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.

Invitations envoyées automatiquement

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ée
  • 400 Bad Request : champ manquant ou invalide (dont assigneeEmail absent)
  • 403 Forbidden : droit de planification manquant
  • 422 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) :

NomTypeDescription
statusStringFiltre sur un statut (READY, CREATED, INITIATED, COMPLETED, ERROR)
scheduledFromStringVisios prévues à partir de cette date (ISO 8601, incluse)
scheduledToStringVisios prévues jusqu'à cette date (ISO 8601, incluse)
limitNumberNombre de visios par page, de 1 à 200 (défaut : 50)
offsetNumberNombre 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ée
  • 400 Bad Request : paramètre invalide (dont scheduledFrom posté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ée
  • 403 Forbidden : droit de consultation manquant
  • 404 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) :

ChampTypeDescription
scheduledAtString ou nullNouvelle date (ISO 8601), ou null pour retirer la date
assigneeEmailStringE-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.

Prévenir les participants

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ée
  • 400 Bad Request : aucun champ à modifier, ou champ invalide
  • 403 Forbidden : droit de re-planification manquant
  • 404 Not Found : visio inconnue, ou hors de votre périmètre
  • 409 Conflict : visio déjà lancée ; elle reste inchangée
  • 422 Unprocessable Entity : personne en charge introuvable dans votre entreprise ou ses filiales

Erreurs communes à toutes les routes​

CodeCause
401 Unauthorized ou 403 ForbiddenToken absent, invalide ou expiré
403 ForbiddenDroit visio manquant pour cette route
423 LockedAccès à l'API suspendu pour votre entreprise (impayé) : contactez votre administrateur
429 Too Many RequestsLimite 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éthodeEndpointDescription
POST/v2/certificall/api/visio-sessionsPlanifier une visio
GET/v2/certificall/api/visio-sessionsLister les visios de votre entreprise et de ses filiales
GET/v2/certificall/api/visio-sessions/:idConsulter une visio
PATCH/v2/certificall/api/visio-sessions/:idRe-planifier une visio (date et/ou personne en charge)