본문으로 건너뛰기

endpoints

관련 문서​

Relaxation API 엔드포인트

Enum 정의​

RelaxationLevel​

  • BEGINNER: 초급자용
  • INTERMEDIATE: 중급자용
  • ADVANCED: 고급자용

RelaxationStress​

  • LOW: 낮은 스트레스용
  • MEDIUM: 보통 스트레스용
  • HIGH: 높은 스트레스용

RelaxationPose​

  • SITTING: 앉은 자세
  • LYING: 누운 자세
  • STANDING: 선 자세

목차​

관련 문서​

1. 엔드포인트 접근 권한 매트릭스​

엔드포인트시스템 관리자일반 사용자서비스 계정비고
GET /v1/relaxation/contents✓✓✓모든 콘텐츠 목록 조회
GET /v1/relaxation/contents/{id}✓✓✓콘텐츠 상세 조회
GET /v1/relaxation/categories✓✓✓카테고리 목록 조회
GET /v1/relaxation/categories/{id}/contents✓✓✓카테고리별 콘텐츠 조회
GET /v1/relaxation/bundles/version✓✓✓번들 버전 확인
GET /v1/relaxation/daily/content✓✓✓일일 추천 이완요법 조회
POST /v1/relaxation/contents/{id}/complete✓✓✓자신만
POST /v1/relaxation/history✓✓✓자신만
POST /v1/relaxation/history/batch✓✓✓자신만
POST /v1/relaxation/downloads/start✓✓✘다운로드 시작
PATCH /v1/relaxation/downloads/{id}/progress✓✓✘다운로드 진행률 업데이트
POST /v1/relaxation/downloads/{id}/pause✓✓✘다운로드 일시정지
POST /v1/relaxation/downloads/{id}/resume✓✓✘다운로드 재개
POST /v1/relaxation/downloads/{id}/complete✓✓✘다운로드 완료
GET /v1/relaxation/downloads/cached✓✓✓캐시된 콘텐츠 조회
DELETE /v1/relaxation/downloads/cache✓✓✘캐시 삭제

| GET /v1/relaxation/settings | ✓ | ✓ | ✓ | 사용자 설정 조회 | | PATCH /v1/relaxation/settings/repeat-mode | ✓ | ✓ | ✘ | 반복 모드 설정 | | PATCH /v1/relaxation/settings/preferred-category | ✓ | ✓ | ✘ | 선호 카테고리 설정 | | GET /v1/relaxation/guides/active | ✓ | ✓ | ✓ | 활성 가이드 조회 | | POST /v1/relaxation/guides/{id}/view | ✓ | ✓ | ✘ | 가이드 열람 기록 | | GET /v1/relaxation/bundles/{bundleId} | ✓ | ✓ | ✓ | 특정 번들 조회 (캐싱용) | | GET /v1/relaxation/bundles/latest | ✓ | ✓ | ✓ | 최신 번들 조회 | | GET /v1/relaxation/bundles/{bundleId}/download | ✓ | ✓ | ✓ | 번들 다운로드 | | POST /v1/relaxation/admin/contents | ✓ | ✘ | ✘ | 관리자만 콘텐츠 생성 가능 | | PATCH /v1/relaxation/admin/contents/{id} | ✓ | ✘ | ✘ | 관리자만 콘텐츠 수정 가능 | | DELETE /v1/relaxation/admin/contents/{id} | ✓ | ✘ | ✘ | 관리자만 콘텐츠 삭제 가능 | | POST /v1/relaxation/admin/bundles | ✓ | ✘ | ✘ | 관리자만 번들 생성 가능 | | POST /v1/relaxation/admin/bundles/{id}/activate | ✓ | ✘ | ✘ | 관리자만 번들 활성화 가능 |

참고:

  • ✓: 접근 가능
  • ✘: 접근 불가
  • 자신만: 자신의 데이터에만 접근 가능

2. 콘텐츠 관리 API​

2.1 콘텐츠 목록 조회​

  • HTTP 메서드: GET
  • 경로: /v1/relaxation/contents
  • Headers:
    • Authorization: Bearer {accessToken}
    • Accept-Language: de-DE (기본값), en-US, ko-KR
  • Query Parameters:
    • categoryId: 카테고리 ID 필터 (선택)
    • isActive: 활성 콘텐츠만 조회 (선택, 기본값: true)
    • page: 페이지 번호 (선택, 기본값: 1)
    • pageSize: 페이지 크기 (선택, 기본값: 10)

응답 (Response)​

  • 성공 응답 (200 OK)
{
  "items": [
    {
      "id": "rc_123",
      "categoryId": "cat_breathing",
      "bundleId": "bundle_v1",
      "backgroundImageUrl": "https://cdn.example.com/images/breathing_bg.jpg",
      "audioFileUrl": "https://cdn.example.com/audio/breathing_01.mp3",
      "duration": 600,
      "orderIndex": 1,
      "level": "BEGINNER",
      "stress": "LOW",
      "poses": ["SITTING", "LYING"],
      "isActive": true,
      "translation": {
        "language": "ko",
        "title": "복식호흡",
        "description": "깊고 차분한 호흡을 통해 긴장을 풀어보세요."
      },
      "category": {
        "id": "cat_breathing",
        "type": "BREATHING_THERAPY",
        "translation": {
          "language": "ko",
          "name": "호흡요법",
          "summary": "호흡을 통한 이완 기법"
        }
      },
      "createdAt": 1715600400000,
      "updatedAt": 1715600400000
    },
    {
      "id": "rc_124",
      "categoryId": "cat_autogenic",
      "bundleId": "bundle_v1",
      "backgroundImageUrl": "https://cdn.example.com/images/autogenic_bg.jpg",
      "audioFileUrl": "https://cdn.example.com/audio/autogenic_01.mp3",
      "duration": 900,
      "orderIndex": 1,
      "level": "INTERMEDIATE",
      "stress": "MEDIUM",
      "poses": ["LYING"],
      "isActive": true,
      "translation": {
        "language": "ko",
        "title": "아우토겐 트레이닝",
        "description": "자율훈련법을 통한 깊은 이완 상태 도달"
      },
      "category": {
        "id": "cat_autogenic",
        "type": "AUTOGENIC_TRAINING",
        "translation": {
          "language": "ko",
          "name": "아우토겐 트레이닝",
          "summary": "자율훈련법"
        }
      },
      "createdAt": 1715600400000,
      "updatedAt": 1715600400000
    }
  ],
  "metadata": {
    "totalCount": 15,
    "currentPage": 1,
    "pageSize": 10,
    "totalPages": 2
  }
}

