# 刷卡資料介接
用於接收由門禁、打卡鐘等外部系統傳來的打卡資料，包括：打卡資料寫入。
## 取得打卡匯入範本
> \`\`\`\
> salary\_item = {\
> "CO\_ID": number, //公司\_ID\
> "CLOCK\_FORMAT\_ID": number, //刷卡鐘代號\_ID\
> "FORMAT\_NAME": string, //格式名稱\
> "FORMAT\_TYPE": string, //資料接收格式 1:純文字檔(.txt,.csv,.dat) 2:Office Excel(.xls,.xlsx)\
> },\
> \`\`\`
````json
{"openapi":"3.0.0","tags":[{"name":"刷卡資料介接","description":"用於接收由門禁、打卡鐘等外部系統傳來的打卡資料，包括：打卡資料寫入。"}],"servers":[{"url":"https://104demotest-api-server.hrmax.104.com.tw"}],"security":[{"bearerAuth":[]}],"components":{"securitySchemes":{"bearerAuth":{"type":"http","scheme":"bearer","bearerFormat":"JWT"}},"responses":{"401":{"description":"認證失敗 (請更新 accessToken 再試一次)"},"403":{"description":"權限不足"},"440":{"description":"參數錯誤 (請檢查 parameters 或 request body 的欄位、格式是否完整及正確)"},"499":{"description":"DB錯誤 `{ code: 499, msg: string }`"},"500":{"description":"系統異常 `{ code: 500, msg: string }`"}}},"paths":{"/api/am/clock/format":{"post":{"tags":["刷卡資料介接"],"summary":"取得打卡匯入範本","description":"```\nsalary_item = {\n \"CO_ID\": number, //公司_ID\n \"CLOCK_FORMAT_ID\": number, //刷卡鐘代號_ID\n \"FORMAT_NAME\": string, //格式名稱\n \"FORMAT_TYPE\": string, //資料接收格式 1:純文字檔(.txt,.csv,.dat) 2:Office Excel(.xls,.xlsx)\n},\n```\n","responses":{"200":{"description":"成功\n```\n{\n code: 200,\n data: [clock, clock, ...],\n}\n```\n"},"401":{"$ref":"#/components/responses/401"},"403":{"$ref":"#/components/responses/403"},"440":{"$ref":"#/components/responses/440"},"490":{"description":"失敗\n```\n{\n code: 490,\n msg: string, // 失敗原因\n}\n```\n"},"499":{"$ref":"#/components/responses/499"},"500":{"$ref":"#/components/responses/500"}}}}}}
````
## 打卡資料寫入
> \`\`\`\
> code, //回傳訊息代號\
> msg: string, //回傳訊息\
> \`\`\`
````json
{"openapi":"3.0.0","tags":[{"name":"刷卡資料介接","description":"用於接收由門禁、打卡鐘等外部系統傳來的打卡資料，包括：打卡資料寫入。"}],"servers":[{"url":"https://104demotest-api-server.hrmax.104.com.tw"}],"security":[{"bearerAuth":[]}],"components":{"securitySchemes":{"bearerAuth":{"type":"http","scheme":"bearer","bearerFormat":"JWT"}},"responses":{"401":{"description":"認證失敗 (請更新 accessToken 再試一次)"},"403":{"description":"權限不足"},"440":{"description":"參數錯誤 (請檢查 parameters 或 request body 的欄位、格式是否完整及正確)"},"499":{"description":"DB錯誤 `{ code: 499, msg: string }`"},"500":{"description":"系統異常 `{ code: 500, msg: string }`"}}},"paths":{"/api/am/clock/insert":{"post":{"tags":["刷卡資料介接"],"summary":"打卡資料寫入","description":"```\ncode, //回傳訊息代號\nmsg: string, //回傳訊息\n```\n","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["CO_ID","EMP_ID","CARD_DATETIME","CARD_TYPE","TEMP_UNIT","TEMP_VALUE"],"properties":{"CO_ID":{"type":"integer","description":"公司ID"},"EMP_ID":{"type":"integer","description":"員工ID"},"CARD_DATETIME":{"type":["string","date"],"description":"打卡時間"},"CARD_TYPE":{"type":"integer","description":"打卡別"},"TEMP_UNIT":{"type":"string","description":"體溫單位"},"TEMP_VALUE":{"type":"double","description":"體溫值"}}}}}},"responses":{"200":{"description":"成功\n```\n{\n code: 200\n}\n```\n"},"401":{"$ref":"#/components/responses/401"},"403":{"$ref":"#/components/responses/403"},"440":{"$ref":"#/components/responses/440"},"490":{"description":"失敗\n```\n{\n code: 490,\n msg: string, // 失敗原因\n}\n```\n"},"491":{"description":"失敗\n```\n{\n code: 491,\n msg: 打卡時間重複\n}\n```\n"},"499":{"$ref":"#/components/responses/499"},"500":{"$ref":"#/components/responses/500"}}}}}}
````
## 批次打卡資料寫入
> 回傳格式：\
> \`\`\`\
> // responses\
> {\
> "code": number \
> "data": {\
> "success": number, //成功筆數\
> "fail": number, //失敗筆數\
> "errorData": \[row, row\...] //失敗資料 \
> }\
> }\
> // 解析資料結果範例 錯誤為object\
> row = {\
> "rowIndex": number, //資料行數\
> "year": 2023, //年\
> "month": 8, //月\
> "day": 2, //日\
> "hour": 8, //時\
> "min": 8, //分\
> "sec": 0, //秒\
> "date": "2023/08/02", //日期\
> "time": "08:08:00", //時間\
> "clock": "002", //卡鐘\
> "empNo": { //員工編號\
> "key": "empNo",\
> "value": "D001",\
> "invalid": "無此員工編號"\
> },\
> }\
> // 錯誤 object\
> err = {\
> "key": string, //錯誤項目\
> "value": string, //取得值\
> "invalid": string //錯誤訊息\
> }\
> \`\`\`
````json
{"openapi":"3.0.0","tags":[{"name":"刷卡資料介接","description":"用於接收由門禁、打卡鐘等外部系統傳來的打卡資料，包括：打卡資料寫入。"}],"servers":[{"url":"https://104demotest-api-server.hrmax.104.com.tw"}],"security":[{"bearerAuth":[]}],"components":{"securitySchemes":{"bearerAuth":{"type":"http","scheme":"bearer","bearerFormat":"JWT"}},"responses":{"401":{"description":"認證失敗 (請更新 accessToken 再試一次)"},"403":{"description":"權限不足"},"440":{"description":"參數錯誤 (請檢查 parameters 或 request body 的欄位、格式是否完整及正確)"},"500":{"description":"系統異常 `{ code: 500, msg: string }`"}}},"paths":{"/api/am/clock/import":{"post":{"tags":["刷卡資料介接"],"summary":"批次打卡資料寫入","description":"回傳格式：\n```\n// responses\n{\n \"code\": number \n \"data\": {\n \"success\": number, //成功筆數\n \"fail\": number, //失敗筆數\n \"errorData\": [row, row...] //失敗資料 \n }\n}\n// 解析資料結果範例 錯誤為object\nrow = {\n \"rowIndex\": number, //資料行數\n \"year\": 2023, //年\n \"month\": 8, //月\n \"day\": 2, //日\n \"hour\": 8, //時\n \"min\": 8, //分\n \"sec\": 0, //秒\n \"date\": \"2023/08/02\", //日期\n \"time\": \"08:08:00\", //時間\n \"clock\": \"002\", //卡鐘\n \"empNo\": { //員工編號\n \"key\": \"empNo\",\n \"value\": \"D001\",\n \"invalid\": \"無此員工編號\"\n },\n}\n// 錯誤 object\nerr = {\n \"key\": string, //錯誤項目\n \"value\": string, //取得值\n \"invalid\": string //錯誤訊息\n}\n```\n","requestBody":{"require":true,"content":{"multipart/form-data":{"schema":{"type":"object","required":["CO_ID","CLOCK_FORMAT_ID","attachment"],"properties":{"CO_ID":{"type":"integer","description":"公司ID"},"CLOCK_FORMAT_ID":{"type":"integer","description":"刷卡鐘代號_ID"},"attachment":{"type":"string","format":"binary","description":"multipart request 的 field name 必須是 'attachment'"}}}}}},"responses":{"200":{"description":"成功"},"401":{"$ref":"#/components/responses/401"},"403":{"$ref":"#/components/responses/403"},"440":{"$ref":"#/components/responses/440"},"450":{"description":"MulterError `{ code: 450, msg?: string }`"},"500":{"$ref":"#/components/responses/500"}}}}}}
````