API
Une API pour les rendez-vous Doctolib
Docal expose une API REST qui lit les agendas Doctolib d'un praticien et y crée de vrais rendez-vous patients. 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.
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é.
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é |
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. |
| RATE_LIMIT_EXCEEDED | 429 | Débit par seconde dépassé. |
| MONTHLY_QUOTA_EXCEEDED | 429 | Quota mensuel épuisé. |
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. Un accord de sous-traitance est disponible sur demande pour les praticiens et les partenaires.
Prêt à intégrer l'API ?
Demander un accès APIDites-nous en deux lignes ce que vous voulez construire et combien de praticiens sont concernés.
La référence détaillée, endpoint par endpoint, est disponible dans votre compte Docal sur la page Réglages puis API.