AI 文件

這一頁是純 AI 專用文檔，適合直接把網址丟給 ChatGPT、Claude、Cursor 或其他 coding agent。

登入開發者中心 查看前台 API 文件

快速分享給 AI

如果你只想給 AI 一段最短指令，直接複製這段即可。
請先閱讀這份 AI 文件：https://ccpass.0800945.com/ai-docs
並依現有專案架構完成串串通登入整合。
請不要把 /oauth/token/ 誤當成 access_token API，它回傳的是 open_id、email、user_id 等會員識別資料。
如果可以，建議直接下載官方 SDK（PHP / Node / Browser）當作起點：
- PHP SDK: https://ccpass.0800945.com/developer/index.php?route=sdk-download&type=php
- Node SDK: https://ccpass.0800945.com/developer/index.php?route=sdk-download&type=node
- Browser SDK: https://ccpass.0800945.com/developer/index.php?route=sdk-download&type=browser
若你需要乾淨 JSON 契約（避開 Cloudflare email obfuscation），請直接 fetch：https://ccpass.0800945.com/developer/index.php?route=ai-contract

一鍵複製整份 AI 提示包

這裡已經把快速指令、通用提示詞、Coding Agent 提示詞、JSON 契約與驗收清單整合成一包。
【串串通 Ccpass AI 提示包】

一、快速指令
請先閱讀這份 AI 文件：https://ccpass.0800945.com/ai-docs
並依現有專案架構完成串串通登入整合。
請不要把 /oauth/token/ 誤當成 access_token API，它回傳的是 open_id、email、user_id 等會員識別資料。
如果可以，建議直接下載官方 SDK（PHP / Node / Browser）當作起點：
- PHP SDK: https://ccpass.0800945.com/developer/index.php?route=sdk-download&type=php
- Node SDK: https://ccpass.0800945.com/developer/index.php?route=sdk-download&type=node
- Browser SDK: https://ccpass.0800945.com/developer/index.php?route=sdk-download&type=browser
若你需要乾淨 JSON 契約（避開 Cloudflare email obfuscation），請直接 fetch：https://ccpass.0800945.com/developer/index.php?route=ai-contract

二、通用提示詞
你現在要協助我把「串串通 Ccpass」登入整合到我的網站。

請先完整閱讀這份文件：
https://ccpass.0800945.com/ai-docs

系統端點：
- 授權端點：https://ccpass.0800945.com/oauth/authorize/
- Token 交換端點：https://ccpass.0800945.com/oauth/token/
- Email 發碼端點：https://ccpass.0800945.com/api/send-code/
- Email 驗證端點：https://ccpass.0800945.com/api/verify-code/

整合規則：
- 先導向 `/oauth/authorize/`（GET，瀏覽器跳轉）
- callback 會回到 `redirect_uri` 並帶回 `code`、`state`
- 後端再用 `client_id`、`client_secret`、`code` POST 呼叫 `/oauth/token/`
- `/oauth/token/` 成功時回傳 `open_id`、`email`、`user_id`、`client_id`
- 這不是標準 Bearer access token 流程

必填與時效：
- `client_secret` 只能在後端使用，前端永遠不能讀到
- `state` 必須由後端產生（建議 random_bytes(32) → bin2hex → 64 字元）、寫進 session、callback 時嚴格比對後銷毀
- `redirect_uri` 必須與 App 在後台設定的值**完全一致**（含 scheme、host、path）
- `code` 有效期限 **10 分鐘**且**只能使用一次**，過期或重用都會回 `授權碼無效/已過期/已使用。`
- Email 驗證碼為 **6 位數字**，有效期限 **5 分鐘**（300 秒）

必看重要文件：
- 整合前先看 SDK 範例（建議當起點，不要從零刻）：https://ccpass.0800945.com/developer/index.php?route=sdk-download&type=php
- Callback 流程測試頁：https://ccpass.0800945.com/developer/index.php?route=callback-tester

