버전: 개발 버전 (최신)

약관 동의 API

이 섹션에서는 서비스 약관 동의와 관련된 API 엔드포인트를 설명합니다.

공통 요청 헤더

모든 dha-sleep API 요청은 공통 요청 헤더를 준수해야 합니다. User-Agent, Accept-Language, 인증 헤더 요구사항을 먼저 확인하세요.

통합 동의 항목 조회

특정 시점(예: 회원가입, 로그인 후 첫 진입)에 사용자에게 반드시 제시하고 동의받아야 하는 필수 약관과 함께 표시될 선택적 동의 항목 및 해당 사용자의 현재 동의 상태를 한 번에 조회하기 위해 사용됩니다. 클라이언트는 이 응답을 사용하여 동의 화면을 구성할 수 있습니다.

HTTP Method: GET
Path: /v1/auth/agreements
인증: appToken 또는 accessToken 필요 (Authorization: Bearer {token})

Headers

Header	Type	Description	Required
`Authorization`	string	발급받은 앱 토큰 (`appToken`) 또는 사용자 액세스 토큰 (`accessToken`)	Yes
`Accept-Language`	string	조회할 약관의 언어 코드 (예: `ko-KR`, `en-US`). 기본값: `ko-KR`	No

Query Parameters

이 엔드포인트는 쿼리 파라미터를 사용하지 않습니다.

Responses Summary

HTTP Status Code	설명	Error Code(s)	Remarks
`200 OK`	성공	-
`401 Unauthorized`	유효하지 않은 토큰	`2051`
`500 Internal Server Error`	서버 내부 오류	`2000`, `4000`	`4000`번 코드는 개인정보 처리방침 `detailsUrl` 누락 시 발생합니다.

Responses

200 OK - 성공

{
  "items": [
    {
      "versionId": "9f8a7b6c-5d4e-3f2g-1h0i-j9k8l7m6n5o4",
      "type": "CONSENT_AGE_VERIFICATION",
      "isRequired": true,
      "title": "만 14세 이상 확인",
      "text": "만 14세 이상입니다.",
      "detailsUrl": null,
      "orderIndex": 0
    },
    {
      "versionId": "a1b2c3d4-5e6f-7g8h-9i0j-k1l2m3n4o5p6",
      "type": "TERMS",
      "isRequired": true,
      "title": "서비스 이용약관",
      "text": "서비스 이용약관",
      "detailsUrl": "https://weltcorp.notion.site/2b83f840cbff8047b5afd81e1881d7f7",
      "orderIndex": 1
    },
    {
      "versionId": "d4e5f6g7-8h9i-0j1k-2l3m-n4o5p6q7r8s9",
      "type": "CONSENT_PERSONAL_DATA",
      "isRequired": true,
      "title": "개인정보 수집·이용 동의",
      "text": "개인정보 수집·이용 동의",
      "detailsUrl": "https://weltcorp.notion.site/2be3f840cbff80859608d28c3bc3fe9d",
      "orderIndex": 2
    },
    {
      "versionId": "c3d4e5f6-7g8h-9i0j-1k2l-m3n4o5p6q7r8",
      "type": "CONSENT_SENSITIVE_DATA",
      "isRequired": false,
      "title": "민감정보 수집·이용 동의",
      "text": "민감정보 수집·이용 동의",
      "detailsUrl": "https://weltcorp.notion.site/2b83f840cbff80a5b6b4c3d29e1b3636",
      "orderIndex": 3
    },
    {
      "versionId": "b2c3d4e5-6f7g-8h9i-0j1k-l2m3n4o5p6q7",
      "type": "PRIVACY_POLICY",
      "isRequired": true,
      "title": "개인정보 처리방침",
      "text": "개인정보 처리방침",
      "detailsUrl": "https://weltcorp.notion.site/2b83f840cbff8014a10de940b0c4468c",
      "orderIndex": 4
    }
  ],
  "privacyPolicy": {
    "versionId": "b2c3d4e5-6f7g-8h9i-0j1k-l2m3n4o5p6q7",
    "type": "PRIVACY_POLICY",
    "title": "개인정보 처리방침",
    "text": "개인정보 처리방침",
    "detailsUrl": "https://weltcorp.notion.site/2b83f840cbff8014a10de940b0c4468c"
  }
}

필드	타입	설명	필수
`items`	array	조회된 약관 및 동의 항목 목록 배열	Yes
`privacyPolicy`	object	개인정보 처리방침 정보 객체	Yes

items 배열 내 객체 필드 정보

