New: an AI assistant that answers with your gym's real numbers. See how it works
Bạn đang kinh doanh gì?Muay ThaiYogaCrossFitPilatesBoxingSwimmingLớp học, hội viên, giá và nội dung được thiết lập cho Muay ThaiThử với hoạt động của bạnBản demo thay đổi lớp, hội viên, giá và từ ngữ cho phù hợp với việc kinh doanh của bạn.Chọn hoạt động của bạn

API v1 · OpenID Connect

Kết nối website với phòng tập của bạn.

Cho hội viên đăng nhập bằng tài khoản phòng tập, kiểm tra gói hội viên, đặt lớp và hiển thị lịch lớp ngay trên website của bạn. OpenID Connect chuẩn, một REST API gọn nhẹ và webhook có chữ ký.

  • OpenID Connect
  • Bắt buộc PKCE
  • Webhook có chữ ký

Đọc Điều khoản API

01 · Bắt đầu nhanh

Bắt đầu nhanh với API MoveMembers: đăng nhập, đổi mã, đọc dữ liệu.

Hội viên đăng nhập bằng tài khoản phòng tập. Website của bạn nhận về một phản hồi có chữ ký kèm mã hội viên, nên thư viện OIDC nào cũng dùng được.

01

Thêm nút

Chuyển hội viên đến trang đăng nhập của phòng tập họ. Mọi ứng dụng đều bắt buộc dùng PKCE, dù là ứng dụng bảo mật hay công khai.

Yêu cầu cấp quyềnHTML
<!-- "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

Đổi mã trên máy chủ của bạn

Bạn nhận được ID token do phòng tập ký (ES256, khóa tại /oauth/jwks). Đừng bao giờ đổi mã từ một trang web: bước này cần client secret của bạn.

Mã ví dụNode.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

Đọc các claim

Chỉ gồm những gì phòng tập đã xác minh và hội viên đã đồng ý. Hãy liên kết hồ sơ của bạn với "sub", đừng bao giờ dùng địa chỉ email.

Các claim của 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 · Kiểm tra hội viên

Kiểm tra mã hội viên cùng với email.

Từ máy chủ đến máy chủ, dùng app token (client_credentials, scope=lookup). Hãy gửi chúng trong phần thân yêu cầu, không đưa vào địa chỉ: địa chỉ sẽ bị lưu lại trong nhật ký máy chủ.

Phản hồi luôn là 200 với một trường duy nhất, "active", nên không ai có thể dùng biểu mẫu của bạn để dò xem ai là hội viên. Chỉ khi nội dung gửi lên sai định dạng mới trả về 400 invalid_request.

Công thức mẫu

Các công thức dùng API phòng tập.

Mọi endpoint ghi dữ liệu đều áp dụng đúng các quy tắc như ứng dụng của phòng tập: khung giờ đặt lịch, danh sách chờ, kiểm tra gói.

Liên kết một hồ sơ

Liên kết một bản ghi trên website của bạn với một hội viên

Một chú chó, một tủ khóa, một chiếc xe: lưu "sub" vào hồ sơ của bạn làm khóa ngoại, đừng dùng email. Sau này hãy kiểm tra lại trạng thái bằng app token.

Xem hướng dẫn

Đặt lớp

Đặt hoặc hủy lịch thay hội viên

Lấy danh sách lịch lớp, rồi đặt bằng access token của hội viên. Lỗi "booking_refused" luôn kèm một lý do mà hội viên hiểu được: hãy hiển thị error.message.

Xem hướng dẫn

Lịch lớp và giá

Hiển thị lịch tập và bảng giá của bạn

Thông tin công khai, không cần hội viên đăng nhập. Một app token với scope=schedule đọc được /schedule và /offers.

Xem hướng dẫn

Xác minh, rồi gán nhóm

Xác minh danh tính qua bên thứ ba, rồi đặt nhóm

Nhà cung cấp gọi đến máy chủ của bạn với kết quả, không bao giờ qua trang trình duyệt. Chỉ gửi nhóm mà hội viên đạt được, không gửi dữ liệu nhận dạng.

Xem hướng dẫn

05 · Webhook

Webhook có chữ ký, xác minh chỉ trong vài dòng.

