Connecter Beds24

1. Obtenir un token API

Beds24 API v2 fonctionne avec un token d'accès de courte durée, obtenu en échangeant un refresh token longue durée. Le refresh token se génère dans le back-office Beds24, sous Settings > Apps > API. L'échange se fait ensuite via POST /authentication/token pour obtenir le token d'accès à utiliser sur les autres appels.

Le client actuel (backend/internal/beds24/beds24.go) ne fait pas encore ce rafraîchissement automatiquement — c'est une TODO connue du code. Pour l'instant, il faut fournir directement un token d'accès valide via BEDS24_API_TOKEN.

2. Variable d'environnement `BEDS24_API_TOKEN`

Le client Beds24 est construit par beds24.NewFromEnv() (backend/internal/beds24/beds24.go), lu depuis DATABASE_URL-style env vars au démarrage de l'app. Si BEDS24_API_TOKEN est vide, tout appel (PushRoomCalendar) tourne en mode simulation (dry-run) : rien n'est envoyé à Beds24, la requête qui aurait été faite est journalisée et un enregistrement est quand même créé dans sync_runs pour que le tableau de bord reflète ce qui se serait passé.

Pour activer les appels réels, définissez le token dans docker-compose.yml (variable BEDS24_API_TOKEN du service app, déjà câblée) ou dans l'environnement au démarrage du conteneur — ne le committez jamais en clair dans le dépôt.

2bis. Gestion des secrets (refresh token, API keys, etc.)

Le refresh token Beds24, la clé Stripe et tout autre secret suivent le même principe : ils vivent uniquement dans l'environnement du conteneur, jamais dans le code ni dans docker-compose.yml committé — ce fichier ne référence que le nom de la variable (ex. BEDS24_API_TOKEN: ${BEDS24_API_TOKEN:-}), pas sa valeur.

En développement : créez un docker-compose.override.yml local (non commité, déjà ignoré par convention Docker Compose qui le charge automatiquement en plus de docker-compose.yml) contenant les vraies valeurs :

services:
  app:
    environment:
      BEDS24_API_TOKEN: "le-vrai-refresh-token"
      STRIPE_SECRET_KEY: "sk_test_..."

docker compose up fusionne automatiquement ce fichier avec docker-compose.yml — aucune commande spéciale à retenir, il suffit qu'il existe à côté. Ajoutez-le à .gitignore pour éviter tout commit accidentel.

En production : les secrets ne passent plus par un fichier local mais par le gestionnaire de secrets managé de Scaleway (Scaleway Secret Manager) — le secret y est stocké chiffré, versionné, et injecté dans le conteneur au déploiement (variable d'environnement ou montage, selon le mode de déploiement Scaleway Serverless Containers/Instances retenu), sans jamais transiter par un fichier sur disque ni par les logs de build. C'est la même logique qu'en dev — le code ne change pas, seule la source de la variable d'environnement change.

3. Limite de débit (crédits)

Beds24 applique une limite basée sur des crédits, sur une fenêtre glissante de 5 minutes au niveau du compte. Chaque réponse HTTP inclut des en-têtes x-five-min-limit-remaining, x-five-min-limit-resets-in et x-request-cost (voir docs/beds24-api-notes.md section 4). Le client actuel ne lit pas encore ces en-têtes ni ne fait de backoff — TODO signalée dans le code : lire ces en-têtes et alimenter sync_runs.credits_used pour éviter qu'une synchro en masse sur ~17-25 propriétés ne se fasse throttler silencieusement.

4. Étapes pour connecter une propriété