API v1 · OpenID Connect
Ligue o seu site ao seu ginásio.
Deixe os membros iniciar sessão com a conta do ginásio, verificar uma subscrição, reservar aulas e mostrar o seu horário no seu próprio site. OpenID Connect padrão, uma API REST simples e webhooks assinados.
- OpenID Connect
- PKCE obrigatório
- Webhooks assinados
01 · Início rápido
Início rápido da API do MoveMembers: entrar, trocar, ler.
Os membros iniciam sessão com a conta do ginásio. O seu site recebe uma resposta assinada com o número de membro, por isso qualquer biblioteca OIDC serve.
Adicionar o botão
Envie o membro para a página de início de sessão do seu ginásio. O PKCE é obrigatório para todas as aplicações, confidenciais ou 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>Troque o código no seu servidor
Recebe um token de identidade assinado pelo ginásio (ES256, chaves em /oauth/jwks). Nunca faça esta troca a partir de uma página: precisa do seu segredo de cliente.
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();Leia as claims
Apenas o que o ginásio verificou e o membro aprovou. Associe o seu registo ao "sub", nunca ao endereço de 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 · Verificar um membro
Verifique um número de membro e um e-mail em conjunto.
De servidor para servidor, com um token de aplicação (client_credentials, scope=lookup). Envie-os no corpo do pedido, nunca no endereço: um endereço fica registado nos logs do servidor.
A resposta é sempre 200 com um único campo, "active", para que ninguém use o seu formulário para descobrir quem é membro. Só um corpo malformado responde 400 invalid_request.
Receitas
Receitas para a API do ginásio.
Cada endpoint de escrita aplica exatamente as mesmas regras das apps do próprio ginásio: janelas de reserva, listas de espera, verificação de planos.
Associar um registo
Associar um registo do seu site a um membro
Um cão, um cacifo, um carro: guarde o "sub" no seu registo como chave externa, nunca o e-mail. Volte a verificar o estado mais tarde com um token de app.
Ver o guiaReservar uma aula
Reservar ou cancelar em nome do membro
Liste o horário e depois reserve com o token de acesso do membro. Um "booking_refused" traz sempre um motivo que o membro reconhece: mostre error.message.
Ver o guiaHorário e preços
Mostrar o horário e os preços
Informação pública, sem necessidade de o membro iniciar sessão. Um token de aplicação com scope=schedule lê /schedule e /offers.
Ver o guiaVerificar e depois definir um grupo
Verificar a identidade com um terceiro e depois definir um grupo
O fornecedor chama o seu servidor com o resultado, nunca uma página do navegador. Envie apenas o grupo que o membro conquistou, nunca dados de identidade.
Ver o guia05 · Webhooks
Webhooks assinados, verificados em poucas linhas.
member.connected, member.disconnected, member.status_changed, booking.created, booking.cancelled, payment.completed, member.group_changed. Repetidos até 5 vezes ao longo de cerca de 3 horas, caso não haja um 2xx.
Verifique sobre o corpo RAW, recuse tudo o que tenha sido assinado há mais de 5 minutos e depois elimine duplicados por X-Webhook-Id. O segredo de assinatura é mostrado uma só vez, no separador Webhooks da app.
10 · Referência
Todos os endpoints da API do MoveMembers.
JSON em todo o lado. Nada se comporta de forma diferente por vir do seu site.
| Método | Caminho | O que faz | Autenticação |
|---|---|---|---|
| GET | /.well-known/openid-configuration | Documento de descoberta | none |
| GET | /oauth/jwks | Chaves de assinatura públicas | none |
| GET | /oauth/authorize | Iniciar um início de sessão ou registo | none |
| POST | /oauth/token | Trocar um código, renovar ou obter um token da aplicação | credenciais da aplicação |
| GET | /oauth/userinfo | As declarações do membro com sessão iniciada | member, Bearer |
| POST | /oauth/revoke | Revogar um token | credenciais da aplicação |
| GET | /api/v1/me | O membro com sessão iniciada | member, Bearer |
| GET | /api/v1/me/bookings | As suas reservas e os seus planos (aulas restantes, datas, montante em dívida) | member, Bearer |
| POST | /api/v1/bookings | Reservar uma aula em seu nome | member, Bearer |
| DELETE | /api/v1/bookings/{id} | Cancelar uma reserva | member, Bearer |
| GET | /api/v1/members/{member_number} | Consulte um membro pelo número | app, scope=lookup |
| POST | /api/v1/members/verify | Verificar em conjunto um número de membro e um e-mail | app, scope=lookup |
| GET | /api/v1/schedule | Horário público de aulas | app, scope=schedule |
| GET | /api/v1/offers | Planos e produtos à venda ao público | app, scope=schedule |
| GET | /api/v1/groups | Grupos que esta aplicação pode definir | app, scope=groups |
| PUT | /api/v1/members/{member_number}/group | Definir (ou limpar) o grupo de um membro | app, scope=groups |
Só GET /members/{member_number} e POST /members/verify funcionam sem o consentimento do membro, e não devolvem nada além de indicar se o plano está ativo.
12 · Limites de pedidos
Limites de pedidos, contados por minuto.
Ao exceder um limite, a API responde 429 rate_limited com um cabeçalho Retry-After. Cada categoria tem o seu próprio orçamento, por isso muitas leituras nunca consomem as suas reservas.
11 · Erros
Erros, com o mesmo formato em todo o lado.
Todos os erros de /api/v1 têm o formato { "error": { "code", "message", "request_id" } }. Os endpoints /oauth mantêm o formato OAuth padrão, por isso as bibliotecas OAuth funcionam tal como estão.
| Código | Significado |
|---|---|
| invalid_request | O pedido está malformado: um campo desconhecido ou mal escrito, um parâmetro em falta, um corpo demasiado grande. |
| invalid_token | O token bearer está em falta, expirou ou foi revogado. |
| insufficient_scope | O token não inclui o âmbito de que este endpoint precisa. |
| capability_off | O ginásio não ativou esta capacidade para a sua aplicação. |
| plan_required | O plano do ginásio não inclui aplicações ligadas neste momento. Nada é apagado; volta assim que passar a um plano superior. |
| não há conversa aberta com esta pessoa | Esse recurso não existe (ou não pertence a este ginásio). |
| rate_limited | Demasiados pedidos. Aguarde os segundos indicados no cabeçalho Retry-After e tente de novo. |
| booking_refused | As regras de reserva recusaram este pedido; a mensagem explica porquê. Uma mensagem que comece por membership_ significa que não foi criada nenhuma reserva. |
| noshow_blocked | Uma mensagem booking_refused: o membro atingiu o limite de faltas do ginásio e não pode reservar online por agora. O erro traz count, threshold e windowDays. |
| age_restricted | Uma mensagem booking_refused: o membro tem menos do que a idade mínima da aula. O erro traz ageMin. |
| guardian_required | Uma mensagem booking_refused: o membro é menor e o ginásio exige o nome e o telefone de um tutor na ficha. |
| guardian_consent_required | Uma mensagem booking_refused: o membro é menor e o ginásio exige o consentimento do tutor, que ainda não foi registado. |
| payment_required | Esta reserva tem de ser paga primeiro. O erro inclui payment_address, a página de pagamento do membro. |
| no_consent | Esse membro ainda não se ligou à sua aplicação. |
| group_not_allowed | Esse grupo não é um dos que o ginásio ativou para a sua aplicação. |
O request_id também é enviado no cabeçalho X-Request-Id: indique-o ao pedir ajuda, é com ele que encontramos a sua chamada no registo.
Perguntas
Perguntas sobre a API do MoveMembers.
Que padrão de início de sessão usa a API do MoveMembers?
Os membros vão ver um ecrã de consentimento de cada vez?
Devo associar os meus registos ao e-mail ou ao sub?
Um número de membro e um e-mail bastam para provar a identidade?
O que acontece quando um membro não tem plano para uma aula?
Que eventos de webhook estão disponíveis?
Como testo a API localmente?
Construa sobre o seu ginásio. Comece com a sua própria conta.
Crie o seu estúdio, registe uma app e um endereço de retorno localhost, e teste o fluxo completo.
- 14 dias de Max grátis
- Sem cartão de crédito
- Sem chamada de vendas
Continuar a ler
Ver também
feature
Reserva de aulasfeature
Gestão de sóciosfeature
Automatização para ginásiospricing
PreçosCritério
Todas as funcionalidades