버전: 0.68.0

약관 조회 API

앱 설정에서 확인할 수 있는 약관 목록을 조회하는 API입니다. 현재 활성화된 필수 약관과 선택적 동의 항목, 그리고 사용자의 동의 상태를 조회할 수 있습니다.

약관 목록 조회

앱 설정 화면에서 표시할 약관 목록과 사용자의 동의 상태를 조회합니다.

HTTP Method: GET
Path: /v1/users/agreements
인증: 사용자 액세스 토큰 (accessToken) 필요

Headers

Header	Type	Description	Required
`Authorization`	string	Bearer 토큰 형식의 앱 토큰 또는 JWT 액세스 토큰이 필요합니다.	Yes
`Accept-Language`	string	응답 언어 (de-DE, ko-KR, en-US). 기본값: de-DE	No

Request Body

이 API는 요청 본문을 사용하지 않습니다.

Responses

HTTP Status Code	설명	Error Code(s)
`200 OK`	약관 목록 조회 성공	-
`401 Unauthorized`	인증 실패 (토큰 누락, 만료, 유효하지 않음)	`1000`
`500 Internal Server Error`	서버 내부 오류	`1007`

200 OK - 약관 목록 조회 성공

약관 목록이 성공적으로 조회되면 활성화된 약관 목록과 개인정보처리방침이 반환됩니다.

{
  "items": [
    {
      "versionId": "8fa325dc-b97b-4aef-ac91-172aff3e9ace",
      "type": "TERMS",
      "isRequired": true,
      "title": "DiGAV § 4 Abs. 2 Terms of Use",
      "text": "Ich stimme den Nutzungsbedingungen gemäß der DiGAV § 4 Abs. 2 zu.",
      "detailsUrl": "https://sleepq.de/legal/einwilligung",
      "orderIndex": 0,
      "isAgreeable": true
    },
    {
      "versionId": "606ac8c6-07b8-40fa-bfa4-60b69428ab9c",
      "type": "CONSENT",
      "isRequired": false,
      "title": "Consent for Data Processing (Functionality, Usability, Development)",
      "text": "Ich erlaube die Verarbeitung meiner Daten zur dauerhaften Gewährleistung der technischen Funktionsfähigkeit, der Nutzerfreundlichkeit und der Weiterentwicklung der digitalen Gesundheitsanwendung.",
      "detailsUrl": null,
      "orderIndex": 1,
      "isAgreeable": true
    },
    {
      "versionId": "ef95e463-c1d4-4d91-b72d-81502fb063af",
      "type": "PRIVACY_POLICY",
      "isRequired": false,
      "title": "Privacy Policy Information",
      "text": "Du kannst in unseren Datenschutzhinweisen nachlesen, wie wir deine Daten verarbeiten.",
      "detailsUrl": "https://sleepq.de/legal/datenschutz-app",
      "orderIndex": 2,
      "isAgreeable": false
    }
  ]
}

필드	타입	설명	예시	필수 (Yes/No)
`items`	array	활성화된 약관 목록 (이용약관, 동의 항목 등)	-	Yes
`items[].versionId`	string	약관 버전 고유 식별자	`b8a961f2-6e29-44f7-a7cd-67005d177362`	Yes
`items[].type`	string	약관 타입 (`TERMS`, `CONSENT`, `MARKETING` 등)	`CONSENT`	Yes
`items[].isRequired`	boolean	필수 약관 여부	`true`	Yes
`items[].title`	string	약관 이름 번역 (agreements_translations.name)	`Consent for Data Processing...`	Yes
`items[].text`	string	약관 요약 텍스트	`I allow the processing of data...`	Yes
`items[].detailsUrl`	string	약관 전문을 확인할 수 있는 URL	`https://www.weltcorp.com/consent/v1.0`	Yes
`items[].orderIndex`	number	동의 항목 순서 인덱스 (type 별 default 값 존재)	0	No
`items[].isAgreeable`	boolean	동의 가능 여부. `true`이면 동의 체크박스를 표시하고, `false`이면 정보 표시 전용	`true`	Yes
`privacyPolicy`	object	개인정보처리방침 정보	-	Yes
`privacyPolicy.versionId`	string	개인정보처리방침 버전 고유 식별자	`f7652384-4224-4b57-923d-58446257dbb8`	Yes
`privacyPolicy.type`	string	항상 `PRIVACY_POLICY`	`PRIVACY_POLICY`	Yes
`privacyPolicy.text`	string	개인정보처리방침 요약 텍스트	`You can read in our privacy policy...`	Yes
`privacyPolicy.detailsUrl`	string	개인정보처리방침 전문을 확인할 수 있는 URL	`https://www.weltcorp.com/privacy/v1.0`	Yes

401 Unauthorized - 인증 실패

{
  "code": 1000,
  "message": "Invalid app token format or signature",
  "detail": "Unauthorized"
}

500 Internal Server Error - 서버 내부 오류

예시: 일반적인 서버 오류 (SERVER_ERROR - 1007)

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

설명

이 API는 앱 설정 화면에서 사용자가 확인할 수 있는 약관 목록을 제공합니다.
주요 처리 단계:
1. 토큰을 통한 인증 (앱 토큰 또는 액세스 토큰)
2. 요청 언어에 따른 약관 번역 조회
3. 현재 활성화된 약관 목록 조회
4. 사용자 로그인 상태 확인 (액세스 토큰인 경우)
5. 사용자별 동의 상태 조회 (로그인된 경우만)
인증 방식:
- 앱 토큰: 로그인하지 않은 상태에서도 약관 목록 조회 가능, isAgreed 필드는 null
- 액세스 토큰: 로그인한 사용자의 실제 동의 상태를 포함하여 반환
언어 지원:
- Accept-Language 헤더를 통해 언어 선택 가능
- 지원 언어: de-DE (독일어, 기본값), ko-KR (한국어), en-US (영어)
약관 타입:
- CONSENT_AGE_VERIFICATION: 만 14세 이상 확인 동의
- TERMS: 서비스 이용 약관
- PRIVACY_POLICY: 개인정보 처리방침
- CONSENT_PERSONAL_DATA: 개인정보 수집·이용 동의
- CONSENT_SENSITIVE_DATA: 민감정보 수집·이용 동의
- CONSENT_SENSITIVE_DATA_HEALTH: 건강정보(민감정보) 수집·이용 동의
- CONSENT: 일반 동의 (기존 호환성 유지)

사용 예시

액세스 토큰으로 약관 목록 조회 (로그인 후)

curl -X GET "https://api.example.com/v1/users/agreements" \
  -H "Authorization: Bearer {{USER_ACCESS_TOKEN}}" \
  -H "Accept-Language: ko-KR"

참고사항

약관 전문 확인: detailsUrl을 통해 약관의 전체 내용을 확인할 수 있습니다.
언어별 번역: 각 언어별로 번역된 약관 텍스트가 제공됩니다.

변경 이력

버전	날짜	작성자	변경 내용
0.1.0	2025-10-13	jeff@weltcorp.com	최초 문서 작성
0.1.1	2025-10-29	jeff@weltcorp.com	ResponseDto 업데이트
0.62.0	2025-12-30	pibi@weltcorp.com	orderIndex, 약관 타입 업데이트
0.63.0	2026-01-05	pibi@weltcorp.com	title 필드 설명 추가
0.67.0	2026-02-23	jeff@weltcorp.com	isAgreeable 필드 추가

약관 목록 조회​

Headers​

Request Body​

Responses​

설명​

사용 예시​

액세스 토큰으로 약관 목록 조회 (로그인 후)​

참고사항​

변경 이력​