請務必遵守：
- 不要把 `code` 寫進前端 localStorage / cookie（敏感、單次使用）
- 不要自己寫 OAuth state 產生器，要用後端內建 random_bytes
- Email 驗證的 `purpose` 預設 `register`，可用值含 `login` / `register` / `forgot_password` 等自由字串（最長 50 字元）
- 遇到 HTTP 422 表示請求格式錯；429 表示 rate limit（請讀 `Retry-After` header）
- 以 `provider=ccpass + open_id` 建立或查詢綁定資料；若 email 已存在但尚未綁定，請設計安全的合併或綁定流程

請直接提供：
- 路由設計（登入入口 / callback / 登出）
- 後端 Token 交換 service（含錯誤處理）
- 綁定資料表（建議 `provider` VARCHAR + `open_id` VARCHAR + `member_id` BIGINT + `email` VARCHAR，unique key 為 `(provider, open_id)`）
- Session / 登入狀態寫入方式
- 驗收步驟（含一個 curl 指令可成功呼叫 `/oauth/token/` 並驗證回應）

完成後請說明：
1. 實際修改了哪些檔案
2. 新增了哪些資料表或欄位
3. 如何用 curl 驗證整合成功

三、Coding Agent 提示詞
你現在是一名 coding agent，請根據這份文件直接在現有專案內完成登入整合：
https://ccpass.0800945.com/ai-docs

工作要求：
1. 先閱讀專案現有會員登入、Session、路由與資料表結構
2. 下載並參考官方 SDK 範例（PHP / Node / Browser 任一）：
   - PHP: https://ccpass.0800945.com/developer/index.php?route=sdk-download&type=php
   - Node: https://ccpass.0800945.com/developer/index.php?route=sdk-download&type=node
   - Browser: https://ccpass.0800945.com/developer/index.php?route=sdk-download&type=browser
3. 新增登入入口與 callback 路由
4. 新增後端 Token 交換 service（含 JSON 解析與錯誤處理）
5. 新增或沿用第三方綁定表，至少保存 `provider`、`open_id`、`member_id`、`email`，並把 `(provider, open_id)` 設為 unique key
6. 完成登入成功後的 Session 寫入與導頁
7. 補上 state 驗證、錯誤處理、Retry-After 讀取

重要規則：
- `/oauth/token/` 回傳的是會員識別資料（`open_id / email / user_id / client_id`），不是 access token
- `client_secret` 不能出現在前端
- `redirect_uri` 必須與 App 設定完全一致
- `state` 必須用後端 `random_bytes(32)` 產生 64 字元、寫進 session、callback 嚴格比對後銷毀
- `code` 10 分鐘內有效且只能使用一次
- Email 驗證碼 6 位數、5 分鐘內有效，`purpose` 預設 `register`

驗收方式：
- 用 curl 指令實際打 `/oauth/token/`，必須拿到 `success: true` + `data.open_id`
- 若失敗，請對照本文件「OAuth 錯誤碼表」排查

請交付：
- 實際修改了哪些檔案
- 新增了哪些資料表或欄位
- 如何設定 `client_id`、`client_secret`、`redirect_uri`
- 如何驗證整合成功（含一條 curl 指令）

