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ý
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.
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.
<!-- "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>Đổ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.
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();Đọ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.
{
"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ẫnLị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ẫnXá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ẫn05 · 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ẫn | Những gì nó làm | Xác thực |
|---|---|---|---|
| GET | /.well-known/openid-configuration | Tài liệu khám phá | none |
| GET | /oauth/jwks | Khóa ký công khai | none |
| GET | /oauth/authorize | Bắ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ụng | thông tin xác thực ứng dụng |
| GET | /oauth/userinfo | Thông tin xác nhận của hội viên đã đăng nhập | member, Bearer |
| POST | /oauth/revoke | Thu hồi token | thông tin xác thực ứng dụng |
| GET | /api/v1/me | Hội viên đã đăng nhập | member, Bearer |
| GET | /api/v1/me/bookings | Cá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ịch | member, 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/verify | Kiểm tra đồng thời số hội viên và email | ứng dụng, scope=lookup |
| GET | /api/v1/schedule | Lịch lớp công khai | ứng dụng, scope=schedule |
| GET | /api/v1/offers | Các gói và sản phẩm đang bán công khai | ứng dụng, scope=schedule |
| GET | /api/v1/groups | Các nhóm mà ứng dụng này có thể gán | ứng dụng, scope=groups |
| PUT | /api/v1/members/{member_number}/group | Gá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.
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_request | Yê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_token | Token bearer bị thiếu, đã hết hạn hoặc đã bị thu hồi. |
| insufficient_scope | Token không có phạm vi quyền mà endpoint này cần. |
| capability_off | Phòng tập chưa bật khả năng này cho ứng dụng của bạn. |
| plan_required | Gó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ấy | Tài nguyên đó không tồn tại (hoặc không thuộc phòng tập này). |
| rate_limited | Quá nhiều yêu cầu. Hãy chờ số giây ghi trong header Retry-After rồi thử lại. |
| booking_refused | Quy 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_blocked | Mộ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_restricted | Mộ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_required | Mộ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_required | Mộ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_required | Lượ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_consent | Hội viên đó chưa kết nối với ứng dụng của bạn. |
| group_not_allowed | Nhó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?
Hội viên có thấy màn hình xin đồng ý mỗi lần không?
Tôi nên liên kết hồ sơ với email hay với sub?
Mã hội viên và email có đủ để chứng minh danh tính không?
Điều gì xảy ra khi hội viên không có gói phù hợp cho một lớp?
Có những sự kiện webhook nào?
Làm sao để thử API trên máy cục bộ?
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
Đọc tiếp
Xem thêm
feature
Đặt lớpfeature
Quản lý hội viênfeature
Tự động hóa cho phòng gympricing
Bảng giáTính năng
Tất cả tính năng