API et domotique

L’API de Bercail sert à brancher le foyer sur autre chose : un tableau de bord, Home Assistant, un script, un affichage dans la cuisine. Elle est en lecture seule : elle expose ce que contient le foyer, elle ne le modifie pas.

Référence interactive (essayer les routes, voir les champs) : https://api.bercail.rilaun.fr
Contrat OpenAPI : openapi.yaml, le fichier qui décrit les routes ci-dessous et alimente la référence

Créer une clé d’API

Dans l’application : Paramètres du foyer → Clés d’API (propriétaire ou administrateur).

Créer une clé et lui donner un nom : celui de l’application qui l’utilisera (« Home Assistant »,

« tableau de bord »). Une clé par application, pour pouvoir en révoquer une sans casser les autres.

Choisir les modules que la clé peut lire : Bernard, Lulu, Léon, Annie.
Copier la clé immédiatement : elle n’est affichée qu’une seule fois. Seule son empreinte est conservée

sur le serveur.

La liste montre la date de création et de dernière utilisation de chaque clé, et permet de la révoquer après confirmation.

Appeler l’API

La clé s’envoie dans un en-tête, jamais dans l’adresse (les adresses finissent dans les journaux et les historiques de navigation) :

curl -H "Authorization: Bearer bcl_…" https://app.bercail.rilaun.fr/api/v1/bernard/stock

X-API-Key: bcl_… est aussi accepté. L’adresse ne contient pas le foyer : c’est la clé qui le désigne. Une session de navigateur ne suffit pas.

Les routes

Route	Module	Ce qu’elle renvoie
`GET /api/v1/bernard/stock`	Bernard	Stock regroupé par aliment (`foods`) et en entrées (`items`)
`GET /api/v1/stock`	Bernard	La même réponse : adresse d’origine, gardée pour les clients existants
`GET /api/v1/lulu/recipes`	Lulu	Recettes du carnet, ingrédients analysés
`GET /api/v1/leon/items`	Léon	Consommables, seuils et état « à racheter »
`GET /api/v1/annie/items`	Annie	Achats, prix, fins de garantie et état de la garantie

Toutes les réponses commencent par une enveloppe commune :

{
  "version": 1,
  "generated_at": "2026-11-06T08:00:00.000Z",
  "today": "2026-11-06",
  "timezone": "Europe/Paris"
}

today et timezone sont ceux du foyer : ils servent à interpréter les dates de péremption et les fins de garantie. Les données suivent sous une clé propre à la route (foods, items, recipes).

Exemple : les produits à finir

curl -s -H "Authorization: Bearer bcl_…" \
  https://app.bercail.rilaun.fr/api/v1/bernard/stock \
  | python3 -c "import json,sys
d = json.load(sys.stdin)
for f in d['foods']:
    if f['expiry_status'] in ('expired', 'expiring'):
        print(f['expiry_status'], f['name'], f['quantity'], f['unit_label'], f['days_left'], 'jours')"

Les erreurs

Toutes les erreurs ont la même forme, avec un code stable à utiliser dans le code client :

{ "error": "scope_missing", "message": "Cette clé ne donne pas accès au module leon", "params": { "module": "leon" } }

Code	Sens
`401 api_key_required`	Clé absente, mal formée, inconnue ou révoquée
`403 scope_missing`	La clé ne donne pas accès à ce module
`403 module_disabled`	Le module est désactivé dans le foyer (il refonctionne s’il est réactivé)
`429 too_many_attempts`	Trop d’échecs d’authentification depuis cette adresse ; l’attente est indiquée
`404 not_found`	Route inconnue
`500 internal`	Erreur du serveur

Versionnement

La version est dans l’adresse (/api/v1) et rappelée dans le champ version.
Sans changer de version, Bercail peut ajouter des routes, des champs ou des codes d’erreur : un client

doit ignorer ce qu’il ne connaît pas.

Supprimer ou renommer un champ, changer son type ou son sens, ou changer une adresse demande une v2,

servie en parallèle pendant une transition annoncée à l’avance.

Bon à savoir

Traitez une clé d’API comme un mot de passe : ni dans une adresse, ni dans un dépôt, ni dans un journal.
Une clé se limite aux modules choisis à sa création : pour ajouter un module, créez une nouvelle clé et

révoquez l’ancienne.

L’API de Bercail ne donne pas accès aux fichiers du foyer (factures, photos) : seules les métadonnées

sortent.