Aller au contenu

Galaxie Artibox

Tutoriel API prise de rendez-vous en 5 étapes

Un jeton, un premier appel, vos types de rendez-vous, un créneau libre, une réservation. Tout se fait avec curl, en quelques minutes.

Ce tutoriel API prise de rendez-vous vous mène du jeton à la première réservation. Il suppose un compte Artibox Calendar en formule Pro ou plus, un type de rendez-vous actif et un terminal avec curl. Les exemples utilisent deux variables : l'adresse de l'API et votre jeton.

export RDV_API="https://adresse-de-votre-application/api/v1"
export RDV_TOKEN="rdv_pat_…"

L'adresse exacte de l'API figure en tête de la référence de l'API : c'est le domaine de l'application suivi de /api/v1.

Étape 1 : créer un jeton personnel

Dans l'application, ouvrez Réglages › Intégrations, carte « API ». Nommez le jeton, choisissez éventuellement une date d'expiration et cochez les portées utiles à ce tutoriel : utilisateur:lire, types:lire et reservations:ecrire. Copiez le jeton aussitôt : il commence par rdv_pat_ et ne s'affichera plus. Le pas à pas en images est dans l'aide API et jetons.

Étape 2 : votre premier appel

Le jeton s'envoie dans l'en-tête x-api-key. Ce premier appel renvoie le compte du jeton, son organisation et ses droits :

curl "$RDV_API/me/context" -H "x-api-key: $RDV_TOKEN"

Toute réponse suit la même enveloppe : message, data, errors. Un jeton absent ou refusé répond 401 ; une portée manquante, 403. Les codes sont détaillés dans limites, erreurs et pagination.

Étape 3 : lister vos types de rendez-vous

curl "$RDV_API/types" -H "x-api-key: $RDV_TOKEN"

Chaque type porte son id, son nom, sa durée (duration_minutes), son mode (video, phone, in_person) et son format. Notez l'id du type sur lequel vous voulez réserver.

Étape 4 : trouver un créneau libre

Les créneaux se calculent comme sur la page de réservation : heures des organisateurs, agendas connectés, marges, préavis et maximum par jour. Donnez une période en ISO 8601 avec décalage (encodez le + en %2B dans l'adresse) :

curl "$RDV_API/types/ID_DU_TYPE/slots?from=2026-12-01T00:00:00%2B01:00&to=2026-12-08T00:00:00%2B01:00" \
  -H "x-api-key: $RDV_TOKEN"

La réponse donne data.slots, une liste de créneaux avec leur start, leur end et les organisateurs libres. data.without_calendar signale un organisateur sans agenda connecté.

Étape 5 : réserver le créneau

curl -X POST "$RDV_API/bookings" \
  -H "x-api-key: $RDV_TOKEN" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{"type_id":"ID_DU_TYPE","start":"2026-12-01T10:00:00+01:00","name":"Camille Martin","email":"camille.martin@example.com","timezone":"Europe/Paris","locale":"fr"}'

La réponse 201 contient le rendez-vous, avec l'origine api. L'invité reçoit sa confirmation comme s'il avait réservé lui-même. Si le créneau a été pris entre-temps, la réponse est un refus (409 ou 422 avec le message du champ start) : relisez les créneaux et proposez-en un autre.

L'en-tête Idempotency-Key est facultatif mais conseillé : rejoué dans les 24 heures avec la même clé, l'appel rend la première réponse sans créer de doublon. Utile après une coupure réseau.

Après ce tutoriel API prise de rendez-vous

Questions fréquentes

Quelle formule faut-il pour utiliser l'API ?

La formule Pro ou plus, pour créer des jetons personnels et des applications OAuth. Les webhooks demandent la formule Équipe. Voir les tarifs.

Pourquoi mon appel répond 403 ?

Le jeton n'a pas la portée de cette route (le message la nomme), ou la route n'est pas ouverte aux jetons, ou le membre du jeton n'a pas ce droit. Ajoutez la portée en créant un nouveau jeton.

Dans quel fuseau sont les créneaux ?

Toutes les dates sont en ISO 8601 avec leur décalage. Le champ timezone de la réservation règle le fuseau des messages envoyés à l'invité.

Peut-on réserver pour un organisateur précis ?

La réservation suit les règles du type : pour un type tournant, l'organisateur est choisi parmi ceux libres. Pour imposer une personne, utilisez un lien signé avec contexte, décrit dans intégrer dans votre plateforme.

Faites votre premier appel

Créez votre compte, puis votre jeton dans Réglages › Intégrations.

Créer mon compte