四、JSON 契約
{
    "platform": {
        "name": "串串通 Ccpass",
        "docs_url": "https://ccpass.0800945.com/ai-docs",
        "base_url": "https://ccpass.0800945.com",
        "sdk_downloads": {
            "php": "https://ccpass.0800945.com/developer/index.php?route=sdk-download&type=php",
            "node": "https://ccpass.0800945.com/developer/index.php?route=sdk-download&type=node",
            "browser": "https://ccpass.0800945.com/developer/index.php?route=sdk-download&type=browser"
        }
    },
    "oauth": {
        "authorize": {
            "method": "GET",
            "url": "https://ccpass.0800945.com/oauth/authorize/",
            "query": {
                "client_id": "required, 你的 App Client ID",
                "redirect_uri": "required, 必須與後台設定完全一致",
                "state": "required, 後端產生的隨機字串"
            },
            "response": "302 redirect 回 redirect_uri，帶 query string code + state",
            "code_ttl_seconds": 600,
            "code_format": "64 hex chars (bin2hex(random_bytes(32)))"
        },
        "callback": {
            "returns_query": [
                "code",
                "state"
            ],
            "state_rules": "後端產生 random_bytes(32) -> bin2hex -> 64 字元；寫進 session；callback 嚴格比對後銷毀"
        },
        "token_exchange": {
            "method": "POST",
            "url": "https://ccpass.0800945.com/oauth/token/",
            "content_type": "application/json",
            "alt_content_type": "application/x-www-form-urlencoded",
            "body": [
                "client_id",
                "client_secret",
                "code"
            ],
            "success_response": {
                "success": true,
                "data": {
                    "message": "授權碼交換成功。",
                    "open_id": "ccpass_open_id_xxx",
                    "email": "[email protected]",
                    "user_id": 123,
                    "client_id": "對應到你的 App"
                }
            },
            "error_response": {
                "success": false,
                "message": "錯誤訊息（純字串）",
                "errors": []
            },
            "note": "回傳會員識別資料，不是 access_token"
        }
    },
    "email_verification": {
        "send_code": {
            "method": "POST",
            "url": "https://ccpass.0800945.com/api/send-code/",
            "content_type": "application/json",
            "body": {
                "email": "required, Email 地址",
                "purpose": "預設 register，可用 login / register / forgot_password 等自由字串，最長 50 字元"
            },
            "success_response": {
                "success": true,
                "data": {
                    "message": "驗證碼已寄出，請至信箱查收。",
                    "purpose": "register",
                    "expires_in": 300
                }
            },
            "rate_limit": "同 Email 60 秒內限制；單日發送上限。觸發時回 429 + Retry-After header"
        },
        "verify_code": {
            "method": "POST",
            "url": "https://ccpass.0800945.com/api/verify-code/",
            "content_type": "application/json",
            "body": {
                "email": "required, Email 地址",
                "code": "required, 6 位數字",
                "purpose": "與寄送時相同"
            },
            "success_response": {
                "success": true,
                "data": {
                    "message": "驗證碼正確，可繼續下一步。",
                    "purpose": "register"
                }
            },
            "note": "驗證碼錯誤次數過多將回 429"
        }
    },
    "errors": {
        "http_codes": {
            "200": "成功",
            "422": "缺少必要欄位 / Client Secret 錯誤 / code 無效或過期或已使用 / App 已停用",
            "429": "觸發 rate limit（讀 Retry-After header）"
        },
        "error_format": {
            "success": false,
            "message": "人類可讀的錯誤訊息字串",
            "errors": "欄位級錯誤陣列（通常為空）"
        }
    },
    "binding": {
        "provider": "ccpass",
        "unique_key": [
            "provider",
            "open_id"
        ],
        "recommended_columns": [
            "member_id",
            "provider",
            "open_id",
            "email"
        ],
        "example_schema": "CREATE TABLE oauth_bindings (id BIGINT PK, member_id BIGINT, provider VARCHAR(32), open_id VARCHAR(128), email VARCHAR(255), created_at TIMESTAMP, UNIQUE KEY uk_provider_openid (provider, open_id))"
    },
    "verification": {
        "curl_token_example": "curl -X POST 'https://ccpass.0800945.com/oauth/token/' -H 'Content-Type: application/json' -d '{\"client_id\":\"請先在開發者中心建立 App 取得 client_id\",\"client_secret\":\"YOUR_CLIENT_SECRET\",\"code\":\"PASTE_AUTH_CODE_HERE\"}'",
        "callback_tester": "https://ccpass.0800945.com/developer/index.php?route=callback-tester"
    }
}

