API 開發者文件 - Quto 智能考勤管理系統

快速開始

Quto API 使用 RESTful 架構，所有請求與回應均採用 JSON 格式。以下是開始使用 API 所需的基本資訊。

API Base URL

https://api.quto.com/v1

認證方式

Bearer Token

請求格式

application/json

認證

所有 API 請求都需要使用 API Key 進行認證。您可以在 Quto 後台的「設定」>「API 整合」中取得您的 API Key。

請妥善保管您的 API Key，切勿在前端程式碼或公開的版本控制系統中暴露。如果您懷疑 API Key 已外洩，請立即在後台重新產生。

HTTP Headers

Authorization: Bearer your_api_key
Content-Type: application/json

cURL 範例

curl -X GET https://api.quto.com/v1/employees \
  -H "Authorization: Bearer your_api_key" \
  -H "Content-Type: application/json"

API 端點

以下列出所有可用的 API 端點，依功能分類。每個端點都需要有效的認證標頭。

👥 員工管理

GET /employees 取得員工列表

POST /employees 新增員工

GET /employees/{id} 取得單一員工

🕐 打卡紀錄

GET /attendance 取得打卡紀錄

POST /attendance/clock-in 打卡上班

POST /attendance/clock-out 打卡下班

📅 請假管理

GET /leaves 取得請假申請

POST /leaves 建立請假申請

PUT /leaves/{id}/approve 核准請假

📊 報表

GET /reports/attendance 出勤報表

GET /reports/leave 請假報表

Webhook

Webhook 可讓您的系統即時接收 Quto 中發生的事件通知。當特定事件發生時，我們會向您設定的 URL 發送 HTTP POST 請求。

支援事件

🕐 員工打卡

📅 請假申請

✅ 審核完成

設定方式

在 Quto 後台的「設定」>「API 整合」>「Webhook」中，新增您的 Webhook URL。您可以選擇要訂閱的事件類型。

Webhook Payload 範例

{
  "event": "attendance.clock_in",
  "timestamp": "2024-01-15T09:00:00Z",
  "data": {
    "employee_id": "emp_123456",
    "employee_name": "王小明",
    "clock_time": "2024-01-15T09:00:00+08:00",
    "location": "台北辦公室"
  }
}

錯誤碼

當 API 請求失敗時，回應會包含對應的 HTTP 狀態碼和錯誤訊息。以下是常見的錯誤碼說明。

狀態碼	說明
400	請求格式錯誤 - 請檢查請求參數是否正確
401	未授權 - API Key 無效或已過期
403	權限不足 - 您的帳號無權執行此操作
404	資源不存在 - 請確認請求的資源 ID 是否正確
429	請求過於頻繁 - 已超過速率限制，請稍後再試

錯誤回應範例

{
  "error": {
    "code": "invalid_request",
    "message": "請求格式錯誤，employee_id 為必填欄位",
    "details": {
      "field": "employee_id",
      "reason": "required"
    }
  }
}

限制

為確保服務品質，API 有以下使用限制。企業版用戶可享有更高的配額。

⚡

1,000 次/分鐘

請求速率限制

🌟

企業版專屬

API 整合功能

如需更高的請求配額或有其他整合需求，請聯絡我們洽談企業方案。

Quto API 開發者文件