Connectez votre outil par l'API
Votre logiciel n'est pas dans la liste ? Générez un jeton d'import et faites envoyer vos logements, vos réservations et vos missions par votre propre outil, avec la source personnalisée.
La vidéo de ce guide arrive bientôt.
La source personnalisée (API) alimente The Big One depuis n'importe quel outil : votre logiciel maison, un tableur automatisé, un outil que nous ne connaissons pas. Votre outil envoie logements, réservations, missions et noms de planning par une simple requête. Cet article vous montre quoi préparer et quoi transmettre à la personne qui fera le branchement. Comptez 5 minutes de votre côté.
Votre logiciel figure dans la page Intégrations ? Reliez-le plutôt sans développement : Connectez votre logiciel de gestion.
Ce que la connexion synchronise
| Donnée | Sens | Remarque |
|---|---|---|
| Logements | De votre outil vers The Big One | Un logement absent d'un envoi n'est jamais supprimé |
| Réservations | De votre outil vers The Big One | Annulées seulement si votre outil déclare une période complète |
| Missions | De votre outil vers The Big One | Une mission commencée, terminée ou validée n'est jamais écrasée |
| Noms de planning | De votre outil vers The Big One | Rapprochés des comptes existants ; aucun compte n'est créé |
Avant de commencer
- Vous êtes administrateur : la page Intégrations est réservée à l'administrateur.
- Une personne sait écrire un petit programme qui envoie des données : votre développeur, ou l'éditeur de votre outil.
- Chaque logement, réservation et mission de votre outil a un identifiant qui ne change pas. Il sert à ne créer aucun doublon.
Générer le jeton d'import
Pas à pas
- 1
Ouvrez Paramètres › Flux et intégrations › Intégrations.
- 2
En haut de la page, cliquez sur le filtre « Développeurs ». La carte « Source personnalisée (API) » s'y trouve.
- 3
Cliquez sur Générer un jeton. La fenêtre « Votre jeton d'import » s'ouvre.
- 4
Cliquez sur Copier le jeton. Le message « Jeton copié. » s'affiche.
- 5
Rangez le jeton dans un endroit sûr, puis fermez la fenêtre. La carte porte la mention « Jeton actif ».
Transmettre les informations à votre développeur
Pas à pas
- 1
Sur la carte, à côté de « Adresse d'envoi : », cliquez sur Copier. Le message « Adresse copiée. » s'affiche.
- 2
Cliquez sur Voir la documentation. La page décrit l'adresse, les en-têtes, un exemple complet, les règles d'import et les limites.
- 3
Envoyez à votre développeur l'adresse d'envoi, le lien de la documentation et, par un canal sûr, le jeton.
Les règles à connaître avant d'écrire le programme :
| Règle | Ce qu'elle veut dire |
|---|---|
| Un identifiant par élément | Chaque élément est reconnu par son identifiant : renvoyer le même contenu ne crée aucun doublon |
| Logement absent d'un envoi | Il n'est jamais supprimé : seule la valeur « actif » envoyée fait foi |
| Linge du logement | À chaque envoi, la partie linge de la fiche est remplacée en entier : une saisie faite à la main est écrasée |
| Mission déjà commencée | Elle n'est jamais écrasée : seuls ses champs vides sont complétés |
Vérifier les imports
Pas à pas
- 1
Sur la carte « Source personnalisée (API) », lisez la ligne « Dernier import : ». Elle donne la date du dernier envoi reçu.
- 2
Dépliez « 30 derniers imports ». Chaque ligne compte, par type de donnée, les éléments créés, mis à jour et conservés.
- 3
Une ligne signale des erreurs ? Dépliez-la pour lire le détail, puis transmettez-le à votre développeur.
Révoquer le jeton
À faire si le jeton a circulé, ou quand vous changez d'outil.
Pas à pas
- 1
Sur la carte, cliquez sur Révoquer. La fenêtre « Révoquer le jeton ? » s'ouvre.
- 2
Cliquez sur Révoquer le jeton. Le message « Jeton révoqué : les prochains appels seront refusés. » s'affiche.
- 3
Pour rebrancher votre outil, cliquez de nouveau sur Générer un jeton et donnez le nouveau jeton à votre développeur.
Questions fréquentes
Faut-il un développeur ?
Oui. La source personnalisée attend des données envoyées par un programme. Sans développeur, reliez un logiciel de la page Intégrations ou un lien iCal.
Un logement importé par l'API peut-il être relié à une annonce d'une autre intégration ?
Non. Votre outil le retrouve par son identifiant à chaque envoi : il ne peut pas être relié à une annonce d'une autre intégration.
Mon outil peut-il être prévenu quand une mission est terminée ?
Oui. Sous le filtre « Développeurs », la carte « Accès développeurs » permet d'ajouter une adresse à prévenir quand une mission est assignée, démarrée, terminée ou validée.
Que se passe-t-il si je génère un nouveau jeton ?
L'ancien est révoqué : les envois qui l'utilisent sont refusés. Donnez le nouveau jeton à votre développeur.
Les comptes des agents sont-ils créés par l'import ?
Non. Aucun compte n'est créé par un import : les noms sans correspondance sont renvoyés à votre outil pour que vous invitiez la personne.