API publique

Le contrat

Le document OpenAPI 3.0 est servi sans clé et engendré depuis le code qui répond : il ne peut pas décrire autre chose que ce que l'API rend réellement. C'est lui qu'il faut donner à un générateur de client.

Ouvrir openapi.json

Commencer

Fabriquez une clé au tableau de bord, dans Configuration. Son secret n'est montré qu'une fois — recopiez-le tout de suite, Cadanse n'en conserve qu'une empreinte et ne peut pas vous le redonner.

Vérifiez-la sur la route d'identité, qui n'exige aucune portée et rend votre studio, vos portées et votre quota restant :

curl -H "Authorization: Bearer cad_..." \
  https://cadanse.app/api/v1/moi

Puis lisez une collection. Chaque réponse porte « data » et « next » ; repassez « next » en « apres » jusqu'à ce qu'il soit nul.

curl -H "Authorization: Bearer cad_..." \
  "https://cadanse.app/api/v1/familles?limite=100"

120 requêtes par minute et 20000 par jour, par clé. Un dépassement rend 429 avec l'en-tête « Retry-After ». Le compteur est fermé par défaut : injoignable, il refuse plutôt que de laisser passer.

Pagination et filtre

Les trois paramètres acceptés par chaque collection.

Collections

Chacune demande la portée « <ressource>:lecture » (par exemple « familles:lecture » ; cours, camps, événements et représentations n'exposent aucune coordonnée de famille). Les champs listés sont exhaustifs : ce qui n'y figure pas ne sort pas de Cadanse.

Écrire

Chaque écriture demande la portée « <ressource>:ecriture » (par exemple « inscriptions:ecriture »), et l'enregistrement d'un paiement sa propre portée « paiements:ecriture », à cocher séparément. Chacune passe par la même règle que l'écran correspondant du tableau de bord : une inscription refusée à l'écran est refusée ici, et le code d'erreur nomme la règle qui a refusé. Les champs listés sont les seuls acceptés ; un champ inconnu, ou un champ que l'API ne lit pas, fait 400.

L'en-tête « Idempotency-Key » est obligatoire : une valeur à vous, unique par écriture. Réessayer avec la même clé rend la réponse d'origine pendant 24 heures, avec l'en-tête « Idempotent-Replayed: true » — c'est ce qui vous laisse réessayer sans risquer une deuxième inscription. La même clé sur un corps différent fait 409 ; une écriture refusée, elle, libère la clé, pour que vous puissiez corriger votre envoi et réessayer avec la même.

Une création, et la même relancée :

curl -X POST -H "Authorization: Bearer cad_..." \
  -H "Idempotency-Key: 8f1c-..." \
  -H "Content-Type: application/json" \
  -d '{"lastName":"…","contactEmail":"…"}' \
  https://cadanse.app/api/v1/familles

Erreurs

Toute erreur rend la même forme : « error.code » et « error.message ». Le code est contractuel, le message peut être reformulé.

Webhooks sortants

L'API se lit et s'écrit à votre initiative ; les webhooks, eux, viennent à vous. Une destination se branche au tableau de bord, dans Configuration : une adresse HTTPS, les événements souscrits, et un secret de signature montré une fois. Cadanse y envoie un POST « application/json » à chaque événement.

Vérifier la signature

Chaque envoi porte l'en-tête « Cadanse-Signature », de la forme « t=<millisecondes>,v1=<hex> » : « v1 » est le HMAC-SHA256 du texte « <t>.<corps brut> », avec votre secret comme clé. Vérifiez le corps BRUT, avant toute désérialisation. Vérifiez la signature d'ABORD et l'horodatage ensuite : refuser sur l'âge avant d'avoir prouvé l'authenticité apprend à qui vous écrit quelle heure vous acceptez. Au-delà de 5 minutes, refusez — c'est ce qui empêche de rejouer chez vous un corps capté une fois. L'en-tête « Cadanse-Event » nomme l'événement, pour router sans lire le corps.

Cadanse-Signature: t=1776171600000,v1=<hex>
Cadanse-Event: inscription.creee

L'enveloppe

Toujours la même forme : « id », « type », « createdAt », « studioId » et « data ». « id » est celui de la LIVRAISON, pas de l'objet : les reprises d'un même envoi le répètent — c'est ce qui vous permet de dédoublonner — et un rejeu demandé à la main en porte un nouveau. « createdAt » est l'instant de l'événement ; aucune charge ne porte un second horodatage. Les champs de « data » sont des identifiants : les fiches complètes se lisent aux collections ci-dessus.

Reprises

Une réponse 2xx conclut la livraison. Sinon, 3 reprises, à 1 h, 6 h, 24 h, puis plus rien : un événement livré trois jours trop tard n'informe plus personne. La fenêtre totale est de 48 h. Répondez vite — un appel est abandonné au-delà de 2 secondes — et faites votre travail après avoir répondu. Le tableau de bord montre chaque livraison, son code de réponse et le message d'erreur de votre serveur ; une livraison épuisée s'y rejoue à la main.

Les événements

Souscrire un événement qui n'envoie encore rien est permis, et la colonne de droite le dit : c'est l'état réel, lu dans le code qui émet.

Connecteurs

Zapier, Make et les assistants qui parlent MCP se branchent sur tout ce qui précède, et sur rien d'autre : la même clé, les mêmes portées, le même quota, le même journal. Un connecteur n'ouvre pas une porte de plus — il emprunte une porte que vous avez déjà ouverte, et la clé se révoque au tableau de bord.

Zapier et Make

Rien à installer : créez une connexion « API par clé » avec l'en-tête « Authorization » et, pour valeur, « Bearer » suivi de votre clé. Testez-la sur https://cadanse.app/api/v1/moi — cette route répond quelles que soient les portées de la clé et vous rend le nom du studio et la liste de ce qu'elle permet.

Vos déclencheurs sont les webhooks ci-dessus. Zapier comme Make vous donnent une URL d'écoute : collez-la au tableau de bord et cochez les événements voulus. Ni l'un ni l'autre ne vérifie la signature pour vous — faites-la vérifier par une étape de code avant d'agir sur une charge, avec la recette donnée plus haut.

Vos actions sont les écritures ci-dessus, appelées par une étape « requête HTTP ». Renseignez toujours « Idempotency-Key » : un scénario que la plateforme rejoue après une panne recréerait sinon la même fiche deux fois.

Serveur MCP

Un assistant qui parle MCP se branche sur https://cadanse.app/api/v1/mcp — transport HTTP, requêtes POST, même en-tête « Authorization ». C'est votre studio qui décide : brancher un assistant fait sortir des données vers un outil que vous choisissez, sous une clé que vous créez et que vous pouvez révoquer.

{
  "mcpServers": {
    "cadanse": {
      "type": "http",
      "url": "https://cadanse.app/api/v1/mcp",
      "headers": {
        "Authorization": "Bearer cad_..."
      }
    }
  }
}

Le serveur expose 9 outils de lecture et 5 outils d'écriture — exactement les collections et les écritures documentées ci-dessus, aucune autre. Le nom d'un outil est celui de son opération, en minuscules soulignées :

lister_familles, lister_eleves, lister_cours, lister_inscriptions, lister_presences, lister_paiements, lister_evenements, lister_camps, lister_representations, creer_famille, creer_eleve, creer_inscription, marquer_presence, creer_paiement

Le catalogue dépend de la clé : « tools/list » ne rend que les outils couverts par ses portées. Un outil hors portée n'existe pas pour cette clé — l'appeler répond « outil inconnu », ce qui évite d'apprendre à un curieux quelles portées existent.

Les lots JSON-RPC sont refusés : un appel est une requête, et une requête est une unité de quota. Les lectures faites par MCP sont consignées comme les autres — une fenêtre par clé, par collection et par jour — au même journal que le studio peut relire.

Les outils d'écriture agissent immédiatement, et ce qu'ils écrivent est visible du personnel et des familles. Chacun accepte un argument « cleIdempotence » facultatif : sans lui, deux appels identiques font deux écritures — c'est voulu, deux paiements comptant du même montant le même samedi sont deux paiements. Le journal d'audit garde la trace de chaque écriture, qu'elle vienne d'un assistant ou d'un appel HTTP.

Pourquoi cette page ne peut pas mentir

Elle est rendue depuis le même document que openapi.json, lui-même engendré depuis les sérialiseurs qui écrivent les réponses. Un champ retiré du code disparaît d'ici sans que personne y pense ; un champ documenté qui ne serait pas servi est impossible à écrire.