API v1 · OpenID Connect
Conecta tu web con tu gimnasio.
Deja que tus miembros inicien sesión con su cuenta del gimnasio, comprueba una membresía, reserva clases y muestra tu horario en tu propia web. OpenID Connect estándar, una API REST sencilla y webhooks firmados.
- OpenID Connect
- PKCE obligatorio
- Webhooks firmados
01 · Inicio rápido
Inicio rápido de la API de MoveMembers: iniciar sesión, intercambiar, leer.
Los miembros inician sesión con su cuenta del gimnasio. Tu web recibe una respuesta firmada con su número de miembro, así que sirve cualquier biblioteca OIDC.
Añade el botón
Envía al miembro a la página de inicio de sesión de su gimnasio. PKCE es obligatorio para todas las apps, confidenciales o públicas.
<!-- "Join Your Gym" -->
<a href="https://movemembers.com/oauth/authorize?client_id=app_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx&response_type=code&scope=openid%20member_number%20profile%20email%20phone%20membership%20bookings%20field%3Avisitor_type&redirect_uri=https://yoursite.com/callback&state=…&nonce=…&code_challenge=…&code_challenge_method=S256&prompt=create"
style="display:inline-flex;align-items:center;gap:10px;padding:12px 20px;
border-radius:10px;background:#ffffff;color:#14161b;border:1px solid #e4e6ef;
font-family:inherit;
font-size:15px;font-weight:600;text-decoration:none">
Join Your Gym
</a>Intercambiar el código en su servidor
Recibes un ID token firmado por el gimnasio (ES256, claves en /oauth/jwks). No hagas nunca este intercambio desde una página: requiere tu client secret.
const { Issuer } = require("openid-client"); // any certified OIDC client works
const issuer = await Issuer.discover("https://movemembers.com");
const client = new issuer.Client({
client_id: "app_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
client_secret: process.env.APP_SECRET, // never hard-code this
redirect_uris: ["https://yoursite.com/callback"],
response_types: ["code"],
});
// codeVerifier is the one you generated before redirecting the member
const tokenSet = await client.callback(
"https://yoursite.com/callback",
params, // req.query, from the redirect
{ code_verifier: codeVerifier, state, nonce },
);
// tokenSet.claims() is verified against the gym's public keys at /oauth/jwks
const member = tokenSet.claims();Leer los claims
Solo lo que el gimnasio ha comprobado y el miembro ha aprobado. Vincula tu registro a "sub", nunca al correo electrónico.
{
"sub": "mbr_4Hq9kR2vLpXsT8nZ",
"member_number": "1042",
"name": "Nok Suwan",
"email": "nok@example.com",
"email_verified": true,
"phone_number": "+66812345678",
"membership": { "status": "active", "plan": "Monthly", "ends": "2026-11-01" },
"fields": { "visitor_type": "…" }
}04 · Comprobar un miembro
Comprueba un número de miembro y un correo a la vez.
De servidor a servidor, con un token de app (client_credentials, scope=lookup). Envíelos en el cuerpo, nunca en la dirección: una dirección acaba en los registros del servidor.
La respuesta es siempre 200 con un único campo, "active", así nadie puede usar tu formulario para averiguar quién es miembro. Solo un cuerpo mal formado responde 400 invalid_request.
Recetas
Recetas para la API del gimnasio.
Cada endpoint de escritura aplica exactamente las mismas reglas que las apps del propio gimnasio: ventanas de reserva, listas de espera, comprobación de planes.
Vincular un registro
Vincular un registro de su sitio a un miembro
Un perro, una taquilla, un coche: guarda "sub" en tu propio registro como clave foránea, nunca el correo. Vuelve a comprobar el estado más tarde con un token de app.
Ver la guíaReservar una clase
Reservar o cancelar en nombre del miembro
Lista el horario y reserva con su token de acceso. Un "booking_refused" siempre incluye un motivo que el miembro entiende: muestra error.message.
Ver la guíaHorario y precios
Mostrar su horario y sus precios
Información pública, sin necesidad de que el miembro inicie sesión. Un token de app con scope=schedule lee /schedule y /offers.
Ver la guíaVerificar y luego asignar un grupo
Verificar la identidad con un tercero y luego asignar un grupo
El proveedor llama a tu servidor con el resultado, nunca a una página del navegador. Envía solo el grupo que el miembro se ha ganado, nunca datos de identidad.
Ver la guía05 · Webhooks
Webhooks firmados, verificados en pocas líneas.
member.connected, member.disconnected, member.status_changed, booking.created, booking.cancelled, payment.completed, member.group_changed. Se reintenta hasta 5 veces durante unas 3 horas si no hay respuesta 2xx.
Verifica sobre el cuerpo RAW, rechaza todo lo firmado hace más de 5 minutos y deduplica por X-Webhook-Id. El secreto de firma se muestra una sola vez, en la pestaña Webhooks de la app.
10 · Referencia
Todos los endpoints de la API de MoveMembers.
JSON en todas partes. Nada se comporta distinto por venir de tu web.
| Medio | Ruta | Qué hace | Autenticación |
|---|---|---|---|
| GET | /.well-known/openid-configuration | Documento de descubrimiento | none |
| GET | /oauth/jwks | Claves de firma públicas | none |
| GET | /oauth/authorize | Iniciar un acceso o un registro | none |
| POST | /oauth/token | Intercambiar un código, renovar u obtener un token de app | credenciales de la app |
| GET | /oauth/userinfo | Los claims del miembro con sesión iniciada | member, Bearer |
| POST | /oauth/revoke | Revocar un token | credenciales de la app |
| GET | /api/v1/me | El miembro con sesión iniciada | member, Bearer |
| GET | /api/v1/me/bookings | Sus reservas y sus planes (clases restantes, fechas, importe pendiente) | member, Bearer |
| POST | /api/v1/bookings | Reservar una clase en su nombre | member, Bearer |
| DELETE | /api/v1/bookings/{id} | Cancelar una reserva | member, Bearer |
| GET | /api/v1/members/{member_number} | Comprobar a un miembro por su número | app, scope=lookup |
| POST | /api/v1/members/verify | Comprobar juntos un número de miembro y un correo | app, scope=lookup |
| GET | /api/v1/schedule | Horario público de clases | app, scope=schedule |
| GET | /api/v1/offers | Planes y productos en venta pública | app, scope=schedule |
| GET | /api/v1/groups | Grupos que esta app puede asignar | app, scope=groups |
| PUT | /api/v1/members/{member_number}/group | Asignar (o quitar) el grupo de un miembro | app, scope=groups |
Solo GET /members/{member_number} y POST /members/verify funcionan sin el consentimiento del miembro, y no devuelven nada más allá de si la membresía está activa.
12 · Límites de uso
Límites de uso, contados por minuto.
Si superas un límite, la API responde 429 rate_limited con una cabecera Retry-After. Cada tipo de llamada tiene su propio presupuesto, así que leer mucho nunca agota tus reservas.
11 · Errores
Errores, con un único formato en todas partes.
Todos los errores de /api/v1 tienen la forma { "error": { "code", "message", "request_id" } }. Los endpoints /oauth mantienen el formato estándar de OAuth, así que las bibliotecas de OAuth funcionan tal cual.
| Código | Significado |
|---|---|
| invalid_request | La solicitud está mal formada: un campo desconocido o mal escrito, un parámetro que falta o un cuerpo demasiado grande. |
| invalid_token | Falta el token bearer, o está caducado o revocado. |
| insufficient_scope | El token no incluye el alcance que necesita este endpoint. |
| capability_off | El gimnasio no ha habilitado esta capacidad para tu app. |
| plan_required | El plan del gimnasio no incluye ahora las apps conectadas. No se borra nada; vuelve en cuanto mejoren de plan. |
| no hay conversación abierta con esta persona | Ese recurso no existe (o no pertenece a este gimnasio). |
| rate_limited | Demasiadas solicitudes. Espera los segundos indicados en la cabecera Retry-After y vuelve a intentarlo. |
| booking_refused | Las reglas de reserva rechazaron esta solicitud; message explica el motivo. Un mensaje que empieza por membership_ significa que no se creó ninguna reserva. |
| noshow_blocked | Un mensaje de booking_refused: el miembro ha alcanzado el límite de ausencias del gimnasio y por ahora no puede reservar en línea. El error incluye count, threshold y windowDays. |
| age_restricted | Un mensaje de booking_refused: el miembro no tiene la edad mínima de la clase. El error incluye ageMin. |
| guardian_required | Un mensaje de booking_refused: el miembro es menor y el gimnasio exige el nombre y el teléfono de un tutor en su ficha. |
| guardian_consent_required | Un mensaje de booking_refused: el miembro es menor y el gimnasio exige el consentimiento del tutor, que aún no está registrado. |
| payment_required | Esta reserva debe pagarse primero. El error incluye payment_address, la página de pago del miembro. |
| no_consent | Ese miembro todavía no se ha conectado a tu app. |
| group_not_allowed | Ese grupo no es uno de los que el gimnasio habilitó para tu app. |
request_id también se envía en la cabecera X-Request-Id: cítalo cuando pidas ayuda, así encontramos tu llamada en el registro.
Preguntas
Preguntas sobre la API de MoveMembers.
¿Qué estándar de inicio de sesión usa la API de MoveMembers?
¿Los miembros verán una pantalla de consentimiento cada vez?
¿Debo vincular mis registros al correo o a sub?
¿Basta un número de miembro y un correo para probar la identidad?
¿Qué pasa cuando un miembro no tiene un plan válido para una clase?
¿Qué eventos de webhook hay disponibles?
¿Cómo pruebo la API en local?
Construya sobre su gimnasio. Empieza con tu propia cuenta.
Crea tu estudio, registra una app y una dirección de retorno localhost, y prueba todo el flujo.
- 14 días de Max gratis
- Sin tarjeta de crédito
- Sin llamada comercial
Sigue leyendo