2.2 콘텐츠 상세 조회​

  • HTTP 메서드: GET
  • 경로: /v1/relaxation/contents/{id}
  • Headers:
    • Authorization: Bearer {accessToken}
    • Accept-Language: de-DE (기본값), en-US, ko-KR

응답 (Response)​

  • 성공 응답 (200 OK)
{
  "id": "rc_123",
  "categoryId": "cat_breathing",
  "bundleId": "bundle_v1",
  "backgroundImageUrl": "https://cdn.example.com/images/breathing_bg.jpg",
  "audioFileUrl": "https://cdn.example.com/audio/breathing_01.mp3",
  "duration": 600,
  "orderIndex": 1,
  "isActive": true,
  "translation": {
    "language": "ko",
    "title": "복식호흡",
    "description": "깊고 차분한 호흡을 통해 긴장을 풀어보세요."
  },
  "category": {
    "id": "cat_breathing",
    "type": "BREATHING_THERAPY",
    "translation": {
      "language": "ko",
      "name": "호흡요법",
      "summary": "호흡을 통한 이완 기법"
    }
  },
  "detail": {
    "id": "cd_123",
    "version": 1,
    "translation": {
      "language": "ko",
      "purpose": "스트레스와 불안을 감소시키고 심신의 안정을 찾습니다.",
      "effects": "혈압 감소, 심박수 안정화, 스트레스 호르몬 감소",
      "mechanism": "깊은 복식호흡은 부교감신경계를 활성화시켜 이완 반응을 유도합니다.",
      "precautions": "호흡곤란이 있는 경우 의사와 상담 후 진행하세요."
    },
    "createdAt": 1715600400000,
    "updatedAt": 1715600400000
  },
  "createdAt": 1715600400000,
  "updatedAt": 1715600400000
}
  • 오류 응답 (404 Not Found)
{
  "code": 8010,
  "message": "CONTENT_NOT_FOUND",
  "detail": "요청한 콘텐츠를 찾을 수 없습니다."
}

2.3 카테고리 목록 조회​

  • HTTP 메서드: GET
  • 경로: /v1/relaxation/categories
  • Headers:
    • Authorization: Bearer {accessToken}
    • Accept-Language: de-DE (기본값), en-US, ko-KR
  • Query Parameters:
    • isActive: 활성 카테고리만 조회 (선택, 기본값: true)

응답 (Response)​

  • 성공 응답 (200 OK)
{
  "items": [
    {
      "id": "cat_breathing",
      "type": "BREATHING_THERAPY",
      "orderIndex": 1,
      "isActive": true,
      "translation": {
        "language": "ko",
        "name": "호흡요법",
        "summary": "호흡을 통한 이완 기법"
      },
      "contentCount": 3,
      "createdAt": 1715600400000,
      "updatedAt": 1715600400000
    },
    {
      "id": "cat_autogenic",
      "type": "AUTOGENIC_TRAINING",
      "orderIndex": 2,
      "isActive": true,
      "translation": {
        "language": "ko",
        "name": "아우토겐 트레이닝",
        "summary": "자율훈련법"
      },
      "contentCount": 2,
      "createdAt": 1715600400000,
      "updatedAt": 1715600400000
    },
    {
      "id": "cat_pmr",
      "type": "PROGRESSIVE_MUSCLE_RELAXATION",
      "orderIndex": 3,
      "isActive": true,
      "translation": {
        "language": "ko",
        "name": "점진적 근육이완",
        "summary": "근육의 긴장과 이완을 통한 이완법"
      },
      "contentCount": 4,
      "createdAt": 1715600400000,
      "updatedAt": 1715600400000
    },
    {
      "id": "cat_visualization",
      "type": "VISUALIZATION",
      "orderIndex": 4,
      "isActive": true,
      "translation": {
        "language": "ko",
        "name": "상상하기",
        "summary": "시각화를 통한 심리적 이완"
      },
      "contentCount": 3,
      "createdAt": 1715600400000,
      "updatedAt": 1715600400000
    },
    {
      "id": "cat_mindfulness",
      "type": "MINDFULNESS",
      "orderIndex": 5,
      "isActive": true,
      "translation": {
        "language": "ko",
        "name": "마음챙김",
        "summary": "현재 순간에 집중하는 명상법"
      },
      "contentCount": 3,
      "createdAt": 1715600400000,
      "updatedAt": 1715600400000
    }
  ],
  "metadata": {
    "totalCount": 5
  }
}

2.4 카테고리별 콘텐츠 조회​

  • HTTP 메서드: GET
  • 경로: /v1/relaxation/categories/{id}/contents
  • Headers:
    • Authorization: Bearer {accessToken}
    • Accept-Language: de-DE (기본값), en-US, ko-KR
  • Query Parameters:
    • isActive: 활성 콘텐츠만 조회 (선택, 기본값: true)

응답 (Response)​

  • 성공 응답 (200 OK)
{
  "category": {
    "id": "cat_breathing",
    "type": "BREATHING_THERAPY",
    "translation": {
      "language": "ko",
      "name": "호흡요법",
      "summary": "호흡을 통한 이완 기법"
    }
  },
  "contents": [
    {
      "id": "rc_123",
      "backgroundImageUrl": "https://cdn.example.com/images/breathing_bg.jpg",
      "audioFileUrl": "https://cdn.example.com/audio/breathing_01.mp3",
      "duration": 600,
      "orderIndex": 1,
      "translation": {
        "language": "ko",
        "title": "복식호흡",
        "description": "깊고 차분한 호흡을 통해 긴장을 풀어보세요."
      }
    },
    {
      "id": "rc_126",
      "backgroundImageUrl": "https://cdn.example.com/images/breathing_bg2.jpg",
      "audioFileUrl": "https://cdn.example.com/audio/breathing_02.mp3",
      "duration": 480,
      "orderIndex": 2,
      "translation": {
        "language": "ko",
        "title": "4-7-8 호흡법",
        "description": "4초 들이쉬고, 7초 멈추고, 8초 내쉬는 호흡법"
      }
    }
  ],
  "metadata": {
    "totalCount": 2
  }
}
  • 오류 응답 (404 Not Found)
{
  "code": 8011,
  "message": "CATEGORY_NOT_FOUND",
  "detail": "요청한 카테고리를 찾을 수 없습니다."
}

