출퇴근 상태 조회

설명

기준일자에 대한 사원의 출퇴근 체크 가능 상태 및 출퇴근 정보를 조회하기 위한 API입니다.

조회 API

사원의 출퇴근 가능상태 및 출퇴근 정보를 조회한다.

요청 URL

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

요청 헤더

헤더명 설명
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 > 기본 설정 > 연동키

요청 파라미터

파라미터 타입 크기 필수 여부 설명
emailId String 100 N 워크플레이스에 등록된 조회대상자 이메일 ID(이메일/외부키 중 하나는 필수)
empExternalKey String 100 N 워크플레이스에 등록된 조회대상자 매핑 키(이메일/외부키 중 하나는 필수)
basicYmd String 8 N 기준일자(입력하지 않으면 현재시각 기준 상태조회)
locale String 10 N 로캘(입력하지 않으면 회사 기본 로캘)

요청 예시

GET https://workplace.apigw.ntruss.com/v1/company/e721e2da-29ee-4782-9672-3d2b150ac1a6/timeclock/check?emailId=admin@abcd.com

GET /timeclock/apigw/v1/company/5b8530ef-75fb-4bd1-aed4-7bba5a3f9c75/timeclock/check
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=

응답 파라미터

파라미터 타입 크기 필수 여부 설명
success String 36 Y 회사 ID
resultCode String 100 N 사용자 이메일(이메일/외부키 중 하나는 필수)
message String 100 N 사용자 확인키(이메일/외부키 중 하나는 필수)
data List N 로캘(입력하지 않으면 회사 기본 로캘)
basicYmd > String 8 Y 출근기준일
workType > String 20 Y 근무상태(출근전(init, 출근가능 상태),출근(on, 출근이 완료된 상태), 퇴근(off, 퇴근이 완료된 상태), 출퇴근불가-휴일(holiday, 근무결과신청가능),출퇴근불가-퇴근시간이후출근/과거/미래일자인 경우로 현재 시점 출퇴근 체크가 불가한 상태(impossible, 근무결과신청가능),출퇴근불가-지정된근무방식없음(none),출퇴근불가-근무시작예정(plan))
errMsg > String 1000 N
poupUrl > String 200 N 근무상태가 출근불가(휴일,퇴근시간이후출근)인 경우 근무 결과 신청서를 작성해야 한다.
onYmdhm > String 12 N 근무 상태가 출근,퇴근인 경우 값 있음
offYmdhm > String 12 N 근무 상태가 퇴근인 경우 값 있음
breakList > List N 근무설정 외 추가휴게시간 리스트
startYmdhm >> String 12 휴게시작시각
endYmdhm >> String 12 휴게종료시각
outWorkList > List N 외근시간 리스트
startYmdhm >> String 12 외근시작시각
endYmdhm >> String 12 외근종료시각
absenceList > List N 부재리스트
absenceName >> String 100 부재명
absenceExternalKey >> String 100 부재 외부키
absenceTime >> String 100 부재시간

응답 예시 (정상)

{
  "success": true,
  "resultCode": "200 OK",
  "message": null,
  "messageCode": null,
  "data": {
    "basicYmd": "20191212",
    "workType": "on",
    "errMsg": null,
    "popupUrl": null,
    "onYmdhms": "201912120919",
    "offYmdhms": null,
    "checkWay": "twiceAday",
    "breakList": [
      {
        "startYmdhm": "201912121200",
        "endYmdhm": "201912121300"
      }
    ],
    "outWorkList": [
      {
        "startYmdhm": "201912121500",
        "endYmdhm": "201912121600"
      },
      {
        "startYmdhm": "201912121900",
        "endYmdhm": "201912121930"
      }
    ],
    "absenceList": []
  }
}

응답 예시 (오류)

{
  "success": false,
  "resultCode": "9057",
  "message": "사용자 정보를 확인 할 수 없습니다.",
  "messageCode": null,
  "data": {}
}

응답

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

HTTP 상태 코드 응답 메시지 설명
200 OK 일반적인 요청 성공
400 Bad Request 일반적인 요청 실패에 사용(대체로 서버가 이해할 수 없는 형식의 요청이 왔을 때 응답하기 위해 사용)
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 시스템 오류 (일시적인 오류로 요청하신 작업을 수행하지 못했습니다)