API d'automatisation
Un bouton, une action.
Avec l'API Bandjo, un bouton connecté, un raccourci de téléphone (Raccourcis sur iPhone, Tasker ou HTTP Shortcuts sur Android), un Stream Deck ou votre domotique (Home Assistant, Jeedom…) peut déclencher une action dans votre famille à chaque appui :
- envoyer un message dans une discussion : « Je suis rentré 🏠 » ;
- ajouter un article à une liste : « Lait (2 L) » dans la liste de courses ;
- cocher une tâche ménagère pour aujourd'hui : « Vaisselle faite ».
1. Créer une clé dans l'application
Dans Bandjo : Menu ⋮ › Automatisations (API) › Nouvelle. Choisissez l'action, la discussion,
la liste ou la tâche visée et le texte. L'application affiche alors votre clé, qui commence par
bdj_.
2. Appeler l'API
| Adresse | https://bandjo.fr/api/v1/action |
|---|---|
| Méthode | POST (sans corps) |
| En-tête | Authorization: Bearer bdj_votre_cle |
Exemple en ligne de commande :
curl -X POST https://bandjo.fr/api/v1/action \
-H "Authorization: Bearer bdj_votre_cle"
Exemple Home Assistant (configuration.yaml) :
rest_command:
bandjo_rentre:
url: https://bandjo.fr/api/v1/action
method: POST
headers:
Authorization: !secret bandjo_cle_rentre
Raccourcis (iPhone) : action « Obtenir le contenu de l'URL », méthode POST, en-tête
Authorization avec la valeur Bearer bdj_….
3. Réponses
| Code | Signification |
|---|---|
200 | Action effectuée. Exemple :
{"ok":true,"action":"liste","name":"Lait","message":"Ajouté à la liste","remaining":4}
(remaining : appels encore possibles dans la fenêtre en cours). |
401 | Clé absente, invalide ou supprimée. |
405 | Méthode autre que POST. |
422 | Action refusée : vous n'avez plus accès à la discussion ou à la liste, le module est désactivé, l'abonnement de la famille a pris fin… L'appel compte dans le quota. |
429 | Quota atteint (quota_atteint) ou trop de clés invalides depuis votre
adresse (trop_d_essais). L'en-tête Retry-After indique en secondes quand réessayer. |
4. Règles d'usage et quota
- 5 appels par tranche glissante de 15 minutes et par personne, toutes clés confondues.
- Au-delà, les appels sont refusés (code
429) sans rien déclencher, puis acceptés à nouveau automatiquement dès qu'une place se libère. - Au premier dépassement, un e-mail « Quota d'usage limite atteint » est envoyé à l'adresse de votre compte (au plus un par 24 heures). Si ce n'est pas vous, supprimez vos clés.
- 10 clés au maximum par personne. Les automatisations sont réservées aux adultes.
- L'API sert à des actions déclenchées par une personne ou un évènement de la maison, pas à des envois en boucle ni à de la publicité. Un usage abusif peut entraîner la suppression des clés.
Besoin d'un quota plus élevé ? Écrivez à [email protected] depuis l'adresse de votre compte Bandjo, avec l'objet « Demande de modification du quota API », en expliquant votre usage (appareil, fréquence attendue).
5. Sécurité
- Une clé = une action figée. L'API n'accepte aucun paramètre : une clé ne peut que rejouer l'action choisie à sa création. Elle ne permet ni de lire vos données, ni d'agir ailleurs.
- L'action s'exécute avec vos droits du moment, revérifiés à chaque appel : si vous quittez la discussion ou la famille, la clé ne fait plus rien.
- La clé (256 bits aléatoires) n'est conservée que sous forme d'empreinte : personne chez Bandjo ne peut la relire. L'application n'en garde que les 4 derniers caractères pour vous aider à la reconnaître.
- Envoyez la clé uniquement dans l'en-tête
Authorization, jamais dans l'adresse : les adresses sont souvent enregistrées dans les historiques. - L'API ne peut pas être appelée depuis une page web (pas de CORS) : elle est faite pour les appareils et les scripts.