출퇴근 내역 조회

설명

사원의 출퇴근 기록을 조회하기 위한 API입니다.

조회 API

출퇴근 기록을 조회한다.

요청 URL

GET https://workplace.apigw.ntruss.com/timeclock/apigw/v1/company/{companyId}/timeclock/hist

요청 헤더

헤더명 설명
x-ncp-apigw-timestamp 1970년 1월 1일 00:00:00 협정 세계시(UTC)부터의 경과 시간을 밀리초(Millisecond)로 나타내며
API Gateway 서버와 시간 차가 5분 이상 나는 경우 유효하지 않은 요청으로 간주

x-ncp-apigw-timestamp:{Timestamp}
x-ncp-apigw-api-key APIGW에서 발급받은 키 값
x-ncp-apigw-api-key:{API Gateway API Key}
x-ncp-iam-access-key 네이버 클라우드 플랫폼 포털에서 발급받은 Access Key ID 값
x-ncp-iam-access-key:{Account Access Key}
x-ncp-apigw-signature-v1 Access Key ID 값과 Secret Key로 암호화한 서명
x-ncp-apigw-signature-v1:{API Gateway Signature}

요청 Path 파라미터

파라미터 타입 크기 필수 여부 설명
companyId String 36 Y 연동키(CompanyId) Developers 기본 설정 연동키

요청 Body 파라미터

파라미터 타입 크기 필수 여부 설명
emailId String 100 N 워크플레이스에 등록된 조회 대상자 이메일 ID(이메일/외부키 모두 없을 경우 회사 전체 기록 조회)
empExternalKey String 100 N 워크플레이스에 등록된 조회 대상자 매핑 키(이메일/외부키 모두 없을 경우 회사 전체 기록 조회)
frBasicYmd String 8 Y 조회 시작 일자
toBasicYmd String 8 Y 조회 종료 일자
pageNo int 9 Y 조회 페이지 번호(모든 페이지 조회 시 0)
rowsPerPage int 9 Y 페이지당 조회 건수

요청 예시

GET https://workplace.apigw.ntruss.com/timeclock/apigw/v1/company//271c0b00-00c8-4f98-896b-f8c1b1213f07/timeclock/hist?pageNo=1&frBasicYmd=20191219&emailId=admin@abcd.com&toBasicYmd=20191219&rowsPerPage=3

GET /timeclock/apigw/v1/company/52e6e775-6993-424d-bc58-62e17268ed29/timeclock/hist
HOST: workplace.apigw.ntruss.com:443
x-ncp-apigw-timestamp:1521787414578
x-ncp-apigw-api-key:AKLJsfKIy12AJDW0Q2MxANdoiAZKxWwG3NOvT6aZ
x-ncp-iam-access-key:6uxz1nKkcYwUjWRG5Q1V7NsW0i5jErlu2NjBXXgy
x-ncp-apigw-signature-v1:iJFK773KH0WwQ79PasqJ+ZGixtpDQ/abS57WGQdld2M=

응답 파라미터

파라미터 타입 크기 필수 여부 설명
totalRows int 9 Y 총건수
pageNo int 9 Y 페이지 번호
list list 100 Y 데이터 list
empName string 5000 Y 사용자명
emailId string 100 N 사용자 이메일
empExternalKey string 100 N 사용자 매핑키
basicYmd string 8 Y 출근 기준일
onYmdhm string 12 Y 출근 시각
offYmdhm string 12 N 퇴근 시각
breakTime int 4 Y 휴게시간 (분)
outWorkTime int 4 Y 외근시간 (분)
absenceTime int 4 Y 부재시간 (분)
lateType string 20 Y 지각 구분
earlyType string 20 Y 조퇴 구분
dutyType string 20 Y 의무근로준수상태
generalTime int 9 Y 일반근로시간 (분)
extensionTime int 9 Y 연장근로시간 (분)
nightTime int 9 Y 야간근로시간 (분)
holGeneralTime int 9 Y 휴일일반근로시간 (분)
holExtensionTime int 9 Y 휴일연장근로시간 (분)
holNightTime int 9 Y 휴일야간근로시간 (분)
totalWorkTime int 9 Y 총근로시간 (분)