member.connected, member.disconnected, member.status_changed, booking.created, booking.cancelled, payment.completed, member.group_changed. Thử lại tối đa 5 lần trong khoảng 3 giờ nếu không nhận được phản hồi 2xx.

Xác minh trên nội dung RAW, từ chối mọi yêu cầu được ký quá 5 phút trước, rồi loại trùng theo X-Webhook-Id. Khóa bí mật để ký chỉ hiển thị một lần, trong tab Webhooks của ứng dụng.

10 · Tham chiếu

Tất cả endpoint của API MoveMembers.

JSON ở mọi nơi. Không có gì hoạt động khác đi chỉ vì yêu cầu đến từ website của bạn.

Phương thứcĐường dẫnNhững gì nó làmXác thực
GET/.well-known/openid-configurationTài liệu khám phánone
GET/oauth/jwksKhóa ký công khainone
GET/oauth/authorizeBắt đầu đăng nhập hoặc đăng kýnone
POST/oauth/tokenĐổi mã, làm mới hoặc lấy token ứng dụngthông tin xác thực ứng dụng
GET/oauth/userinfoThông tin xác nhận của hội viên đã đăng nhậpmember, Bearer
POST/oauth/revokeThu hồi tokenthông tin xác thực ứng dụng
GET/api/v1/meHội viên đã đăng nhậpmember, Bearer
GET/api/v1/me/bookingsCác lượt đặt lịch và gói của họ (số lớp còn lại, ngày, số tiền cần trả)member, Bearer
POST/api/v1/bookingsĐặt lớp thay mặt họmember, Bearer
DELETE/api/v1/bookings/{id}Hủy một lượt đặt lịchmember, Bearer
GET/api/v1/members/{member_number}Kiểm tra hội viên theo số hội viênứng dụng, scope=lookup
POST/api/v1/members/verifyKiểm tra đồng thời số hội viên và emailứng dụng, scope=lookup
GET/api/v1/scheduleLịch lớp công khaiứng dụng, scope=schedule
GET/api/v1/offersCác gói và sản phẩm đang bán công khaiứng dụng, scope=schedule
GET/api/v1/groupsCác nhóm mà ứng dụng này có thể gánứng dụng, scope=groups
PUT/api/v1/members/{member_number}/groupGán (hoặc bỏ) nhóm của một hội viênứng dụng, scope=groups

Chỉ GET /members/{member_number} và POST /members/verify chạy được khi chưa có sự đồng ý của hội viên, và chúng chỉ trả về việc gói hội viên còn hiệu lực hay không, không có gì thêm.

12 · Giới hạn tốc độ

Giới hạn tốc độ, tính theo từng phút.

Khi vượt giới hạn, API trả về 429 rate_limited kèm header Retry-After. Mỗi nhóm lệnh có hạn mức riêng, nên việc đọc dữ liệu nhiều không bao giờ làm hết hạn mức đặt lịch của bạn.

300lệnh đọc mỗi ứng dụng / phút/me, /me/bookings, /schedule, /offers, /groups
120lệnh ghi mỗi ứng dụng / phútđặt chỗ và nhóm
120lượt kiểm tra hội viên mỗi ứng dụng / phútmột hạn mức dùng chung cho lookup và verify
600lệnh mỗi phút trên /api/v1dùng chung cho mọi ứng dụng của một phòng tập

11 · Lỗi

Lỗi, một dạng thống nhất ở mọi nơi.

Mọi lỗi của /api/v1 đều có dạng { "error": { "code", "message", "request_id" } }. Các endpoint /oauth giữ nguyên cấu trúc OAuth chuẩn, nên thư viện OAuth dùng được ngay.