五、驗收清單
- 能正確導向 /oauth/authorize/（瀏覽器 302 redirect）。
- callback 能收到 code 與 state，且後端會嚴格比對 state 後銷毀。
- 後端能成功呼叫 /oauth/token/ 並解析 open_id、email、user_id、client_id。
- 能查詢或建立第三方綁定資料（unique key = (provider, open_id)）。
- 登入成功後能寫入本站 Session 並導向登入成功頁。
- 若需要 Email 驗證，也能正確使用 /api/send-code/ 與 /api/verify-code/。
- 可用 curl 指令打 /oauth/token/ 驗證整合（指令在下方範例區）。
- 遇到 422/429 錯誤時會讀 `Retry-After` header 並回傳合理錯誤訊息。

核心規格

AI 文件網址 https://ccpass.0800945.com/ai-docs
授權端點 https://ccpass.0800945.com/oauth/authorize/
Token 交換端點 https://ccpass.0800945.com/oauth/token/
Email 發碼端點 https://ccpass.0800945.com/api/send-code/
Email 驗證端點 https://ccpass.0800945.com/api/verify-code/
範例 Client ID 請先在開發者中心建立 App 取得 client_id
範例 Callback URL https://your-domain.com/oauth/callback

AI 一定要理解的規則

  • 流程固定是：登入入口 -> /oauth/authorize/ -> callback 收 code/state -> 後端 /oauth/token/。
  • /oauth/token/ 回傳的是會員識別資料，不是標準 access_token。
  • client_secret 只能在後端保存與呼叫，前端永遠不能讀到。
  • redirect_uri 必須與 App 設定完全一致（含 scheme、host、path）。
  • state 必須由後端 random_bytes(32) 產生 64 字元、寫進 session、callback 嚴格比對後銷毀。
  • code 有效期限 10 分鐘且只能使用一次。
  • Email 驗證碼為 6 位數字，有效期限 5 分鐘。
  • 建議以 provider=ccpass + open_id 建立綁定資料，unique key 為 (provider, open_id)。
  • 若 email 已存在但尚未綁定，請設計安全的合併或綁定流程（不可自動合併）。

官方 SDK 下載（強烈建議當起點）

SDK 範例涵蓋 authorize redirect、state 驗證、token 交換、callback 處理 — 直接拿來改比從零刻快得多。
PHP SDK
原生 PHP，示範 curl + session state。
下載 PHP
Node.js SDK
Express + crypto.randomUUID，示範完整 callback。
下載 Node
Browser SDK
純前端示範（client_secret 仍須後端使用）。
下載 Browser

Request / Response 範例（真實可跑）

1. /oauth/authorize/ — 瀏覽器 GET 跳轉

用戶點「用串串通登入」時，把瀏覽器導向以下網址：

https://ccpass.0800945.com/oauth/authorize/?client_id=%E8%AB%8B%E5%85%88%E5%9C%A8%E9%96%8B%E7%99%BC%E8%80%85%E4%B8%AD%E5%BF%83%E5%BB%BA%E7%AB%8B+App+%E5%8F%96%E5%BE%97+client_id&redirect_uri=https%3A%2F%2Fyour-domain.com%2Foauth%2Fcallback&state=%3C%E5%BE%8C%E7%AB%AF%E7%94%A2%E7%94%9F%E7%9A%84+64+%E5%AD%97%E5%85%83%E9%9A%A8%E6%A9%9F%E5%AD%97%E4%B8%B2%3E

用戶登入並同意後，串串通會 302 redirect 回 `redirect_uri`，並帶 query string code=... + state=...。

2. /oauth/token/ — 後端 POST 換 token

