使用說明

透過 出勤打卡管理， 公司管理員 得以制定員工可進行打卡的特定範圍，以符合組織需求。此設定可包括 IP 範圍與 GPS 範圍，有效確保員工打卡記錄的精確性。同時，系統支援相關的記錄查詢功能，進一步提高管理效率。

應用情境¶

HR部門想要提高工作效率，於是決定將UOF X打卡資料整合到公司的HR系統中。他們委託資訊部門進行開發，很快就成功地實現了這一目標。現在，員工的打卡記錄可以輕鬆地在HR系統中查詢，大大簡化了計薪的流程。
公司的外勤人員經常需要在不同地點工作，因此想要將他們在 UOF X 打卡的資料也同步到既有的打卡系統內。資訊部門聽取了這個需求，通過對既有系統的升級，成功實現了外勤人員的打卡資料與內部系統的同步，使管理更加方便。

此程式範例包含¶

使用 Visual Studio 建立一個主控台應用程式 (Console App)，程式語言為 C#。依照實際需求，您也可以使用 WebApi、ClassLibrary 來完成外部起單，請參考系統需求篇的支援說明。

搜尋單一使用者打卡紀錄
搜尋指定部門人員的打卡紀錄

在繼續往下說明之前，請確認您下列事項皆已經準備完成:

透過 Visual Studio 建立一個新的主控台應用程式 (Console App)
已將專案透過 NuGet 安裝 SDK，並設定好 SDK 參數
已取得 UOF X 站台網址
已開啟打卡功能，以利進行打卡測試
已取得金鑰，使用 SDK 必須要有一組金鑰，UOF X 提供可針對不同的外部系統 (例: ERP、HR、CIM...)，各別開啟專屬的金鑰，並給予不同的參數設定，且可透過僅允許來自特定範圍的IP地址進行連接，以防止未授權的訪問，從而提高系統的安全性。請參照此篇文章取得金鑰。

為了方便測試，可以在出勤打卡管理中設定「新增出勤打卡規則」時，將 IP 範圍設至為「0.0.0.0/1,128.0.0.0/1」，允許任意 IP 進行打卡。也可自訂打卡範圍，將打卡規則設為 不限制。

範例程式下載: https://github.com/UOfficeForceX/SDK-Quickstart

開始寫程式...¶

以下為完整的範例內容

using Ede.Uofx.PubApi.Sdk.NetStd.Models.Eip; //<==== 加上新的 usting
using Ede.Uofx.PubApi.Sdk.NetStd.Service;

//設定金鑰
UofxService.Key = "xxx";

//設定 UOF X 站台網址
UofxService.UofxServerUrl = "https://myuofx.com.tw";

try
{
    //請求打卡紀錄的物件
    var punchModel = new UserPunchApiRequestModel
    {
        //公司代碼
        CorpCode = "ede",
        //起訖時間
        StartDate = DateTimeOffset.Now.AddDays(-1),
        EndDate = DateTimeOffset.Now,
        //打卡類型類型(0:全部,1:出勤,2:外出)
        QueryPunchHistoryType = 0,
        //查詢結果的時區
        TimeZoneId = "Taipei Standard Time",

        //人員資料類型(0:Account, 1:EmployeeNo)
        UserType = 0,
        //人員識別碼(依UserType填入對應值)
        UserCode = "admin"
    };

    //取得打卡紀錄
    var result = await UofxService.EIP.Punch.GetUserPunch(punchModel);
    Console.WriteLine(UofxService.Json.Convert(result));

    //請求部門人員打卡紀錄的物件
    var deptPunchModel = new DeptUserPunchApiRequestModel
    {
        //公司代碼
        CorpCode = "ede",
        //起訖時間
        StartDate = DateTimeOffset.Now.AddDays(-1),
        EndDate = DateTimeOffset.Now,
        //打卡類型類型(0:全部,1:出勤,2:外出)
        QueryPunchHistoryType = 0,
        //查詢結果的時區
        TimeZoneId = "Taipei Standard Time",

        //部門代號
        DeptCode = "demo",
        //是否包含子部門
        ContainChild = true
    };

    //取得部門人員打卡紀錄
    var deptResult = await UofxService.EIP.Punch.GetDeptUserPunch(deptPunchModel);
    Console.WriteLine(UofxService.Json.Convert(deptResult));
}
catch (Exception e)
{
    //將 exception 轉換成較容易判斷的 model
    var model = UofxService.Error.ConvertToModel(e);
    //將 model 轉成 json 格式印出
    Console.WriteLine(UofxService.Json.Convert(model));
}