MãÝ nghĩa
invalid_requestYêu cầu sai định dạng: trường không xác định hoặc gõ sai, thiếu tham số, hoặc nội dung quá lớn.
invalid_tokenToken bearer bị thiếu, đã hết hạn hoặc đã bị thu hồi.
insufficient_scopeToken không có phạm vi quyền mà endpoint này cần.
capability_offPhòng tập chưa bật khả năng này cho ứng dụng của bạn.
plan_requiredGói của phòng tập hiện không bao gồm ứng dụng kết nối. Không có gì bị xóa; mọi thứ sẽ trở lại ngay khi họ nâng cấp.
Không tìm thấyTài nguyên đó không tồn tại (hoặc không thuộc phòng tập này).
rate_limitedQuá nhiều yêu cầu. Hãy chờ số giây ghi trong header Retry-After rồi thử lại.
booking_refusedQuy tắc đặt chỗ đã từ chối yêu cầu này; message sẽ giải thích lý do. Nếu message bắt đầu bằng membership_ thì chưa có chỗ nào được đặt.
noshow_blockedMột thông báo booking_refused: hội viên đã đạt giới hạn số lần vắng mặt của phòng tập và tạm thời không thể đặt chỗ trực tuyến. Lỗi này kèm theo count, threshold và windowDays.
age_restrictedMột thông báo booking_refused: hội viên chưa đủ độ tuổi tối thiểu của lớp. Lỗi này kèm theo ageMin.
guardian_requiredMột thông báo booking_refused: hội viên là trẻ vị thành niên và phòng tập cần tên và số điện thoại của người giám hộ trong hồ sơ.
guardian_consent_requiredMột thông báo booking_refused: hội viên là trẻ vị thành niên và phòng tập cần sự đồng ý của người giám hộ, hiện chưa được ghi nhận.
payment_requiredLượt đặt này cần được thanh toán trước. Lỗi kèm payment_address, trang thanh toán của hội viên.
no_consentHội viên đó chưa kết nối với ứng dụng của bạn.
group_not_allowedNhóm đó không nằm trong số nhóm phòng tập đã bật cho ứng dụng của bạn.

request_id cũng được gửi trong header X-Request-Id: hãy cung cấp mã này khi nhờ hỗ trợ, chúng tôi sẽ tìm ra lệnh gọi của bạn trong nhật ký.

Câu hỏi

Câu hỏi về API MoveMembers.

API MoveMembers dùng chuẩn đăng nhập nào?
OpenID Connect chuẩn với PKCE, bắt buộc cho mọi ứng dụng, dù là confidential hay public. Thư viện client OIDC nào đã được chứng nhận cũng dùng được, và tài liệu discovery nằm tại /.well-known/openid-configuration.
Hội viên có thấy màn hình xin đồng ý mỗi lần không?
Không. Màn hình đăng nhập sẽ được bỏ qua khi họ vẫn đang đăng nhập phòng tập trên thiết bị đó, và việc phê duyệt chỉ hiện một lần cho mỗi hội viên và mỗi ứng dụng. Hãy tránh prompt=login, prompt=consent và max_age trừ khi thật sự cần.
Tôi nên liên kết hồ sơ với email hay với sub?
Hãy dùng "sub". Giá trị này không bao giờ đổi với hội viên và ứng dụng này, kể cả khi họ đổi email. Coi "email_verified": false là chưa được xác minh.
Mã hội viên và email có đủ để chứng minh danh tính không?
Không. Chúng chỉ chứng tỏ có người biết các thông tin đó, chưa chắc là hội viên. Để chắc chắn đó là chủ tài khoản, hãy dùng nút đăng nhập và đọc "sub" của họ.
Điều gì xảy ra khi hội viên không có gói phù hợp cho một lớp?
Lượt đặt trả về booking_refused với thông báo bắt đầu bằng membership_, và không có lượt đặt nào được tạo. Hãy đọc GET /me/bookings và hướng hội viên đến mua gói.
Có những sự kiện webhook nào?
member.connected, member.disconnected, member.status_changed, booking.created, booking.cancelled, payment.completed và member.group_changed, được gửi dưới dạng POST có chữ ký.
Làm sao để thử API trên máy cục bộ?
Hãy đăng ký http://localhost (cổng nào cũng được) làm địa chỉ trả về: đây là địa chỉ duy nhất được chấp nhận qua http thuần. Nhớ thêm địa chỉ thật của bạn trước khi chạy chính thức.

Xây dựng trên nền phòng tập của bạn. Bắt đầu với chính tài khoản của bạn.

Tạo studio, đăng ký một ứng dụng cùng địa chỉ trả về localhost, rồi thử toàn bộ quy trình.

  • 14 ngày dùng Max miễn phí
  • Không cần thẻ tín dụng
  • Không có cuộc gọi bán hàng