버전: 개발 버전 (최신)

목표 기상 시각 설정 API

개요

목표 기상 시각 설정 API는 사용자가 rTIB(Recommended Time In Bed) 처방을 받은 당일에 다음 일차의 목표 기상 시각을 설정하는 기능을 제공합니다. 이 API를 통해 사용자는 개인의 생활 패턴에 맞게 목표 기상 시각을 조정할 수 있으며, 시스템은 설정된 기상 시각과 rTIB를 기반으로 목표 취침 시각을 자동으로 계산합니다.

rTIB 처방 및 목표 설정 흐름

rTIB 처방과 목표 기상 시각 설정은 다음과 같은 흐름으로 이루어집니다:

rTIB 처방: 사용자가 7일차에 수면 기록을 작성하면, 최소 4개 이상의 유효한 수면 기록이 확보된 경우 즉시 rTIB가 계산됩니다.
목표 설정 기회: 7일차(rTIB 처방일)에 이 API를 사용하여 8일차의 목표 기상 시각을 설정할 수 있습니다.
목표 적용: 설정된 목표는 8일차부터 적용되며, 목표 취침 시각은 자동으로 계산됩니다.

제약사항

일차 제한: 현재 일차 + 1에 해당하는 목표만 설정 가능합니다.

목표 기상 시각 설정

rTIB 처방일에 다음 일차의 목표 기상 시각을 설정합니다.

HTTP Method: PATCH
Path: /v1/sleep/goals/target-wake-time
인증: 액세스 토큰 (accessToken) 필요

Headers

Header	Type	Description	Required
`Content-Type`	`application/json`	요청 본문 형식을 지정합니다.	Yes
`Authorization`	`Bearer {accessToken}`	사용자 인증을 통해 발급받은 액세스 토큰입니다.	Yes
`Accept-Language`	`de-DE`, `en-US`, `ko-KR`	오류 메시지의 언어를 지정합니다. 지역 코드를 포함한 형식(예: de-DE, en-US, ko-KR)만 지원합니다.	No

Request Body

{
  "targetAET": 1800,
  "targetDayIndex": 8
}

필드	타입	설명	제약사항
`targetAET`	number	설정하고자 하는 목표 기상 분 (자정부터의 경과 분, Kotlin: `Int`, Swift: `Int`)
`targetDayIndex`	number	목표를 적용할 다음 일차 (현재 일차 + 1, Kotlin: `Int`, Swift: `Int`)	양의 정수, 현재 일차의 다음 일차여야 함

참고:

targetDayIndex: 현재 일차에서 rTIB 처방을 받은 경우, 다음 일차(현재 일차 + 1)의 목표만 설정 가능

targetAET: 24시간 형식으로 입력하며, 분 단위까지 설정 가능

Responses

HTTP Status Code	설명	Error Code(s)
`200 OK`	성공	-
`400 Bad Request`	잘못된 요청 (rTIB 처방일이 아니거나 목표 일차 불일치)	`10016`
`404 Not Found`	리소스 없음 (수면 목표 또는 rTIB 추천 정보 없음)	`10041`
`500 Internal Server Error`	서버 내부 오류	`10000`

200 OK - 성공

목표 기상 시각 설정 성공:

{
  "id": "sg_12345",
  "targetDayIndex": 8,
  "targetLOT": 1715385000000,
  "targetAET": 1715412600000,
  "rTIBMinutes": 480,
  "goalType": "USER",
  "createdAt": 1715225400000,
  "updatedAt": 1715315400000
}

필드	타입	설명
`id`	string	수면 목표 고유 ID
`targetDayIndex`	number	목표가 적용되는 치료 주기 일차 (Kotlin: `Int`, Swift: `Int`)
`targetLOT`	number	계산된 목표 취침 시각 (Kotlin: `Int`, Swift: `Int`)
`targetAET`	number	설정된 목표 기상 시각 (Kotlin: `Int`, Swift: `Int`)
`rTIBMinutes`	number	권장 침대 시간 (분, rTIB 처방값 유지, Kotlin: `Int`, Swift: `Int`)
`goalType`	string	목표 유형 ("USER" - 사용자가 수정한 목표)
`createdAt`	number	최초 생성 시각 (Unix timestamp in milliseconds, Kotlin: `Long`, Swift: `Int64`)
`updatedAt`	number	마지막 수정 시각 (Unix timestamp in milliseconds, Kotlin: `Long`, Swift: `Int64`)

중요:

targetLOT는 targetAET - rTIBMinutes로 자동 계산됩니다.

goalType이 "USER"로 변경되어 사용자가 수정한 목표임을 나타냅니다.

400 Bad Request - 잘못된 요청

예시 1: 일차 불일치 (TARGET_WAKE_TIME_CHANGE_NOT_ALLOWED - 10016)

{
  "code": 10016,
  "message": "TARGET_WAKE_TIME_CHANGE_NOT_ALLOWED",
  "detail": "목표 기상 시각 변경이 허용되지 않습니다",
  "metadata": {
    "userId": "user_123",
    "currentDayIndex": 7,
    "targetDayIndex": 9,
    "reason": "rTIB 처방을 받은 당일에만 다음 일차를 위해 설정할 수 있습니다."
  }
}

예시 2: rTIB 처방이 아닌 수면 목표 (TARGET_WAKE_TIME_CHANGE_NOT_ALLOWED - 10016)

{
  "code": 10016,
  "message": "TARGET_WAKE_TIME_CHANGE_NOT_ALLOWED",
  "detail": "목표 기상 시각 변경이 허용되지 않습니다",
  "metadata": {
    "userId": "user_123",
    "currentDayIndex": 7,
    "targetDayIndex": 8,
    "reason": "rTIB 처방 받은 수면 목표만 변경할 수 있습니다."
  }
}

404 Not Found - 리소스 없음

예시: 수면 목표 없음 (SLEEP_GOAL_NOT_FOUND - 10041)

{
  "code": 10041,
  "message": "SLEEP_GOAL_NOT_FOUND",
  "detail": "목표 기상 시각을 설정할 수면 목표가 없습니다.",
  "metadata": {
    "userId": "user_12345",
    "targetDayIndex": 8
  }
}

500 Internal Server Error - 서버 내부 오류

예시: 일반 서버 오류 (SERVER_ERROR - 10000)

{
  "code": 10000,
  "message": "SERVER_ERROR",
  "detail": "서버 내부 오류가 발생했습니다."
}

설명

이 API는 사용자가 rTIB 처방을 받은 당일에 개인의 생활 패턴에 맞게 목표 기상 시각을 조정할 수 있게 해줍니다.
목표 기상 시각이 설정되면, 시스템은 rTIB 값을 유지하면서 목표 취침 시각을 자동으로 재계산합니다.
사용 시나리오:
- 7일차에 rTIB 처방(예: 480분)을 받은 사용자가 8일차 목표 기상 시각을 "07:30"으로 설정
- 시스템은 목표 취침 시각을 "23:30"(07:30 - 8시간)으로 자동 계산
- 8일차부터 새로운 목표 시간이 적용되어 수면 기록 시 목표 달성 여부 평가에 활용
데이터 활용:
- 설정된 목표는 향후 수면 기록 입력 시 목표 달성 여부 계산에 사용됩니다.
- 사용자 맞춤형 수면 패턴 개선을 위한 개인화된 치료 계획 수립에 활용됩니다.

개요​

rTIB 처방 및 목표 설정 흐름​

제약사항​

목표 기상 시각 설정​

Headers​

Request Body​

Responses​

설명​

개요