API pública

El contrato

El documento OpenAPI 3.0 se sirve sin clave y se genera desde el código que responde: no puede describir nada distinto de lo que la API devuelve realmente. Es lo que hay que entregar a un generador de clientes.

Abrir openapi.json

Empezar

Cree una clave en el panel, en Configuración. Su secreto se muestra una sola vez — cópielo enseguida; Cadanse solo guarda una huella y no puede volver a mostrarlo.

Compruébela en la ruta de identidad, que no exige ningún alcance y devuelve su escuela, sus alcances y su cuota restante:

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

Después lea una colección. Cada respuesta lleva «data» y «next»; devuelva «next» como «apres» hasta que sea nulo.

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

120 peticiones por minuto y 20000 por día, por clave. Superarlas devuelve 429 con la cabecera «Retry-After». El contador está cerrado por defecto: si no responde, la petición se rechaza en vez de dejarse pasar.

Paginación y filtro

Los tres parámetros que acepta cada colección.

Colecciones

Cada una exige el alcance «<recurso>:lecture» (por ejemplo «familles:lecture»; cursos, campamentos, eventos y funciones no exponen datos de contacto de las familias). Los campos indicados son exhaustivos: lo que no aparece no sale de Cadanse.

Escribir

Cada escritura exige el alcance «<recurso>:ecriture» (por ejemplo «inscriptions:ecriture»), y registrar un pago tiene su propio alcance «paiements:ecriture», que se marca aparte. Cada una pasa por la misma regla que la pantalla correspondiente del panel: una inscripción rechazada en pantalla se rechaza también aquí, y el código de error nombra la regla que la rechazó. Los campos indicados son los únicos aceptados; un campo desconocido, o uno que la API no lee, devuelve 400.

La cabecera «Idempotency-Key» es obligatoria: un valor suyo, único por escritura. Reintentar con la misma clave devuelve la respuesta original durante 24 horas, con la cabecera «Idempotent-Replayed: true» — eso es lo que le permite reintentar sin arriesgar una segunda inscripción. La misma clave con un cuerpo distinto devuelve 409; una escritura rechazada, en cambio, libera la clave, para que pueda corregir su envío y reintentar con la misma.

Una creación, y la misma llamada repetida:

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

Errores

Todo error devuelve la misma forma: «error.code» y «error.message». El código es contractual; el mensaje puede reformularse.

Webhooks salientes

La API se lee y se escribe por iniciativa suya; los webhooks, en cambio, van hacia usted. Un destino se conecta desde el panel, en Configuración: una dirección HTTPS, los eventos suscritos y un secreto de firma que se muestra una sola vez. Cadanse envía allí un POST «application/json» en cada evento.

Verificar la firma

Cada envío lleva la cabecera «Cadanse-Signature», con la forma «t=<milisegundos>,v1=<hex>»: «v1» es el HMAC-SHA256 del texto «<t>.<cuerpo en bruto>», con su secreto como clave. Verifique el cuerpo EN BRUTO, antes de deserializarlo. Compruebe primero la firma y solo después la marca de tiempo: rechazar por antigüedad antes de probar la autenticidad revela a quien le escribe qué hora acepta. Pasados 5 minutos, rechace — eso es lo que impide reproducir en su sistema un cuerpo captado una vez. La cabecera «Cadanse-Event» nombra el evento, para enrutar sin leer el cuerpo.

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

El sobre

Siempre la misma forma: «id», «type», «createdAt», «studioId» y «data». «id» es el de la ENTREGA, no el del objeto: los reintentos de un mismo envío lo repiten — es lo que le permite eliminar duplicados — y una reproducción manual lleva uno nuevo. «createdAt» es el instante del evento; ninguna carga lleva una segunda marca de tiempo. Los campos de «data» son identificadores: las fichas completas se leen en las colecciones anteriores.

Reintentos

Una respuesta 2xx cierra la entrega. Si no, 3 reintentos, a las 1 h, 6 h, 24 h, y después nada: un evento entregado tres días tarde ya no informa a nadie. La ventana total es de 48 h. Responda rápido — una llamada se abandona pasados 2 segundos — y haga su trabajo después de responder. El panel muestra cada entrega, su código de respuesta y el mensaje de error de su servidor; una entrega agotada se reproduce allí a mano.

Los eventos

Suscribir un evento que todavía no envía nada está permitido, y la columna de la derecha lo dice: es el estado real, leído en el código que emite.

Conectores

Zapier, Make y los asistentes que hablan MCP se conectan a todo lo anterior, y a nada más: la misma clave, los mismos alcances, la misma cuota, el mismo registro. Un conector no abre una puerta más — pasa por una puerta que usted ya abrió, y la clave se revoca desde el panel.

Zapier y Make

Nada que instalar: cree una conexión «API por clave» con la cabecera «Authorization» y, como valor, «Bearer» seguido de su clave. Pruébela en https://cadanse.app/api/v1/moi — esa ruta responde cualesquiera sean los alcances de la clave y devuelve el nombre del estudio y la lista de lo que permite.

Sus disparadores son los webhooks de arriba. Tanto Zapier como Make le dan una URL de escucha: péguela en el panel y marque los eventos que quiera. Ninguno verifica la firma por usted — hágala verificar por un paso de código antes de actuar sobre una carga, con la receta indicada más arriba.

Sus acciones son las escrituras de arriba, llamadas desde un paso de «solicitud HTTP». Rellene siempre «Idempotency-Key»: de lo contrario, un escenario que la plataforma reproduce tras una avería crearía dos veces la misma ficha.

Servidor MCP

Un asistente que habla MCP se conecta a https://cadanse.app/api/v1/mcp — transporte HTTP, solicitudes POST, la misma cabecera «Authorization». Decide su estudio: conectar un asistente hace salir datos hacia una herramienta que usted elige, bajo una clave que usted crea y puede revocar.

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

El servidor expone 9 herramientas de lectura y 5 de escritura — exactamente las colecciones y las escrituras documentadas arriba, ninguna otra. El nombre de una herramienta es el de su operación, en minúsculas con guiones bajos:

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

El catálogo depende de la clave: «tools/list» solo devuelve las herramientas que cubren sus alcances. Una herramienta fuera de alcance no existe para esa clave — llamarla responde «herramienta desconocida», lo que evita enseñarle a un curioso qué alcances existen.

Los lotes JSON-RPC se rechazan: una llamada es una solicitud, y una solicitud es una unidad de cuota. Las lecturas hechas por MCP se registran como las demás — una ventana por clave, por colección y por día — en el mismo registro que el estudio puede releer.

Las herramientas de escritura actúan de inmediato, y lo que escriben lo ven el personal y las familias. Cada una acepta un argumento «cleIdempotence» opcional: sin él, dos llamadas idénticas hacen dos escrituras — es deliberado, dos pagos en efectivo del mismo importe el mismo sábado son dos pagos. El registro de auditoría conserva cada escritura, venga de un asistente o de una llamada HTTP.

Por qué esta página no puede mentir

Se genera desde el mismo documento que openapi.json, que a su vez se genera desde los serializadores que escriben las respuestas. Un campo retirado del código desaparece de aquí sin que nadie lo piense; un campo documentado que no se sirve no se puede escribir.