본문으로 건너뛰기
버전: 0.68.0

목표 기상 시각 설정 API

개요​

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

rTIB 처방 및 목표 설정 흐름​

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

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

제약사항​

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

목표 기상 시각 설정​

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

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

Headers​

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

Request Body​

{
  "targetAET": 1800,
  "targetDayIndex": 8
}
필드타입설명제약사항
targetAETnumber설정하고자 하는 목표 기상 분 (자정부터의 경과 분, Kotlin: Int, Swift: Int)
targetDayIndexnumber목표를 적용할 다음 일차 (현재 일차 + 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
}
필드타입설명
idstring수면 목표 고유 ID
targetDayIndexnumber목표가 적용되는 치료 주기 일차 (Kotlin: Int, Swift: Int)
targetLOTnumber계산된 목표 취침 시각 (Kotlin: Int, Swift: Int)
targetAETnumber설정된 목표 기상 시각 (Kotlin: Int, Swift: Int)
rTIBMinutesnumber권장 침대 시간 (분, rTIB 처방값 유지, Kotlin: Int, Swift: Int)
goalTypestring목표 유형 ("USER" - 사용자가 수정한 목표)
createdAtnumber최초 생성 시각 (Unix timestamp in milliseconds, Kotlin: Long, Swift: Int64)
updatedAtnumber마지막 수정 시각 (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일차부터 새로운 목표 시간이 적용되어 수면 기록 시 목표 달성 여부 평가에 활용
  • 데이터 활용:
    • 설정된 목표는 향후 수면 기록 입력 시 목표 달성 여부 계산에 사용됩니다.
    • 사용자 맞춤형 수면 패턴 개선을 위한 개인화된 치료 계획 수립에 활용됩니다.