2.5 콘텐츠 번들 버전 확인​

  • HTTP 메서드: GET
  • 경로: /v1/relaxation/bundles/version
  • Headers:
    • Authorization: Bearer {accessToken}
  • Query Parameters:
    • clientVersion: 클라이언트의 현재 번들 버전 (선택)

응답 (Response)​

  • 성공 응답 (200 OK)
{
  "currentVersion": "1.2.0",
  "clientVersion": "1.1.0",
  "needsUpdate": true,
  "bundleId": "bundle_v1_2_0",
  "bundleName": "2025년 1월 콘텐츠 업데이트",
  "generatedAt": 1715690500000,
  "hash": "a1b2c3d4e5f6",
  "contentCount": 15,
  "totalSize": 524288000
}

3. 오늘의 추천 이완요법 API​

📌 클라이언트 구현: 이 API는 사용자 가입일을 기준으로 5일간만 추천 콘텐츠를 제공합니다.

3.1 일일 추천 콘텐츠 조회​

  • HTTP 메서드: GET
  • 경로: /v1/relaxation/daily/content
  • Headers:
    • Authorization: Bearer {accessToken}
    • Accept-Language: de-DE (기본값), en-US, ko-KR (필수)

기능 설명​

추천 정책:

  • 사용자 가입일로부터 5일간만 추천 콘텐츠를 제공합니다.
  • 일차별로 정해진 콘텐츠를 추천합니다:
    • 1일차: Bauchatmung (복식호흡)
    • 2일차: Sitzmeditation (앉아서 명상)
    • 3일차: PMR Hände und Arme (손과 팔 점진적 이완)
    • 4일차: Dein Strand (나만의 해변)
    • 5일차: Die Zitronenübung (레몬 연습)
  • 6일차 이후부터는 추천 섹션을 제공하지 않습니다.

일차 계산 방식:

  • 사용자 가입일(UTC 기준)을 1일차로 하여 현재 날짜까지의 차이로 계산
  • 시간대는 사용자 프로필의 timezoneId를 기준으로 처리

응답 (Response)​

  • 성공 응답 (200 OK) - 추천 기간 중 (1-5일차)
{
  "bundleId": "latest_budle_uuid_123jhr34h_bh54_1l239_dfnle34",
  "currentDayIndex": 1,
  "contentId": "content_uuid_134hdjf_irjk_sd_jfjrekek"
}
  • 성공 응답 (200 OK) - 추천 기간 만료 (6일차 이후)
{
  "bundleId": "latest_budle_uuid_123jhr34h_bh54_1l239_dfnle34",
  "currentDayIndex": 6
}

일차별 추천 콘텐츠 예시​

1일차 - Bauchatmung (복식호흡)

{
  "bundleId": "latest_budle_uuid_123jhr34h_bh54_1l239_dfnle34",
  "currentDayIndex": 1,
  "contentId": "category_01_content_01_uuid"
}

2일차 - Sitzmeditation (앉아서 명상)

{
  "bundleId": "latest_budle_uuid_123jhr34h_bh54_1l239_dfnle34",
  "currentDayIndex": 2,
  "contentId": "category_05_content_04_uuid"
}

3일차 - PMR Hände und Arme (손과 팔 점진적 이완)

{
  "bundleId": "latest_budle_uuid_123jhr34h_bh54_1l239_dfnle34",
  "currentDayIndex": 3,
  "contentId": "category_02_content_01_uuid"
}

4일차 - Dein Strand (나만의 해변)

{
  "bundleId": "latest_budle_uuid_123jhr34h_bh54_1l239_dfnle34",
  "currentDayIndex": 4,
  "contentId": "category_04_content_04_uuid"
}

5일차 - Die Zitronenübung (레몬 연습)

{
  "bundleId": "latest_budle_uuid_123jhr34h_bh54_1l239_dfnle34",
  "currentDayIndex": 5,
  "contentId": "category_03_content_01_uuid"
}
  • 오류 응답 (404 Not Found) - 사용자 상태 없음
{
  "code": 6044,
  "message": "USER_NOT_FOUND",
  "detail": "사용자 정보를 찾을 수 없습니다."
}
  • 오류 응답 (404 Not Found) - 추천 콘텐츠 없음
{
  "code": 8040,
  "message": "RECOMMENDATION_CONTENT_NOT_FOUND",
  "detail": "해당 일차의 추천 콘텐츠를 찾을 수 없습니다."
}

4. 이완요법 완료 API​

4.1 콘텐츠 완료 처리​

  • HTTP 메서드: POST
  • 경로: /v1/relaxation/contents/{id}/complete
  • Headers:
    • Content-Type: application/json
    • Authorization: Bearer {accessToken}
  • 설명: 해당 이완요법 콘텐츠를 완료 처리합니다. 완료된 콘텐츠는 사용자의 이완요법 진행 통계에 반영됩니다.

응답 (Response)​

  • 성공 응답 (200 OK)
{
  "success": true
}
  • 오류 응답 (400 Bad Request)
{
  "code": 8041,
  "message": "CONTENT_ALREADY_COMPLETED",
  "detail": "이미 완료된 콘텐츠입니다."
}
  • 오류 응답 (404 Not Found)
{
  "code": 8010,
  "message": "CONTENT_NOT_FOUND",
  "detail": "요청한 콘텐츠를 찾을 수 없습니다."
}

5. 이완요법 이력 API​

📌 기술 구현 문서: TBD

이완요법 이력 API는 사용자의 이완요법 콘텐츠 이용 과정을 상세히 추적하고 관리하는 기능을 제공합니다. 재생 시작/종료 시간, 일시정지/재개 이벤트를 기록하여 정확한 이용 소요시간을 측정하고 이용 패턴을 분석할 수 있습니다.

주요 특징:

  • 상세 이용 추적: 시작, 종료, 일시정지, 재개 등 모든 이용 이벤트 기록
  • 배치 처리 지원: 빈번한 일시정지/재개 이벤트를 효율적으로 처리하기 위한 배치 API 제공
  • 소요시간 계산: 실제 이용에 소요된 시간을 정확히 계산 (일시정지 시간 제외)
  • 이용 패턴 분석: 사용자의 이완요법 이용 습관과 패턴 분석을 위한 데이터 수집

