🚀 簡介

Jii-Secure 提供一套完整的 RESTful API，讓您輕鬆整合企業級認證服務到您的應用程式中。所有 API 端點都使用 JSON 格式進行資料交換。

Base URL

https://auth.justdrink.com.tw
💡 提示： 所有請求都必須包含 Content-Type: application/json 標頭。

🔐 認證機制

Jii-Secure 使用 JWT (JSON Web Token) 進行用戶認證。在登入成功後，您會收到一個 access token，需要在後續的 API 請求中使用。

使用 Token

在需要認證的 API 請求中，請在 HTTP 標頭中包含以下內容：

Authorization Header 
Authorization: Bearer YOUR_ACCESS_TOKEN
⚠️ 注意： Token 有效期為 24 小時，過期後需要重新登入或使用 refresh token。

📝 用戶註冊

POST /register
建立新的用戶帳戶。註冊成功後，系統會發送驗證郵件到用戶的電子郵件地址。

請求參數

參數名稱 類型 必填 說明
fullName string 必填 用戶名稱，長度 2-50 字元
email string 必填 電子郵件地址，需符合標準格式
password string 必填 密碼，至少 8 字元
phone string 非必填

請求範例

Request Body 
{
  "name": "張三",
  "email": "[email protected]",
  "password": "securePassword123"
}

成功回應

200 OK

Response 
{
  "success": true,
  "message": "註冊成功，請檢查您的電子郵件以驗證帳戶",
  "data": {
    "user_id": "user_123456",
    "email": "[email protected]",
    "name": "張三"
  }
}

🔑 用戶登入

POST /login
使用電子郵件和密碼登入系統，成功後返回 JWT token。

請求參數

參數名稱 類型 必填 說明
email string 必填 註冊的電子郵件地址
password string 必填 用戶密碼

請求範例

Request Body 
{
  "email": "[email protected]",
  "password": "securePassword123"
}

成功回應

200 OK

Response 
{
  "success": true,
  "message": "登入成功",
  "data": {
    "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
    "refresh_token": "refresh_token_abc123...",
    "expires_in": 86400,
    "user": {
      "id": "user_123456",
      "name": "張三",
      "email": "[email protected]",
      "is_verified": true
    }
  }
}

✅ Email 驗證

GET /verify?token={verification_token}
驗證用戶的電子郵件地址。用戶點擊驗證郵件中的連結後，會自動調用此端點。

URL 參數

參數名稱 類型 必填 說明
token string 必填 郵件中的驗證 token

成功回應

200 OK

Response 
{
  "success": true,
  "message": "Email 驗證成功"
}

👤 獲取用戶資訊

GET /user
獲取當前登入用戶的詳細資訊。需要在請求標頭中包含有效的 JWT token。
🔒 需要認證： 此端點需要在 Authorization 標頭中包含有效的 Bearer token。

請求標頭

Headers 
Authorization: Bearer YOUR_ACCESS_TOKEN

成功回應

200 OK

Response 
{
  "success": true,
  "data": {
    "id": "user_123456",
    "name": "張三",
    "email": "[email protected]",
    "is_verified": true,
    "created_at": "2025-01-15T10:30:00Z",
    "updated_at": "2025-01-20T14:22:00Z"
  }
}

🔄 刷新 Token

POST /refresh
使用 refresh token 獲取新的 access token，避免用戶頻繁登入。

請求參數

參數名稱 類型 必填 說明
refresh_token string 必填 登入時獲得的 refresh token

請求範例

Request Body 
{
  "refresh_token": "refresh_token_abc123..."
}

成功回應

200 OK

Response 
{
  "success": true,
  "message": "Token 刷新成功",
  "data": {
    "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
    "expires_in": 86400
  }
}

🚪 用戶登出

POST /logout
登出當前用戶，使當前的 access token 失效。
🔒 需要認證： 此端點需要在 Authorization 標頭中包含有效的 Bearer token。

請求標頭

Headers 
Authorization: Bearer YOUR_ACCESS_TOKEN

成功回應

200 OK

Response 
{
  "success": true,
  "message": "登出成功"
}

⚠️ 錯誤處理

當 API 請求失敗時，會返回相應的 HTTP 狀態碼和錯誤訊息。所有錯誤回應都遵循統一的格式。

錯誤回應格式

Error Response 
{
  "success": false,
  "message": "錯誤描述訊息",
  "error_code": "ERROR_CODE"
}

常見錯誤碼

HTTP 狀態碼 錯誤碼 說明
400 INVALID_REQUEST 請求參數無效或缺少必填欄位
401 UNAUTHORIZED 未提供認證憑證或憑證無效
401 INVALID_CREDENTIALS 電子郵件或密碼錯誤
401 TOKEN_EXPIRED Token 已過期，請刷新或重新登入
403 EMAIL_NOT_VERIFIED 電子郵件尚未驗證
404 USER_NOT_FOUND 用戶不存在
409 EMAIL_EXISTS 電子郵件已被註冊
429 RATE_LIMIT_EXCEEDED 請求頻率超過限制
500 INTERNAL_ERROR 伺服器內部錯誤

錯誤處理範例

JavaScript Example 
fetch('https://api.jii-secure.com/auth/login', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    email: '[email protected]',
    password: 'password123'
  })
})
.then(response => response.json())
.then(data => {
  if (data.success) {
    console.log('登入成功', data.data.token);
  } else {
    console.error('登入失敗:', data.message);
  }
})
.catch(error => {
  console.error('請求錯誤:', error);
});
💡 最佳實踐： 請妥善處理所有可能的錯誤狀況，並向用戶顯示友善的錯誤訊息。

⏱️ 速率限制

為了保護系統穩定性和安全性，API 實施了速率限制。

📊 限制規則：
  • 一般端點：每分鐘最多 60 次請求
  • 登入端點：每分鐘最多 5 次請求
  • 註冊端點：每小時最多 3 次請求

速率限制標頭

每個 API 回應都會包含以下標頭，幫助您追蹤使用情況：

Response Headers 
X-RateLimit-Limit: 60
X-RateLimit-Remaining: 45
X-RateLimit-Reset: 1642598400

✨ 最佳實踐

🎯 建議事項

  • 安全儲存 Token： 切勿將 token 儲存在 localStorage 中用於生產環境，建議使用 httpOnly cookies
  • HTTPS 連線： 始終使用 HTTPS 協議進行 API 通訊
  • Token 刷新： 實作自動 token 刷新機制，提升用戶體驗
  • 錯誤處理： 實作完善的錯誤處理和重試機制
  • 日誌記錄： 記錄 API 請求和回應以便除錯
  • 版本控制： 在整合時指定 API 版本，避免不相容問題

💬 技術支援

如果您在使用 API 時遇到任何問題，請通過以下方式聯繫我們：

📧 Email
[email protected]
📚 文檔
https://auth.justdrink.com.tw/docs.html