API

Une API pour les rendez-vous Doctolib

Docal expose une API REST qui lit les agendas Doctolib d'un praticien, y crée de vrais rendez-vous patients et suit leur déroulé au cabinet. Elle sert les éditeurs de logiciels, les agents vocaux et les intégrateurs qui veulent poser un rendez-vous dans Doctolib sans passer par l'interface.

Ce que l'API permet

Agendas

Lister les agendas du compte et leurs identifiants.

Motifs

Lister les motifs de consultation, avec leur durée et leurs conditions de réservation. Le paramètre agendaId limite la liste aux motifs réellement utilisables sur un agenda donné, avec leur durée effective sur celui-ci. Sans lui, elle inclut aussi des motifs que cet agenda ne peut pas utiliser.

Disponibilités

Lire les créneaux libres d'un agenda pour un motif et une plage de dates.

Rendez-vous pris

Lister les rendez-vous d'une journée ou d'une plage de dates : horaires, praticien, motif, patient et coordonnées, statut. Pour créer la fiche patient dans votre CRM ou afficher le planning du jour.

Option sur un créneau

Poser une option temporaire sur un créneau, le temps de confirmer avec le patient.

Création

Créer un vrai rendez-vous patient, avec recherche de la fiche patient existante ou création si nécessaire.

Modification et annulation

Déplacer ou annuler un rendez-vous déjà posé.

Arrivée du patient

Passer un patient en salle d'attente, en consultation ou vu, ou le ramener à confirmé, comme les boutons de Doctolib, qui horodate l'arrivée. Pour les rendez-vous d'hier à demain ; un rendez-vous annulé ou un patient marqué absent ne change pas de statut.

Prérequis

Un compte praticien Docal avec le compte Doctolib du praticien connecté et un essai en cours ou l'option API.
Google Agenda n'est pas nécessaire pour utiliser l'API : un partenaire qui n'utilise que l'API peut démarrer sans jamais le connecter.
Le mode rendez-vous patient activé par Docal sur le compte, sur demande.

Il n'existe pas d'accès API sans compte praticien : l'API agit toujours au nom d'un praticien identifié, sur ses propres agendas.

Essai et conditions d'accès

L'API est incluse pendant les 7 jours d'essai, avec un quota réduit à 500 appels, de quoi mener une intégration complète. Au-delà de l'essai, l'accès API fait l'objet d'une option mensuelle distincte de l'abonnement de synchronisation, activée après paiement. Écrivez-nous pour en discuter.

Plafonds

Débit, quotas mensuels et comportement en cas de dépassement

Débit	5 appels par seconde et par compte
Quota mensuel, compte payé	5 000 appels par mois civil
Quota mensuel, pendant l'essai	500 appels
Dépassement	Réponse 429 avec un en-tête Retry-After, aucun appel facturé à l'unité
Plage de dates	90 jours au plus pour les disponibilités, 31 jours pour la lecture des rendez-vous (sans dates : la journée en cours)
Lecture des rendez-vous	Résultat gardé 60 secondes en cache par compte : un statut changé par l'API est visible à l'appel suivant, un changement fait dans Doctolib au plus tard 60 secondes après. Chaque appel compte dans le quota, cache ou pas.

Les plafonds portent sur le compte, pas sur la clé : générer plusieurs clés ne multiplie pas le débit.

Idempotence

La création de rendez-vous accepte une clé d'idempotence. Si votre appel se perd en route et que vous le rejouez avec la même clé, Docal renvoie le rendez-vous déjà créé au lieu d'en créer un second. C'est la garantie qu'une coupure réseau ne produit pas de doublon dans l'agenda du praticien.

Erreurs

Toutes les erreurs partagent la même forme, { "error": { "code": "...", "message": "..." } }.

Code	Statut	Signification
INVALID_API_KEY	401	Clé absente, inconnue ou révoquée.
APPOINTMENT_MODE_DISABLED	403	Le mode rendez-vous n'est pas activé sur ce compte.
API_ACCESS_REQUIRED	403	Ni essai en cours, ni option API active.
AGENDA_NOT_ENABLED	403	Compte géré par un partenaire : cet agenda n'est pas activé pour l'API.
APPOINTMENT_NOT_FOUND	404	Rendez-vous introuvable sur les agendas du compte (pour un changement de statut : entre hier et demain).
SLOT_UNAVAILABLE	409	Créneau déjà pris ou hors des plages d'ouverture.
INVALID_STATUS_TRANSITION	409	Statut non modifiable : le rendez-vous est annulé ou le patient a été marqué absent.
APPOINTMENT_CHANGED	409	Rendez-vous modifié dans Doctolib pendant la demande : statut inchangé, relisez-le puis réessayez.
IDEMPOTENCY_IN_PROGRESS	409	Une requête portant la même clé d'idempotence est encore en cours.
VALIDATION_ERROR	422	Paramètre ou corps de requête invalide, par exemple un statut non pris en charge.
INVALID_RANGE	422	Date invalide ou plage trop longue.
INVALID_AGENDA	422	Agenda inconnu pour ce compte.
INVALID_VISIT_MOTIVE	422	Motif inconnu ou inutilisable sur cet agenda.
IDEMPOTENCY_KEY_REUSE	422	Clé d'idempotence déjà utilisée avec un autre contenu.
RATE_LIMIT_EXCEEDED	429	Débit par seconde dépassé.
MONTHLY_QUOTA_EXCEEDED	429	Quota mensuel épuisé.
DOCTOLIB_SESSION_FAILED	502	Connexion au compte Doctolib du praticien impossible.
APPOINTMENTS_LOOKUP_FAILED	502	Lecture des rendez-vous Doctolib impossible.
APPOINTMENT_STATUS_FAILED	502	Le changement de statut n'a pas pu être effectué ou confirmé : relisez le rendez-vous avant de réessayer.

Données personnelles

L'API agit sur les données du praticien, hébergées chez Doctolib et chez Google. Docal ne conserve pas les motifs de consultation en base. Les rendez-vous lus par l'API restent au plus 60 secondes en cache, puis sont effacés. Un accord de sous-traitance est disponible sur demande pour les praticiens et les partenaires.

Prêt à intégrer l'API ?

Découvrir l’offre partenaire

Une facture pour tous vos praticiens, une clé API par praticien, essai gratuit.

La référence détaillée, endpoint par endpoint, est disponible dans votre compte Docal sur la page Réglages puis API.