API 레퍼런스

출퇴근 기록

직원이 실제로 찍은 출퇴근 세션이다. 지각·조퇴·대타 분석과 근무 행태 파악에 쓴다. 인건비 계산에는 근무 기록 API 를 써야 한다.

GET /attendance-records GET /attendance-records/{record_id}

출퇴근 기록 목록

GET /attendance-records attendance:read

기간 내 출퇴근 세션을 조회한다. 실근무시간과 휴게시간이 계산되어 함께 온다.

인건비를 이 API 로 계산하지 마시오

출퇴근을 찍지 않고 등록된 근무가 급여에는 반영된다. 이 API 만 쓰면 인건비가 과소 집계된다. 인건비는 근무 기록 API 로 계산한다.

쿼리 파라미터

이름	타입	설명
store_id 필수	string	매장 식별자
from 필수	date	조회 시작일 (YYYY-MM-DD, 매장 로컬 날짜)
to 필수	date	조회 종료일. to − from ≤ 30일 (양끝 포함 31일)
staff_id	string	특정 직원만 조회
updated_since	datetime	이 시각 이후 변경된 것만. 삭제는 잡히지 않는다
limit	int	페이지 크기. 기본 100, 최대 1000
cursor	string	다음 페이지 커서. 응답의 next_cursor 를 그대로 넣는다

응답 필드

이름	타입	설명
total_attend_minutes	int	출근~퇴근 체류시간. 휴게 포함
break_minutes	int	휴게시간
net_work_minutes	int	체류 − 휴게. 실근무시간
status	enum	open(퇴근 전) \| closed
flags	object	지각·조퇴·대타 판정
judgment_available	bool	false 면 그 매장은 스케줄 기능이 꺼져 판정할 수 없다
check_method	enum	gps \| wifi \| qr \| manual

알아둘 것

status 가 open 인 세션은 clock_out_at 과 근무시간 필드가 모두 null 이다. 0 이 아니다.
자정을 넘긴 야간 근무 중 아직 퇴근하지 않은 세션은 조회 기간 밖이어도 함께 반환된다.
judgment_available 이 false 면 flags 의 값을 신뢰하지 말 것. 판정 자체가 불가능한 매장이다.
설정된 인정 근무시간을 넘긴 초과분은 근무로 인정되지 않으며, 응답값은 이미 잘린 값이다.

cURL

curl -sS "https://developer.openapi.giig.app/api/v1/attendance-records?store_id=&from=&to=" \
  -H "Authorization: Bearer $GIG_ACCESS_TOKEN"

200 OK · application/json

{
  "data": [
    {
      "record_id": "",
      "store_id": "",
      "staff_id": "",
      "work_date": "2026-08-14",
      "clock_in_at": "2026-08-14T09:03:00+09:00",
      "clock_out_at": "2026-08-14T18:12:00+09:00",
      "total_attend_minutes": 549,
      "break_minutes": 60,
      "net_work_minutes": 489,
      "status": "closed",
      "flags": { "late": true, "early_leave": false, "substitute": false },
      "judgment_available": true,
      "check_method": "gps",
      "updated_at": "2026-08-14T18:12:04+09:00"
    }
  ],
  "next_cursor": "eyJ0IjoiMjAyNi0wOC0xNCIsImkiOiJhciJ9",
  "has_more": true
}

에러 · application/json

{
  "error": {
    "code": "range_too_large",
    "message": "...",
    "request_id": "req_01J8XQ4M2N7P"
  }
}

출퇴근 기록 단건

GET /attendance-records/{record_id} attendance:read

휴게 구간별 내역을 포함한 상세를 조회한다.

경로 파라미터

이름	타입	설명
record_id 필수	string	기록 식별자

cURL

curl -sS "https://developer.openapi.giig.app/api/v1/attendance-records/" \
  -H "Authorization: Bearer $GIG_ACCESS_TOKEN"

200 OK · application/json

{
  "record_id": "",
  "store_id": "",
  "staff_id": "",
  "work_date": "2026-08-14",
  "clock_in_at": "2026-08-14T09:03:00+09:00",
  "clock_out_at": "2026-08-14T18:12:00+09:00",
  "total_attend_minutes": 549,
  "break_minutes": 60,
  "net_work_minutes": 489,
  "breaks": [
    { "start_at": "2026-08-14T12:30:00+09:00", "end_at": "2026-08-14T13:30:00+09:00" }
  ],
  "flags": { "late": true, "early_leave": false, "substitute": false },
  "judgment_available": true,
  "updated_at": "2026-08-14T18:12:04+09:00"
}

에러 · application/json

{
  "error": {
    "code": "store_not_found",
    "message": "...",
    "request_id": "req_01J8XQ4M2N7P"
  }
}

이전 직원 다음 근무 기록