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

약관 동의 API

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

공통 요청 헤더

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

통합 동의 항목 조회​

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

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

Headers​

HeaderTypeDescriptionRequired
Authorizationstring발급받은 앱 토큰 (appToken) 또는 사용자 액세스 토큰 (accessToken)Yes
Accept-Languagestring조회할 약관의 언어 코드 (예: ko-KR, en-US). 기본값: ko-KRNo

Query Parameters​

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

Responses Summary​

HTTP Status Code설명Error Code(s)Remarks
200 OK성공-
401 Unauthorized유효하지 않은 토큰2051
500 Internal Server Error서버 내부 오류2000, 40004000번 코드는 개인정보 처리방침 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"
  }
}
필드타입설명필수
itemsarray조회된 약관 및 동의 항목 목록 배열Yes
privacyPolicyobject개인정보 처리방침 정보 객체Yes

items 배열 내 객체 필드 정보​

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

privacyPolicy 객체 필드 정보​

필드타입설명필수
versionIdstring개인정보처리방침 버전 고유 ID (UUID 형식)Yes
typestring항목 유형: PRIVACY_POLICY (AgreementType 참조)Yes
titlestring약관 이름 번역 (agreements_translations.name)Yes
textstring약관 내용Yes
detailsUrlstring상세 내용 URLYes
401 Unauthorized - 유효하지 않은 토큰
{
  "code": 2051,
  "message": "INVALID_TOKEN",
  "detail": "토큰이 유효하지 않습니다"
}
필드타입설명필수
codenumber애플리케이션 오류 코드Yes
messagestring오류 메시지 코드Yes
detailstring사용자 친화적인 오류 설명Yes
500 Internal Server Error - 서버 내부 오류
{
  "code": 2000,
  "message": "SERVER_ERROR",
  "detail": "서버 내부 오류"
}
필드타입설명필수
codenumber애플리케이션 오류 코드Yes
messagestring오류 메시지 코드Yes
detailstring사용자 친화적인 오류 설명Yes
500 Internal Server Error - 개인정보 처리방침 상세 URL 누락

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

{
  "code": 4000,
  "message": "SERVER_ERROR",
  "detail": "Privacy Policy detailsUrl is missing."
}
필드타입설명필수
codenumber애플리케이션 오류 코드 (4000)Yes
messagestring오류 메시지 코드 ("AGREEMENTS_SERVER_ERROR")Yes
detailstring사용자 친화적인 오류 설명Yes

특정 약관 버전 상세 조회​

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

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

Path Parameters​

ParameterTypeDescriptionRequired
versionIdstring조회할 약관 버전 IDYes

Query Parameters​

ParameterTypeDescriptionRequired
languagestring조회할 언어 코드 (예: ko, en). 기본값: koNo

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​

ParameterTypeDescriptionRequired
versionIdstring동의할 약관 버전 IDYes

Headers​

HeaderTypeDescriptionRequired
Authorizationstring사용자 액세스 토큰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​

ParameterTypeDescriptionRequired
versionIdstring확인할 약관 버전 IDYes

Headers​

HeaderTypeDescriptionRequired
Authorizationstring사용자 액세스 토큰Yes

Responses​

200 OK - 성공
{
  "isAgreed": true
}
필드타입설명필수
isAgreedboolean동의 여부Yes
401 Unauthorized - 인증 실패
{
  "code": 2051,
  "message": "INVALID_TOKEN",
  "detail": "토큰이 유효하지 않습니다"
}

설명​

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

항목 타입별 특징​

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

  1. 약관(TERMS) 항목:

    • versionId는 UUID 형식의 약관 버전 ID입니다.
    • isRequired는 약관 설정에 따라 true(필수 동의) 또는 false(선택적 동의)입니다.
    • text는 Accept-Language 헤더에 따라 현지화된 약관 제목입니다.
    • detailsUrl은 약관 전문을 볼 수 있는 URL이며, 언어 코드가 포함됩니다.

  2. 만 14세 이상 확인(CONSENT_AGE_VERIFICATION) 항목:

    • 만 14세 이상임을 확인하는 필수 동의 항목입니다.
    • isRequired는 true입니다.
    • detailsUrl은 null입니다.

  3. 개인정보 수집·이용 동의(CONSENT_PERSONAL_DATA) 항목:

    • 서비스 제공을 위한 필수 개인정보 수집·이용 동의입니다.
    • isRequired는 true입니다.
    • detailsUrl은 개인정보 수집·이용 상세 내용 URL입니다.

  4. 민감정보 수집·이용 동의(CONSENT_SENSITIVE_DATA) 항목:

    • 사용자가 직접 입력하는 민감정보(건강 정보) 수집·이용 동의입니다.
    • isRequired는 false입니다 (선택적 동의).
    • detailsUrl은 민감정보 수집·이용 상세 내용 URL입니다.

  5. 건강정보 수집·이용 동의(CONSENT_SENSITIVE_DATA_HEALTH) 항목:

    • 외부 건강 데이터 연동(HealthKit, Google Fit 등) 동의입니다.
    • isRequired는 false입니다 (선택적 동의).
    • 이 동의가 있는 경우 로그인 응답에 health:read 권한이 부여됩니다.

  6. 일반 동의(CONSENT) 항목 (레거시 호환):

    • 기존 시스템과의 호환성을 위해 유지되는 일반 동의 타입입니다.
    • isRequired는 설정에 따라 true 또는 false입니다.
    • detailsUrl은 동의와 관련된 추가 정보를 볼 수 있는 URL이거나 null입니다.

  7. 개인정보 처리방침(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