Novo: um assistente de IA que responde com os números reais da sua academia. Descobrir

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

Ler os termos da API

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.

01

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.

Pedido de autorizaçãoHTML
<!-- "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

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.

Exemplo de códigoNode.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

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.

Claims do 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 · 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 guia

Reservar 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 guia

Horá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 guia

Verificar 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 guia

05 · 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étodoCaminhoO que fazAutenticação
GET/.well-known/openid-configurationDocumento de descobertanone
GET/oauth/jwksChaves de assinatura públicasnone
GET/oauth/authorizeIniciar um início de sessão ou registonone
POST/oauth/tokenTrocar um código, renovar ou obter um token da aplicaçãocredenciais da aplicação
GET/oauth/userinfoAs declarações do membro com sessão iniciadamember, Bearer
POST/oauth/revokeRevogar um tokencredenciais da aplicação
GET/api/v1/meO membro com sessão iniciadamember, Bearer
GET/api/v1/me/bookingsAs suas reservas e os seus planos (aulas restantes, datas, montante em dívida)member, Bearer
POST/api/v1/bookingsReservar uma aula em seu nomemember, Bearer
DELETE/api/v1/bookings/{id}Cancelar uma reservamember, Bearer
GET/api/v1/members/{member_number}Consulte um membro pelo númeroapp, scope=lookup
POST/api/v1/members/verifyVerificar em conjunto um número de membro e um e-mailapp, scope=lookup
GET/api/v1/scheduleHorário público de aulasapp, scope=schedule
GET/api/v1/offersPlanos e produtos à venda ao públicoapp, scope=schedule
GET/api/v1/groupsGrupos que esta aplicação pode definirapp, scope=groups
PUT/api/v1/members/{member_number}/groupDefinir (ou limpar) o grupo de um membroapp, 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.

300chamadas de leitura por app / min/me, /me/bookings, /schedule, /offers, /groups
120chamadas de escrita por app / minreservas e grupos
120verificações de membros por app / minum orçamento partilhado para lookup e verify
600chamadas por minuto em /api/v1partilhado por todas as aplicações de um ginásio

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ódigoSignificado
invalid_requestO pedido está malformado: um campo desconhecido ou mal escrito, um parâmetro em falta, um corpo demasiado grande.
invalid_tokenO token bearer está em falta, expirou ou foi revogado.
insufficient_scopeO token não inclui o âmbito de que este endpoint precisa.
capability_offO ginásio não ativou esta capacidade para a sua aplicação.
plan_requiredO 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 pessoaEsse recurso não existe (ou não pertence a este ginásio).
rate_limitedDemasiados pedidos. Aguarde os segundos indicados no cabeçalho Retry-After e tente de novo.
booking_refusedAs 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_blockedUma 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_restrictedUma mensagem booking_refused: o membro tem menos do que a idade mínima da aula. O erro traz ageMin.
guardian_requiredUma mensagem booking_refused: o membro é menor e o ginásio exige o nome e o telefone de um tutor na ficha.
guardian_consent_requiredUma mensagem booking_refused: o membro é menor e o ginásio exige o consentimento do tutor, que ainda não foi registado.
payment_requiredEsta reserva tem de ser paga primeiro. O erro inclui payment_address, a página de pagamento do membro.
no_consentEsse membro ainda não se ligou à sua aplicação.
group_not_allowedEsse 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?
OpenID Connect padrão com PKCE, obrigatório para todas as apps, confidenciais ou públicas. Qualquer biblioteca cliente OIDC certificada serve, e o documento de descoberta está em /.well-known/openid-configuration.
Os membros vão ver um ecrã de consentimento de cada vez?
Não. O ecrã de início de sessão é ignorado enquanto continuarem com sessão iniciada no ginásio nesse dispositivo, e a aprovação é pedida uma vez por membro e aplicação. Evite prompt=login, prompt=consent e max_age, a menos que precise mesmo deles.
Devo associar os meus registos ao e-mail ou ao sub?
Ao "sub". Nunca muda para este membro e esta app, mesmo que ele mude de e-mail. Trate "email_verified": false como não verificado.
Um número de membro e um e-mail bastam para provar a identidade?
Não. Prova que alguém os conhece, não que essa pessoa é o membro. Para ter a certeza de que é o titular da conta, use o botão de início de sessão e leia o "sub".
O que acontece quando um membro não tem plano para uma aula?
A reserva responde booking_refused com uma mensagem a começar por membership_ e nenhuma reserva é criada. Consulte GET /me/bookings e encaminhe o membro para comprar um plano.
Que eventos de webhook estão disponíveis?
member.connected, member.disconnected, member.status_changed, booking.created, booking.cancelled, payment.completed e member.group_changed, entregues como POST assinados.
Como testo a API localmente?
Registe http://localhost (qualquer porta) como endereço de retorno: é o único endereço aceite em http simples. Adicione o seu endereço de produção real antes de publicar.

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