什麼是 API？
可以把 OB 系統資料想像成存放在一個上鎖的房間裡。API Token 就像一把專屬鑰匙，讓獲得授權的系統可以讀取目前 API 支援的資料。
開發人員需要先建立外部系統與 OB API 之間的串接，並在每次請求中帶入 Token。缺少串接或有效的 Token，外部系統就無法取得資料。API 大部分功能為讀取資料，少數端點也可以更新資料，因此建立 Token 時需選擇是否允許寫入。選擇「唯讀」建立的 Token 永遠無法變更 OB 中的任何資料——若僅需報表用途，請使用唯讀 Token。
功能開關：
示範步驟一：建立 API Token
前往 後台 → 客製化功能 → API → 內容，點選 建立 Token，輸入名稱，選擇權限（Access）與模式（Mode）後儲存。請複製 Token 並妥善保管。Token 為長期有效，直到您在此頁面將其刪除。
權限與模式在建立時即固定，事後無法修改。若需變更，請刪除該 Token 並重新建立。此設計是刻意的：以唯讀測試 Token 開發的串接，不應在無人察覺的情況下取得變更正式資料的能力。
示範步驟二：從 API 技術文件複製 URL
開啟 API 技術文件，找到您要取得資料的 GET 端點。例如，若要取得使用者資料，可使用 /v1/users。
示範步驟三：將 URL 貼到 API 工具
開啟 Postman 或其他 API 工具並建立新的 HTTP 請求。選擇 GET，再貼上從 API 技術文件複製的 URL。
示範步驟四：設定 Authorization Header 並送出
在 Headers 中新增 Authorization，值填入 Bearer <您的 Token>。點選 Send 後即可查看回應內容。
API 資料範圍常見問題
1. 是否能取得會員購買方案與剩餘堂數？
部分支援。GET /v1/user-passes 可取得會員已購課卡、購買與啟用日期、到期日、類型，以及購買時的總堂數或點數。visits 欄位代表已購課卡的總堂數或點數，並非即時計算的剩餘堂數；目前 API 尚未提供獨立的剩餘堂數欄位。
2. 是否能取得會員歷史及未來預約紀錄？
可以。使用 GET /v1/reservations，可依會員 Email 或姓名，以及 date_from、date_to 篩選日期區間。結果會依上課時間由新到舊排序。已取消的預約則由 GET /v1/cancellations 另外提供。
3. 是否有實際出席、取消及未到狀態？
部分支援。預約資料包含 attended 布林值；取消資料則包含取消時間、由誰取消及是否套用取消罰則。目前沒有一個欄位可完整區分所有狀態：attended: false 可能代表未來預約、尚未標記出席，或未到課，因此串接系統還需要一併判斷課程時間及取消紀錄。
4. 是否能透過 API 辨識體驗課程？
目前沒有專用欄位。課程回應不包含「體驗課」旗標。若店家以特定課程 ID 或命名方式區分體驗課，串接系統可依該規則自行辨識。
5. 是否能取得會員最近一次上課日期？
可以。GET /v1/users 及 GET /v1/users/{id} 會回傳 lastAttendance，代表會員最近一次已記錄的出席時間；若沒有出席紀錄則可能為 null。
6. 是否能查詢付款或購買紀錄？
可查詢課卡購買紀錄。GET /v1/user-passes 會回傳購買時間、付款狀態、付款方式、價格、會員及課卡資料；GET /v1/user-passes/{id} 另包含付款參考編號。目前 API 尚未提供涵蓋所有付款或商店商品購買類型的完整交易明細。
Webhook 與事件通知
目前 API 尚未提供 Webhook 或事件通知。若串接系統需要得知資料變動，必須定期查詢相關端點，並遵守請求頻率限制。這與寫入權限無關：API 現在可以更新少數資料，但當 OB 中的資料變動時，系統不會主動通知您的系統。
身分驗證、請求頻率限制與 Token 管理
身分驗證：API 採用 JWT Bearer Token，而非 OAuth。啟用 API 客製化功能後，請前往 後台 → 客製化功能 → API → 內容 並點選 建立 Token。無需另外申請 API 金鑰。每次請求都需以 Authorization: Bearer <您的 token> 帶入 Token。
權限（Access）——這組 Token 可以做什麼。唯讀 Token 僅能發出 GET 請求；任何會變更資料的請求都會回傳 HTTP 403 Forbidden。讀寫 Token 則兩者皆可。報表與數據分析類串接建議選擇唯讀：這是較安全的選擇，且因為權限事後無法修改，唯讀 Token 不可能被誤放寬。
模式（Mode）——這組 Token 存取哪一份資料。Live Token 操作您真實的商家資料；Test Token 會被導向共用的沙箱商家，讓您可以實際呼叫會變更資料的端點，而完全不影響自己的資料。詳見下方使用測試 Token 進行測試。
兩者互相獨立，因此 Token 可以是「正式資料唯讀」、「沙箱讀寫」或其他任意組合。API 內容頁面會顯示每組 Token 的權限與模式。
可持有的 Token 數量。每個商家同時最多可持有三組 Live Token。達到上限後，建立 Token 時就不再提供 Live 模式——模式（Mode）選單只會列出 Test（沙箱），下方的說明文字也會改為提示已達 Live Token 上限，而不再說明沙箱用途。Test Token 沒有數量限制，因為它們僅會存取共用沙箱。刪除一組 Live Token 會立即空出名額，Live 模式也會重新可供選擇，因此您仍可透過先刪除舊 Token、再建立新 Token 的方式進行更換。
Token 安全性：Token 為長期有效，請比照密碼保管，切勿放在前端瀏覽器程式碼或公開的程式庫中。若要撤銷 Token，請在 API 內容頁面開啟該列的選單並刪除。
頻率限制：每組 API Token 每小時（固定一小時視窗）最多 100 次請求。回應包含 X-RateLimit-Limit、X-RateLimit-Remaining 與 X-RateLimit-Reset。超過限制會回傳 HTTP 429 與 Retry-After。另有突發流量防護，每個 IP 約每秒 5 次請求。列表端點單次最多回傳 100 筆，並使用從 0 開始的 start 參數分頁。
追蹤 API 使用量
如需了解使用量表格、篩選條件、回應狀態碼及疑難排解流程，請參閱追蹤 API 使用量。
使用測試 Token 進行測試
測試（Test）Token 可讓您試用 API——包含會變更資料的端點——而完全不會影響您真實的資料。建立方式與上述相同，只需將模式選為 Test，並以相同的 Authorization: Bearer 標頭送出即可，串接的其他部分都不需要調整。
請求會送到哪裡。使用測試 Token 的每個請求都會被導向共用的沙箱商家。測試 Token 永遠不會讀取或寫入您自己的資料，因此腳本中的錯誤不可能取消真實課程或變更您的可預約範圍。
沙箱不會發出任何對外訊息。無論您在其中建立或取消多少預約，都不會寄出任何Email 或通知。在測試模式中取消課程，不會通知任何顧客或員工。
沙箱每晚都會重置。請將其中的資料視為可丟棄，切勿將沙箱的 ID 儲存在您自己的系統中——它明天就不存在了。若測試結果突然變得不合理，請先確認是否剛好遇到每晚的重置。
沙箱的 ID 與您的 ID 不同。沙箱屬於另一個商家，因此請勿沿用正式資料中的課程、顧客或課卡 ID。請先以 GET 取得：例如先查詢課表列表，從回應中取一個 ID，再用該 ID 進行您要測試的請求。
沙箱為共用環境。其他商家也會在同一個沙箱進行測試，因此會出現並非您建立的資料，且可能在您操作期間變動。建議依據您自己請求所回傳的內容進行驗證，而非依據總數或筆數。
正式上線。請另外建立一組 Live Token 並替換使用。由於 Token 的模式建立後無法修改，因此不可能不小心讓測試串接指向正式資料——上線一定是刻意建立新 Token 的動作。
