본문으로 건너뛰기
버전: 개발 버전 (최신)

약관 동의 API

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

통합 동의 항목 조회​

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

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

Headers​

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

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", // 약관 Version ID (UUID 형식)
      "type": "TERMS", // 약관 항목
      "isRequired": true, // 필수 동의 여부
      "title": "Nutzungsbedingungen", // 약관 이름 번역 (agreements_translations.name)
      "text": "Ich stimme den Nutzungsbedingungen gemäß der DiGAV § 4 Abs. 2 zu.", // 현지화된 텍스트
      "detailsUrl": "https://www.weltcorp.com", // 관련 설명 페이지 URL
      "orderIndex": 0,
      "isAgreeable": true // 동의 가능 여부 (동의 체크박스 표시)
    },
    {
      "versionId": "2222222225d4e-3f2g-1h0i-j8k8l7m6n5o4", // 동의 Version ID (UUID 형식)
      "type": "CONSENT", // 동의 항목
      "isRequired": false,
      "title": "Datenverarbeitung zur Verbesserung", // 동의 항목 이름 번역
      "text": "Ich erlaube die Verarbeitung der zu der dauerhaften Gewährleistung der technischen Funktionsfähigkeit...", // 현지화된 텍스트
      "detailsUrl": "https://www.weltcorp.com", // 관련 설명 페이지 URL
      "orderIndex": 1,
      "isAgreeable": true // 동의 가능 여부 (동의 체크박스 표시)
    }
    // ... 다른 필요한 약관 또는 동의 항목 추가 ...
  ],
  "privacyPolicy": {
    "versionId": "2222222225d4e-3f2g-1h0i-j8k8l7m6n5o4", // Privacy Policy version ID (UUID 형식)
    "type": "PRIVACY_POLICY", // 개인 정보 처리 항목
    "title": "Datenschutzhinweise", // 약관 이름 번역 (agreements_translations.name)
    "text": "Du kannst in unseren Datenschutzhinweisen nachlesen, wie wir deine Daten verarbeiten.", // 현지화된 텍스트
    "detailsUrl": "https://www.weltcorp.com", // 설명 페이지 URL
    "isAgreeable": false // 개인정보처리방침은 동의 항목이 아님 (정보 표시 전용)
  }
}
필드타입설명필수
itemsarray조회된 약관 및 동의 항목 목록 배열Yes
privacyPolicyobject개인정보 처리방침 정보 객체Yes

items 배열 내 객체 필드 정보​

필드타입설명필수
versionIdstring항목 버전 고유 IDYes
typestring항목 유형: TERMS, CONSENT, PRIVACY_POLICY 중 하나 (AgreementType 참조)Yes
isRequiredboolean필수 여부Yes
titlestring약관 이름 번역 (agreements_translations.name)Yes
textstring약관 내용 (현지화된 텍스트)Yes
detailsUrlstring상세 내용 URL (null일 수 있음)No
orderIndexnumber동의 항목 순서 인덱스 (type 별 default 값 존재)No
isAgreeableboolean동의 가능 여부. true이면 동의 체크박스를 표시하고, false이면 정보 표시 전용Yes

privacyPolicy 객체 필드 정보​

필드타입설명필수
versionIdstring개인정보처리방침 버전 고유 IDYes
typestring항목 유형: PRIVACY_POLICY (AgreementType 참조)Yes
titlestring약관 이름 번역 (agreements_translations.name)Yes
textstring약관 내용Yes
detailsUrlstring상세 내용 URLYes
isAgreeableboolean항상 false (개인정보처리방침은 동의 항목이 아닌 정보 표시 전용)Yes
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

설명​

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

항목 타입별 특징​

  1. 약관(TERMS) 항목 (AgreementType 참조):

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

  2. 동의(CONSENT) 항목 (AgreementType 참조):

    • versionId는 UUID 형식의 동의 버전 ID입니다.
    • isRequired는 항상 false입니다 (모든 동의 항목은 선택적).
    • text는 Accept-Language 헤더에 따라 현지화된 동의 문구입니다.
    • detailsUrl은 동의와 관련된 추가 정보를 볼 수 있는 URL이거나 null입니다.

  3. 개인정보 처리방침(PRIVACY_POLICY) 항목 (AgreementType 참조):

    • privacyPolicy 객체로 제공되는 개인정보 처리방침 정보입니다.
    • versionId는 UUID 형식의 개인정보 처리방침 버전 ID입니다.
    • text는 Accept-Language 헤더에 따라 현지화된 개인정보 처리방침 제목입니다.
    • detailsUrl은 개인정보 처리방침 전문을 볼 수 있는 URL입니다.

변경 이력​

버전날짜작성자변경 내용
0.62.02025-12-30pibi@weltcorp.comorderIndex 업데이트
0.67.02026-02-23jeff@weltcorp.comisAgreeable 필드 추가