4.1 이완요법 이력 저장​

📌 관련 문서: TBD

  • HTTP 메서드: POST
  • 경로: /v1/relaxation/history
  • Headers:
    • Content-Type: application/json
    • Authorization: Bearer {accessToken}
  • 설명: 단일 이완요법 이벤트(재생 시작, 일시정지, 재개, 중단 등)를 기록합니다.

요청 (Request)​

{
  "contentId": "rc_123",
  "eventType": "START",
  "timestamp": 1715690600000,
  "sessionId": "session_20240515_001",
  "position": 0
}

응답 (Response)​

  • 성공 응답 (201 Created)
{
  "id": "history_456",
  "contentId": "rc_123",
  "eventType": "START",
  "timestamp": 1715690600000,
  "sessionId": "session_20240515_001",
  "position": 0,
  "createdAt": 1715690601000
}
  • 오류 응답 (400 Bad Request)
{
  "code": 10001,
  "message": "INVALID_EVENT_TYPE",
  "detail": "유효하지 않은 이벤트 타입입니다. 지원 타입: START, PAUSE, RESUME, END"
}

4.2 이완요법 이력 배치 저장​

📌 관련 문서: TBD

  • HTTP 메서드: POST
  • 경로: /v1/relaxation/history/batch
  • Headers:
    • Content-Type: application/json
    • Authorization: Bearer {accessToken}
  • 설명: 여러 이완요법 이벤트를 한 번에 배치 처리합니다. 네트워크 효율성을 위해 클라이언트에서 수집한 이벤트들을 묶어서 전송할 때 사용합니다.

요청 (Request)​

{
  "contentId": "rc_123",
  "sessionId": "session_20240515_001",
  "events": [
    {
      "eventType": "START",
      "timestamp": 1715690600000,
      "position": 0
    },
    {
      "eventType": "PAUSE",
      "timestamp": 1715690660000,
      "position": 60
    },
    {
      "eventType": "RESUME",
      "timestamp": 1715690720000,
      "position": 60
    },
    {
      "eventType": "END",
      "timestamp": 1715690900000,
      "position": 240
    }
  ]
}

응답 (Response)​

  • 성공 응답 (201 Created)
{
  "batchId": "batch_789",
  "contentId": "rc_123",
  "sessionId": "session_20240515_001",
  "processedCount": 4,
  "failedCount": 0,
  "results": [
    {
      "id": "history_456",
      "eventType": "START",
      "timestamp": 1715690600000,
      "status": "SUCCESS"
    },
    {
      "id": "history_457",
      "eventType": "PAUSE",
      "timestamp": 1715690660000,
      "status": "SUCCESS"
    },
    {
      "id": "history_458",
      "eventType": "RESUME",
      "timestamp": 1715690720000,
      "status": "SUCCESS"
    },
    {
      "id": "history_459",
      "eventType": "END",
      "timestamp": 1715690900000,
      "status": "SUCCESS"
    }
  ],
  "metrics": {
    "totalPlayTimeMs": 300000,
    "activePlayTimeMs": 240000,
    "pausedTimeMs": 60000,
    "pauseCount": 1
  },
  "createdAt": 1715690901000
}
  • 오류 응답 (400 Bad Request)
{
  "code": 10002,
  "message": "BATCH_TOO_LARGE",
  "detail": "배치 크기가 너무 큽니다. 최대 100개 이벤트까지 처리 가능합니다."
}

6. 다운로드 관리 API​

6.1 다운로드 시작​

  • HTTP 메서드: POST
  • 경로: /v1/relaxation/downloads/start
  • Headers:
    • Content-Type: application/json
    • Authorization: Bearer {accessToken}

요청 (Request)​

{
  "userId": "user_abc_123",
  "contentId": "rc_123"
}

응답 (Response)​

  • 성공 응답 (201 Created)
{
  "id": "ds_123",
  "userId": "user_abc_123",
  "userCycleId": "cycle_789",
  "contentId": "rc_123",
  "downloadProgress": 0,
  "status": "IN_PROGRESS",
  "downloadUrl": "https://cdn.example.com/audio/breathing_01.mp3?token=xyz",
  "downloadUrlExpiry": 1715694200000,
  "createdAt": 1715691300000,
  "updatedAt": 1715691300000
}
  • 오류 응답 (409 Conflict)
{
  "code": 8021,
  "message": "DOWNLOAD_ALREADY_EXISTS",
  "detail": "해당 콘텐츠의 다운로드가 이미 진행 중입니다."
}

6.2 다운로드 진행률 업데이트​

  • HTTP 메서드: PATCH
  • 경로: /v1/relaxation/downloads/{id}/progress
  • Headers:
    • Content-Type: application/json
    • Authorization: Bearer {accessToken}

요청 (Request)​

{
  "downloadProgress": 45.5
}

응답 (Response)​

  • 성공 응답 (200 OK)
{
  "id": "ds_123",
  "downloadProgress": 45.5,
  "status": "IN_PROGRESS",
  "updatedAt": 1715691400000
}

6.3 다운로드 일시정지​

  • HTTP 메서드: POST
  • 경로: /v1/relaxation/downloads/{id}/pause
  • Headers:
    • Authorization: Bearer {accessToken}

응답 (Response)​

  • 성공 응답 (200 OK)
{
  "id": "ds_123",
  "status": "PAUSED",
  "downloadProgress": 45.5,
  "updatedAt": 1715691500000
}

6.4 다운로드 재개​

  • HTTP 메서드: POST
  • 경로: /v1/relaxation/downloads/{id}/resume
  • Headers:
    • Authorization: Bearer {accessToken}

응답 (Response)​

  • 성공 응답 (200 OK)
{
  "id": "ds_123",
  "status": "IN_PROGRESS",
  "downloadProgress": 45.5,
  "downloadUrl": "https://cdn.example.com/audio/breathing_01.mp3?token=abc",
  "downloadUrlExpiry": 1715695000000,
  "updatedAt": 1715691600000
}

6.5 다운로드 완료​

  • HTTP 메서드: POST
  • 경로: /v1/relaxation/downloads/{id}/complete
  • Headers:
    • Content-Type: application/json
    • Authorization: Bearer {accessToken}

요청 (Request)​

{
  "cacheLocation": "/app/cache/audio/breathing_01.mp3"
}

