Plataforma

Cómo integrar Acatudy con tu web: API, tokens y altas automáticas

Actualizado el 05/09/2026

Si tu academia ya vende en su propia web —WordPress con WooCommerce, un CRM, un TPV a medida—, no necesitas dar de alta alumnos a mano: la API v1 de Acatudy recibe la compra, crea o localiza al alumno y le da acceso, y recibe la cancelación para quitárselo. En esta guía montamos la integración completa con ejemplos curl reales.

¿Qué vas a montar y para quién es?

El circuito "compra en mi web → acceso en mi academia". Tu sistema externo notifica a Acatudy dos eventos: la compra (alta y acceso) y la cancelación o reembolso (revocación). Acatudy no procesa pagos de alumnos ni lo hará: el cobro sigue en tu web; la API solo sincroniza usuarios y accesos, exactamente como harías a mano desde Usuarios pero sin tocar el panel.

Es para academias con venta online propia que quieren que el alumno entre a estudiar al minuto de pagar, sin intervención manual ni errores de transcripción.

Requisitos previos

  • Tu academia creada y con los cursos publicados que vendes fuera.
  • Un token de API: lo emite el equipo de Acatudy (superadmin) desde Plataforma → Academias → tu academia → API externa (tokens), con nombre libre (p. ej. "WooCommerce") y los permisos que necesites: read para consultas y write para altas y matrículas. El token se muestra una sola vez al crearlo: guárdalo como una contraseña. Pídelo por Soporte indicando el nombre y permisos.
  • Un sistema capaz de hacer llamadas HTTPS con JSON (un plugin, un webhook o un script tuyo).

Conceptos clave antes de empezar

  • La academia se identifica por el token, no por el dominio: todas las llamadas van a la misma base URL del dominio central, https://acatudy.com/api/v1, con la cabecera Authorization: Bearer <token> y Accept: application/json.
  • Identidades externas: puedes mapear tu ID de usuario externo (el user_id de WordPress, por ejemplo) con el usuario de Acatudy, así nunca dependes de que el email coincida.
  • Idempotencia: cada compra se identifica con un external_purchase_id único y estable (el ID del pedido). Si reenvías la misma compra, Acatudy devuelve el resultado original con duplicate: true sin aplicar nada dos veces. Regla de oro: reenvía tranquilo.
  • Límite de ritmo: 60 peticiones por minuto por token (429 si lo superas).

Paso a paso

Paso 1: comprueba el token con ping

Primera llamada, la más simple, para validar credenciales:

curl -H "Authorization: Bearer <token>" -H "Accept: application/json" https://acatudy.com/api/v1/ping

Respuesta: {"ok": true, "tenant": {"id": 3, "slug": "tu-academia", "name": "Tu Academia"}, "version": "1.0"}. Si recibes 401, el token no es válido; si recibes 403, le falta el permiso read o tu academia está suspendida.

Paso 2: mapea tus productos a cursos

curl -H "Authorization: Bearer <token>" -H "Accept: application/json" https://acatudy.com/api/v1/courses

Devuelve los cursos de tu academia con su id, title y status. Guarda en tu web la correspondencia producto → course_id (por ejemplo, en los metadatos del producto WooCommerce). Con GET /api/v1/tenant además ves tu plan y el uso de cuotas (alumnos usados/restantes).

Paso 3: notifica la compra (alta + acceso)

Cuando un pedido se complete en tu web, llama a POST /api/v1/enrollments (requiere permiso write):

curl -X POST https://acatudy.com/api/v1/enrollments -H "Authorization: Bearer <token>" -H "Accept: application/json" -H "Content-Type: application/json" -d '{"buyer": {"email": "alumna@example.com", "name": "Ana Ruiz", "provider": "woocommerce", "external_user_id": "4521"}, "course_id": 12, "purchase": {"external_purchase_id": "wc-order-100234", "amount_cents": 4900, "currency": "EUR", "purchased_at": "2026-09-05T10:30:00Z"}}'

Acatudy localiza al usuario por su identidad externa o por email (o lo crea, generando contraseña aleatoria si no envías una), lo adjunta a tu academia si no era miembro y le da acceso como pagado. Obligatorios: buyer.email, buyer.provider, course_id y purchase.external_purchase_id. La respuesta 201 incluye el usuario, el acceso y duplicate: false; si reenvías exactamente la misma compra, obtienes 200 con duplicate: true y ningún efecto extra.

Si prefieres crear el usuario antes de vender (por ejemplo, al registrarse en tu web), existe POST /api/v1/users: lo crea o localiza y lo adjunta como impagado, y con provider + external_user_id guarda la identidad externa.

Paso 4: notifica la cancelación o reembolso

curl -X POST https://acatudy.com/api/v1/enrollments/wc-order-100234/cancel -H "Authorization: Bearer <token>" -H "Accept: application/json" -H "Content-Type: application/json" -d '{"provider": "woocommerce", "course_id": 12, "email": "alumna@example.com"}'

Revoca el acceso que dio esa compra (pasa a impagado, conservando su histórico). También es idempotente: cancelar dos veces devuelve duplicate: true sin efectos extra. Si el usuario no existe en tu academia, responde 404 user_not_found.

Códigos de error

Todos los errores tienen la misma forma: {"error": {"code": "…", "message": "…"}}.

  • 401 unauthenticated: falta el token o no es válido.
  • 403 forbidden: el token no tiene el permiso necesario (read/write).
  • 403 tenant_inactive: academia suspendida o expirada.
  • 403 quota_exceeded: cuota de alumnos de tu plan llena (el alta queda rechazada hasta ampliar el plan).
  • 404 not_found / course_not_found / user_not_found: recurso inexistente o de otra academia (el course_id debe ser un curso tuyo).
  • 422 validation_failed: body inválido; el objeto fields detalla campo a campo.
  • 429 rate_limited: más de 60 peticiones por minuto; espera y reintenta.

Errores comunes de integración

  • Generar un external_purchase_id nuevo en cada reintento. Debe ser estable (el ID del pedido): es la clave que hace segura la retransmisión. Si cambia, duplicarás accesos.
  • Llamar a la API por el subdominio de tu academia. La API vive en el dominio central; el token ya dice qué academia eres.
  • Guardar el token en el código o en el navegador. Va en el servidor de tu web, como una contraseña; si se filtra, pide revocarlo y crear uno nuevo.
  • No programar los reintentos. Ante un fallo de red o un 500, reintenta con el mismo body: la idempotencia garantiza que no pasa nada por insistir.

Preguntas frecuentes

¿Quién crea el token?

El equipo de Acatudy desde el panel de plataforma (Academias → tu academia → API externa). Pídelo por Soporte con el nombre que quieres darle y los permisos (read, write o ambos); te lo entregan una única vez.

¿Puedo tener varios tokens?

Sí: uno por integración (WooCommerce, CRM, scripts internos), cada uno revocable por separado sin tumbar el resto.

¿Qué pasa si el alumno ya existe en Acatudy con ese email?

No se duplica: se adjunta a tu academia y se le da acceso. Y si envías provider + external_user_id, queda mapeado para siempre con tu ID externo.

¿Hay plugin de WordPress oficial?

Está en el roadmap; mientras tanto, cualquier plugin de webhooks (o un pequeño código en el hook de pedido completado/reembolsado) hace estas dos llamadas. La documentación interna del endpoint está en docs/ACATUDY_API.md.

Empieza hoy

Pide tu token, haz el ping y manda tu primera matrícula de prueba con curl. Crea tu academia gratis y automatiza el alta de tus alumnos esta misma semana.

Guías relacionadas