Aller au contenu

Galaxie Artibox

Intégrer la prise de rendez-vous dans un CRM ou votre logiciel

Une application OAuth pour toutes les organisations de vos clients, des liens signés qui rattachent chaque rendez-vous à votre fiche, et des webhooks pour tout synchroniser.

Vous éditez un CRM, un logiciel métier ou une plateforme utilisée par d'autres entreprises, et vous voulez intégrer la prise de rendez-vous dans un CRM sans la redévelopper : vos utilisateurs gardent leur agenda Artibox Calendar, et chaque rendez-vous revient dans votre outil, rattaché à la bonne fiche. Cette page décrit l'architecture conseillée, pièce par pièce.

Intégrer la prise de rendez-vous dans un CRM : les trois pièces

  1. Une application OAuth, déclarée une fois, que chaque client autorise pour son compte.
  2. Des liens signés avec contexte, qui ouvrent la page de réservation préremplie et rattachent le rendez-vous à un objet de votre outil (un contact, une affaire, un dossier).
  3. Des webhooks, qui vous préviennent de chaque rendez-vous pris, déplacé, annulé ou constaté, avec ce contexte.

Une application OAuth pour toutes les organisations

Ne demandez jamais à vos clients de vous confier un jeton personnel. Déclarez votre outil comme application OAuth : dans votre propre organisation, en formule Pro, le propriétaire l'ajoute dans Réglages › Intégrations › Applications OAuth, avec ses adresses de retour et les portées dont elle a besoin. Vous recevez un client_id (rdv_app_…) et un secret (rdv_cs_…, affiché une seule fois).

Une application déclarée une fois peut être autorisée par les membres de n'importe quelle organisation : chacun voit l'écran de consentement /oauth/autoriser, puis votre serveur échange le code contre un jeton d'accès. Le jeton agit au nom de ce membre, dans son organisation, avec ses droits et les seules portées accordées. Chaque membre retire l'accès quand il veut, depuis « Applications connectées ». Le parcours complet, avec PKCE, est détaillé dans authentification.

Conservez par client : l'identifiant de l'organisation (organisation_id des webhooks), le jeton d'accès (2 heures) et le jeton de rafraîchissement (90 jours, renouvelé à chaque usage).

Le lien signé avec contexte

Un lien signé ouvre la page de réservation d'un type avec un contexte : la source (votre outil), le type d'objet, son identifiant et un libellé. Le contexte peut aussi préremplir le nom, le courriel et le téléphone de l'invité, et imposer un organisateur. Il est enregistré sur le rendez-vous, renvoyé dans les webhooks (contexte) et sert de filtre à GET /bookings?context_source=…&context_id=….

Le plus simple : le faire signer par l'API

Avec la portée liens:ecrire, l'API signe le lien pour vous :

curl -X POST "$RDV_API/types/ID_DU_TYPE/signed-links" \
  -H "x-api-key: $RDV_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"source":"mon-crm","type":"affaire","id":"AFF-2026-0042","libelle":"Projet Dupont","prerempli":{"nom":"Camille Martin","email":"camille.martin@example.com"},"days":14}'

La réponse donne data.url, de la forme /r/{espace}/{type}?c=…, valable de 1 à 90 jours (14 par défaut) et lié à ce seul type.

Ou le signer vous-même

Pour fabriquer les liens sans appel, le propriétaire génère une clé de contexte (Réglages › Organisation, ou POST /organization/context-key, affichée une seule fois ; une nouvelle clé invalide les anciens liens). Le jeton de contexte a la forme charge.signature :

  • charge : le JSON du contexte encodé en base64url, sans = final ;
  • signature : le HMAC-SHA256 de charge (la chaîne encodée), avec la clé de contexte, encodé en base64url.

Le JSON accepte source, type et id (obligatoires), libelle, prerempli (nom, email, telephone), organisateur (l'identifiant d'un membre) et exp (expiration, en secondes Unix). Exemple en Node.js :

import crypto from "node:crypto";

const key = process.env.RDV_CONTEXT_KEY; // la clé de contexte de l'organisation
const payload = { source: "mon-crm", type: "affaire", id: "AFF-2026-0042", libelle: "Projet Dupont",
  prerempli: { nom: "Camille Martin", email: "camille.martin@example.com" },
  exp: Math.floor(Date.now() / 1000) + 14 * 86400 };
const body = Buffer.from(JSON.stringify(payload)).toString("base64url");
const signature = crypto.createHmac("sha256", key).update(body).digest("base64url");
const url = `https://adresse-de-votre-application/r/mon-espace/premier-echange?c=${body}.${signature}`;

Un type réglé sur « contexte requis » ne s'ouvre qu'avec un contexte valable. Un lien falsifié ou expiré ne s'ouvre pas.

Préremplir sans contexte

Pour un simple préremplissage, la page de réservation lit aussi name (ou first_name et last_name), email, phone, et a1 à a10 pour les réponses aux questions du type, dans leur ordre. Les paramètres de suivi utm_*, gclid, fbclid et ref sont gardés sur le rendez-vous. Le widget d'intégration les transmet pour vous.

Synchroniser dans les deux sens

  • Vers votre outil : abonnez-vous aux événements reservation.* avec votre application OAuth (POST /webhook-subscriptions). Une application n'entend que ce que son membre peut voir. Détail et vérification de la signature : webhooks.
  • Depuis votre outil : créez, déplacez ou annulez par l'API (POST /bookings, POST /bookings/{id}/move, POST /bookings/{id}/cancel), avec un Idempotency-Key sur chaque création.
  • Rattrapage : relisez les rendez-vous d'un objet avec GET /bookings?context_source=mon-crm&context_id=AFF-2026-0042.

Exemple : le CRM Pestaly

Le CRM Pestaly se branche comme n'importe quel autre client : il n'a pas de connecteur à part. Son intégration repose sur les trois pièces de cette page. Par exemple, sur une fiche affaire, un bouton « Proposer un rendez-vous » peut demander à l'API un lien signé avec source = pestaly, type = affaire et l'identifiant de l'affaire ; le rendez-vous pris revient ensuite par webhook, avec ce contexte, sur la bonne fiche. Si vous utilisez HubSpot, Salesforce ou Pipedrive, il n'y a rien à développer : voir les intégrations CRM.

Bonnes pratiques

  • Demandez les portées les plus étroites : types:lire et liens:ecrire suffisent pour poser des liens de réservation ; ajoutez reservations:lire pour lire les rendez-vous.
  • Gardez le secret de l'application, les jetons et la clé de contexte côté serveur, jamais dans un navigateur ou une application mobile.
  • Traitez les webhooks de façon idempotente et rafraîchissez les jetons avant leur expiration.
  • Respectez la limite de 100 appels par minute par jeton : voir limites et erreurs.

Questions fréquentes

Mon application doit-elle être déclarée dans chaque organisation cliente ?

Non. Elle est déclarée une fois, dans votre organisation ; chaque membre d'une autre organisation l'autorise ensuite pour son compte.

Le contexte est-il visible par l'invité ?

Le contexte voyage dans l'adresse, mais il est signé : toute modification rend le lien invalide. N'y mettez rien de confidentiel.

Puis-je imposer l'organisateur du rendez-vous ?

Oui, avec le champ organisateur du contexte (l'identifiant d'un membre). Le lien ne propose alors que ses créneaux.

Comment retrouver les rendez-vous d'une affaire ?

Avec GET /bookings et les filtres context_source et context_id, ou en lisant le champ contexte des webhooks.

Déclarez votre application

Créez votre compte, passez en formule Pro et déclarez votre application OAuth dans Réglages › Intégrations.

Créer mon compte