API 레퍼런스

통계

연결된 매장의 집계 지표다. 원시 데이터를 직접 집계하지 않아도 되도록 서버가 계산해 준다. 호출 1회가 여러 건으로 계산되므로 레이트리밋 가중치를 확인할 것.

GET /stats/labor GET /stats/hourly-distribution GET /stats/weekday-distribution GET /stats/attendance-quality GET /stats/staff GET /stats/schedule-adherence

근무시간·인건비 요약

GET /stats/labor attendance:read

기간 내 총 근무시간과 기본 인건비를 집계한다.

base_labor_cost 는 추정치다

주휴수당, 4대보험 사업자 부담분, 소득세, 야간·연장 가산액이 포함되지 않는다. 응답의 excludes 배열이 제외 항목을 알려준다.

쿼리 파라미터

이름	타입	설명
store_id 필수	string	매장 식별자
from 필수	date	조회 시작일 (YYYY-MM-DD, 매장 로컬 날짜)
to 필수	date	조회 종료일. to − from ≤ 30일 (양끝 포함 31일)
staff_id	string	특정 직원만 조회
granularity	enum	day \| week \| month. 기본 day

알아둘 것

야간·연장 근무는 시간으로만 집계된다. 금액 환산은 각자의 규칙으로 한다.

cURL

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

200 OK · application/json

{
  "store_id": "",
  "period": { "from": "", "to": "" },
  "granularity": "day",
  "currency": "KRW",
  "is_estimate": true,
  "excludes": ["holiday_allowance", "insurance", "tax", "premium_amounts"],
  "totals": {
    "work_minutes": 128400,
    "break_minutes": 14400,
    "base_labor_cost": 23112000,
    "night_work_minutes": 4800,
    "extended_work_minutes": 2100,
    "overtime_work_minutes": 0,
    "staff_count": 12,
    "record_count": 341
  },
  "series": [
    { "date": "", "work_minutes": 4320, "base_labor_cost": 777600, "staff_count": 9 }
  ]
}

에러 · application/json

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

시간대별 분포

GET /stats/hourly-distribution attendance:read

0~23시 각 시간대의 근무 인원과 근무시간을 집계한다. 시간대별 생산성 분석의 입력값이다.

쿼리 파라미터

이름	타입	설명
store_id 필수	string	매장 식별자
from 필수	date	조회 시작일 (YYYY-MM-DD, 매장 로컬 날짜)
to 필수	date	조회 종료일. to − from ≤ 30일 (양끝 포함 31일)
staff_id	string	특정 직원만 조회

알아둘 것

근무 구간이 시간 경계를 걸치면 분 단위로 쪼개 배분한다. 출근 시각만 세는 방식이 아니다.
avg_staff_on_duty 는 그 시간대에 근무 중이던 인원의 기간 평균이다.

cURL

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

200 OK · application/json

{
  "store_id": "",
  "period": { "from": "", "to": "" },
  "timezone": "Asia/Seoul",
  "buckets": [
    { "hour": 9, "work_minutes": 5400, "avg_staff_on_duty": 2.9, "peak_staff_on_duty": 5 }
  ]
}

에러 · application/json

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

요일별 분포

GET /stats/weekday-distribution attendance:read

요일별 근무시간·인원·인건비를 집계한다.

쿼리 파라미터

이름	타입	설명
store_id 필수	string	매장 식별자
from 필수	date	조회 시작일 (YYYY-MM-DD, 매장 로컬 날짜)
to 필수	date	조회 종료일. to − from ≤ 30일 (양끝 포함 31일)
staff_id	string	특정 직원만 조회

cURL

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

200 OK · application/json

{
  "store_id": "",
  "period": { "from": "", "to": "" },
  "buckets": [
    { "weekday": "mon", "work_minutes": 18600, "base_labor_cost": 3348000, "avg_staff_count": 4.2 }
  ]
}

에러 · application/json

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

근태 품질

GET /stats/attendance-quality attendance:read

지각·조퇴·대타·결근 건수와 비율을 집계한다.

judgment_available 을 반드시 확인할 것

false 면 그 매장은 스케줄 기능이 꺼져 있어 판정이 불가능하다. 이때 카운트는 0 이 아니라 null 로 온다. 0 으로 해석하면 "지각이 한 건도 없는 매장" 으로 잘못 읽게 된다.

쿼리 파라미터

이름	타입	설명
store_id 필수	string	매장 식별자
from 필수	date	조회 시작일 (YYYY-MM-DD, 매장 로컬 날짜)
to 필수	date	조회 종료일. to − from ≤ 30일 (양끝 포함 31일)
staff_id	string	특정 직원만 조회

cURL

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

200 OK · application/json

{
  "store_id": "",
  "period": { "from": "", "to": "" },
  "judgment_available": true,
  "totals": {
    "record_count": 341,
    "late_count": 22,
    "early_leave_count": 7,
    "substitute_count": 15,
    "no_show_count": 4,
    "late_rate": 0.0645,
    "avg_late_minutes": 8.3
  }
}

에러 · application/json

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

직원별 집계

GET /stats/staff attendance:read staff:read

직원별 근무시간·기본 인건비·근태 품질을 집계한다.

쿼리 파라미터

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

알아둘 것

인사평가 목적의 사용은 이용약관상 금지된다.

cURL

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

200 OK · application/json

{
  "store_id": "",
  "period": { "from": "", "to": "" },
  "data": [
    {
      "staff_id": "",
      "work_minutes": 10800,
      "break_minutes": 1200,
      "base_labor_cost": 1944000,
      "record_count": 22,
      "late_count": 3,
      "no_show_count": 0
    }
  ]
}

에러 · application/json

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

예정 대비 실제

v2 예정

GET /stats/schedule-adherence attendance:read schedules:read

예정 근무와 실제 근무의 차이를 매칭해 집계한다.

아직 제공되지 않는다

v2 에서 제공 예정이다. 그 전까지는 스케줄 API 와 근무 기록 API 를 각자 조인해 계산해야 하며, 야간 근무·대타 처리에서 값이 갈릴 수 있다.

쿼리 파라미터

이름	타입	설명
store_id 필수	string	매장 식별자
from 필수	date	조회 시작일 (YYYY-MM-DD, 매장 로컬 날짜)
to 필수	date	조회 종료일. to − from ≤ 30일 (양끝 포함 31일)
staff_id	string	특정 직원만 조회

cURL

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

200 OK · application/json

{
  "store_id": "",
  "period": { "from": "", "to": "" },
  "totals": {
    "planned_work_minutes": 124800,
    "actual_work_minutes": 128400,
    "variance_minutes": 3600,
    "no_show_count": 4,
    "unplanned_work_count": 15
  }
}

에러 · application/json

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

이전 급여 기초정보 다음 사용량