{"openapi":"3.1.0","info":{"title":"기그 Open API","version":"1.0.0","description":"기그를 쓰는 매장의 근태·근무 데이터를 조회하고 통계를 받아가는 읽기 전용 API. 쓰기 작업은 제공하지 않는다.","contact":{"name":"기그 개발자 포털","url":"https://developer.openapi.giig.app"}},"servers":[{"url":"https://developer.openapi.giig.app/api/v1","description":"운영"},{"url":"https://developer.openapi.giig.app/api/sandbox/v1","description":"샌드박스"}],"tags":[{"name":"매장","description":"연결된 고용주 계정에 속한 매장을 조회한다. 매장 1개는 사업자등록번호 1개이며, 기그 사장님 계정 1개에 대응한다. 매장 목록은 연결(link)로 결정되므로 요청에 매장을 지정하지 않는다."},{"name":"직원","description":"매장에 소속된 직원과 고용 정보를 조회한다. 개인정보 보호를 위해 제공 항목을 엄격히 제한한다."},{"name":"출퇴근 기록","description":"직원이 실제로 찍은 출퇴근 세션이다. 지각·조퇴·대타 분석과 근무 행태 파악에 쓴다. 인건비 계산에는 근무 기록 API 를 써야 한다."},{"name":"근무 기록","description":"급여 정산에 실제로 반영되는 근무 기록이다. 적용된 시급이 스냅샷으로 남아 있어 소급 계산이 정확하다. 인건비 계산은 반드시 이 API 로 한다."},{"name":"근무 스케줄","description":"예정된 근무다. 반복 규칙은 서버가 날짜별 인스턴스로 전개해서 돌려주므로, 반복 규칙을 직접 해석할 필요가 없다."},{"name":"급여 기초정보","description":"급여 산정에 필요한 매장·직원 설정값이다. 계산 결과가 아니라 기초정보이며, 현재 설정값만 제공한다."},{"name":"통계","description":"연결된 매장의 집계 지표다. 원시 데이터를 직접 집계하지 않아도 되도록 서버가 계산해 준다. 호출 1회가 여러 건으로 계산되므로 레이트리밋 가중치를 확인할 것."},{"name":"사용량","description":"자신의 API 사용량을 조회한다. 스코프가 필요 없다."}],"security":[{"oauth2":[]}],"components":{"securitySchemes":{"oauth2":{"type":"oauth2","description":"client credentials 로 액세스 토큰을 발급받아 Bearer 로 보낸다.","flows":{"clientCredentials":{"tokenUrl":"https://developer.openapi.giig.app/oauth/token","scopes":{"stores:read":"매장 목록과 기본 정보","staff:read":"직원 목록과 고용 정보","attendance:read":"출퇴근 기록, 근무 기록, 통계","schedules:read":"근무 스케줄","payroll_basis:read":"급여 산정 기초정보"}}}}},"schemas":{"Error":{"type":"object","required":["error"],"properties":{"error":{"type":"object","required":["code","message"],"properties":{"code":{"type":"string","description":"기계가 분기할 값. message 가 아니라 이 값을 보고 처리한다.","examples":["range_too_large","store_not_found","rate_limited"]},"message":{"type":"string","description":"사람이 읽는 설명. 예고 없이 바뀐다. 파싱하지 않는다."},"request_id":{"type":"string","description":"문의 시 함께 알려주면 서버 로그를 특정할 수 있다."}}}}},"Page":{"type":"object","properties":{"data":{"type":"array","items":{"type":"object"}},"next_cursor":{"type":["string","null"],"description":"다음 페이지 커서. 불투명 값이므로 해석하지 않는다."},"has_more":{"type":"boolean"}}}}},"paths":{"/stores":{"get":{"operationId":"listStores","summary":"매장 목록","description":"연결된 매장 전체를 조회한다. 연결하지 않은 매장은 나타나지 않는다.\n\n**status 는 폐업을 반영하지 못한다** — 기그에 폐업 여부를 나타내는 필드가 없다. 폐업한 매장이 목록에 남을 수 있으므로, 최근 근무 기록 유무로 판단하는 편이 정확하다.","tags":["매장"],"parameters":[{"name":"limit","in":"query","required":false,"description":"페이지 크기. 기본 100","schema":{"type":"integer","format":"int32"}},{"name":"cursor","in":"query","required":false,"description":"다음 페이지 커서","schema":{"type":"string"}}],"security":[{"oauth2":["stores:read"]}],"responses":{"200":{"description":"성공","content":{"application/json":{"schema":{"type":"object"},"example":{"data":[{"store_id":"st_7Kq2","display_name":"○○치킨 강남점","business_number":"123-45-67890","store_type":"direct","status":"active","staff_count":12,"granted_scopes":["staff:read","attendance:read","schedules:read"],"linked_at":"2026-09-01T10:00:00+09:00"}],"next_cursor":null,"has_more":false}}}},"400":{"description":"에러","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"에러","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"에러","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"에러","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"에러","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/stores/{store_id}":{"get":{"operationId":"getStore","summary":"매장 단건","description":"매장 하나의 상세 정보를 조회한다.","tags":["매장"],"parameters":[{"name":"store_id","in":"path","required":true,"description":"매장 식별자","schema":{"type":"string"}}],"security":[{"oauth2":["stores:read"]}],"responses":{"200":{"description":"성공","content":{"application/json":{"schema":{"type":"object"},"example":{"store_id":"st_7Kq2","display_name":"○○치킨 강남점","business_number":"123-45-67890","store_type":"direct","status":"active","staff_count":12,"category":"한식","granted_scopes":["staff:read","attendance:read"],"linked_at":"2026-09-01T10:00:00+09:00"}}}},"400":{"description":"에러","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"에러","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"에러","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"에러","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"에러","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/stores/{store_id}/staff":{"get":{"operationId":"listStaff","summary":"직원 목록","description":"매장의 직원 목록과 고용 정보를 조회한다.\n\n**제공하지 않는 항목** — 주민등록번호·외국인등록번호, 계좌번호, 은행코드, 상세주소, 생년월일, 연락처는 어떤 스코프로도 제공하지 않는다.\n\n- \"아르바이트\"라는 고용형태 값은 존재하지 않는다. 기그의 실제 값은 없음·정규직·일용직·프리랜서·기타소득자 다섯 가지다.\n- weekly_contract_hours 는 정규직에만 원천 데이터가 존재한다. 그 외 고용형태는 null 이다.\n- 직원 식별자는 회원별·매장별로 다른 가명 값이다. 다른 매장의 staff_id 와 대조해 동일인을 판별할 수 없다.","tags":["직원"],"parameters":[{"name":"store_id","in":"path","required":true,"description":"매장 식별자","schema":{"type":"string"}},{"name":"include_left","in":"query","required":false,"description":"퇴사자 포함 여부. 기본 false","schema":{"type":"boolean"}},{"name":"limit","in":"query","required":false,"description":"페이지 크기","schema":{"type":"integer","format":"int32"}},{"name":"cursor","in":"query","required":false,"description":"다음 페이지 커서","schema":{"type":"string"}}],"security":[{"oauth2":["staff:read"]}],"responses":{"200":{"description":"성공","content":{"application/json":{"schema":{"type":"object"},"example":{"data":[{"staff_id":"sf_9Xb1","name":"김근무","employment_type":"full_time","joined_on":"2026-03-02","left_on":null,"status":"active","weekly_contract_hours":null,"position":"홀"}],"next_cursor":null,"has_more":false}}}},"400":{"description":"에러","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"에러","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"에러","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"에러","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"에러","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/attendance-records":{"get":{"operationId":"listAttendanceRecords","summary":"출퇴근 기록 목록","description":"기간 내 출퇴근 세션을 조회한다. 실근무시간과 휴게시간이 계산되어 함께 온다.\n\n**인건비를 이 API 로 계산하지 마시오** — 출퇴근을 찍지 않고 등록된 근무가 급여에는 반영된다. 이 API 만 쓰면 인건비가 과소 집계된다. 인건비는 근무 기록 API 로 계산한다.\n\n- status 가 open 인 세션은 clock_out_at 과 근무시간 필드가 모두 null 이다. 0 이 아니다.\n- 자정을 넘긴 야간 근무 중 아직 퇴근하지 않은 세션은 조회 기간 밖이어도 함께 반환된다.\n- judgment_available 이 false 면 flags 의 값을 신뢰하지 말 것. 판정 자체가 불가능한 매장이다.\n- 설정된 인정 근무시간을 넘긴 초과분은 근무로 인정되지 않으며, 응답값은 이미 잘린 값이다.","tags":["출퇴근 기록"],"parameters":[{"name":"store_id","in":"query","required":true,"description":"매장 식별자","schema":{"type":"string"}},{"name":"from","in":"query","required":true,"description":"조회 시작일 (YYYY-MM-DD, 매장 로컬 날짜)","schema":{"type":"string","format":"date","example":"2026-08-01"}},{"name":"to","in":"query","required":true,"description":"조회 종료일. to − from ≤ 30일 (양끝 포함 31일)","schema":{"type":"string","format":"date","example":"2026-08-01"}},{"name":"staff_id","in":"query","required":false,"description":"특정 직원만 조회","schema":{"type":"string"}},{"name":"updated_since","in":"query","required":false,"description":"이 시각 이후 변경된 것만. 삭제는 잡히지 않는다","schema":{"type":"string","format":"date-time","example":"2026-08-01T00:00:00+09:00"}},{"name":"limit","in":"query","required":false,"description":"페이지 크기. 기본 100, 최대 1000","schema":{"type":"integer","format":"int32"}},{"name":"cursor","in":"query","required":false,"description":"다음 페이지 커서. 응답의 next_cursor 를 그대로 넣는다","schema":{"type":"string"}}],"security":[{"oauth2":["attendance:read"]}],"responses":{"200":{"description":"성공","content":{"application/json":{"schema":{"type":"object"},"example":{"data":[{"record_id":"ar_3Fd8","store_id":"st_7Kq2","staff_id":"sf_9Xb1","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}}}},"400":{"description":"에러","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"에러","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"에러","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"에러","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"에러","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/attendance-records/{record_id}":{"get":{"operationId":"getAttendanceRecord","summary":"출퇴근 기록 단건","description":"휴게 구간별 내역을 포함한 상세를 조회한다.","tags":["출퇴근 기록"],"parameters":[{"name":"record_id","in":"path","required":true,"description":"기록 식별자","schema":{"type":"string"}}],"security":[{"oauth2":["attendance:read"]}],"responses":{"200":{"description":"성공","content":{"application/json":{"schema":{"type":"object"},"example":{"record_id":"ar_3Fd8","store_id":"st_7Kq2","staff_id":"sf_9Xb1","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"}}}},"400":{"description":"에러","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"에러","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"에러","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"에러","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"에러","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/work-records":{"get":{"operationId":"listWorkRecords","summary":"근무 기록 목록","description":"기간 내 근무 기록을 조회한다. 항목별 시급·근무시간·야간/연장 플래그를 포함한다.\n\n**인건비 계산의 기준** — 기본 인건비 = Σ(items[].hourly_wage × items[].work_minutes ÷ 60). 주휴수당·4대보험·세금·가산액은 포함되지 않는다.\n\n- hourly_wage 와 야간/연장/특근 플래그는 stamp_type 이 hourly 일 때만 존재한다. 다른 유형은 null 이다.\n- hourly_wage 는 스냅샷이므로 이후 매장의 기본 시급이 바뀌어도 과거 기록은 변하지 않는다. 소급 계산은 이 값을 쓴다.\n- source 가 manual 인 기록이 출퇴근 기록에는 없는 근무다. 인건비 차이의 원인이 여기에 있다.\n- 야간·연장·특근은 플래그일 뿐 금액이 아니다. 가산 금액은 저장되어 있지 않다.","tags":["근무 기록"],"parameters":[{"name":"store_id","in":"query","required":true,"description":"매장 식별자","schema":{"type":"string"}},{"name":"from","in":"query","required":true,"description":"조회 시작일 (YYYY-MM-DD, 매장 로컬 날짜)","schema":{"type":"string","format":"date","example":"2026-08-01"}},{"name":"to","in":"query","required":true,"description":"조회 종료일. to − from ≤ 30일 (양끝 포함 31일)","schema":{"type":"string","format":"date","example":"2026-08-01"}},{"name":"staff_id","in":"query","required":false,"description":"특정 직원만 조회","schema":{"type":"string"}},{"name":"updated_since","in":"query","required":false,"description":"이 시각 이후 변경된 것만. 삭제는 잡히지 않는다","schema":{"type":"string","format":"date-time","example":"2026-08-01T00:00:00+09:00"}},{"name":"limit","in":"query","required":false,"description":"페이지 크기. 기본 100, 최대 1000","schema":{"type":"integer","format":"int32"}},{"name":"cursor","in":"query","required":false,"description":"다음 페이지 커서. 응답의 next_cursor 를 그대로 넣는다","schema":{"type":"string"}}],"security":[{"oauth2":["attendance:read"]}],"responses":{"200":{"description":"성공","content":{"application/json":{"schema":{"type":"object"},"example":{"data":[{"work_record_id":"wr_5Tz3","store_id":"st_7Kq2","staff_id":"sf_9Xb1","work_date":"2026-08-14","stamp_type":"hourly","source":"attendance","items":[{"start_at":"2026-08-14T09:00:00+09:00","end_at":"2026-08-14T18:00:00+09:00","break_minutes":60,"work_minutes":480,"hourly_wage":10800,"night_work":false,"extended_work":false,"overtime_work":false}],"settled":true,"settled_at":"2026-09-01T03:00:00+09:00","updated_at":"2026-08-14T18:12:04+09:00"}],"next_cursor":null,"has_more":false}}}},"400":{"description":"에러","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"에러","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"에러","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"에러","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"에러","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/schedules":{"get":{"operationId":"listSchedules","summary":"스케줄 목록","description":"기간 내 예정 근무를 날짜별로 조회한다.\n\n- day_off 는 공휴일이 아니라 \"그날 근무 없음\" 표시다.\n- 야간 근무는 planned_end_at 이 다음 날이 된다.\n- 스케줄 기능을 쓰지 않는 매장은 빈 배열을 반환한다.","tags":["근무 스케줄"],"parameters":[{"name":"store_id","in":"query","required":true,"description":"매장 식별자","schema":{"type":"string"}},{"name":"from","in":"query","required":true,"description":"조회 시작일 (YYYY-MM-DD, 매장 로컬 날짜)","schema":{"type":"string","format":"date","example":"2026-08-01"}},{"name":"to","in":"query","required":true,"description":"조회 종료일. to − from ≤ 30일 (양끝 포함 31일)","schema":{"type":"string","format":"date","example":"2026-08-01"}},{"name":"staff_id","in":"query","required":false,"description":"특정 직원만 조회","schema":{"type":"string"}},{"name":"limit","in":"query","required":false,"description":"페이지 크기. 기본 100, 최대 1000","schema":{"type":"integer","format":"int32"}},{"name":"cursor","in":"query","required":false,"description":"다음 페이지 커서. 응답의 next_cursor 를 그대로 넣는다","schema":{"type":"string"}}],"security":[{"oauth2":["schedules:read"]}],"responses":{"200":{"description":"성공","content":{"application/json":{"schema":{"type":"object"},"example":{"data":[{"store_id":"st_7Kq2","staff_id":"sf_9Xb1","schedule_date":"2026-08-14","type":"work","planned_start_at":"2026-08-14T09:00:00+09:00","planned_end_at":"2026-08-14T18:00:00+09:00","planned_break_minutes":60,"planned_work_minutes":480,"source":"recurring","is_exception":false}],"next_cursor":null,"has_more":false}}}},"400":{"description":"에러","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"에러","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"에러","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"에러","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"에러","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/stores/{store_id}/payroll-basis":{"get":{"operationId":"getPayrollBasis","summary":"급여 기초정보","description":"매장 직원별 급여 설정을 조회한다.\n\n**소급 계산에 쓰지 마시오** — as_of 는 조회 시각이며, 시점별 급여 이력은 제공되지 않는다. 과거 기간의 인건비는 근무 기록의 hourly_wage 스냅샷으로 계산한다.\n\n- pay_cycle 에 \"시급\" 값이 없다. 기그의 매장 설정에는 시급이라는 정산 유형이 존재하지 않으며, 시급은 근무 기록 단위로만 드러난다.\n- 따라서 \"이 매장은 시급제다\" 를 매장 단위로 판단하지 말 것. 근무 기록의 stamp_type 을 보아야 한다.","tags":["급여 기초정보"],"parameters":[{"name":"store_id","in":"path","required":true,"description":"매장 식별자","schema":{"type":"string"}}],"security":[{"oauth2":["payroll_basis:read"]}],"responses":{"200":{"description":"성공","content":{"application/json":{"schema":{"type":"object"},"example":{"store_id":"st_7Kq2","as_of":"2026-09-02T14:00:00+09:00","currency":"KRW","staff":[{"staff_id":"sf_9Xb1","pay_cycle":"unspecified","base_amount":10800,"pay_day":10,"night_pay_enabled":true,"night_pay_multiplier":1.5,"overtime_pay_enabled":true,"overtime_pay_multiplier":1.5,"holiday_allowance_enabled":true,"weekly_contract_hours":null,"insurance":{"national_pension":true,"health":true,"employment":true,"industrial_accident":true},"income_tax_type":"simplified"}]}}}},"400":{"description":"에러","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"에러","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"에러","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"에러","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"에러","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/stats/labor":{"get":{"operationId":"statsLabor","summary":"근무시간·인건비 요약","description":"기간 내 총 근무시간과 기본 인건비를 집계한다.\n\n**base_labor_cost 는 추정치다** — 주휴수당, 4대보험 사업자 부담분, 소득세, 야간·연장 가산액이 포함되지 않는다. 응답의 excludes 배열이 제외 항목을 알려준다.\n\n- 야간·연장 근무는 시간으로만 집계된다. 금액 환산은 각자의 규칙으로 한다.","tags":["통계"],"parameters":[{"name":"store_id","in":"query","required":true,"description":"매장 식별자","schema":{"type":"string"}},{"name":"from","in":"query","required":true,"description":"조회 시작일 (YYYY-MM-DD, 매장 로컬 날짜)","schema":{"type":"string","format":"date","example":"2026-08-01"}},{"name":"to","in":"query","required":true,"description":"조회 종료일. to − from ≤ 30일 (양끝 포함 31일)","schema":{"type":"string","format":"date","example":"2026-08-01"}},{"name":"staff_id","in":"query","required":false,"description":"특정 직원만 조회","schema":{"type":"string"}},{"name":"granularity","in":"query","required":false,"description":"day | week | month. 기본 day","schema":{"type":"string"}}],"security":[{"oauth2":["attendance:read"]}],"responses":{"200":{"description":"성공","content":{"application/json":{"schema":{"type":"object"},"example":{"store_id":"st_7Kq2","period":{"from":"2026-08-01","to":"2026-08-31"},"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":"2026-08-01","work_minutes":4320,"base_labor_cost":777600,"staff_count":9}]}}}},"400":{"description":"에러","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"에러","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"에러","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"에러","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"에러","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/stats/hourly-distribution":{"get":{"operationId":"statsHourly","summary":"시간대별 분포","description":"0~23시 각 시간대의 근무 인원과 근무시간을 집계한다. 시간대별 생산성 분석의 입력값이다.\n\n- 근무 구간이 시간 경계를 걸치면 분 단위로 쪼개 배분한다. 출근 시각만 세는 방식이 아니다.\n- avg_staff_on_duty 는 그 시간대에 근무 중이던 인원의 기간 평균이다.","tags":["통계"],"parameters":[{"name":"store_id","in":"query","required":true,"description":"매장 식별자","schema":{"type":"string"}},{"name":"from","in":"query","required":true,"description":"조회 시작일 (YYYY-MM-DD, 매장 로컬 날짜)","schema":{"type":"string","format":"date","example":"2026-08-01"}},{"name":"to","in":"query","required":true,"description":"조회 종료일. to − from ≤ 30일 (양끝 포함 31일)","schema":{"type":"string","format":"date","example":"2026-08-01"}},{"name":"staff_id","in":"query","required":false,"description":"특정 직원만 조회","schema":{"type":"string"}}],"security":[{"oauth2":["attendance:read"]}],"responses":{"200":{"description":"성공","content":{"application/json":{"schema":{"type":"object"},"example":{"store_id":"st_7Kq2","period":{"from":"2026-08-01","to":"2026-08-31"},"timezone":"Asia/Seoul","buckets":[{"hour":9,"work_minutes":5400,"avg_staff_on_duty":2.9,"peak_staff_on_duty":5}]}}}},"400":{"description":"에러","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"에러","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"에러","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"에러","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"에러","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/stats/weekday-distribution":{"get":{"operationId":"statsWeekday","summary":"요일별 분포","description":"요일별 근무시간·인원·인건비를 집계한다.","tags":["통계"],"parameters":[{"name":"store_id","in":"query","required":true,"description":"매장 식별자","schema":{"type":"string"}},{"name":"from","in":"query","required":true,"description":"조회 시작일 (YYYY-MM-DD, 매장 로컬 날짜)","schema":{"type":"string","format":"date","example":"2026-08-01"}},{"name":"to","in":"query","required":true,"description":"조회 종료일. to − from ≤ 30일 (양끝 포함 31일)","schema":{"type":"string","format":"date","example":"2026-08-01"}},{"name":"staff_id","in":"query","required":false,"description":"특정 직원만 조회","schema":{"type":"string"}}],"security":[{"oauth2":["attendance:read"]}],"responses":{"200":{"description":"성공","content":{"application/json":{"schema":{"type":"object"},"example":{"store_id":"st_7Kq2","period":{"from":"2026-08-01","to":"2026-08-31"},"buckets":[{"weekday":"mon","work_minutes":18600,"base_labor_cost":3348000,"avg_staff_count":4.2}]}}}},"400":{"description":"에러","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"에러","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"에러","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"에러","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"에러","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/stats/attendance-quality":{"get":{"operationId":"statsQuality","summary":"근태 품질","description":"지각·조퇴·대타·결근 건수와 비율을 집계한다.\n\n**judgment_available 을 반드시 확인할 것** — false 면 그 매장은 스케줄 기능이 꺼져 있어 판정이 불가능하다. 이때 카운트는 0 이 아니라 null 로 온다. 0 으로 해석하면 \"지각이 한 건도 없는 매장\" 으로 잘못 읽게 된다.","tags":["통계"],"parameters":[{"name":"store_id","in":"query","required":true,"description":"매장 식별자","schema":{"type":"string"}},{"name":"from","in":"query","required":true,"description":"조회 시작일 (YYYY-MM-DD, 매장 로컬 날짜)","schema":{"type":"string","format":"date","example":"2026-08-01"}},{"name":"to","in":"query","required":true,"description":"조회 종료일. to − from ≤ 30일 (양끝 포함 31일)","schema":{"type":"string","format":"date","example":"2026-08-01"}},{"name":"staff_id","in":"query","required":false,"description":"특정 직원만 조회","schema":{"type":"string"}}],"security":[{"oauth2":["attendance:read"]}],"responses":{"200":{"description":"성공","content":{"application/json":{"schema":{"type":"object"},"example":{"store_id":"st_7Kq2","period":{"from":"2026-08-01","to":"2026-08-31"},"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}}}}},"400":{"description":"에러","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"에러","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"에러","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"에러","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"에러","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/stats/staff":{"get":{"operationId":"statsStaff","summary":"직원별 집계","description":"직원별 근무시간·기본 인건비·근태 품질을 집계한다.\n\n- 인사평가 목적의 사용은 이용약관상 금지된다.","tags":["통계"],"parameters":[{"name":"store_id","in":"query","required":true,"description":"매장 식별자","schema":{"type":"string"}},{"name":"from","in":"query","required":true,"description":"조회 시작일 (YYYY-MM-DD, 매장 로컬 날짜)","schema":{"type":"string","format":"date","example":"2026-08-01"}},{"name":"to","in":"query","required":true,"description":"조회 종료일. to − from ≤ 30일 (양끝 포함 31일)","schema":{"type":"string","format":"date","example":"2026-08-01"}},{"name":"staff_id","in":"query","required":false,"description":"특정 직원만 조회","schema":{"type":"string"}},{"name":"limit","in":"query","required":false,"description":"페이지 크기. 기본 100, 최대 1000","schema":{"type":"integer","format":"int32"}},{"name":"cursor","in":"query","required":false,"description":"다음 페이지 커서. 응답의 next_cursor 를 그대로 넣는다","schema":{"type":"string"}}],"security":[{"oauth2":["attendance:read","staff:read"]}],"responses":{"200":{"description":"성공","content":{"application/json":{"schema":{"type":"object"},"example":{"store_id":"st_7Kq2","period":{"from":"2026-08-01","to":"2026-08-31"},"data":[{"staff_id":"sf_9Xb1","work_minutes":10800,"break_minutes":1200,"base_labor_cost":1944000,"record_count":22,"late_count":3,"no_show_count":0}]}}}},"400":{"description":"에러","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"에러","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"에러","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"에러","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"에러","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/stats/schedule-adherence":{"get":{"operationId":"statsAdherence","summary":"예정 대비 실제","description":"예정 근무와 실제 근무의 차이를 매칭해 집계한다.\n\n**아직 제공되지 않는다** — v2 에서 제공 예정이다. 그 전까지는 스케줄 API 와 근무 기록 API 를 각자 조인해 계산해야 하며, 야간 근무·대타 처리에서 값이 갈릴 수 있다.","tags":["통계"],"parameters":[{"name":"store_id","in":"query","required":true,"description":"매장 식별자","schema":{"type":"string"}},{"name":"from","in":"query","required":true,"description":"조회 시작일 (YYYY-MM-DD, 매장 로컬 날짜)","schema":{"type":"string","format":"date","example":"2026-08-01"}},{"name":"to","in":"query","required":true,"description":"조회 종료일. to − from ≤ 30일 (양끝 포함 31일)","schema":{"type":"string","format":"date","example":"2026-08-01"}},{"name":"staff_id","in":"query","required":false,"description":"특정 직원만 조회","schema":{"type":"string"}}],"security":[{"oauth2":["attendance:read","schedules:read"]}],"responses":{"200":{"description":"성공","content":{"application/json":{"schema":{"type":"object"},"example":{"store_id":"st_7Kq2","period":{"from":"2026-08-01","to":"2026-08-31"},"totals":{"planned_work_minutes":124800,"actual_work_minutes":128400,"variance_minutes":3600,"no_show_count":4,"unplanned_work_count":15}}}}},"400":{"description":"에러","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"에러","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"에러","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"에러","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"에러","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"deprecated":false,"x-status":"planned"}},"/usage":{"get":{"operationId":"getUsage","summary":"사용량 조회","description":"기간별 호출 수와 응답 행 수를 조회한다.","tags":["사용량"],"parameters":[{"name":"from","in":"query","required":true,"description":"조회 시작일","schema":{"type":"string","format":"date","example":"2026-08-01"}},{"name":"to","in":"query","required":true,"description":"조회 종료일","schema":{"type":"string","format":"date","example":"2026-08-01"}},{"name":"group_by","in":"query","required":false,"description":"day | endpoint. 기본 day","schema":{"type":"string"}}],"security":[{}],"responses":{"200":{"description":"성공","content":{"application/json":{"schema":{"type":"object"},"example":{"period":{"from":"2026-08-01","to":"2026-08-31"},"totals":{"call_count":18422,"row_count":1204331,"error_count":12},"limits":{"requests_per_minute":60,"requests_per_day":10000,"rows_per_month":5000000,"linked_stores":{"used":3,"max":10}},"series":[{"date":"2026-08-01","call_count":612,"row_count":40122,"error_count":0}]}}}},"400":{"description":"에러","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"에러","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"에러","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"에러","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"에러","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}}}}