Premier appel

Vérifie ta clé avec un appel gratuit, lis ton solde de crédits, puis fais ton premier appel facturé sur tes élèves.

Ton premier appel ne coûte rien. Il vérifie que ta clé fonctionne, et il te dit qui tu es pour l'API, ce que ta clé peut faire et combien de crédits il te reste.

1. Appelle `GET /me`

Ouvre le Terminal (Mac) ou l'Invite de commandes (Windows 10 et plus). Remplace fd_live_xxxxxxxx par ta clé et lance :

curl "https://api.fitdistance.io/api/partner/v1/me" -H "Authorization: Bearer fd_live_xxxxxxxx"

Garde le mot Bearer, une espace, puis ta clé entière.

2. Lis la réponse

Voici un extrait, avec des valeurs fictives :

{
  "coach": { "id": 42, "first_name": "Camille", "last_name": "Martin" },
  "tier": "maestro",
  "key": { "name": "Synchro nocturne", "scopes": ["students:read", "training:read"] },
  "credits": {
    "plan_remaining": 487,
    "plan_resets_at": "2026-11-01T00:00:00.000Z",
    "bonus_remaining": 0
  }
}

Champ	Ce qu'il dit
`coach`	Toi : ton identifiant, ton prénom et ton nom.
`tier`	Ton offre.
`key.scopes`	Ce que la clé peut faire.
`credits.plan_remaining`	Les crédits inclus qu'il te reste ce mois-ci.
`credits.plan_resets_at`	La date où les crédits inclus sont remis à zéro.
`credits.bonus_remaining`	Ta réserve : les crédits achetés en packs ou accordés, qui ne périment jamais. Seul le propriétaire de l'équipe achète des packs.

La réponse complète a d'autres champs, décrits dans la référence. Cet appel est gratuit, mais il compte dans la cadence de ta clé.

Si tu reçois un 401 UNAUTHORIZED, la clé est absente, inconnue ou révoquée : recopie-la en entier. Un 403 PLAN_NOT_ELIGIBLE veut dire que ton offre n'ouvre pas l'API.

3. Fais un appel facturé

Liste maintenant tes élèves. L'option -i affiche aussi les en-têtes de la réponse :

curl -i "https://api.fitdistance.io/api/partner/v1/students?limit=50" -H "Authorization: Bearer fd_live_xxxxxxxx"

Cet appel renvoie jusqu'à 50 élèves actifs et coûte un crédit, débité avant l'exécution. Il demande le périmètre Élèves › Lire (students:read). Un paramètre refusé, comme limit=500, donne un 400 VALIDATION et coûte aussi un crédit. Sur une opération, c'est différent : un argument que son schéma refuse est remboursé, et seul le refus de l'opération elle-même reste facturé. Voici un extrait du corps :

{
  "data": [
    {
      "id": 1,
      "first_name": "Léa",
      "last_name": "Dupont",
      "contract_status": "ACTIVE",
      "updated_at": "2026-10-24T08:12:00.000Z"
    }
  ],
  "next_cursor": null,
  "has_more": false
}

Les élèves sont dans data. Quand has_more vaut true, il reste des pages : next_cursor est ce que tu passes dans cursor pour lire la suivante.

4. Repère les crédits dans les en-têtes

Chaque réponse facturée porte deux en-têtes :

X-Credits-Remaining: 486
X-Credits-Plan-Resets-At: 2026-11-01T00:00:00.000Z

X-Credits-Remaining est le total qu'il te reste, crédits inclus et réserve ensemble. X-Credits-Plan-Resets-At est la date de remise à zéro des crédits inclus. GET /me ne renvoie pas ces en-têtes : il donne les mêmes chiffres dans son corps.

Si tu reçois un 403 SCOPE_MISSING, la clé n'a pas le périmètre demandé et details.scope le nomme. Un 402 CREDITS_EXHAUSTED veut dire qu'il ne te reste aucun crédit. Ni l'un ni l'autre ne coûte un crédit.

La suite

Passe à Écrire un script pour lire toutes les pages et écrire sans doublon, ou à Clés et crédits pour savoir ce qui coûte un crédit.