응답 (Response)​

  • 성공 응답 (200 OK)
{
  "id": "ds_123",
  "status": "COMPLETED",
  "downloadProgress": 100,
  "cacheLocation": "/app/cache/audio/breathing_01.mp3",
  "completedAt": 1715691700000,
  "updatedAt": 1715691700000
}

6.6 캐시된 콘텐츠 조회​

  • HTTP 메서드: GET
  • 경로: /v1/relaxation/downloads/cached
  • Headers:
    • Authorization: Bearer {accessToken}
  • Query Parameters:
    • userId: 사용자 ID (필수)
    • contentId: 특정 콘텐츠 ID (선택)

응답 (Response)​

  • 성공 응답 (200 OK)
{
  "userId": "user_abc_123",
  "cachedContents": [
    {
      "contentId": "rc_123",
      "downloadStatus": {
        "id": "ds_123",
        "status": "COMPLETED",
        "cacheLocation": "/app/cache/audio/breathing_01.mp3",
        "completedAt": 1715691700000
      },
      "cacheInfo": {
        "location": "/app/cache/audio/breathing_01.mp3",
        "size": 5242880,
        "lastAccessedAt": 1715691800000,
        "expiresAt": 1718283700000
      }
    },
    {
      "contentId": "rc_124",
      "downloadStatus": {
        "id": "ds_124",
        "status": "COMPLETED",
        "cacheLocation": "/app/cache/audio/autogenic_01.mp3",
        "completedAt": 1715690000000
      },
      "cacheInfo": {
        "location": "/app/cache/audio/autogenic_01.mp3",
        "size": 7340032,
        "lastAccessedAt": 1715690100000,
        "expiresAt": 1718282000000
      }
    }
  ],
  "metadata": {
    "totalCount": 2,
    "totalSize": 12582912
  }
}

6.7 캐시 삭제​

  • HTTP 메서드: DELETE
  • 경로: /v1/relaxation/downloads/cache
  • Headers:
    • Authorization: Bearer {accessToken}
  • Query Parameters:
    • userId: 사용자 ID (필수)
    • contentId: 특정 콘텐츠 ID (선택, 없으면 전체 삭제)

응답 (Response)​

  • 성공 응답 (200 OK)
{
  "userId": "user_abc_123",
  "deletedCount": 2,
  "freedSpace": 12582912,
  "message": "캐시가 성공적으로 삭제되었습니다."
}

7. 사용자 설정 API​

7.1 사용자 설정 조회​

  • HTTP 메서드: GET
  • 경로: /v1/relaxation/settings
  • Headers:
    • Authorization: Bearer {accessToken}
  • Query Parameters:
    • userId: 사용자 ID (필수)

응답 (Response)​

  • 성공 응답 (200 OK)
{
  "id": "us_123",
  "userId": "user_abc_123",
  "userCycleId": "cycle_789",
  "repeatMode": false,
  "preferredCategory": "cat_breathing",
  "lastPlayedContentId": "rc_123",
  "createdAt": 1715600400000,
  "updatedAt": 1715691900000
}

7.2 반복 모드 설정​

  • HTTP 메서드: PATCH
  • 경로: /v1/relaxation/settings/repeat-mode
  • Headers:
    • Content-Type: application/json
    • Authorization: Bearer {accessToken}

요청 (Request)​

{
  "userId": "user_abc_123",
  "repeatMode": true
}

응답 (Response)​

  • 성공 응답 (200 OK)
{
  "id": "us_123",
  "userId": "user_abc_123",
  "repeatMode": true,
  "updatedAt": 1715692000000
}

7.3 선호 카테고리 설정​

  • HTTP 메서드: PATCH
  • 경로: /v1/relaxation/settings/preferred-category
  • Headers:
    • Content-Type: application/json
    • Authorization: Bearer {accessToken}

요청 (Request)​

{
  "userId": "user_abc_123",
  "preferredCategory": "cat_mindfulness"
}

응답 (Response)​

  • 성공 응답 (200 OK)
{
  "id": "us_123",
  "userId": "user_abc_123",
  "preferredCategory": "cat_mindfulness",
  "updatedAt": 1715692100000
}

8. 사용 가이드 API​

8.1 활성 가이드 조회​

  • HTTP 메서드: GET
  • 경로: /v1/relaxation/guides/active
  • Headers:
    • Authorization: Bearer {accessToken}
    • Accept-Language: de-DE (기본값), en-US, ko-KR

응답 (Response)​

  • 성공 응답 (200 OK)
{
  "id": "ug_123",
  "version": 1,
  "isActive": true,
  "translation": {
    "language": "ko",
    "content": "# 이완요법 사용 가이드\n\n## 1. 편안한 자세 찾기\n조용하고 편안한 공간에서 편하게 앉거나 누워주세요.\n\n## 2. 헤드폰 사용 권장\n더 나은 경험을 위해 헤드폰이나 이어폰 사용을 권장합니다.\n\n## 3. 집중하기\n안내 음성에 따라 천천히 호흡하고 지시를 따라주세요.\n\n## 4. 규칙적인 연습\n매일 같은 시간에 연습하면 더 좋은 효과를 볼 수 있습니다."
  },
  "createdAt": 1715600400000,
  "updatedAt": 1715600400000
}

8.2 가이드 열람 기록​

  • HTTP 메서드: POST
  • 경로: /v1/relaxation/guides/{id}/view
  • Headers:
    • Content-Type: application/json
    • Authorization: Bearer {accessToken}

요청 (Request)​

{
  "userId": "user_abc_123"
}

응답 (Response)​

  • 성공 응답 (200 OK)
{
  "guideId": "ug_123",
  "userId": "user_abc_123",
  "viewedAt": 1715692200000,
  "message": "가이드 열람이 기록되었습니다."
}

9. 모바일 캐싱 API​

9.1 번들 버전 조회​

  • HTTP 메서드: GET
  • 경로: /v1/relaxation/bundles/{bundleId}
  • Headers:
    • Authorization: Bearer {accessToken}
    • Accept-Language: de-DE (기본값), en-US, ko-KR
  • Path Parameters:
    • bundleId: 번들 ID (필수)
  • Query Parameters:
    • includeContents: 콘텐츠 포함 여부 (선택, 기본값: true)
    • includeCategories: 카테고리 포함 여부 (선택, 기본값: true)

