API et webhooks
Brancher vos autres outils sur les données de l'agence avec une clé d'API, et recevoir ses événements sur votre propre adresse.
Les clés se gèrent dans Organisation › API, les adresses de réception dans Organisation › Webhooks.
Avant de commencer
- Les rubriques API et Webhooks n'apparaissent dans le menu qu'avec le droit « Intégrations » (par défaut l'administrateur seul).
- Les deux pages ne s'ouvrent qu'à l'administrateur. Un manager ou un agent à qui l'on a donné le droit « Intégrations » voit les rubriques, mais il est renvoyé à l'accueil.
- Chaque fonction doit être comprise dans votre palier : « API » pour les clés, « Webhooks » pour les adresses (voir Abonnement et facturation). Sinon, la page le dit et propose Voir les paliers.
L'API
L'API donne accès aux données de votre agence, et d'elle seule.
| Ce que l'API permet | Clé nécessaire |
|---|---|
| Lire les contacts, les deux pipelines et leurs étapes, les opportunités, les mandats, les annonces et les visites | lecture |
| Créer un lead (contact retrouvé par son e-mail ou créé ; sur une annonce, une opportunité acquéreur) | lecture et écriture |
| Déplacer une opportunité vers une autre étape de son pipeline | lecture et écriture |
- Les mandats sont donnés sans marge de négociation, sans commission et sans journal.
- Chaque clé a droit à 120 requêtes par minute et 20 000 par jour.
La documentation technique
La page API affiche l'Adresse de l'API et un lien Documentation. Ce lien ouvre la documentation technique publique de l'API, destinée à votre développeur : chaque accès, ses paramètres, ses réponses, la façon de s'authentifier avec la clé et de parcourir les résultats page par page. En production, elle se trouve à l'adresse https://api.immobooking.be/api/v1/externe/docs.
Créer une clé
- Ouvrez Organisation › API.
- Sur la carte Nouvelle clé, saisissez le Nom de la clé (2 à 60 caractères), par exemple « Site de l'agence » ou « Tableau de bord ».
- Cochez Peut aussi écrire (créer des leads, déplacer des opportunités) si l'outil doit écrire. Sinon, la clé ne fait que lire.
- Cliquez sur Créer la clé.
- Sur la carte Votre nouvelle clé, cliquez sur Copier, puis rangez la clé en lieu sûr.
- Cliquez sur J'ai copié la clé.
Suivre et révoquer les clés
La liste Vos clés montre pour chaque clé son nom, son début, le badge « Lecture » ou « Lecture et écriture », sa date de création et sa dernière utilisation (ou « Jamais utilisée »).
- Cliquez sur Révoquer à côté de la clé.
- Confirmez. Le message « Clé révoquée. » s'affiche.
Les outils qui utilisent cette clé perdent l'accès immédiatement ; les autres clés continuent de fonctionner. Si votre palier perd la fonction « API », toutes les clés sont refusées.
Les webhooks
Un webhook envoie un message à l'adresse de votre outil à chaque événement de l'agence.
| Événement | Quand il part |
|---|---|
| « Lead créé (nouvelle opportunité) » | une nouvelle opportunité est créée |
| « Mandat signé » | un mandat est signé |
| « Annonce publiée » | une annonce est publiée |
| « Visite réservée » | une visite réservée en ligne est confirmée |
Ajouter une adresse
- Ouvrez Organisation › Webhooks.
- Sur la carte Nouvelle adresse, saisissez l'Adresse (https) de votre outil.
- Cochez au moins un des Événements.
- Cliquez sur Enregistrer l'adresse.
- Sur la carte Secret de signature, cliquez sur Copier et remettez le secret à votre développeur.
- Cliquez sur J'ai copié le secret.
- Le secret ne s'affiche qu'une fois. Votre outil s'en sert pour vérifier que les messages viennent bien d'ImmoBooking ; la carte Vérifier un message explique comment.
- Dix adresses au plus.
- Refus possibles : « Cette adresse n'est pas valable. », « L'adresse doit commencer par https://. », « Cette adresse désigne un réseau interne : elle est refusée. ».
Gérer une adresse
Dans Vos adresses, chaque adresse porte le badge « Active » ou « En pause ».
- Envoyer un essai : un message d'essai part dans la minute.
- Mettre en pause et Reprendre.
- Supprimer : plus aucun message n'y est envoyé, et l'historique de ses envois est effacé.
Suivre les envois
Sous Derniers envois, chaque message porte l'état « En attente », « Livré » ou « Échec », le nombre d'essais et, s'il y a lieu, l'heure du prochain essai.
- Votre outil doit répondre dans les 10 secondes par une réponse de succès. Une redirection n'est pas suivie et compte comme un échec.
- En cas d'échec, le message est renvoyé 1, 5 et 30 minutes plus tard, puis après 2, 6, 12 et 24 heures, soit pendant près de deux jours.
- Après le dernier essai, l'échec est définitif. Rejouer remet le message en attente (« Envoi remis en attente. »).