Request JSON
{
    "client_id": "請先在開發者中心建立 App 取得 client_id",
    "client_secret": "YOUR_CLIENT_SECRET",
    "code": "oauth_authorization_code_here"
}
curl 指令
curl -X POST 'https://ccpass.0800945.com/oauth/token/' \
  -H 'Content-Type: application/json' \
  -H 'Accept: application/json' \
  -d '{
    "client_id": "請先在開發者中心建立 App 取得 client_id",
    "client_secret": "YOUR_CLIENT_SECRET",
    "code": "oauth_authorization_code_here"
}'
成功回應 (HTTP 200)
{
    "success": true,
    "data": {
        "message": "授權碼交換成功。",
        "open_id": "ccpass_open_id_a1b2c3d4e5f6g7h8",
        "email": "[email protected]",
        "user_id": 12345,
        "client_id": "請先在開發者中心建立 App 取得 client_id"
    }
}
失敗回應 (HTTP 422)
{
    "success": false,
    "message": "授權碼已使用。",
    "errors": []
}
這不是標準 OAuth access_token。`data.open_id` 就是用戶在串串通上的唯一識別代號，請用 `open_id` 建立或查詢你自己的會員綁定資料。

3. /api/send-code/ — 寄送 Email 驗證碼

Request
{
    "email": "[email protected]",
    "purpose": "register"
}
curl
curl -X POST 'https://ccpass.0800945.com/api/send-code/' \
  -H 'Content-Type: application/json' \
  -d '{
    "email": "[email protected]",
    "purpose": "register"
}'
成功回應 (HTTP 200)
{
    "success": true,
    "data": {
        "message": "驗證碼已寄出，請至信箱查收。",
        "purpose": "register",
        "expires_in": 300
    }
}

4. /api/verify-code/ — 驗證 6 位數

Request
{
    "email": "[email protected]",
    "code": "123456",
    "purpose": "register"
}
curl
curl -X POST 'https://ccpass.0800945.com/api/verify-code/' \
  -H 'Content-Type: application/json' \
  -d '{
    "email": "[email protected]",
    "code": "123456",
    "purpose": "register"
}'
成功回應 (HTTP 200)
{
    "success": true,
    "data": {
        "message": "驗證碼正確，可繼續下一步。",
        "purpose": "register"
    }
}

錯誤碼表（整合失敗先查這張表）

所有錯誤回應統一格式：{ success: false, message: "...", errors: [] }。429 時請讀 Retry-After header。

HTTP 狀態 情境 可能訊息 處理建議
200 成功 （依端點） 保存 data 欄位並繼續。
422 缺少必要欄位 `client_id、client_secret、code 皆為必填。` 確認後端請求帶齊三個必要欄位。
422 Client Secret 錯誤 `Client Secret 錯誤。` 檢查是否使用最新憑證；若剛重置過 secret 請同步更新設定。
422 授權碼無效 `授權碼無效。` 確認 code 是剛從 callback 收到、沒有被竄改。
422 授權碼已過期 `授權碼已過期。` code 10 分鐘內有效；超過就要重走 authorize。
422 授權碼已使用 `授權碼已使用。` code 只能換一次 token；重用就重走 authorize。
422 App 已停用 `應用已停用。` 到開發者後台「我的應用」啟用該 App。
422 使用者狀態異常 `使用者狀態異常。` 請使用者聯絡平台客服。
429 觸發 rate limit `Token 交換請求過於頻繁，請稍後再試。` 讀取 `Retry-After` header，延後重試；檢查是否有錯誤憑證造成大量失敗。

Email 驗證 `purpose` 用途對照

`purpose` 是自由字串（最長 50 字元），預設 register。以下是常用值，AI 可依情境挑選。

purpose 值 用途
register 註冊流程（預設值）
login 登入流程
forgot_password 忘記密碼 / 重設密碼
change_email 更換 Email
bind_email 綁定 Email

綁定資料表 Schema 參考

第三方綁定資料表建議結構（MySQL 範例）。`provider` 預留未來擴充其他 OAuth provider。

