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

게스트 등록 API

게스트 등록 API는 약관 동의를 기반으로 임시 게스트 계정을 발급합니다. 게스트 계정은 제한된 신원 수준(Identity Level)으로 서비스의 일부 기능을 체험할 수 있으며, 추후 정식 사용자로 업그레이드할 수 있습니다.

공통 요청 헤더

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

참고

게스트 등록을 위해서는 먼저 앱 인증을 통해 appToken을 획득해야 합니다.

게스트 등록​

앱 토큰과 필수 약관 동의를 검증하고 게스트 계정을 발급합니다.

  • HTTP Method: POST
  • Path: /v1/auth/guest/register (API_PREFIX 기본값이 v1이며 환경에 따라 변경 가능)
  • 인증: appToken 필요 (Authorization: Bearer {appToken})

Headers​

HeaderTypeDescriptionRequired
Authorizationstring앱 인증 토큰 (Bearer {appToken})Yes
Content-Typeapplication/json요청 본문 형식을 지정합니다.Yes
User-AgentstringUser-Agent 헤더 (format: <product>/<version> (<platform>; <os>; <device>; <channel>; locale/<locale>))Yes

User-Agent 예시:

User-Agent: dha-sleep-app/2.3.1 (iOS; iOS 17.5; iPhone14,5; AppStore; locale/ko-KR)

User-Agent 헤더에서 다음 정보를 자동으로 추출합니다:

  • region: locale에서 추출 (예: ko-KR → KR)
  • platform, appVersion, osVersion, model: 디바이스 정보

Request Body​

필수 약관 포함

agreements 배열에는 통합 동의 항목 조회 API에서 반환되는 items 배열 중 isRequired: true인 항목의 동의가 포함되어야 합니다.

참고: privacyPolicy 객체는 별도로 표시되며, agreements 배열에 포함할 필요가 없습니다. 개인정보 처리방침은 UI에서 사용자에게 표시만 되고, 명시적 동의 항목으로 검증되지 않습니다.

{
  "agreements": [
    { "versionId": "9f8a7b6c-5d4e-3f2g-1h0i-j9k8l7m6n5o4", "isAgreed": true },
    { "versionId": "a1b2c3d4-5e6f-7g8h-9i0j-k1l2m3n4o5p6", "isAgreed": true },
    { "versionId": "marketing-agreement-version-id", "isAgreed": false }
  ],
  "deviceUuid": "e8e53358-c282-4f69-89c4-bae40f0b7587",
  "profile": {
    "language": "ko-KR",
    "timezone": {
      "id": "Asia/Seoul",
      "offsetInMinutes": 540
    }
  }
}
필드타입설명필수
agreementsarray약관 동의 목록 (정식 회원가입과 동일한 형식). 통합 동의 항목 조회를 통해 획득한 약관의 versionId와 동의 여부를 포함합니다.Yes
agreements[].versionIdstring약관 버전 ID (예: 9f8a7b6c-5d4e-3f2g-1h0i-j9k8l7m6n5o4)Yes
agreements[].isAgreedboolean동의 여부 (true 또는 false)Yes
deviceUuidstring디바이스 UUID. 앱 인증 API의 deviceId.uuid와 동일한 값 사용Yes
profileobject사용자 프로필 정보 (언어, 시간대) - 정식 회원가입과 동일한 형식Yes
profile.languagestring사용자 언어 설정 (예: ko-KR, de-DE, en-US)Yes
profile.timezoneobject사용자 시간대 설정Yes
profile.timezone.idstring시간대 ID (예: Asia/Seoul, Europe/Berlin)Yes
profile.timezone.offsetInMinutesnumberUTC 기준 시간대 오프셋 (분 단위, 예: 540은 UTC+9)Yes

Responses​

등록 후 로그인 필요

게스트 등록 성공 후에는 별도의 게스트 로그인 API를 호출하여 인증 토큰을 발급받아야 합니다. 이는 정식 회원가입 API(/v1/auth/register)와 동일한 패턴입니다.

201 Created - 게스트 계정 발급 성공
{
  "success": true
}
필드타입설명필수
successboolean게스트 등록 성공 여부를 나타냅니다.Yes
등록 후 로그인 필요

게스트 등록 API는 계정 생성만 수행합니다. 토큰 발급 및 상세 정보는 게스트 로그인 API를 통해 획득합니다.

400 Bad Request - 잘못된 요청

필수 필드 누락, 유효하지 않은 약관 버전 등 다양한 원인으로 발생할 수 있습니다.

예시: 디바이스 ID 오류

{
  "code": 2011,
  "message": "INVALID_DEVICE_ID",
  "detail": "디바이스 ID가 유효하지 않거나 필수 필드가 누락되었습니다",
  "errors": [
    {
      "field": "device.uuid",
      "message": "device.uuid는 필수입니다."
    }
  ]
}

예시: 약관 버전을 찾을 수 없음

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

기타 BadRequestException으로 변환될 수 있는 다양한 유효성 검사 오류가 발생할 수 있습니다.

