Documentation technique

Inscrivez-vous sur app.optibilan.com/inscription. Choisissez votre offre (Solo/Studio/Cabinet), renseignez votre marque (nom, logo, couleurs), votre vocabulaire (coaché, patient, membre...), et votre domaine si vous en avez un. En 3 minutes, votre espace est prêt.

Depuis l'admin → Équipe, ajoutez vos coachs, diététiciens, préparateurs mentaux. Définissez leur rôle (coach/mental/diet) pour scoper leurs accès. Ils reçoivent un lien d'activation pour définir leur mot de passe.

Deux options : (1) Création manuelle depuis l'espace coach → "Ajouter un client" → lien d'activation à transmettre. (2) Via l'API : POST /api/v1/clients avec votre clé API (scope clients:write). Le coaché reçoit son lien, choisit son mot de passe, remplit le questionnaire de lancement.

Admin → Organisation → Marque : logo, couleurs (thème ou palette custom), nom de l'assistant IA, vocabulaire, message d'accueil, modules on/off, mentions légales du cabinet, URL d'avis, programme parrainage. Tout est appliqué instantanément sur l'espace coaché.

Générez une clé API dans Admin → API (format obk_...). Scopez-la (clients:read, checkins:write, cron...). Utilisez le header Authorization: Bearer obk_.... Rate limit : 120 req/min par clé.

GET /api/v1/clients (liste, pagination, filtres), GET /api/v1/clients/:id, POST /api/v1/clients, PATCH /api/v1/clients/:id. Réponse JSON standardisée avec data, meta.

GET /api/v1/clients/:id/checkins, POST /api/v1/clients/:id/checkins. Champs : poids, mensurations (JSON), faim, motivation, sommeil, pas, texte libre. Scope auto par orgId de la clé.

GET/POST /api/v1/clients/:id/nutrition. Structure : protéines, glucides, lipides, légumes, fruits, plaisirs, courses, compléments, méthodes, repas, notes.

GET/POST /api/v1/clients/:id/photos. Upload via multipart/form-data ou data-URL. Types : FACE, PROFIL, DOS. Vignettes auto-générées. Stockage Supabase bucket privé.

GET/POST /api/v1/clients/:id/health. Métriques : sleep_hours, sleep_score, hrv, resting_hr, vo2max, steps, weight, body_fat. Sources : manual, apple_health, oura, whoop, garmin.

Admin → Webhooks : URL, événements (client.created, checkin.submitted, badge.earned, nutrition.updated, call.overdue, client.weak_signal...), secret HMAC. Signature dans header x-optibilan-signature. Retry exponentiel (max 5x). Idempotence via externalId.

Deux voies : (1) Côté coaché : raccourci iOS "Health Auto Export" → POST sur /api/health-sync avec header Authorization: Bearer hsk_... (token généré dans Mon compte). (2) Côté cabinet : n8n/Make/Zapier qui récupère via API partenaire et pousse sur /api/health-sync avec clé API scope cron.

Chaque staff a un token calendrier dans Mon compte → Calendrier. L'URL https://app.optibilan.com/api/calendrier/.ics s'abonne dans Google Calendar, Apple Calendrier, Outlook. Contient les appels planifiés (titre, date, lien fiche coaché). Filtré par rôle (coach ne voit pas les coachés masqués).

Utilisez les clés API (scope cron ou clients:read + checkins:write) + webhooks pour automatiser : nouveau client → créer dossier Notion, bilan déposé → poster sur Slack, paiement Stripe → envoyer email personnalisé.

Admin → Organisation → Webhook Slack entrant. Reçoit : nouveau coaché, bilan déposé, appel en retard, signal faible, demande suppression RGPD. Format message structuré avec liens vers l'app.

Via n8n webhook note.created : pousse les notes de suivi coaching dans une base Notion (propriétés : client, coach, date, type, contenu, visibilité).

Extension Prisma tenant-guard : injection auto de orgId sur TOUTES les requêtes (lecture/écriture/nested). Fail-closed : pas de contexte org = erreur. Testé par test:isolation.mts (13/13).

Admin → Export : JSON complet de TOUTES les données du cabinet (37 modèles). Vérifié en CI (check-tenant.mjs) : aucun modèle cloisonné oublié. Purge auto paramétrable (durée + flag). Droit à l'oubli : suppression client (cascade) par admin.

Content-Security-Policy stricte (script-src 'self' 'unsafe-inline', connect-src 'self' https://api.stripe.com, frame-ancestors 'none', base-uri 'self'). HSTS, X-Frame-Options: DENY, X-Content-Type-Options: nosniff, Referrer-Policy: strict-origin-when-cross-origin, Permissions-Policy restrictif.

Persistant en base (survit aux redémarrages). Fenêtres glissantes : login IP (30/15min), login email (5/15min + lock 15min), 2FA (6/15min), IA user (15/min, 25/jour), IA org (plafond mensuel par offre), API keys (120/min), cron (budget 240s). Fail-open : ne bloque jamais un légitime.

Deux niveaux : AuditLog (par org, actions utilisateurs) + PlatformAuditLog (équipe Optibilan : suspension org, changement plan, dépannage). Horodaté, IP, user-agent, meta JSON.

Fichier .env (local) ou deploy/prod.env (VPS). Secrets : AUTH_SECRET (≥32c), CRON_SECRET (≥24c), STRIPE_*, RESEND_API_KEY, SUPABASE_*, ANTHROPIC_API_KEY, VAPID_*. NEXT_PUBLIC_APP_URL pour les liens publics.

docker compose -f compose.prod.yml up -d. Image standalone Next.js. Healthcheck /api/health. Traefik reverse proxy (TLS auto via Let's Encrypt). Volumes : uploads (Supabase), logs.

cloudflared tunnel run --token $TOKEN optibilan. Pas de port ouvert sur le VPS. WAF, DDoS, cache, analytics inclus. Zéro config nginx/Traefik.

Healthcheck /api/health (DB, Redis, Supabase). Logs structurés JSON. Cron /api/cron/maintenance rapporte : usage par org, conservation, essais expirés, tokens purgés. Alertes Slack sur erreurs 5xx.

Supabase : PITR (Point-in-Time Recovery) 7 jours + snapshots quotidiens. Script npm run vps:backup déclenche systemctl start optibilan-backup.service (pg_dump compressé, chiffré, stocké sur S3-compatible). Rétention 30 jours.