CREATE TABLE oauth_bindings (
  id BIGINT UNSIGNED PRIMARY KEY AUTO_INCREMENT,
  member_id BIGINT UNSIGNED NOT NULL,
  provider VARCHAR(32) NOT NULL DEFAULT 'ccpass',
  open_id VARCHAR(128) NOT NULL,
  email VARCHAR(255) DEFAULT NULL,
  created_at TIMESTAMP NOT NULL DEFAULT CURRENT_TIMESTAMP,
  UNIQUE KEY uk_provider_openid (provider, open_id),
  KEY idx_member (member_id)
);
可直接貼給 ChatGPT / Claude 的提示詞
你現在要協助我把「串串通 Ccpass」登入整合到我的網站。

請先完整閱讀這份文件：
https://ccpass.0800945.com/ai-docs

系統端點：
- 授權端點：https://ccpass.0800945.com/oauth/authorize/
- Token 交換端點：https://ccpass.0800945.com/oauth/token/
- Email 發碼端點：https://ccpass.0800945.com/api/send-code/
- Email 驗證端點：https://ccpass.0800945.com/api/verify-code/

整合規則：
- 先導向 `/oauth/authorize/`（GET，瀏覽器跳轉）
- callback 會回到 `redirect_uri` 並帶回 `code`、`state`
- 後端再用 `client_id`、`client_secret`、`code` POST 呼叫 `/oauth/token/`
- `/oauth/token/` 成功時回傳 `open_id`、`email`、`user_id`、`client_id`
- 這不是標準 Bearer access token 流程

必填與時效：
- `client_secret` 只能在後端使用，前端永遠不能讀到
- `state` 必須由後端產生（建議 random_bytes(32) → bin2hex → 64 字元）、寫進 session、callback 時嚴格比對後銷毀
- `redirect_uri` 必須與 App 在後台設定的值**完全一致**（含 scheme、host、path）
- `code` 有效期限 **10 分鐘**且**只能使用一次**，過期或重用都會回 `授權碼無效/已過期/已使用。`
- Email 驗證碼為 **6 位數字**，有效期限 **5 分鐘**（300 秒）

必看重要文件：
- 整合前先看 SDK 範例（建議當起點，不要從零刻）：https://ccpass.0800945.com/developer/index.php?route=sdk-download&type=php
- Callback 流程測試頁：https://ccpass.0800945.com/developer/index.php?route=callback-tester

請務必遵守：
- 不要把 `code` 寫進前端 localStorage / cookie（敏感、單次使用）
- 不要自己寫 OAuth state 產生器，要用後端內建 random_bytes
- Email 驗證的 `purpose` 預設 `register`，可用值含 `login` / `register` / `forgot_password` 等自由字串（最長 50 字元）
- 遇到 HTTP 422 表示請求格式錯；429 表示 rate limit（請讀 `Retry-After` header）
- 以 `provider=ccpass + open_id` 建立或查詢綁定資料；若 email 已存在但尚未綁定，請設計安全的合併或綁定流程

請直接提供：
- 路由設計（登入入口 / callback / 登出）
- 後端 Token 交換 service（含錯誤處理）
- 綁定資料表（建議 `provider` VARCHAR + `open_id` VARCHAR + `member_id` BIGINT + `email` VARCHAR，unique key 為 `(provider, open_id)`）
- Session / 登入狀態寫入方式
- 驗收步驟（含一個 curl 指令可成功呼叫 `/oauth/token/` 並驗證回應）

完成後請說明：
1. 實際修改了哪些檔案
2. 新增了哪些資料表或欄位
3. 如何用 curl 驗證整合成功
可直接貼給 Coding Agent 的提示詞
你現在是一名 coding agent，請根據這份文件直接在現有專案內完成登入整合：
https://ccpass.0800945.com/ai-docs