응답 예시

{
  "success": true,
  "resultCode": "200 OK",
  "message": null,
  "messageCode": null,
  "data": {
    "pageNo": 1,
    "totalRows": 3,
    "list": [
      {
        "empName": "(관리자",
        "emailId": "admin@abcd.com",
        "empExternalKey": "96b02530-82de-41c8-8223-3055c74e705e",
        "basicYmd": "20191125",
        "onYmdhm": "201911260026",
        "offYmdhm": "",
        "breakTime": "0",
        "outWorkTime": "0",
        "absenceTime": "480",
        "lateType": "X",
        "earlyType": "",
        "dutyType": "",
        "generalTime": "480",
        "extensionTime": "0",
        "nightTime": "0",
        "holGeneralTime": "0",
        "holExtensionTime": "0",
        "holNightTime": "0",
        "totalWorkTime": "480"
      },
      {
        "empName": "관리자",
        "emailId": "admin@abcd.com",
        "empExternalKey": "96b02530-82de-41c8-8223-3055c74e705e",
        "basicYmd": "20191126",
        "onYmdhm": "",
        "offYmdhm": "",
        "breakTime": "0",
        "outWorkTime": "0",
        "absenceTime": "480",
        "lateType": "",
        "earlyType": "",
        "dutyType": "",
        "generalTime": "480",
        "extensionTime": "0",
        "nightTime": "0",
        "holGeneralTime": "0",
        "holExtensionTime": "0",
        "holNightTime": "0",
        "totalWorkTime": "480"
      },
      {
        "empName": "관리자",
        "emailId": "admin@abcd.com",
        "empExternalKey": "96b02530-82de-41c8-8223-3055c74e705e",
        "basicYmd": "20191127",
        "onYmdhm": "201911271101",
        "offYmdhm": "201911271200",
        "breakTime": "0",
        "outWorkTime": "0",
        "absenceTime": "480",
        "lateType": "X",
        "earlyType": "X",
        "dutyType": "",
        "generalTime": "480",
        "extensionTime": "59",
        "nightTime": "0",
        "holGeneralTime": "0",
        "holExtensionTime": "0",
        "holNightTime": "0",
        "totalWorkTime": "539"
      }
    ]
  }
}

응답

HTTP 상태 코드로 리턴되고, Body 정보로 전달한다.

HTTP 상태 코드 응답 메시지 설명
200 OK 일반적인 요청 성공
400 Bad Request 일반적인 요청 실패에 사용(대체로 서버가 이해할 수 없는 형식의 요청이 왔을 때 응답하기 위해 사용)
401 Unauthorized 인증이 필요
403 Forbidden 서버요청거부
404 Not Found 요청한 페이지 찾을 수 없음
500 Internal Server Error 일반적인 서버 오류에 대한 응답 코드. 4XX대의 오류 코드가 클라이언트 측 오류를 나타내기 위해 사용된다면,
5XX대의 오류 코드는 서버 측 오류를 나타내기 위해 사용됩니다.

응답 상세

데이터 처리 중 입력 항목에 대한 정합성 체크 오류여부로 HTTP 상태코드 200과 함께 추가적인 항목으로 전달된다.

success(false)로 전달되고

