시작하기

핵심 개념

기그의 데이터 모델은 일반적인 근태 시스템과 다른 점이 있습니다. 여기를 읽지 않으면 값을 잘못 해석하게 됩니다.

매장

매장 1개 = 사업자등록번호 1개 = 기그 사장님 계정 1개입니다. 본사가 직영점을 여러 개 운영하면 기그에 이미 계정이 나뉘어 있고, 그 집합이 그대로 매장 목록이 됩니다.

직원

직원은 매장과의 고용관계 단위입니다. 같은 사람이 두 매장에서 일하면 각 매장에서 별개의 직원으로 취급되고, staff_id 도 서로 다릅니다.

이는 의도된 설계입니다. 매장을 넘어 개인을 추적할 수 없도록 식별자를 분리합니다.

두 종류의 근무 데이터

가장 중요한 구분입니다. 기그에는 근무를 나타내는 데이터가 둘 있고, 용도가 다릅니다.

반대로 근무 행태 분석(지각·조퇴·대타, 실제 출퇴근 시각)은 출퇴근 기록으로 해야 합니다. 근무 기록에는 그 정보가 없습니다.

시급이 어디에 있는가

기그의 매장 설정에는 "시급제"라는 정산 유형이 없습니다. 매장 설정의 pay_cycle 은 unspecified · daily · weekly · monthly · custom 뿐입니다.

시급은 근무 기록 단위로만 드러납니다. 각 근무 항목에 그때 적용된 시급이 스냅샷으로 박혀 있어, 이후에 매장의 기본 시급이 바뀌어도 과거 기록은 변하지 않습니다. 소급 계산이 정확한 이유입니다.

"items": [
  {
    "start_at": "2026-08-14T09:00:00+09:00",
    "end_at":   "2026-08-14T18:00:00+09:00",
    "work_minutes": 480,
    "hourly_wage": 10800,   // ← 이 근무에 실제 적용된 시급
    "night_work": false
  }
]

스케줄

스케줄은 예정 근무입니다. 기그 내부에서는 반복 규칙으로 저장되지만, API 는 날짜별 인스턴스로 전개해서 돌려줍니다. 반복 규칙을 직접 해석할 필요가 없고, 해석해서도 안 됩니다 — "이 날만 수정" 같은 예외 처리가 서버 쪽에 있습니다.

• type: "day_off" 는 공휴일이 아니라 "그날 근무 없음" 표시입니다.
• 야간 근무는 planned_end_at 이 다음 날이 됩니다.
• 스케줄 기능을 쓰지 않는 매장은 빈 배열이 옵니다. 이때 지각·조퇴 판정도 불가능합니다.

식별자

store_id, staff_id, record_id 는 모두 불투명 문자열입니다. 내부 구조를 가정하지 마시고 그대로 저장해 쓰세요.

• 회원마다 값이 다릅니다. 다른 회원과 대조해 동일 대상을 판별할 수 없습니다.
• 같은 사람이라도 매장이 다르면 staff_id 가 다릅니다.
• 연결을 끊었다가 다시 연결해도 같은 값이 유지됩니다.