필드	타입	설명	필수
`versionId`	string	항목 버전 고유 ID (UUID 형식)	Yes
`type`	string	항목 유형 (AgreementType 참조). 가능한 값: `TERMS`, `CONSENT`, `CONSENT_AGE_VERIFICATION`, `CONSENT_PERSONAL_DATA`, `CONSENT_SENSITIVE_DATA`, `CONSENT_SENSITIVE_DATA_HEALTH`, `PRIVACY_POLICY`	Yes
`isRequired`	boolean	필수 여부	Yes
`title`	string	약관 이름 번역 (agreements_translations.name)	Yes
`text`	string	약관 내용 (현지화된 텍스트)	Yes
`detailsUrl`	string	상세 내용 URL (null일 수 있음)	No
`orderIndex`	number	UI 표시 순서 (0부터 시작). 클라이언트는 이 값을 기준으로 약관 항목을 정렬하여 표시해야 합니다.	Yes

privacyPolicy 객체 필드 정보

필드	타입	설명	필수
`versionId`	string	개인정보처리방침 버전 고유 ID (UUID 형식)	Yes
`type`	string	항목 유형: `PRIVACY_POLICY` (AgreementType 참조)	Yes
`title`	string	약관 이름 번역 (agreements_translations.name)	Yes
`text`	string	약관 내용	Yes
`detailsUrl`	string	상세 내용 URL	Yes

401 Unauthorized - 유효하지 않은 토큰

{
  "code": 2051,
  "message": "INVALID_TOKEN",
  "detail": "토큰이 유효하지 않습니다"
}

필드	타입	설명	필수
`code`	number	애플리케이션 오류 코드	Yes
`message`	string	오류 메시지 코드	Yes
`detail`	string	사용자 친화적인 오류 설명	Yes

500 Internal Server Error - 서버 내부 오류

{
  "code": 2000,
  "message": "SERVER_ERROR",
  "detail": "서버 내부 오류"
}

필드	타입	설명	필수
`code`	number	애플리케이션 오류 코드	Yes
`message`	string	오류 메시지 코드	Yes
`detail`	string	사용자 친화적인 오류 설명	Yes

500 Internal Server Error - 개인정보 처리방침 상세 URL 누락

이 오류는 privacyPolicy 객체에 필수적인 detailsUrl 필드가 누락된 경우 발생합니다.

{
  "code": 4000,
  "message": "SERVER_ERROR",
  "detail": "Privacy Policy detailsUrl is missing."
}

필드	타입	설명	필수
`code`	number	애플리케이션 오류 코드 (4000)	Yes
`message`	string	오류 메시지 코드 ("AGREEMENTS_SERVER_ERROR")	Yes
`detail`	string	사용자 친화적인 오류 설명	Yes

특정 약관 버전 상세 조회

특정 약관 버전의 상세 정보를 조회합니다.

HTTP Method: GET
Path: /v1/agreements/versions/:versionId
인증: 불필요 (Public)

Path Parameters

Parameter	Type	Description	Required
`versionId`	string	조회할 약관 버전 ID	Yes

Query Parameters

Parameter	Type	Description	Required
`language`	string	조회할 언어 코드 (예: `ko`, `en`). 기본값: `ko`	No

Responses

200 OK - 성공

{
  "versionId": "version-uuid-1",
  "agreementsId": "agreement-uuid-1",
  "version": "1.0.0",
  "status": "ACTIVE",
  "content": "서비스 이용약관",
  "detailsUrl": "https://weltcorp.notion.site/2b83f840cbff8047b5afd81e1881d7f7",
  "createdAt": "2024-01-01T00:00:00.000Z"
}

404 Not Found - 약관 버전을 찾을 수 없음

{
  "code": 4004,
  "message": "AGREEMENT_VERSION_NOT_FOUND",
  "detail": "약관 버전을 찾을 수 없습니다"
}

사용자 약관 동의 기록

사용자가 특정 약관 버전에 동의한 것을 기록합니다.

HTTP Method: POST
Path: /v1/agreements/versions/:versionId/agree
인증: accessToken 필요 (Authorization: Bearer {token})

Path Parameters

Parameter	Type	Description	Required
`versionId`	string	동의할 약관 버전 ID	Yes

Headers

Header	Type	Description	Required
`Authorization`	string	사용자 액세스 토큰	Yes

Responses

200 OK - 성공

{
  "success": true,
  "message": "약관에 동의하였습니다."
}

401 Unauthorized - 인증 실패

{
  "code": 2051,
  "message": "INVALID_TOKEN",
  "detail": "토큰이 유효하지 않습니다"
}

404 Not Found - 약관 버전을 찾을 수 없음

{
  "code": 4004,
  "message": "AGREEMENT_VERSION_NOT_FOUND",
  "detail": "약관 버전을 찾을 수 없습니다"
}

사용자 약관 동의 여부 확인

사용자가 특정 약관 버전에 동의했는지 확인합니다.

HTTP Method: GET
Path: /v1/agreements/versions/:versionId/has-agreed
인증: accessToken 필요 (Authorization: Bearer {token})