工作要求：
1. 先閱讀專案現有會員登入、Session、路由與資料表結構
2. 下載並參考官方 SDK 範例（PHP / Node / Browser 任一）：
   - PHP: https://ccpass.0800945.com/developer/index.php?route=sdk-download&type=php
   - Node: https://ccpass.0800945.com/developer/index.php?route=sdk-download&type=node
   - Browser: https://ccpass.0800945.com/developer/index.php?route=sdk-download&type=browser
3. 新增登入入口與 callback 路由
4. 新增後端 Token 交換 service（含 JSON 解析與錯誤處理）
5. 新增或沿用第三方綁定表，至少保存 `provider`、`open_id`、`member_id`、`email`，並把 `(provider, open_id)` 設為 unique key
6. 完成登入成功後的 Session 寫入與導頁
7. 補上 state 驗證、錯誤處理、Retry-After 讀取

重要規則：
- `/oauth/token/` 回傳的是會員識別資料（`open_id / email / user_id / client_id`），不是 access token
- `client_secret` 不能出現在前端
- `redirect_uri` 必須與 App 設定完全一致
- `state` 必須用後端 `random_bytes(32)` 產生 64 字元、寫進 session、callback 嚴格比對後銷毀
- `code` 10 分鐘內有效且只能使用一次
- Email 驗證碼 6 位數、5 分鐘內有效，`purpose` 預設 `register`

驗收方式：
- 用 curl 指令實際打 `/oauth/token/`，必須拿到 `success: true` + `data.open_id`
- 若失敗，請對照本文件「OAuth 錯誤碼表」排查

