01 · 快速上手
MoveMembers API 快速上手: 登录、换取、读取。.
会员用健身房账号登录。您的网站会收到带有会员编号的签名响应,所以任何 OIDC 库都能使用。
添加按钮
把会员引导到其所在健身房的登录页。所有应用都必须使用 PKCE,无论是机密客户端还是公开客户端。
<!-- "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>在您的服务器上兑换代码
您会拿到由健身房签名的 ID 令牌(ES256,密钥位于 /oauth/jwks)。切勿在网页里执行这一步换取:它需要用到您的 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();读取声明
只返回健身房已核实、会员已授权的内容。请把您的记录关联到「sub」,不要关联到电子邮箱。
{
"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 · 核验会员
同时核验 会员编号和电子邮箱。.
服务器对服务器,使用应用令牌(client_credentials,scope=lookup)。请放在请求体里发送,不要放在地址里:地址会留在服务器日志中。
响应始终是 200,只含一个字段「active」,所以没有人能借您的表单查出谁是会员。只有请求体格式错误时才返回 400 invalid_request。
示例做法
健身房 API 实用范例。.
每个写入接口都沿用健身房自家应用的同一套规则:预约时间窗口、候补名单、套餐校验。
05 · Webhook
签名 webhook, 几行代码即可验证。.
member.connected、member.disconnected、member.status_changed、booking.created、booking.cancelled、payment.completed、member.group_changed。若未收到 2xx 响应,约 3 小时内最多重试 5 次。
请对原始请求体验签,拒绝签名超过 5 分钟的请求,再按 X-Webhook-Id 去重。签名密钥只显示一次,位于应用的 Webhooks 标签页。
10 · 参考
MoveMembers API 的全部接口.
全程 JSON。请求来自您的网站,行为也不会有任何不同。
| 方式 | 路径 | 它能做什么 | 认证 |
|---|---|---|---|
| GET | /.well-known/openid-configuration | 发现文档 | none |
| GET | /oauth/jwks | 公开签名密钥 | none |
| GET | /oauth/authorize | 发起登录或注册 | none |
| POST | /oauth/token | 兑换授权码、刷新,或获取应用令牌 | 应用凭据 |
| GET | /oauth/userinfo | 已登录会员的声明信息 | member, Bearer |
| POST | /oauth/revoke | 撤销令牌 | 应用凭据 |
| GET | /api/v1/me | 已登录的会员 | member, Bearer |
| GET | /api/v1/me/bookings | 他们的预约和套餐(剩余课程数、日期、应付金额) | member, Bearer |
| POST | /api/v1/bookings | 代会员预约课程 | member, Bearer |
| DELETE | /api/v1/bookings/{id} | 取消预约 | member, Bearer |
| GET | /api/v1/members/{member_number} | 按编号核对会员 | 应用,scope=lookup |
| POST | /api/v1/members/verify | 同时核对会员编号和电子邮件 | 应用,scope=lookup |
| GET | /api/v1/schedule | 公开课程表 | 应用,scope=schedule |
| GET | /api/v1/offers | 公开销售的方案和商品 | 应用,scope=schedule |
| GET | /api/v1/groups | 此应用可设置的分组 | 应用,scope=groups |
| PUT | /api/v1/members/{member_number}/group | 设置(或清除)会员的分组 | 应用,scope=groups |
只有 GET /members/{member_number} 和 POST /members/verify 无需会员同意即可使用,并且除了会籍是否有效之外,不会返回任何内容。
12 · 速率限制
速率限制, 按分钟计算。.
超出限制时,API 返回 429 rate_limited 并带有 Retry-After 响应头。每类调用各有独立额度,大量读取不会占用您的预约额度。
11 · 错误
错误格式,处处一致.
每个 /api/v1 错误的格式都是 { "error": { "code", "message", "request_id" } }。/oauth 端点保持标准 OAuth 格式,所以 OAuth 库可以直接使用。
| 卡号 | 含义 |
|---|---|
| invalid_request | 请求格式有误:字段未知或拼写错误、缺少参数,或请求体过大。 |
| invalid_token | 缺少 Bearer 令牌,或令牌已过期或被撤销。 |
| insufficient_scope | 该令牌不包含此接口所需的权限范围。 |
| capability_off | 该健身房尚未为您的应用开启此功能。 |
| plan_required | 该健身房当前的套餐不包含已连接的应用。不会删除任何内容,升级后立即恢复。 |
| 与此人尚无会话 | 该资源不存在(或不属于这家健身房)。 |
| rate_limited | 请求过多。请等待 Retry-After 响应头指定的秒数后再重试。 |
| booking_refused | 预约规则拒绝了这次请求,message 会说明原因。message 以 membership_ 开头,表示没有创建任何预约。 |
| noshow_blocked | booking_refused 消息:会员已达到场馆的缺席上限,暂时无法在线预约。错误中包含 count、threshold 和 windowDays。 |
| age_restricted | booking_refused 消息:会员未达到该课程的最低年龄。错误中包含 ageMin。 |
| guardian_required | booking_refused 消息:会员是未成年人,场馆需要在档案中留有监护人的姓名和电话。 |
| guardian_consent_required | booking_refused 消息:会员是未成年人,场馆需要监护人的同意,但尚未记录。 |
| payment_required | 此预约需要先付款。错误信息里带有 payment_address,即会员的付款页面。 |
| no_consent | 该会员尚未连接到您的应用。 |
| group_not_allowed | 该分组不在健身房为您的应用开启的范围内。 |
request_id 也会作为 X-Request-Id 响应头返回:求助时请附上它,我们据此能在日志里找到您的调用。
问题
关于 MoveMembers API 的问题.
MoveMembers API 使用哪种登录标准?
会员每次都会看到授权页面吗?
我应该把记录关联到邮箱还是 sub?
会员编号加邮箱足以证明身份吗?
会员没有适用某节课的套餐时会怎样?
有哪些 webhook 事件?
如何在本地测试 API?
在你的健身房之上搭建。 从您自己的账户开始。.
创建您的工作室,注册一个应用和一个 localhost 回调地址,然后测试整个流程。
- 免费体验 Max 14 天
- 无需信用卡
- 无需销售来电