Path Parameters

Parameter	Type	Description	Required
`versionId`	string	확인할 약관 버전 ID	Yes

Headers

Header	Type	Description	Required
`Authorization`	string	사용자 액세스 토큰	Yes

Responses

200 OK - 성공

{
  "isAgreed": true
}

필드	타입	설명	필수
`isAgreed`	boolean	동의 여부	Yes

401 Unauthorized - 인증 실패

{
  "code": 2051,
  "message": "INVALID_TOKEN",
  "detail": "토큰이 유효하지 않습니다"
}

설명

이 API는 동의가 필요한 약관과 선택적 동의 항목을 통합적으로 조회하여 클라이언트가 동의 화면을 구성하는 데 필요한 모든 정보를 제공합니다.

항목 타입별 특징

전체 타입 목록은 AgreementType을 참조하세요.

약관(TERMS) 항목:
- versionId는 UUID 형식의 약관 버전 ID입니다.
- isRequired는 약관 설정에 따라 true(필수 동의) 또는 false(선택적 동의)입니다.
- text는 Accept-Language 헤더에 따라 현지화된 약관 제목입니다.
- detailsUrl은 약관 전문을 볼 수 있는 URL이며, 언어 코드가 포함됩니다.
만 14세 이상 확인(CONSENT_AGE_VERIFICATION) 항목:
- 만 14세 이상임을 확인하는 필수 동의 항목입니다.
- isRequired는 true입니다.
- detailsUrl은 null입니다.
개인정보 수집·이용 동의(CONSENT_PERSONAL_DATA) 항목:
- 서비스 제공을 위한 필수 개인정보 수집·이용 동의입니다.
- isRequired는 true입니다.
- detailsUrl은 개인정보 수집·이용 상세 내용 URL입니다.
민감정보 수집·이용 동의(CONSENT_SENSITIVE_DATA) 항목:
- 사용자가 직접 입력하는 민감정보(건강 정보) 수집·이용 동의입니다.
- isRequired는 false입니다 (선택적 동의).
- detailsUrl은 민감정보 수집·이용 상세 내용 URL입니다.
건강정보 수집·이용 동의(CONSENT_SENSITIVE_DATA_HEALTH) 항목:
- 외부 건강 데이터 연동(HealthKit, Google Fit 등) 동의입니다.
- isRequired는 false입니다 (선택적 동의).
- 이 동의가 있는 경우 로그인 응답에 health:read 권한이 부여됩니다.
일반 동의(CONSENT) 항목 (레거시 호환):
- 기존 시스템과의 호환성을 위해 유지되는 일반 동의 타입입니다.
- isRequired는 설정에 따라 true 또는 false입니다.
- detailsUrl은 동의와 관련된 추가 정보를 볼 수 있는 URL이거나 null입니다.
개인정보 처리방침(PRIVACY_POLICY) 항목:
- privacyPolicy 객체로도 별도 제공되는 개인정보 처리방침 정보입니다.
- versionId는 UUID 형식의 개인정보 처리방침 버전 ID입니다.
- text는 Accept-Language 헤더에 따라 현지화된 개인정보 처리방침 제목입니다.
- detailsUrl은 개인정보 처리방침 전문을 볼 수 있는 URL입니다.

약관 상세 페이지 URL

약관 항목	URL
서비스 이용약관	https://weltcorp.notion.site/2b83f840cbff8047b5afd81e1881d7f7
개인정보 처리방침	https://weltcorp.notion.site/2b83f840cbff8014a10de940b0c4468c
개인정보 수집·이용 동의	https://weltcorp.notion.site/2be3f840cbff80859608d28c3bc3fe9d
민감정보 수집·이용 동의	https://weltcorp.notion.site/2b83f840cbff80a5b6b4c3d29e1b3636

통합 동의 항목 조회​

Headers​

Query Parameters​

Responses Summary​

Responses​

items 배열 내 객체 필드 정보​

privacyPolicy 객체 필드 정보​

특정 약관 버전 상세 조회​

Path Parameters​

Query Parameters​

Responses​

사용자 약관 동의 기록​

Path Parameters​

Headers​

Responses​

사용자 약관 동의 여부 확인​

Path Parameters​

Headers​

Responses​

설명​

항목 타입별 특징​

약관 상세 페이지 URL​

통합 동의 항목 조회

Headers

Query Parameters

Responses Summary

Responses

items 배열 내 객체 필드 정보

privacyPolicy 객체 필드 정보

특정 약관 버전 상세 조회

Path Parameters

Query Parameters

Responses

사용자 약관 동의 기록

Path Parameters

Headers

Responses

사용자 약관 동의 여부 확인

Path Parameters

Headers

Responses

설명

항목 타입별 특징

약관 상세 페이지 URL