Novità: un assistente AI che risponde con i dati reali della tua palestra. Scopri

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

Leggi i termini API

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.

01

Aggiungi il pulsante

Porta il membro alla pagina di accesso della sua palestra. PKCE è obbligatorio per ogni app, riservata o pubblica.

Richiesta di autorizzazioneHTML
<!-- "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>
02

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.

Esempio di codiceNode.js
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();
03

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.

Claim dell'ID tokenJSON
{
  "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 guida

Prenota 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 guida

Orario 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 guida

Verificare, 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 guida

05 · 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.

MetodoPercorsoCosa faAutenticazione
GET/.well-known/openid-configurationDocumento di discoverynone
GET/oauth/jwksChiavi di firma pubblichenone
GET/oauth/authorizeAvvia un accesso o una registrazionenone
POST/oauth/tokenScambia un codice, aggiorna o ottieni un token dell'appcredenziali dell'app
GET/oauth/userinfoI claim del membro connessomember, Bearer
POST/oauth/revokeRevoca un tokencredenziali dell'app
GET/api/v1/meIl membro connessomember, Bearer
GET/api/v1/me/bookingsLe sue prenotazioni e i suoi piani (lezioni rimaste, date, importo dovuto)member, Bearer
POST/api/v1/bookingsPrenota un corso per suo contomember, Bearer
DELETE/api/v1/bookings/{id}Annulla una prenotazionemember, Bearer
GET/api/v1/members/{member_number}Verifica un membro dal numeroapp, scope=lookup
POST/api/v1/members/verifyVerifica insieme un numero di membro e un'e-mailapp, scope=lookup
GET/api/v1/scheduleOrario pubblico dei corsiapp, scope=schedule
GET/api/v1/offersPiani e prodotti in vendita al pubblicoapp, scope=schedule
GET/api/v1/groupsGruppi che questa app può impostareapp, scope=groups
PUT/api/v1/members/{member_number}/groupImposta (o rimuovi) il gruppo di un membroapp, 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.

300chiamate di lettura per app / min/me, /me/bookings, /schedule, /offers, /groups
120chiamate di scrittura per app / minprenotazioni e gruppi
120verifiche di membri per app / minun unico budget condiviso per ricerca e verifica
600chiamate al minuto su /api/v1condiviso da tutte le app di una stessa palestra

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.

CodiceSignificato
invalid_requestLa richiesta è malformata: un campo sconosciuto o scritto male, un parametro mancante, un corpo troppo grande.
invalid_tokenIl token bearer manca, è scaduto o è stato revocato.
insufficient_scopeIl token non ha lo scope richiesto da questo endpoint.
capability_offLa palestra non ha abilitato questa funzione per la tua app.
plan_requiredIl 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 personaQuesta risorsa non esiste (o non appartiene a questa palestra).
rate_limitedTroppe richieste. Attenda i secondi indicati nell'intestazione Retry-After, poi riprovi.
booking_refusedLe 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_blockedUn 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_restrictedUn messaggio booking_refused: il membro non ha l'età minima del corso. L'errore contiene ageMin.
guardian_requiredUn messaggio booking_refused: il membro è minorenne e la palestra richiede nella scheda il nome e il telefono di un tutore.
guardian_consent_requiredUn messaggio booking_refused: il membro è minorenne e la palestra richiede il consenso del tutore, non ancora registrato.
payment_requiredQuesta prenotazione richiede prima il pagamento. L'errore contiene payment_address, la pagina di pagamento del membro.
no_consentQuesto membro non si è ancora collegato alla tua app.
group_not_allowedQuesto 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?
OpenID Connect standard con PKCE, obbligatorio per ogni app, confidenziale o pubblica. Funziona qualsiasi libreria client OIDC certificata e il documento di discovery si trova su /.well-known/openid-configuration.
I membri vedranno ogni volta una schermata di consenso?
No. La schermata di accesso viene saltata finché la persona risulta ancora connessa alla palestra su quel dispositivo, e l'approvazione compare una sola volta per membro e per app. Eviti prompt=login, prompt=consent e max_age, a meno che non le servano davvero.
Devo collegare i miei record all'e-mail o a sub?
A "sub". Non cambia mai per questo membro e questa app, anche se cambia e-mail. Consideri "email_verified": false come non verificato.
Numero di membro ed e-mail bastano a provare l'identità?
No. Provano che qualcuno li conosce, non che sia il membro. Per essere certo che si tratti del titolare dell'account, usi il pulsante di accesso e legga il suo "sub".
Cosa succede quando un membro non ha un piano valido per un corso?
La prenotazione risponde booking_refused con un messaggio che inizia per membership_ e nessuna prenotazione viene creata. Legga GET /me/bookings e indirizzi il membro all'acquisto di un piano.
Quali eventi webhook sono disponibili?
member.connected, member.disconnected, member.status_changed, booking.created, booking.cancelled, payment.completed e member.group_changed, consegnati come POST firmati.
Come testo l'API in locale?
Registri http://localhost (qualsiasi porta) come indirizzo di ritorno: è l'unico indirizzo accettato via http semplice. Aggiunga il Suo vero indirizzo di produzione prima della messa online.

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