Tokens de API: conecta tu tienda o tu web, renueva y revoca
Usa la API de Acatudy para crear alumnos y darles acceso desde tu tienda online o tu web externa. Cómo conseguir un token, qué permite, cuándo caduca y cómo renovarlo o revocarlo.
En esta página
En este tema 7
- Tu suscripción a Acatudy: planes, precios, facturas y cancelación
- Almacenamiento y límites del plan: qué cuenta, dónde verlo y cómo liberar espacio
- Protege tu cuenta: contraseñas, sesiones y cierre de sesión
- Privacidad, cookies y datos de los alumnos (RGPD): qué hace Acatudy por ti
- Tokens de API: conecta tu tienda o tu web, renueva y revoca
- Copias de seguridad: qué incluye tu plan y cómo restaurar tu academia
- Papelera: recupera preguntas, temas, unidades y exámenes borrados
En esta guía
- Para qué sirve la API y cómo conseguir un token.
- Permisos y caducidad.
- Renovar un token antes de que caduque, o revocarlo.
- Peticiones, límites y códigos de error para tu programador.
Para qué sirve la API
La API permite que un sistema externo actúe sobre tu academia sin que nadie escriba en el panel. El caso típico: vendes un curso en tu propia tienda online y, cuando se confirma el pago, la tienda crea al alumno en Acatudy y le da acceso al curso académico o a las asignaturas correspondientes. Si solo vendes con el pago de Acatudy, no necesitas la API: mira Vende el acceso a tus cursos con Stripe.
Consigue un token
-
Abre un ticket de soporte
Los tokens los emite nuestro equipo, para que cada uno tenga un responsable y un uso claros. En Ayuda → Soporte, dinos para qué integración es y si solo tiene que leer datos o también crear alumnos y matrículas.
-
Copia el token cuando te lo demos
Un token se muestra una sola vez. Pégalo directamente en tu tienda o integración y guárdalo como una contraseña: nunca en el código público de tu web, en un documento compartido ni en un hilo de emails.
-
Encuéntralo en Tokens de la API
Ve a Mi academia → General → Datos y dominio y abre la pestaña API. Verás el Nombre, los Permisos, la Caducidad y el Último uso de cada token, con los botones Renovar y Revocar.
Tokens de la API: caducidad y último uso de un vistazo.
Solo el propietario y los administradores de la academia pueden abrir esta página. Los profesores no ven los tokens.
Permisos y caducidad
| Permiso | Permite |
|---|---|
| read | Comprobar la conexión y leer la academia, su plan y su uso, sus asignaturas, y buscar un alumno por email. |
| write | Todo lo anterior, más crear alumnos y crear o anular matrículas. |
Cada token caduca a 1 año (recomendado), a 90 días o, si lo pides, nunca. Los tokens que caducan obligan a rotarlos de forma regular: si uno se filtra, deja de funcionar solo.
Avisos de caducidad
- Avisamos por email a los propietarios y administradores de la academia 30, 7 y 1 día antes de que caduque un token.
- Desde 30 días antes, todas las páginas del panel muestran un aviso con Renovar y Ver tokens.
- Una vez caducado, la integración recibe un error (
token_expired) hasta que lo renuevas.
Renueva o revoca un token
-
Pulsa Renovar
Se crea un token nuevo con el mismo nombre, los mismos permisos y la misma duración (1 año si el antiguo no caducaba). Se muestra una vez, con el botón Copiar: «Token nuevo creado. Cópialo ahora: no se volverá a mostrar.»
-
Pégalo en tu integración
Mientras tanto, el token antiguo sigue funcionando, así que nada se rompe durante el cambio.
-
Revoca el token antiguo
Cuando compruebes que la integración funciona con el nuevo, pulsa Revocar el token antiguo (o Revocar en su fila). Revocar es inmediato: «¿Revocar este token? Las integraciones que lo usen dejarán de funcionar.»
Revoca al momento si un token se filtra
Si un token ha acabado en algún sitio público, o se va un programador que lo tenía, revócalo y pídenos uno nuevo.
Para tu programador
URL base: https://acatudy.com/api/v1. Autenticación: Authorization: Bearer <token>. El token identifica a la academia.
| Petición | Permiso | Qué hace |
|---|---|---|
GET /ping | read | Comprobar la conexión |
GET /tenant | read | Datos de la academia |
GET /plans | read | Plan, límites, uso y almacenamiento |
GET /courses | read | Asignaturas (id, título, estado) |
GET /users?email= | read | Buscar un alumno por email |
POST /users | write | Crear un alumno o vincular una cuenta existente |
POST /enrollments | write | Matricular tras una compra externa y dar acceso; repetir la llamada con el mismo external_purchase_id no duplica |
POST /enrollments/{external_purchase_id}/cancel | write | Anular esa matrícula |
Límite: 60 peticiones por minuto por token. Los errores llegan en JSON con un code:
| HTTP | code | Significado |
|---|---|---|
| 401 | unauthenticated / token_expired | Token ausente, erróneo, revocado o caducado |
| 403 | forbidden | Al token le falta el permiso (por ejemplo, uno de lectura intentando crear un alumno) |
| 403 | quota_exceeded | Se ha llenado el límite de alumnos de tu plan |
| 403 | tenant_inactive / tenant_payment_suspended | La academia está vencida, suspendida o en pausa por impago |
| 404 | not_found, course_not_found, user_not_found | El registro no existe |
| 422 | validation_failed | Datos no válidos; fields detalla cada problema |
| 429 | rate_limited | Demasiadas peticiones; espera los segundos de Retry-After |
Preguntas frecuentes
¿Qué planes incluyen la API?
Todos. El plan solo influye a través de su límite de alumnos.
¿Puedo listar todos mis alumnos con la API?
No. La API busca un alumno por email, crea alumnos y gestiona matrículas.
¿Acatudy envía webhooks a mi sistema?
No. Es tu sistema el que llama a la API cuando ocurre algo en su lado.
Sigue esta guía con tu propia academia
Créala gratis en un par de minutos y ten el panel abierto al lado mientras lees.
Abre un ticket desde Ayuda → Soporte en tu panel: te respondemos en 24-48 h según tu plan.