resultCode message 설명
false 9001 외부근무 종료시간은 {0}까지 입력할 수 있습니다
false 9002 외부근무 시작시간은 {0}부터 입력할 수 있습니다
false 9003 퇴근시간은 출근시간 이후로 입력해주세요
false 9004 출근시간과 퇴근시간은 같은 시간으로 입력할 수 없습니다
false 9005 휴게시간은 겹치게 입력할 수 없습니다
false 9006 외부근무 시작시간과 종료시간을 동일한 시간으로 입력할 수 없습니다
false 9007 휴게 시작시간과 종료시간을 동일한 시간으로 입력할 수 없습니다
false 9008 {0} 이전으로 출근시간을 입력할 수 없습니다
false 9009 출근일자를 확인해주세요
false 9010 현재시간 이후로 퇴근시간을 입력할 수 없습니다
false 9011 퇴근일자를 확인해주세요
false 9012 외부근무시간을 포함하여 출퇴근시간을 24시간이상 입력할 수 없습니다
false 9013 연장가능시간을 초과했습니다
false 9014 외부근무시간을 입력해주세요
false 9015 출근시간을 입력해주세요
false 9016 퇴근시간을 입력해주세요
false 9017 휴게시간을 입력해주세요
false 9018 관리자에 의해 근로시간이 작성되어 수정할 수 없습니다
false 9019 사용자의 회사 정보를 확인하는데 실패했습니다
false 9020 사용자의 부서 정보를 확인하는데 실패했습니다
false 9021 사용자의 IP 정보를 확인할 수 없습니다
false 9022 사용자의 위치 정보를 확인할 수 없습니다
false 9023 사용자에게 지정된 근무방식을 찾을 수 없습니다
false 9024 의무근로미준수인 경우 퇴근 시각을 변경할 수 없습니다
false 9025 조퇴인 경우 퇴근 시각을 변경할 수 없습니다
false 9026 지각인 경우 출근 시각을 변경할 수 없습니다
false 9027 의무근로미준수인 경우 출근 시각을 변경할 수 없습니다
false 9028 현재 IP에서는 출퇴근 체크가 불가합니다
false 9029 현재 위치에서는 출퇴근 체크가 불가합니다
false 9030 퇴근 가능 시각이 아닙니다
false 9031 출근 가능 시각이 아닙니다
false 9032 해당 일자 근무기록이 마감되어 처리가 불가능합니다
false 9033 외부근무시간 형식이 잘못되었습니다
false 9034 출근시간 형식이 잘못되었습니다
false 9035 퇴근시간 형식이 잘못되었습니다
false 9036 휴게시간 형식이 잘못되었습니다
false 9037 휴게종료시간은 퇴근시간 이전으로 입력할 수 있습니다
false 9038 휴게시작시간은 출근시간 이후로 입력할 수 있습니다
false 9039 외부근무시간은 겹치게 입력할 수 없습니다
false 9040 근무설정 정보가 잘못되었습니다
false 9041 출근체크가 가능한 상태입니다
false 9042 퇴근체크가 가능한 상태입니다
false 9043 출퇴근체크가 가능한 상태입니다
false 9044 이미 출퇴근체크를 완료했습니다
false 9045 근무 시작 예정입니다
false 9046 근로 시간이 종료되었습니다
false 9047 근로일이 아닙니다
false 9048 지정된 근무 방식이 없습니다
false 9049 테넌트 아이디가 입력되지 않았습니다
false 9050 회사 아이디가 입력되지 않았습니다
false 9051 사번이 입력되지 않았습니다
false 9052 출퇴근 체크 구분이 입력되지 않았습니다
false 9053 기준일자가 입력되지 않았습니다
false 9054 외부근무시간을 입력 할 수 없습니다
false 9055 추가 휴게 시간을 입력 할 수 없습니다
false 9056 출퇴근 체크 가능 기준일이 아닙니다
false 9057 사용자 정보를 확인 할 수 없습니다
false 9058 페이지 정보를 확인해 주세요
false 9059 사용자 정보를 확인 할 수 없습니다.
false 9060 퇴근 일시를 확인해 주세요.
false 9061 출근 일시를 확인해 주세요.
false 9062 기준 시작일은 종료일 이전 이어야 합니다.
false 9063 외근 종료 시각은 외근 시작 시각 이전일 수 없습니다.
false 9064 휴게 종료 시각은 휴게 시작 시각 이전일 수 없습니다.
false 9065 출근 체크가 불가능한 일자입니다.
false 9066 휴게종료시간은 {0}까지 입력할 수 있습니다.
false 9999 시스템 오류 (일시적인 오류로 요청하신 작업을 수행하지 못했습니다)