응답 (Response)​

  • 성공 응답 (200 OK)
{
  "bundleId": "bundle_v1_2_0",
  "version": "1.1.0",
  "language": "de-DE",
  "generatedAt": 1715600400000,
  "categories": [
    {
      "id": "cat_breathing",
      "type": "BREATHING_THERAPY",
      "orderIndex": 1,
      "name": "호흡요법",
      "summary": "호흡을 통한 이완 기법"
    }
    // ... 다른 카테고리들
  ],
  "contents": [
    {
      "id": "rc_123",
      "categoryId": "cat_breathing",
      "thumbnailImageUrl": "https://cdn.example.com/images/thumb/xxx_1_0_0.mp4",
      "lottieFileUrl": "https://cdn.example.com/images/lottie_1_0_0.mp4",
      "backgroundImageUrl": "https://cdn.example.com/images/breathing_bg_1_0_0.mp4",
      "audioFileUrl": "https://cdn.example.com/audio/breathing_01.mp3",
      "duration": 600,
      "orderIndex": 0,
      "level": "BEGINNER",
      "stress": "LOW",
      "poses": ["SITTING", "LYING"],
      "title": "복식호흡",
      "description": "깊고 차분한 호흡을 통해 긴장을 풀어보세요."
    }
    // ... 다른 콘텐츠들
  ],
  "metadata": {
    "contentCount": 15,
    "totalSize": 524288000
  },
  "createdAt": 1715690500000,
  "updatedAt": 1715690500000
}
  • 오류 응답 (404 Not Found)
{
  "code": 8030,
  "message": "BUNDLE_NOT_FOUND",
  "detail": "요청한 번들을 찾을 수 없습니다."
}

9.2 최신 번들 조회​

  • HTTP 메서드: GET
  • 경로: /v1/relaxation/bundles/latest
  • Headers:
    • Authorization: Bearer {appToken}
    • Accept-Language: de-DE (기본값), en-US, ko-KR (필수)
  • Query Parameters: query parameter 값을 받지않고 기본 값을 내부에서 이용
    • includeContents: 콘텐츠 포함 여부 (기본값: true)
    • includeCategories: 카테고리 포함 여부 (기본값: true)

응답 (Response)​

  • 성공 응답 (200 OK)
{
  "bundleId": "bundle_v1_2_0",
  "language": "de-DE",
  "categories": [
    {
      "id": "cat_breathing",
      "orderIndex": 0,
      "title": "호흡요법",
      "summary": "호흡을 통한 이완 기법"
    },
    {
      "id": "cat_pmr",
      "orderIndex": 1,
      "title": "점진적 근육이완 요법",
      "summary": "근육 긴장과 이완을 통한 전신 이완"
    },
    {
      "id": "cat_autogenic",
      "orderIndex": 2,
      "title": "아우토겐 트레이닝",
      "summary": "자기 암시를 통한 자율적 이완 훈련"
    },
    {
      "id": "cat_imagination",
      "orderIndex": 3,
      "title": "상상하기",
      "summary": "안내된 상상과 심상 여행을 통한 이완"
    },
    {
      "id": "cat_mindfulness",
      "orderIndex": 4,
      "title": "마음챙김",
      "summary": "현재 순간의 의식적 인식을 통한 평온함"
    }
  ],
  "contents": [
    {
      "id": "rc_001",
      "categoryId": "cat_breathing",
      "thumbnailImageUrl": "https://cdn.example.com/images/thumb/abdominal_breathing_1_0_0.jpg",
      "lottieFileUrl": "https://cdn.example.com/lottie/breathing_animation_1_0_0.json",
      "backgroundLottieUrl": "https://cdn.example.com/videos/breathing_bg_1_0_0.mp4",
      "backgroundImageUrl": "https://cdn.example.com/images/backgrounds/breathing_bg_1_0_0.jpg",
      "audioFileUrl": "https://cdn.example.com/audio/abdominal_breathing.mp3",
      "durationSeconds": 600,
      "orderIndex": 0,
      "level": "BEGINNER",
      "stress": "LOW",
      "poses": ["SITTING"],
      "title": "복식호흡",
      "summary": "깊은 복식호흡을 통한 기본적인 이완 호흡법"
    },
    {
      "id": "rc_002",
      "categoryId": "cat_breathing",
      "thumbnailImageUrl": "https://cdn.example.com/images/thumb/deep_abdominal_breathing_1_0_0.jpg",
      "lottieFileUrl": "https://cdn.example.com/lottie/deep_breathing_animation_1_0_0.json",
      "backgroundLottieUrl": "https://cdn.example.com/videos/deep_breathing_bg_1_0_0.mp4",
      "backgroundImageUrl": "https://cdn.example.com/images/backgrounds/deep_breathing_bg_1_0_0.jpg",
      "audioFileUrl": "https://cdn.example.com/audio/deep_abdominal_breathing.mp3",
      "durationSeconds": 720,
      "orderIndex": 1,
      "level": "INTERMEDIATE",
      "stress": "MEDIUM",
      "poses": ["SITTING"],
      "title": "최대 복식호흡",
      "summary": "더 깊은 이완을 위한 강화된 복식호흡법"
    },
    {
      "id": "rc_015",
      "categoryId": "cat_mindfulness",
      "thumbnailImageUrl": "https://cdn.example.com/images/thumb/body_scan_1_0_0.jpg",
      "lottieFileUrl": "https://cdn.example.com/lottie/body_scan_animation_1_0_0.json",
      "backgroundLottieUrl": "https://cdn.example.com/videos/body_scan_bg_1_0_0.mp4",
      "backgroundImageUrl": "https://cdn.example.com/images/backgrounds/body_scan_bg_1_0_0.jpg",
      "audioFileUrl": "https://cdn.example.com/audio/body_scan.mp3",
      "durationSeconds": 1200,
      "orderIndex": 0,
      "level": "BEGINNER",
      "stress": "LOW",
      "poses": ["LYING"],
      "title": "바디스캔",
      "summary": "의식적인 신체 감각을 위한 마음챙김 연습"
    }
    // ... 다른 콘텐츠들 (총 26개)
  ]
}
  • 오류 응답 (409 Conflict) - 활성 번들이 없는 경우
{
  "code": 8033,
  "message": "NO_ACTIVE_BUNDLE",
  "detail": "활성화된 번들이 없습니다."
}

