Créer et utiliser des clés API Vitruve

L'API Vitruve permet à un autre système de lire les données de votre organisation : récupérer les entraînements et les données d'entraînement, lister les utilisateurs de votre organisation, et alimenter des tableaux de bord personnalisés, des outils d'analyse, des automatisations ou votre propre entrepôt de données. Une API (Application Programming Interface, ou interface de programmation) est l'intermédiaire qui permet à deux systèmes d'échanger des données de façon sécurisée.

Elle s'adresse aux coachs, aux analystes de données et aux développeurs qui veulent exploiter davantage les données Vitruve. Pour connecter un partenaire prêt à l'emploi comme RockDaisy, TeamBuildr ou FYTT, créez plutôt la clé de ce partenaire dans Intégrations → Exporter.

Conditions requisesCopier le lien

• Vous êtes le Propriétaire de l'organisation.
• L'organisation dispose du forfait Professional (appelé Pro sur le site d'assistance).

Si Accès API n'apparaît pas dans les Paramètres, l'une de ces conditions n'est pas remplie. Consultez Forfait et accès.

Créer une clé APICopier le lien

1. Ouvrez Paramètres : sur le web ou l'ordinateur, la roue dentée de la barre latérale ; sur mobile, Plus (...) en bas à droite, puis Paramètres.
2. Sélectionnez Accès API.
3. Sélectionnez le bouton + en haut à droite.

4. Dans Créer une clé API, saisissez un Nom (obligatoire, par exemple l'outil qui l'utilisera) et une Description facultative.
5. Sélectionnez Enregistrer.

Vérification : la clé apparaît dans la liste avec son nom et une valeur abrégée. Utilisez le bouton de copie pour copier la clé complète ; l'application affiche Clé API copiée dans le presse-papiers.

Créez une clé par outil ou par intégration, pour pouvoir en révoquer une sans perturber les autres.

Consulter la documentationCopier le lien

La référence complète pour les développeurs, avec chaque point de terminaison, des exemples de réponses et les codes d'erreur, est la référence de l'API Vitruve (en anglais). Vous débutez ? Commencez par le Quickstart.

Appeler l'APICopier le lien

Chaque requête doit inclure la clé dans cet en-tête :

X-API-Key: your_key_here

Chaque clé est limitée à l'organisation qui l'a créée. L'URL de base est https://api-next.vitruve.fit/v1, et l'API lit avec GET et peut aussi créer, modifier et supprimer des athlètes, des équipes, des affectations de coachs, vos propres exercices, des profils charge-vitesse et des rapports de blessure, dans la limite de votre plan.

curl "https://api-next.vitruve.fit/v1/athletes?limit=5" \
  -H "X-API-Key: your_key_here"

Elle couvre les athlètes, les coachs, les équipes, les entraînements avec leurs séries et leurs répétitions, les programmes, les modèles, les profils charge-vitesse, les leaderboards, le bien-être (Wellness) et les blessures. Les listes sont paginées, et une clé peut envoyer 30 requêtes par minute (limites de débit).

Réponses d'erreur courantes :

Consultez les codes d'erreur pour la liste complète.

Révoquer une cléCopier le lien

1. Ouvrez Paramètres → Accès API.
2. Sélectionnez Révoquer à côté de la clé.
3. Confirmez avec Révoquer la clé.

La clé cesse immédiatement de fonctionner : les requêtes qui l'utilisent sont rejetées, ce qui peut interrompre tout système qui en dépend encore. Vous ne pouvez plus consulter ni modifier une clé révoquée. Créez une nouvelle clé et mettez à jour l'autre système s'il a encore besoin d'un accès.

Si un appel échoueCopier le lien

• 401 : vérifiez le nom de l'en-tête X-API-Key, que la clé a été copiée en entier et qu'elle n'a pas été révoquée.
• 403 « Your plan no longer includes API access » : les clés suivent le forfait à chaque requête. Elles cessent de fonctionner lorsque l'organisation quitte le forfait Professional ou que son abonnement prend fin, et fonctionnent de nouveau une fois le forfait rétabli.
• Aucun entraînement renvoyé : par défaut, la liste des entraînements ne contient que les séances terminées. Élargissez from et to, ou vérifiez avec status=pending.
• L'entrée Accès API a disparu : le forfait a peut-être changé, ou la propriété a été transférée. Seul le Propriétaire d'une organisation Professional peut gérer les clés.

Pour obtenir de l'aide sur l'API, écrivez à support@vitruve.fit.