직원

직원의 출퇴근 기록과 근무시간 요약을 조회합니다.

출퇴근 기록 조회

GET

https://api.superplace.so

/workforce/v1/attendance/sessions

OAuth 2.0

출근과 퇴근 기록을 최신순으로 돌려줍니다. 매니저는 모든 직원의 기록을, 그 외 직원은 본인 기록만 볼 수 있습니다. 기록마다 상태(OPEN 근무 중, CLOSED 퇴근, VOIDED 무효), 근무 시간(durationSeconds, 초 단위), 정정 이력(adjustments)이 있습니다.

MCP 도구: workforce_get_attendance_sessions

출퇴근 기록 조회 › query Parameters

page

integer · min: 1

페이지 번호입니다. 1부터 시작합니다.

Default: 1

perPage

integer · min: 1 · max: 200

한 페이지에 담을 건수입니다. 생략하면 서버 기본값이 적용됩니다.

Default: 20

start

integer · min: 0

범위 조회의 시작 위치입니다. end와 함께 보내며, page·perPage를 함께 보내면 무시됩니다.

end

integer · min: 0

범위 조회의 끝 위치입니다. 이 값은 포함되지 않습니다. 한 번에 200건까지 조회할 수 있습니다.

sort

string · enum

정렬 기준입니다. startedAt(출근 시각)만 지원합니다.

Enum values:

startedAt

Default: startedAt

order

string · enum

정렬 방향입니다. asc는 오름차순, desc는 내림차순입니다.

Enum values:

asc

desc

Default: desc

filter

string

조건 JSON입니다. userId(직원), startedAt({"gte":…,"lte":…}), placeId를 쓸 수 있습니다.

출퇴근 기록 조회 › Responses

요청이 처리됐습니다. 결과는 data에 담겨 옵니다.

success

boolean

data

total

integer

근무시간 요약 조회

GET

https://api.superplace.so

/workforce/v1/reports/attendance

OAuth 2.0

기간의 직원별 근무시간을 요약합니다. 직원마다 총 경과 시간, 휴게 시간, 실근무 시간(workedSeconds), 근무 일수, 야간·휴일·연장 근무 시간이 초 단위로 담깁니다. from은 매장 시간대의 자정이어야 하고, 매장에 주 시작 요일이 정해져 있으면 그 요일이어야 합니다. 맞지 않으면 400입니다. 여러 주를 조회하면 from부터 7일 단위로 묶입니다.

MCP 도구: workforce_get_reports_attendance

근무시간 요약 조회 › query Parameters

from

string · date-time · required

조회 시작 시각입니다. 매장 시간대의 자정이어야 하고, 매장에 주 시작 요일이 있으면 그 요일이어야 합니다. 연장 근무가 주 단위 판정이라 어긋나면 400입니다.

to

string · date-time · required

조회 끝 시각입니다.

timezone

string · required

매장의 시간대입니다. 예: Asia/Seoul. 근무일 계산과 휴게 판정이 이 시간대로 이루어져 필수입니다.

userId

string[] · maxItems: 200

직원 ID입니다. 점주·매니저만 사용할 수 있고, 직원마다 파라미터를 반복해서 보냅니다.

requireClosed

boolean

근태 내보내기용 확인입니다. true이면 요청한 모든 직원의 해당 기간이 마감되어 있어야 합니다. 아니면 409이고 마감되지 않은 직원이 details에 담깁니다.

Default: false

filter

string

조건 JSON입니다. 조직 계정은 매장을 {"placeId":"…"}로 지정해야 합니다.

근무시간 요약 조회 › Responses

요청이 처리됐습니다. 결과는 data에 담겨 옵니다.

success

boolean

data

프로모션 기기