Aller au contenu
Bandjo

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_.

La clé n'est affichée qu'une seule fois. Copiez-la tout de suite et gardez-la secrète, comme un mot de passe. En cas de perte ou de doute, supprimez-la dans l'application et créez-en une nouvelle.

2. Appeler l'API

Adressehttps://bandjo.fr/api/v1/action
MéthodePOST (sans corps)
En-têteAuthorization: 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

CodeSignification
200Action 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).
401Clé absente, invalide ou supprimée.
405Méthode autre que POST.
422Action 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.
429Quota 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.