使用方法¶

請先在appsettings.josn中設定好服務資訊，時區設定請參考 Default Time Zones 中的 Timezone 欄位：

{
"UofxServiceSettings": {
    "UofxServiceKey": "", //您的 UOF X 服務金鑰
    "UofxServiceUrl": "https://demoxdev.edetw.com/", //您的 UOF X 站台網址
    "TimeZoneId": "Taipei Standard Time" //您的時區
}
}

設定好打卡後，使用者打卡完畢，可以在首頁查詢自己的打卡紀錄。^1

範例程式中，UofxService.EIP.Punch.GetUserPunch 為取得個人的打卡紀錄：

//請求打卡紀錄的物件
var punchModel = new UserPunchApiRequestModel
{
    //公司代碼
    CorpCode = "ede",
    //起訖時間
    StartDate = DateTimeOffset.Now.AddDays(-1),
    EndDate = DateTimeOffset.Now,
    //打卡類型類型(0:全部,1:出勤,2:外出)
    QueryPunchHistoryType = 0,
    //查詢結果的時區
    TimeZoneId = TimeZoneId,

    //人員資料類型(0:Account/帳號, 1:EmployeeNo/員工編號)
    UserType = 0,
    //人員識別碼(依UserType填入對應值)
    UserCode = "admin"
};

var result = await UofxService.EIP.Punch.GetUserPunch(punchModel);

管理者也可以在管理者頁面依組織查詢打卡紀錄。^2

範例程式中，UofxService.EIP.Punch.GetDeptUserPunch 為取得指定組織下所有使用者的打卡紀錄：

//請求部門人員打卡紀錄的物件
var deptPunchModel = new DeptUserPunchApiRequestModel
{
    //公司代碼
    CorpCode = "ede",
    //起訖時間
    StartDate = DateTimeOffset.Now.AddDays(-1),
    EndDate = DateTimeOffset.Now,
    //打卡類型類型(0:全部,1:出勤,2:外出)
    QueryPunchHistoryType = 0,
    //查詢結果的時區
    TimeZoneId = TimeZoneId,

    //部門代號
    DeptCode = "demo",
    //是否包含子部門
    ContainChild = false
};

var deptResult = await UofxService.EIP.Punch.GetDeptUserPunch(deptPunchModel);

若您希望搜尋全公司的打卡資料，請將 DeptCode 設為空值，並將 ContainChild 設為 true。

以上兩種搜尋語法都會回傳 UserPunchInfoModel 集合，其中包含「公司代號、人員帳號、員工編號、打卡時間(轉換後的時區)、打卡類型(上班/下班)、打卡名稱」，您可視需求寫入到資料庫、外部系統或產出 Excel。

Note

若您的HR系統中需透過轉換才能與 UOF X 中的使用者代號對應，可以考慮透過取得全公司人員後，依人員搜尋打卡紀錄。如此一來，當該人員進行使用者代號對應出現錯誤時，就可以跳出迴圈，避免寫入多個因轉換異常的錯誤訊息。

例如：HR 系統 Max 需要先將 UOFX 中的人員帳號轉換為 Max 系統中的使用者 ID，這時先取得全公司人員用迴圈進行轉換，轉換成功後再利用 UofxService.EIP.Punch.GetUserPunch 取得該使用者的打卡紀錄。當有使用者 ID 轉換失敗時先寫入 Log 後跳過此人員，如採取 UofxService.EIP.Punch.GetDeptUserPunch 先取得打卡資料再轉換使用者 ID，將會出現多筆重複的轉換失敗 Log。