產生型別
用 openapi-typescript 產生一份型別檔，呼叫端就有欄位提示與編譯期檢查。
Samples & AI
01範例
改一行就能跑的純前端範例
OAuth + PKCE 登入 → 換 token → 讀寫 Profile，全部只用 client_id， 沒有任何 client_secret 進到瀏覽器。解開後照 README 的三步走就好。
hs-quickstart/README.md三步跑起來、跑完該看到什麼、不要做的事。
hs-quickstart/callback.html用 code + code_verifier 換 access_token。
hs-quickstart/config.js只有這個要改：apiBase 與 clientId。
hs-quickstart/index.html產生 PKCE、導到 /oauth/authorize、顯示登入狀態。
hs-quickstart/profile.html從 token 解出 sub，讀寫 /v1/profile/{userId}。
跑起來需要本機 http 伺服器（
python -m http.server 8080 或 npx serve -l 8080）；用 file:// 直接開會因為 PKCE 的 crypto.subtle 不可用而失敗。回呼網址要加進 Auth 白名單：http://localhost:8080/callback.html。02AI Skill
把契約交給 AI，而不是給它一段舊文章
每個上線服務都有一份由 OpenAPI／服務模組產生的 SKILL.md： 基底 URL、憑證、配額維度與端點清單都跟現在的程式一致。把它貼進 Cursor／Claude 當知識來源，比讓模型憑印象寫 API 呼叫可靠。
身份驗證auth用戶資料快取profileEmailemail手機驗證phone_verify人機驗證captcha支付pay發票invoice文件托管files商品commerce碼codes用戶物品inventory條款與政策legal訪客guestWebhooksevents好友friends
還有一份整站的 openapi.json（所有 /v1 端點）與 llms.txt（指南索引，每一頁都可以在網址後面加 .md 取得 Markdown）。
讀 https://api.hsystem.halphastech.com/v1/public/skills/pay，照裡面的端點、參數與憑證說明， 用 Node.js 寫一段「建立結帳 → 收 webhook → 查訂單狀態」的範例。 規則： - 不要發明欄位；文件沒寫的參數先問我。 - webhook 一定要驗簽，並用事件 id 去重。 - 金額用最小單位（整數），不要用浮點數。
03SDK
目前沒有官方 SDK 套件
與其發一個跟不上契約的 SDK，不如把契約本身當介面。三條實務做法： 用 OpenAPI 產生型別、讓 AI 讀 SKILL.md、或直接抄文件的 curl／fetch 片段。
交給 AI
把對應服務的 SKILL.md 貼進對話，要求它只使用文件裡列的端點與參數。
抄片段
每篇指南與 Reference 都有可直接執行的 curl；先跑通，再包成你自己的 client。
# 產生 TypeScript 型別（不用裝任何 HSystem SDK） npx openapi-typescript https://docs.hsystem.halphastech.com/openapi.json -o src/hsystem-api.ts
注意：/api/public/* 是公開平面的鏡像路徑，SDK 與型別請以 /v1/* 為準。