기능 설명​

  • 최신 번들 자동 조회: 시스템에서 현재 활성화된 최신 번들을 자동으로 조회합니다.
  • 캐싱 최적화: 모든 사용자가 동일한 최신 번들을 사용하므로 Redis 캐시를 활용하여 응답 속도를 최적화합니다.
  • 언어별 번역: Accept-Language 헤더에 따라 해당 언어의 번역된 콘텐츠를 제공합니다.
  • 선택적 포함: Query Parameter를 통해 카테고리나 콘텐츠 정보를 선택적으로 포함할 수 있습니다.

9.3 번들 다운로드​

  • HTTP 메서드: GET
  • 경로: /v1/relaxation/bundles/{bundleId}/download
  • Headers:
    • Authorization: Bearer {accessToken}

응답 (Response)​

  • 성공 응답 (200 OK)
{
  "bundleId": "bundle_v1_2_0",
  "downloadUrl": "https://cdn.example.com/bundles/relaxation_v1_2_0.zip?token=xyz",
  "downloadUrlExpiry": 1715694200000,
  "fileSize": 524288000,
  "checksum": "a1b2c3d4e5f6",
  "expiresIn": 3600
}

10. 관리자 API​

10.1 콘텐츠 생성​

  • HTTP 메서드: POST
  • 경로: /v1/relaxation/admin/contents
  • Headers:
    • Content-Type: application/json
    • Authorization: Bearer {adminToken}

요청 (Request)​

{
  "categoryId": "cat_breathing",
  "backgroundImageUrl": "https://cdn.example.com/images/breathing_new.jpg",
  "audioFileUrl": "https://cdn.example.com/audio/breathing_new.mp3",
  "duration": 540,
  "orderIndex": 4,
  "level": "ADVANCED",
  "stress": "HIGH",
  "poses": ["SITTING", "LYING", "STANDING"],
  "isActive": true,
  "translations": [
    {
      "language": "ko",
      "title": "상급 호흡법",
      "description": "고급 호흡 기법을 통한 깊은 이완"
    },
    {
      "language": "en",
      "title": "Advanced Breathing",
      "description": "Deep relaxation through advanced breathing techniques"
    },
    {
      "language": "de",
      "title": "Fortgeschrittene Atmung",
      "description": "Tiefe Entspannung durch fortgeschrittene Atemtechniken"
    }
  ],
  "detail": {
    "translations": [
      {
        "language": "ko",
        "purpose": "고급 호흡 기법을 통해 더 깊은 이완 상태에 도달합니다.",
        "effects": "깊은 이완, 명상 상태 도달, 스트레스 해소",
        "mechanism": "복합적인 호흡 패턴을 통해 신경계를 안정화시킵니다.",
        "precautions": "초보자는 기본 호흡법부터 시작하세요."
      }
      // ... 다른 언어 번역
    ]
  }
}

응답 (Response)​

  • 성공 응답 (201 Created)
{
  "id": "rc_130",
  "categoryId": "cat_breathing",
  "backgroundImageUrl": "https://cdn.example.com/images/breathing_new.jpg",
  "audioFileUrl": "https://cdn.example.com/audio/breathing_new.mp3",
  "duration": 540,
  "orderIndex": 4,
  "isActive": true,
  "translations": [
    {
      "id": "rct_ko_130",
      "language": "ko",
      "title": "상급 호흡법",
      "description": "고급 호흡 기법을 통한 깊은 이완"
    }
    // ... 다른 언어 번역
  ],
  "detail": {
    "id": "cd_130",
    "version": 1,
    "translations": [
      {
        "id": "cdt_ko_130",
        "language": "ko",
        "purpose": "고급 호흡 기법을 통해 더 깊은 이완 상태에 도달합니다.",
        "effects": "깊은 이완, 명상 상태 도달, 스트레스 해소",
        "mechanism": "복합적인 호흡 패턴을 통해 신경계를 안정화시킵니다.",
        "precautions": "초보자는 기본 호흡법부터 시작하세요."
      }
      // ... 다른 언어 번역
    ]
  },
  "createdAt": 1715692300000,
  "updatedAt": 1715692300000
}
  • 오류 응답 (403 Forbidden)
{
  "code": 2060,
  "message": "PERMISSION_DENIED",
  "detail": "콘텐츠를 생성할 권한이 없습니다."
}

10.2 콘텐츠 수정​

  • HTTP 메서드: PATCH
  • 경로: /v1/relaxation/admin/contents/{id}
  • Headers:
    • Content-Type: application/json
    • Authorization: Bearer {adminToken}

요청 (Request)​

{
  "duration": 600,
  "orderIndex": 3,
  "translations": [
    {
      "language": "ko",
      "title": "상급 호흡법 (개정판)",
      "description": "개선된 고급 호흡 기법을 통한 깊은 이완"
    }
  ]
}

응답 (Response)​

  • 성공 응답 (200 OK)
{
  "id": "rc_130",
  "categoryId": "cat_breathing",
  "duration": 600,
  "orderIndex": 3,
  "translations": [
    {
      "id": "rct_ko_130",
      "language": "ko",
      "title": "상급 호흡법 (개정판)",
      "description": "개선된 고급 호흡 기법을 통한 깊은 이완"
    }
    // ... 다른 언어 번역
  ],
  "updatedAt": 1715692400000
}

10.3 콘텐츠 삭제​

  • HTTP 메서드: DELETE
  • 경로: /v1/relaxation/admin/contents/{id}
  • Headers:
    • Authorization: Bearer {adminToken}

응답 (Response)​

  • 성공 응답 (200 OK)
{
  "message": "콘텐츠가 성공적으로 삭제되었습니다.",
  "id": "rc_130",
  "deletedAt": 1715692500000
}
  • 오류 응답 (409 Conflict)
{
  "code": 8031,
  "message": "CONTENT_CANNOT_BE_DELETED",
  "detail": "해당 콘텐츠는 사용자 재생 이력이 존재하여 삭제할 수 없습니다."
}

10.4 번들 생성​

  • HTTP 메서드: POST
  • 경로: /v1/relaxation/admin/bundles
  • Headers:
    • Content-Type: application/json
    • Authorization: Bearer {adminToken}

요청 (Request)​

{
  "bundleName": "2025년 2월 콘텐츠 업데이트",
  "contentIds": ["rc_123", "rc_124", "rc_125", "rc_126", "rc_127", "rc_128", "rc_129", "rc_130"]
}