請交付：
- 實際修改了哪些檔案
- 新增了哪些資料表或欄位
- 如何設定 `client_id`、`client_secret`、`redirect_uri`
- 如何驗證整合成功（含一條 curl 指令）
可直接給 AI / Agent 讀的 JSON 契約
{
    "platform": {
        "name": "串串通 Ccpass",
        "docs_url": "https://ccpass.0800945.com/ai-docs",
        "base_url": "https://ccpass.0800945.com",
        "sdk_downloads": {
            "php": "https://ccpass.0800945.com/developer/index.php?route=sdk-download&type=php",
            "node": "https://ccpass.0800945.com/developer/index.php?route=sdk-download&type=node",
            "browser": "https://ccpass.0800945.com/developer/index.php?route=sdk-download&type=browser"
        }
    },
    "oauth": {
        "authorize": {
            "method": "GET",
            "url": "https://ccpass.0800945.com/oauth/authorize/",
            "query": {
                "client_id": "required, 你的 App Client ID",
                "redirect_uri": "required, 必須與後台設定完全一致",
                "state": "required, 後端產生的隨機字串"
            },
            "response": "302 redirect 回 redirect_uri，帶 query string code + state",
            "code_ttl_seconds": 600,
            "code_format": "64 hex chars (bin2hex(random_bytes(32)))"
        },
        "callback": {
            "returns_query": [
                "code",
                "state"
            ],
            "state_rules": "後端產生 random_bytes(32) -> bin2hex -> 64 字元；寫進 session；callback 嚴格比對後銷毀"
        },
        "token_exchange": {
            "method": "POST",
            "url": "https://ccpass.0800945.com/oauth/token/",
            "content_type": "application/json",
            "alt_content_type": "application/x-www-form-urlencoded",
            "body": [
                "client_id",
                "client_secret",
                "code"
            ],
            "success_response": {
                "success": true,
                "data": {
                    "message": "授權碼交換成功。",
                    "open_id": "ccpass_open_id_xxx",
                    "email": "[email protected]",
                    "user_id": 123,
                    "client_id": "對應到你的 App"
                }
            },
            "error_response": {
                "success": false,
                "message": "錯誤訊息（純字串）",
                "errors": []
            },
            "note": "回傳會員識別資料，不是 access_token"
        }
    },
    "email_verification": {
        "send_code": {
            "method": "POST",
            "url": "https://ccpass.0800945.com/api/send-code/",
            "content_type": "application/json",
            "body": {
                "email": "required, Email 地址",
                "purpose": "預設 register，可用 login / register / forgot_password 等自由字串，最長 50 字元"
            },
            "success_response": {
                "success": true,
                "data": {
                    "message": "驗證碼已寄出，請至信箱查收。",
                    "purpose": "register",
                    "expires_in": 300
                }
            },
            "rate_limit": "同 Email 60 秒內限制；單日發送上限。觸發時回 429 + Retry-After header"
        },
        "verify_code": {
            "method": "POST",
            "url": "https://ccpass.0800945.com/api/verify-code/",
            "content_type": "application/json",
            "body": {
                "email": "required, Email 地址",
                "code": "required, 6 位數字",
                "purpose": "與寄送時相同"
            },
            "success_response": {
                "success": true,
                "data": {
                    "message": "驗證碼正確，可繼續下一步。",
                    "purpose": "register"
                }
            },
            "note": "驗證碼錯誤次數過多將回 429"
        }
    },
    "errors": {
        "http_codes": {
            "200": "成功",
            "422": "缺少必要欄位 / Client Secret 錯誤 / code 無效或過期或已使用 / App 已停用",
            "429": "觸發 rate limit（讀 Retry-After header）"
        },
        "error_format": {
            "success": false,
            "message": "人類可讀的錯誤訊息字串",
            "errors": "欄位級錯誤陣列（通常為空）"
        }
    },
    "binding": {
        "provider": "ccpass",
        "unique_key": [
            "provider",
            "open_id"
        ],
        "recommended_columns": [
            "member_id",
            "provider",
            "open_id",
            "email"
        ],
        "example_schema": "CREATE TABLE oauth_bindings (id BIGINT PK, member_id BIGINT, provider VARCHAR(32), open_id VARCHAR(128), email VARCHAR(255), created_at TIMESTAMP, UNIQUE KEY uk_provider_openid (provider, open_id))"
    },
    "verification": {
        "curl_token_example": "curl -X POST 'https://ccpass.0800945.com/oauth/token/' -H 'Content-Type: application/json' -d '{\"client_id\":\"請先在開發者中心建立 App 取得 client_id\",\"client_secret\":\"YOUR_CLIENT_SECRET\",\"code\":\"PASTE_AUTH_CODE_HERE\"}'",
        "callback_tester": "https://ccpass.0800945.com/developer/index.php?route=callback-tester"
    }
}

驗收清單

  • 能正確導向 /oauth/authorize/（瀏覽器 302 redirect）。
  • callback 能收到 code 與 state，且後端會嚴格比對 state 後銷毀。
  • 後端能成功呼叫 /oauth/token/ 並解析 open_id、email、user_id、client_id。
  • 能查詢或建立第三方綁定資料（unique key = (provider, open_id)）。
  • 登入成功後能寫入本站 Session 並導向登入成功頁。
  • 若需要 Email 驗證，也能正確使用 /api/send-code/ 與 /api/verify-code/。
  • 可用 curl 指令打 /oauth/token/ 驗證整合（指令在下方範例區）。
  • 遇到 422/429 錯誤時會讀 `Retry-After` header 並回傳合理錯誤訊息。

使用建議

最短可給 AI 的網址
https://ccpass.0800945.com/ai-docs
Callback 測試頁
/developer/index.php?route=callback-tester
官方 SDK 下載
PHP Node Browser
最重要提醒
`/oauth/token/` 回傳的是會員識別資料，不是 Bearer `access_token`。
建議搭配
  • 要完整背景時，先看 `API 文件`
  • 要測 callback 時，使用 `Callback 測試頁`
  • 要寫程式時，先下載 SDK 當起點，比從零刻快
  • 要直接給 AI 做事時，就丟這一頁