For AI agents: visit https://docs.hsystem.halphastech.com/llms.txt for an index.
Append .md to any documentation page URL to get its markdown version.

# Getting Started
- [OAuth 登入（完整流程）](https://docs.hsystem.halphastech.com/guides/00-intro.md): 一個可以直接開在瀏覽器的單頁 HTML：按下「登入」→ 導到 HSystem 託管登入頁 → 回到你的頁面 → 換到 accesstoken。

# Guides
- [第一次呼叫（30 分鐘）](https://docs.hsystem.halphastech.com/guides/01-first-call.md): 如果你符合下面任何一項，就從這裡開始：
- [登入片段](https://docs.hsystem.halphastech.com/guides/10-auth-login.md): 在你的頁面放一顆登入按鈕，按下後把使用者導到 HSystem 託管授權頁，登入完成再帶著 code 回來。
- [Google 登入（平台統一）](https://docs.hsystem.halphastech.com/guides/12-auth-google.md): 搞懂 HSystem 的 Google 登入為什麼「只是一個開關」，以及使用者第一次用 Google 登入時會遇到什麼。
- [資料權限（dataScopes 三態）](https://docs.hsystem.halphastech.com/guides/14-data-scopes.md): 設定每個個資欄位（email、display name、頭像…）的分享策略，並搞清楚這件事會怎麼影響授權頁與 API 回應。
- [Callback 片段](https://docs.hsystem.halphastech.com/guides/15-auth-callback.md): 一個放在 callback.html 的片段：讀出網址上的 code，搭配登入時存下的 codeverifier，向 /oauth/token 換到 accesstoken。
- [App 用戶列表（Users API）](https://docs.hsystem.halphastech.com/guides/18-app-users.md): 知道「我的 App 現在有哪些使用者」，包含他們的授權狀態；也知道什麼時候你會只看到遮蔽後的個資。
- [原生 App OAuth（Google）](https://docs.hsystem.halphastech.com/guides/19-native-oauth.md): 原生 App 接 Google 登入的兩條路徑，以及各自該打的端點、要帶的參數、和會遇到的 pending 狀態。
- [Email 驗證](https://docs.hsystem.halphastech.com/guides/20-email-verify.md): 一個可以寄出驗證碼、再確認驗證碼的流程。使用者輸入 email → 收到 6 位數 → 輸入後完成驗證。
- [Email 通知](https://docs.hsystem.halphastech.com/guides/21-email-notify.md): 一個「寄一封通知信給使用者」的按鈕。例如訂單成立、密碼變更提醒、活動通知。
- [Public Ping](https://docs.hsystem.halphastech.com/guides/25-public-ping.md): 用一個最小的請求確認「平台活著、你的網路到得了、CORS 沒擋你」。
- [用戶資料](https://docs.hsystem.halphastech.com/guides/30-profile.md): 一個登入後就能讀取、儲存使用者資料的頁面。
- [法律中心](https://docs.hsystem.halphastech.com/guides/40-legal.md): 登入頁與同意頁都需要「隱私權政策」和「服務條款」的連結。
- [收款：從商品到結帳](https://docs.hsystem.halphastech.com/guides/50-pay-checkout.md): 一條最短的收款路線：建立商品 → 查價格 → 結帳 → 付款 → 看訂單變成 paid。
- [上傳與讀取檔案](https://docs.hsystem.halphastech.com/guides/52-files-upload.md): 上傳一個檔案，拿到它的 path；接著決定「誰可以讀」：
- [人機驗證（擋註冊機器人）](https://docs.hsystem.halphastech.com/guides/54-captcha.md): 在你自己的網頁上放一個驗證元件，通過後拿到 captchaticket，再把 ticket 一起送進登入或註冊。

# API Reference
- [身份驗證](https://docs.hsystem.halphastech.com/reference/auth.md): 託管登入頁與 REST／SDK 註冊登入、OAuth 授權碼 + PKCE、JWT 存取權杖。
- [用戶資料快取](https://docs.hsystem.halphastech.com/reference/profile.md): 以 App + 用戶為鍵的 JSON 資料快取。寫入合併指定的鍵。允許的鍵留空時不限制鍵名與型別；有清單時才依宣告檢查。已授權的聯絡方式仍從帳號投影。
- [Email](https://docs.hsystem.halphastech.com/reference/email.md): Email 驗證碼與確認歸屬；含一般通知寄送（模板或 HTML）。
- [手機驗證](https://docs.hsystem.halphastech.com/reference/phone_verify.md): 以 SMS OTP 確認手機號碼（Twilio Verify）。
- [人機驗證](https://docs.hsystem.halphastech.com/reference/captcha.md): 人機驗證：網頁 widget（Turnstile／reCAPTCHA v3／Altcha／Cap／mCaptcha 單選）與應用程序圖片挑戰 API；Auth 僅掛載觸發條件。
- [支付](https://docs.hsystem.halphastech.com/reference/pay.md): 開發者向終端用戶收款（BYOK，非平台代收）。建議商品結帳 POST /v1/pay/checkout（items[] 多品）；薄收款 intents。通道為內建清單（stub／綠界／Stripe），一家金流可建多個帳號，並用 regionRoutes 依地區排鏈；新增通道需改程式並重新部署。出站事件請用「Webhooks」服務。電子發票是獨立服務，見「發票」。Agent Token 需 pay:read／pay:write 才能讀寫支付設定，切換 apiMode=live 另需 pay:live。
- [發票](https://docs.hsystem.halphastech.com/reference/invoice.md): 電子發票（綠界 Einv B2C）：開立、查詢、作廢與折讓。獨立服務，金鑰用自己的 MerchantID／HashKey／HashIV，不必與「支付」共用；訂單來自支付，但發票不因支付停用而失效。可設定付款成功後自動開立，退款時自動折讓。出站事件請用「Webhooks」服務。
- [文件托管](https://docs.hsystem.halphastech.com/reference/files.md): 任意檔案上傳、路徑／前綴管理、內容去重與公開／私密讀取。控制台預設 console/* 資產前綴。
- [商品](https://docs.hsystem.halphastech.com/reference/commerce.md): 管理 App 內商品型錄：實體／虛擬／方案／服務／普通物品；支援 Tag 分類、規格、選配、綁定文件與自訂 JSON。目錄幣別的金額用 dinero.js 的最小單位。地區價格先用 Frankfurter 匯率換算，再加百分比或固定偏移。新建預設下架。公開型錄：GET /v1/commerce/apps/{appId}/…；管理 CRUD（App Secret）：/v1/commerce/products|tags。結帳見「支付」（多品 items[]）；用戶背包見「用戶物品」；折扣與邀請碼見「碼」。
- [碼](https://docs.hsystem.halphastech.com/reference/codes.md): 統一管理折扣碼、商品兌換碼、渠道歸因碼，以及註冊邀請碼。兌換／領券事件請訂閱「Webhooks」服務。
- [用戶物品](https://docs.hsystem.halphastech.com/reference/inventory.md): 托管終端用戶背包（購買／兌換／App 代發）。API：GET /v1/inventory/items|entitlements、POST …/consume、DELETE …/items/:id；App Secret：POST /v1/inventory/grant、PATCH …/items/:id。設定 allowAppGrant／allowUserConsume 控制寫入。
- [條款與政策](https://docs.hsystem.halphastech.com/reference/legal.md): 產生並託管隱私權政策、服務條款等文件；提供公開 URL 與匯出。
- [訪客](https://docs.hsystem.halphastech.com/reference/guest.md): 免註冊訪客身份：每 App 專屬 guest pool，與 Auth 正式池分離。可設定服務白名單、session／refresh 壽命；refresh／logout 與 Auth 共用。升級後同一 user id 遷入正式池。
- [Webhooks](https://docs.hsystem.halphastech.com/reference/events.md): 把登入、付款、兌換等事件送到你的後端、Discord 或 Slack。金流公司打回來的回呼網址在支付。
- [好友](https://docs.hsystem.halphastech.com/reference/friends.md): App 內好友關係：搜尋、邀請／直加、名單與顯示欄位。