API v1 · OpenID Connect
Colleghi il Suo sito alla Sua palestra.
Permetta ai membri di accedere con il proprio account della palestra, verifichi un abbonamento, prenoti i corsi e mostri l'orario sul Suo sito. OpenID Connect standard, una piccola API REST e webhook firmati.
- OpenID Connect
- PKCE obbligatorio
- Webhook firmati
01 · Avvio rapido
Avvio rapido dell'API di MoveMembers: accesso, scambio, lettura.
I membri accedono con il proprio account della palestra. Il Suo sito riceve una risposta firmata con il numero di membro, quindi funziona qualsiasi libreria OIDC.
Aggiungi il pulsante
Porta il membro alla pagina di accesso della sua palestra. PKCE è obbligatorio per ogni app, riservata o pubblica.
<!-- "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>Scambia il codice sul tuo server
Riceve un ID token firmato dalla palestra (ES256, chiavi su /oauth/jwks). Non faccia mai questo scambio da una pagina: richiede il Suo 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();Leggi i claim
Solo ciò che la palestra ha verificato e il membro ha approvato. Colleghi il Suo record a "sub", mai all'indirizzo e-mail.
{
"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 · Verificare un membro
Verifichi insieme un numero di membro e un indirizzo e-mail.
Da server a server, con un token dell'app (client_credentials, scope=lookup). Li invii nel corpo della richiesta, mai nell'indirizzo: un indirizzo finisce nei log del server.
La risposta è sempre 200 con un solo campo, "active", così nessuno può usare il Suo modulo per scoprire chi è membro. Solo un corpo malformato risponde 400 invalid_request.
Esempi pratici
Ricette per l'API della palestra.
Ogni endpoint di scrittura applica le stesse regole delle app della palestra: finestre di prenotazione, liste d'attesa, verifica dei piani.
Collegare un record
Collegare un record del suo sito a un membro
Un cane, un armadietto, un'auto: salvi "sub" nel Suo record come chiave esterna, mai l'e-mail. Verifichi lo stato in seguito con un token dell'app.
Vedi la guidaPrenota un corso
Prenotare o annullare a nome del membro
Elenchi l'orario, poi prenoti con il token di accesso del membro. Un "booking_refused" riporta sempre un motivo comprensibile al membro: mostri error.message.
Vedi la guidaOrario e prezzi
Mostra il tuo calendario e i prezzi
Informazioni pubbliche, nessun accesso dei membri necessario. Un solo token dell'app con scope=schedule legge /schedule e /offers.
Vedi la guidaVerificare, poi assegnare un gruppo
Verificare l'identità con una terza parte, poi impostare un gruppo
Il provider chiama il Suo server con il risultato, mai una pagina del browser. Invii solo il gruppo che il membro ha ottenuto, mai dati di identità.
Vedi la guida05 · Webhook
Webhook firmati, verificati in poche righe.
member.connected, member.disconnected, member.status_changed, booking.created, booking.cancelled, payment.completed, member.group_changed. Nuovo tentativo fino a 5 volte in circa 3 ore in assenza di una risposta 2xx.
Verifichi sul corpo RAW, rifiuti tutto ciò che è firmato da più di 5 minuti, poi deduplichi su X-Webhook-Id. Il secret di firma viene mostrato una sola volta, nella scheda Webhook dell'app.
10 · Riferimento
Tutti gli endpoint dell'API di MoveMembers.
JSON ovunque. Nulla cambia per il fatto di arrivare dal Suo sito.
| Metodo | Percorso | Cosa fa | Autenticazione |
|---|---|---|---|
| GET | /.well-known/openid-configuration | Documento di discovery | none |
| GET | /oauth/jwks | Chiavi di firma pubbliche | none |
| GET | /oauth/authorize | Avvia un accesso o una registrazione | none |
| POST | /oauth/token | Scambia un codice, aggiorna o ottieni un token dell'app | credenziali dell'app |
| GET | /oauth/userinfo | I claim del membro connesso | member, Bearer |
| POST | /oauth/revoke | Revoca un token | credenziali dell'app |
| GET | /api/v1/me | Il membro connesso | member, Bearer |
| GET | /api/v1/me/bookings | Le sue prenotazioni e i suoi piani (lezioni rimaste, date, importo dovuto) | member, Bearer |
| POST | /api/v1/bookings | Prenota un corso per suo conto | member, Bearer |
| DELETE | /api/v1/bookings/{id} | Annulla una prenotazione | member, Bearer |
| GET | /api/v1/members/{member_number} | Verifica un membro dal numero | app, scope=lookup |
| POST | /api/v1/members/verify | Verifica insieme un numero di membro e un'e-mail | app, scope=lookup |
| GET | /api/v1/schedule | Orario pubblico dei corsi | app, scope=schedule |
| GET | /api/v1/offers | Piani e prodotti in vendita al pubblico | app, scope=schedule |
| GET | /api/v1/groups | Gruppi che questa app può impostare | app, scope=groups |
| PUT | /api/v1/members/{member_number}/group | Imposta (o rimuovi) il gruppo di un membro | app, scope=groups |
Solo GET /members/{member_number} e POST /members/verify funzionano senza il consenso del membro, e non restituiscono nulla oltre all'indicazione se l'abbonamento è attivo.
12 · Limiti di frequenza
Limiti di frequenza, conteggiati al minuto.
Oltre il limite, l'API risponde 429 rate_limited con un'intestazione Retry-After. Ogni classe ha un proprio budget, quindi molte letture non consumano mai le Sue prenotazioni.
11 · Errori
Errori, una sola forma ovunque.
Ogni errore di /api/v1 ha questa forma: { "error": { "code", "message", "request_id" } }. Gli endpoint /oauth mantengono il formato OAuth standard, quindi le librerie OAuth funzionano così come sono.
| Codice | Significato |
|---|---|
| invalid_request | La richiesta è malformata: un campo sconosciuto o scritto male, un parametro mancante, un corpo troppo grande. |
| invalid_token | Il token bearer manca, è scaduto o è stato revocato. |
| insufficient_scope | Il token non ha lo scope richiesto da questo endpoint. |
| capability_off | La palestra non ha abilitato questa funzione per la tua app. |
| plan_required | Il piano della palestra al momento non include le app collegate. Non viene eliminato nulla; tutto torna appena passa a un piano superiore. |
| nessuna conversazione aperta con questa persona | Questa risorsa non esiste (o non appartiene a questa palestra). |
| rate_limited | Troppe richieste. Attenda i secondi indicati nell'intestazione Retry-After, poi riprovi. |
| booking_refused | Le regole di prenotazione hanno rifiutato la richiesta; message ne spiega il motivo. Un messaggio che inizia con membership_ indica che non è stata creata alcuna prenotazione. |
| noshow_blocked | Un messaggio booking_refused: il membro ha raggiunto il limite di assenze della palestra e per ora non può prenotare online. L'errore contiene count, threshold e windowDays. |
| age_restricted | Un messaggio booking_refused: il membro non ha l'età minima del corso. L'errore contiene ageMin. |
| guardian_required | Un messaggio booking_refused: il membro è minorenne e la palestra richiede nella scheda il nome e il telefono di un tutore. |
| guardian_consent_required | Un messaggio booking_refused: il membro è minorenne e la palestra richiede il consenso del tutore, non ancora registrato. |
| payment_required | Questa prenotazione richiede prima il pagamento. L'errore contiene payment_address, la pagina di pagamento del membro. |
| no_consent | Questo membro non si è ancora collegato alla tua app. |
| group_not_allowed | Questo gruppo non è tra quelli che la palestra ha abilitato per la tua app. |
request_id viene inviato anche come intestazione X-Request-Id: lo indichi quando chiede assistenza, ci permette di ritrovare la Sua chiamata nel log.
Domande
Domande sull'API di MoveMembers.
Quale standard di accesso usa l'API di MoveMembers?
I membri vedranno ogni volta una schermata di consenso?
Devo collegare i miei record all'e-mail o a sub?
Numero di membro ed e-mail bastano a provare l'identità?
Cosa succede quando un membro non ha un piano valido per un corso?
Quali eventi webhook sono disponibili?
Come testo l'API in locale?
Costruisca sulla Sua palestra. Parta dal Suo account.
Crei il Suo studio, registri un'app e un indirizzo di ritorno localhost, e provi l'intero flusso.
- 14 giorni di Max gratis
- Senza carta di credito
- Nessuna chiamata commerciale
Continua a leggere