응답 (Response)​

  • 성공 응답 (201 Created)
{
  "id": "bundle_v1_3_0",
  "bundleName": "2025년 2월 콘텐츠 업데이트",
  "version": "1.3.0",
  "hash": "b2c3d4e5f6g7",
  "isActive": false,
  "generatedAt": 1715692600000,
  "contentCount": 8,
  "totalSize": 419430400,
  "createdAt": 1715692600000,
  "updatedAt": 1715692600000
}

10.5 번들 활성화​

  • HTTP 메서드: POST
  • 경로: /v1/relaxation/admin/bundles/{id}/activate
  • Headers:
    • Authorization: Bearer {adminToken}

응답 (Response)​

  • 성공 응답 (200 OK)
{
  "id": "bundle_v1_3_0",
  "bundleName": "2025년 2월 콘텐츠 업데이트",
  "version": "1.3.0",
  "isActive": true,
  "activatedAt": 1715692700000,
  "previousActiveBundle": {
    "id": "bundle_v1_2_0",
    "version": "1.2.0",
    "deactivatedAt": 1715692700000
  },
  "updatedAt": 1715692700000
}

11. 오류 코드​

이완요법 도메인 API에서 사용하는 주요 오류 코드는 다음과 같습니다.

HTTP 상태 코드오류 코드메시지설명
5008000SERVER_ERROR서버 내부 오류
4008001INVALID_INPUT_DATA요청 데이터가 유효하지 않음
4048010CONTENT_NOT_FOUND요청한 콘텐츠를 찾을 수 없음
4048011CATEGORY_NOT_FOUND요청한 카테고리를 찾을 수 없음
4098020ALREADY_COMPLETED해당 콘텐츠는 이미 완료됨
4098021DOWNLOAD_ALREADY_EXISTS해당 콘텐츠의 다운로드가 이미 진행 중
4048022DOWNLOAD_NOT_FOUND요청한 다운로드를 찾을 수 없음
4098023INVALID_DOWNLOAD_STATUS현재 다운로드 상태에서 수행할 수 없는 작업
4048024PLAYBACK_NOT_FOUND요청한 재생 이력을 찾을 수 없음
4098025PLAYBACK_ALREADY_STOPPED이미 중단된 재생

| 404 | 8028 | USER_SETTING_NOT_FOUND | 사용자 설정을 찾을 수 없음 | | 404 | 8029 | GUIDE_NOT_FOUND | 요청한 가이드를 찾을 수 없음 | | 404 | 8030 | BUNDLE_NOT_FOUND | 요청한 번들을 찾을 수 없음 | | 409 | 8031 | CONTENT_CANNOT_BE_DELETED | 사용자 이력이 존재하여 콘텐츠를 삭제할 수 없음 | | 409 | 8032 | BUNDLE_ALREADY_ACTIVE | 해당 번들은 이미 활성화됨 | | 409 | 8033 | NO_ACTIVE_BUNDLE | 활성화된 번들이 없음 | | 409 | 8034 | BUNDLE_CANNOT_BE_MODIFIED | 활성화된 번들은 수정할 수 없음 | | 400 | 8041 | CONTENT_ALREADY_COMPLETED | 이미 완료된 콘텐츠입니다 | | 403 | 2060 | PERMISSION_DENIED | 요청한 작업에 대한 권한 없음 | | 401 | 2010 | UNAUTHORIZED | 인증되지 않은 요청 | | 404 | 6044 | USER_NOT_FOUND | 사용자를 찾을 수 없음 |

| 13080번대: 이완요법 이력 관련 오류 | | 400 | 13081 | INVALID_EVENT_TYPE | 유효하지 않은 이벤트 타입입니다. 지원 타입: START, PAUSE, RESUME, END | | 400 | 13086 | BATCH_TOO_LARGE | 배치 크기가 너무 큽니다. 최대 100개 이벤트까지 처리 가능합니다. | | 400 | 13082 | INVALID_SESSION_ID | 유효하지 않은 세션 ID입니다. | | 409 | 13083 | DUPLICATE_EVENT | 중복된 이벤트입니다. | | 400 | 13084 | INVALID_EVENT_SEQUENCE | 유효하지 않은 이벤트 순서입니다. | | 404 | 13080 | HISTORY_NOT_FOUND | 해당 이완요법 이력을 찾을 수 없습니다. | | 400 | 13085 | INVALID_TIMESTAMP | 유효하지 않은 타임스탬프입니다. | | 500 | 13087 | BATCH_PROCESSING_FAILED | 배치 처리 중 오류가 발생했습니다. |

| 11000번대: Learning 도메인 관련 오류 | | 500 | 11000 | SERVER_ERROR | 서버 내부 오류 | | 400 | 11080 | INVALID_EVENT_TYPE | 유효하지 않은 이벤트 타입입니다. 지원 타입: START, PAUSE, RESUME, END | | 400 | 11081 | BATCH_TOO_LARGE | 배치 크기가 너무 큽니다. 최대 100개 이벤트까지 처리 가능합니다 | | 404 | 11082 | HISTORY_NOT_FOUND | 해당 학습 이력을 찾을 수 없습니다 |

12. 변경 이력​

버전날짜작성자변경 내용
0.1.02025-06-10bok@weltcorp.com최초 작성
0.1.12025-06-10bok@weltcorp.com모바일 캐싱을 위한 번들 API 추가
0.1.22025-06-12bok@weltcorp.comlottieFileUrl 필드 추가, 권한 매트릭스 업데이트
0.1.32025-06-12bok@weltcorp.com콘텐츠에 level, stress, poses 필드 추가 및 관련 enum 정의
0.1.42025-06-12bok@weltcorp.com추천 관리 API 제거 (클라이언트 구현으로 변경)
0.1.52025-07-16elizabeth@weltcorp.com재생 관리 API를 이완요법 이력 API로 간소화 - learning 도메인과 동일한 히스토리 기반 패턴 적용
0.1.62025-07-18elizabeth@weltcorp.com오늘의 추천 이완요법 API 추가 - 가입 후 5일간 일차별 추천 콘텐츠 제공
0.1.72025-01-15claude@assistant.com이완요법 완료 API 추가 - learning domain과 유사한 콘텐츠 완료 처리 endpoint 추가