401 Unauthorized - 인증 실패 (예: 유효하지 않은 앱 토큰)
{
  "code": 2051,
  "message": "INVALID_TOKEN",
  "detail": "토큰이 유효하지 않습니다"
}
필드타입설명필수
codenumber애플리케이션 오류 코드Yes
messagestring오류 메시지 코드Yes
detailstring사용자 친화적인 오류 설명Yes
403 Forbidden - 접근 차단 (예: 블랙리스트 디바이스)
{
  "code": 2013,
  "message": "DEVICE_BLACKLISTED",
  "detail": "해당 디바이스는 접근이 차단되었습니다"
}
412 Precondition Failed - 사전 조건 실패 (예: 필수 약관 미동의)
{
  "code": 2080,
  "message": "REQUIRED_AGREEMENTS_NOT_AGREED",
  "detail": "필수 약관에 동의하지 않았습니다",
  "metadata": {
    "missingAgreements": [
      "9f8a7b6c-5d4e-3f2g-1h0i-j9k8l7m6n5o4"
    ]
  }
}
429 Too Many Requests - 요청 제한 초과
{
  "code": 2040,
  "message": "RATE_LIMIT_EXCEEDED",
  "detail": "요청 횟수가 제한을 초과했습니다"
}
500 Internal Server Error - 서버 내부 오류
{
  "code": 2000,
  "message": "SERVER_ERROR",
  "detail": "서버 내부 오류"
}

설명​

전체 프로세스 가이드

게스트 등록 프로세스, 제한사항, Step-up 인증 등 전체 흐름은 게스트 등록 프로세스 가이드를 참고하세요.

약관 동의 처리​

  • agreements 배열에는 모든 약관(필수/선택)의 versionId와 동의 여부가 포함됩니다.
  • 각 약관의 isAgreed를 true 또는 false로 명시적으로 지정합니다.
  • 필수 약관의 isAgreed가 false인 경우 등록이 실패합니다.
  • 약관 목록은 통합 동의 항목 조회 API를 통해 조회할 수 있습니다.
  • 정식 회원가입 API와 동일한 형식을 사용하여 일관성을 유지합니다.
  • privacyPolicy 객체는 UI에서 별도로 표시되며, agreements 배열에 포함하지 않아도 됩니다.

디바이스 정보​

  • device 객체는 필수이며, 디바이스 식별에 사용됩니다.
  • device.uuid: 디바이스 고유 식별자 (필수)
    • 앱 인증 API의 deviceId.uuid와 동일한 값을 사용합니다.
    • 디바이스 보안 검증은 앱 인증 단계에서 deviceIdHash를 통해 이미 완료되었으므로, 게스트 등록에서는 uuid만 필요합니다.

프로필 정보​

  • profile 객체는 필수이며, 정식 회원가입과 동일한 형식을 사용합니다.
  • profile.language: 사용자 언어 설정 (필수)
    • 예: ko-KR (한국어), de-DE (독일어), en-US (영어)
    • 앱 콘텐츠 언어 및 알림 언어에 사용됩니다.
  • profile.timezone: 사용자 시간대 설정 (필수)
    • id: IANA 시간대 식별자 (예: Asia/Seoul, Europe/Berlin)
    • offsetInMinutes: UTC 기준 오프셋 (분 단위, 예: 540 = UTC+9)
    • 수면 기록, 알림 스케줄링 등 시간 기반 기능에 사용됩니다.
프로필 정보 수집

프로필 정보는 User-Agent 헤더에서 신뢰할 수 없으므로 클라이언트에서 명시적으로 수집해야 합니다.

  • language: 디바이스 설정 또는 사용자 선택을 통해 획득
  • timezone: 디바이스의 시스템 시간대 정보를 통해 획득

지역 코드 자동 추출​

User-Agent 헤더의 locale 정보에서 지역 코드를 자동으로 추출합니다:

  • locale/ko-KR → region: "KR" (한국 - K-FDA 규제 적용)
  • locale/de-DE → region: "DE" (독일 - GDPR, DiGA 규제 적용)
  • locale/en-US → region: "US" (미국 - FDA 규제 적용)

지역별로 다른 약관, 정책, 규제가 적용됩니다.

등록 후 로그인​

게스트 등록이 완료되면 게스트 로그인 API를 호출하여 인증 토큰을 발급받아야 합니다. 이는 정식 회원가입과 동일한 패턴으로, 등록(register)과 로그인(login)이 분리되어 있습니다.

로그인 성공 시 발급받은 accessToken을 이후 API 요청의 Authorization 헤더에 포함하여 사용합니다:

Authorization: Bearer {accessToken}

refreshToken을 사용하여 accessToken이 만료되기 전에 새로운 토큰을 발급받을 수 있습니다.

오류 참조​

오류 코드와 메시지는 Swagger 스키마의 응답 예시를 우선 참고하세요.

공통 오류 응답 형식​

모든 오류 응답은 다음과 같은 공통 형식을 따릅니다. 특정 오류에 대한 errors나 metadata 필드는 선택적으로 포함될 수 있습니다.

{
  "code": 2000,
  "message": "ERROR_CODE_NAME",
  "detail": "사용자 친화적 오류 메시지",
  "metadata": {
    "exampleKey": "exampleValue"
  }
}
필드타입필수설명
codenumberY애플리케이션 오류 코드
messagestringY오류 메시지
detailstringN상세 설명
metadataobjectN오류 관련 추가 메타데이터 (선택 사항)