{
  "openapi": "3.0.3",
  "info": {
    "title": "OnTime Cloud Attendance Open API",
    "description": "OnTime 智慧辦公室打卡與出勤系統 Open API 規格契約",
    "version": "1.0.0"
  },
  "servers": [
    {
      "url": "https://asia-east1-ontime-tw-prod.cloudfunctions.net/api/v1",
      "description": "Production Cloud Functions Endpoint"
    }
  ],
  "paths": {
    "/employees": {
      "get": {
        "summary": "取得租戶員工名冊與考勤配置",
        "description": "查詢公司組織下所有在職員工、所屬部門與出勤薪資規則",
        "parameters": [
          {
            "name": "X-API-Key",
            "in": "header",
            "required": true,
            "schema": { "type": "string" }
          }
        ],
        "responses": {
          "200": {
            "description": "成功回傳員工清冊",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "status": { "type": "string", "example": "success" },
                    "employees": { "type": "array", "items": { "type": "object" } }
                  }
                }
              }
            }
          }
        }
      }
    },
    "/attendance": {
      "get": {
        "summary": "查詢考勤出勤紀錄",
        "description": "依日期區間與員工條件過濾打卡簽到、簽退時間與地點防偽資訊",
        "parameters": [
          { "name": "startDate", "in": "query", "schema": { "type": "string", "format": "date" } },
          { "name": "endDate", "in": "query", "schema": { "type": "string", "format": "date" } },
          { "name": "X-API-Key", "in": "header", "required": true, "schema": { "type": "string" } }
        ],
        "responses": {
          "200": {
            "description": "成功回傳出勤紀錄清單",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "status": { "type": "string", "example": "success" },
                    "records": { "type": "array", "items": { "type": "object" } }
                  }
                }
              }
            }
          }
        }
      }
    },
    "/monthly-report": {
      "get": {
        "summary": "取得月度工時、加班與遲到早退統計報表",
        "description": "產出符合勞基法規範之出勤工時統計，支援一鍵核發與薪資試算",
        "parameters": [
          { "name": "month", "in": "query", "required": true, "schema": { "type": "string", "example": "2026-10" } },
          { "name": "X-API-Key", "in": "header", "required": true, "schema": { "type": "string" } }
        ],
        "responses": {
          "200": { "description": "成功回傳月度報表" }
        }
      }
    },
    "/leaves": {
      "get": {
        "summary": "查詢請假紀錄與審核狀態",
        "parameters": [
          { "name": "status", "in": "query", "schema": { "type": "string", "enum": ["pending", "approved", "rejected"] } },
          { "name": "X-API-Key", "in": "header", "required": true, "schema": { "type": "string" } }
        ],
        "responses": {
          "200": { "description": "成功回傳請假列表" }
        }
      }
    }
  }
}
