본문으로 건너뛰기

endpoints

관련 문서​

AccessCode API 명세서

관련 문서​

목차​

1. 개요​

AccessCode 도메인의 API는 불면증 진단을 받은 환자의 앱 회원가입을 위한 인증 코드의 생성, 검증, 관리를 위한 엔드포인트를 제공합니다. 모든 API는 RESTful 원칙을 따르며, 도메인 이벤트를 통해 다른 바운디드 컨텍스트와 상호작용합니다.

기본 URL: https://api.example.com/v1/access-codes

2. 공통 사항​

2.1 인증 및 권한​

  • Bearer 토큰 인증 사용: Authorization: Bearer {token}
  • 관리자 API는 추가로 X-Admin-Token 헤더 필요
  • 권한 검증은 모든 요청에서 수행됨
  • IAM 정책 기반 접근 제어 적용

2.2 엔드포인트 접근 권한 매트릭스​

엔드포인트System AdminIAM AdminService AccountRegular User
POST /v1/access-codes/permissions/validate✓✓✓-
POST /v1/access-codes/permissions/assign✓✓ (범위 내)--
DELETE /v1/access-codes/permissions/{permissionId}✓✓ (범위 내)--
GET /v1/access-codes/permissions✓✓ (범위 내)✓-
POST /v1/access-codes✓✓ (범위 내)--
POST /v1/access-codes/validate✓✓✓✓
POST /v1/access-codes/{codeId}/use✓-✓-
POST /v1/access-codes/batch✓✓ (범위 내)--
GET /v1/access-codes/personal-data/{userId}✓✓ (범위 내)-✓ (자신만)
PATCH /v1/access-codes/personal-data/{userId}✓✓ (범위 내)-✓ (자신만)
DELETE /v1/access-codes/personal-data/{userId}✓--✓ (자신만)
POST /v1/access-codes/personal-data/{userId}/restrict✓--✓ (자신만)
GET /v1/access-codes/personal-data/{userId}/export✓--✓ (자신만)
GET /v1/access-codes/consent/{userId}✓✓ (범위 내)✓✓ (자신만)
PUT /v1/access-codes/consent/{userId}✓--✓ (자신만)
GET /v1/access-codes/time-machine/status✓✓✓-
GET /v1/access-codes/time-machine/{codeId}✓✓✓-

참고:

  • ✓: 접근 가능
  • -: 접근 불가
  • (범위 내): 할당된 조직/팀 범위 내에서만 접근 가능
  • (자신만): 자신의 데이터에만 접근 가능

2.3 응답 형식​

2.3.1 성공 응답 (단일 객체)​

{
  "id": "user123",
  "name": "John Doe",
  "email": "john@example.com"
}

2.3.2 성공 응답 (컬렉션)​

{
  "items": [
    {
      "id": "user123",
      "name": "John Doe",
      "email": "john@example.com"
    },
    {
      "id": "user456",
      "name": "Jane Smith",
      "email": "jane@example.com"
    }
  ],
  "metadata": {
    "totalCount": 42,
    "currentPage": 1,
    "pageSize": 10,
    "totalPages": 5
  }
}

2.3.3 에러 응답​

{
  "code": 1001,
  "message": "INVALID_INPUT",
  "detail": "Invalid input parameters",
  "errors": [
    {
      "field": "email",
      "message": "올바른 이메일 형식이 아닙니다"
    }
  ]
}

2.4 개인정보 보호 헤더​

모든 API 요청에 다음 헤더 포함 필요:

Privacy-Policy-Version: 2025-04-16
Consent-Token: {consent_token}
Data-Processing-Purpose: USER_AUTHENTICATION

3. API 엔드포인트​

3.1 권한 관리 API​

📌 기술 문서: 권한 관리 구현 가이드 | 권한 관리 명세

권한 관리 API는 Access Code 생성 및 관리를 위한 사용자 권한을 관리하는 기능을 제공합니다. IAM과 연동하여 세밀한 접근 제어를 지원합니다.

3.1.1 권한 검증​

  • HTTP 메서드: POST
  • 경로: /v1/access-codes/permissions/validate
  • Headers:
    • Content-Type: application/json
    • Authorization: Bearer {token}
요청 본문​
{
  "accessCodeId": "code_789",
  "action": "CREATE_CODE",
  "scope": "org_123",
  "resource": "access_code"
}
응답 (200 OK)​
{
  "allowed": true,
  "scope": "org_123",
  "permissions": ["CREATE_CODE", "READ_CODE"]
}

3.1.2 권한 할당​

  • HTTP 메서드: POST
  • 경로: /v1/access-codes/permissions/assign
  • Headers:
    • Content-Type: application/json
    • Authorization: Bearer {token}
    • X-Admin-Token: {admin_token}
요청 본문​
{
  "userId": "user_123",
  "scope": "org_123",
  "permissions": ["CREATE_CODE", "READ_CODE"],
  "expiresAt": 1735689599000
}
응답 (201 Created)​
{
  "id": "perm_456",
  "userId": "user_123",
  "scope": "org_123",
  "permissions": ["CREATE_CODE", "READ_CODE"],
  "grantedAt": 1711706400000,
  "expiresAt": 1735689599000
}

3.1.3 권한 회수​

  • HTTP 메서드: DELETE
  • 경로: /v1/access-codes/permissions/{permissionId}
  • Headers:
    • Authorization: Bearer {token}
    • X-Admin-Token: {admin_token}
응답 (200 OK)​
{
  "id": "perm_456",
  "revokedAt": 1711706400000
}

3.1.4 권한 조회​

  • HTTP 메서드: GET
  • 경로: /v1/access-codes/permissions
  • Headers:
    • Authorization: Bearer {token}
  • Query Parameters:
    • userId: 사용자 ID (선택)
    • scope: 권한 범위 (선택)
    • page: 페이지 번호 (기본값: 1)
    • size: 페이지 크기 (기본값: 10)
응답 (200 OK)​
{
  "items": [
    {
      "id": "perm_456",
      "userId": "user_123",
      "scope": "org_123",
      "permissions": ["CREATE_CODE", "READ_CODE"],
      "grantedAt": 1711706400000,
      "expiresAt": 1735689599000
    }
  ],
  "metadata": {
    "totalCount": 42,
    "currentPage": 1,
    "pageSize": 10,
    "totalPages": 5
  }
}

3.2 Access Code 관리 API​

📌 기술 문서: Access Code 관리 구현 가이드 | Access Code 관리 명세

Access Code 관리 API는 앱 사용자 등록을 위한 코드의 생성, 검증, 사용 등 전체 생명주기를 관리하는 기능을 제공합니다.

3.2.1 코드 생성​

  • HTTP 메서드: POST
  • 경로: /v1/access-codes
  • Headers:
    • Authorization: Bearer {token}
    • X-Admin-Token: {admin_token}
    • Privacy-Policy-Version: 2025-04-16
    • Data-Processing-Purpose: USER_AUTHENTICATION
    • Content-Type: application/json
요청 본문​
{
  "type": "TREATMENT",
  "creatorId": "user_123",
  "accountId": "account_456",
  "treatmentPeriod": 90,
  "groupId": "group_therapy_A",
  "planId": "plan.therapeutic",
  "usagePeriod": 90,
  "email": "m***@example.com",
  "registrationChannel": "WEB",
  "randomizationCode": "RND123",
  "deliveryMethod": "EMAIL",
  "timeMachineOptions": {
    "useTimeMachine": true,
    "virtualTimeStartDate": 1710924000000,
    "expirationBasedOnVirtualTime": true,
    "synchronizeWithUserRegistration": true,
    "timeMachineReason": "테스트 목적"
  }
}
응답 (201 Created)​
{
  "id": "code_789",
  "code": "AB12CD34EF56GH78",
  "expiresAt": 1713602400000,
  "status": "UNUSED",
  "createdAt": 1710924000000,
  "timeMachineEnabled": true,
  "virtualTimeStartDate": 1710924000000
}

3.2.2 코드 검증​

  • HTTP 메서드: POST
  • 경로: /v1/access-codes/validate
  • Headers:
    • Content-Type: application/json
요청 본문​
{
  "code": "AB12CD34EF56GH78",
  "deviceId": "DEVICE_001"
}
응답 (200 OK)​
{
  "isValid": true,
  "codeInfo": {
    "id": "code_789",
    "treatmentPeriod": 90,
    "expiresAt": 1713602400000
  }
}

3.2.3 코드 사용​

  • HTTP 메서드: POST
  • 경로: /v1/access-codes/{codeId}/use
  • Headers:
    • Content-Type: application/json
    • Authorization: Bearer {service_token}
요청 본문​
{
  "userId": "user_123",
  "deviceId": "DEVICE_001",
  "consent": {
    "termsOfServiceDiGAV": true,
    "dataProcessingForImprovement": false
  },
  "timeMachineOptions": {
    "useTimeMachine": true,
    "virtualTimeStartDate": 1711374600000,
    "overrideCodeSettings": false,
    "reason": "사용자 등록 처리"
  }
}
응답 (200 OK)​
{
  "id": "code_789",
  "status": "USED",
  "usedAt": 1711374600000,
  "userId": "user_123",
  "timeMachineEnabled": true,
  "virtualTimeStartDate": 1711374600000
}

3.2.4 일괄 코드 생성​

  • HTTP 메서드: POST
  • 경로: /v1/access-codes/batch
  • Headers:
    • Content-Type: application/json
    • Authorization: Bearer {token}
    • X-Admin-Token: {admin_token}
요청 본문​
{
  "count": 10,
  "type": "TREATMENT",
  "creatorId": "user_123",
  "accountId": "account_456",
  "treatmentPeriod": 90,
  "usagePeriod": 90,
  "groupId": "group_therapy_A",
  "planId": "plan.therapeutic",
  "registrationChannel": "WEB",
  "timeMachineOptions": {
    "useTimeMachineForAll": true,
    "commonVirtualTimeStartDate": 1710924000000,
    "expirationBasedOnVirtualTime": true,
    "reason": "일괄 테스트 코드 생성"
  }
}
응답 (201 Created)​
{
  "items": [
    {
      "id": "code_789",
      "code": "AB12CD34EF56GH78",
      "expiresAt": 1713602400000,
      "timeMachineEnabled": true,
      "virtualTimeStartDate": 1710924000000
    }
    // ... other items
  ],
  "metadata": {
    "totalCount": 10,
    "currentPage": 1,
    "pageSize": 10,
    "totalPages": 1
  },
  "batchId": "batch_001",
  "timeMachineEnabled": true
}

3.3 개인정보 관리 API​

📌 기술 문서: TBD

개인정보 관리 API는 GDPR 등 개인정보 보호 법규를 준수하기 위한 개인정보 열람, 수정, 삭제, 처리 제한, 이동 기능을 제공합니다.

3.3.1 개인정보 열람​

  • HTTP 메서드: GET
  • 경로: /v1/access-codes/personal-data/{userId}
  • Headers:
    • Authorization: Bearer {token}
    • Privacy-Policy-Version: 2025-04-16

3.3.2 개인정보 수정​

  • HTTP 메서드: PATCH
  • 경로: /v1/access-codes/personal-data/{userId}
  • Headers:
    • Authorization: Bearer {token}
    • Privacy-Policy-Version: 2025-04-16

3.3.3 개인정보 삭제​

  • HTTP 메서드: DELETE
  • 경로: /v1/access-codes/personal-data/{userId}
  • Headers:
    • Authorization: Bearer {token}
    • Privacy-Policy-Version: 2025-04-16

3.3.4 개인정보 처리 제한​

  • HTTP 메서드: POST
  • 경로: /v1/access-codes/personal-data/{userId}/restrict
  • Headers:
    • Authorization: Bearer {token}
    • Privacy-Policy-Version: 2025-04-16

3.3.5 개인정보 이동​

  • HTTP 메서드: GET
  • 경로: /v1/access-codes/personal-data/{userId}/export
  • Headers:
    • Authorization: Bearer {token}
    • Privacy-Policy-Version: 2025-04-16

3.4 동의 관리 API​

📌 기술 문서: TBD

동의 관리 API는 사용자의 개인정보 처리 동의 상태를 조회하고 변경하는 기능을 제공합니다.

3.4.1 동의 상태 조회​

  • HTTP 메서드: GET
  • 경로: /v1/access-codes/consent/{userId}
  • Headers:
    • Authorization: Bearer {token}

3.4.2 동의 설정 변경​

  • HTTP 메서드: PUT
  • 경로: /v1/access-codes/consent/{userId}
  • Headers:
    • Authorization: Bearer {token}
    • Content-Type: application/json
요청 본문​
{
  "consents": {
    "dataProcessing": true,
    "emailMarketing": false,
    "thirdPartySharing": false
  },
  "validUntil": 1742460000000
}

3.5 TimeMachine 통합 API​

📌 기술 문서: TimeMachine 통합 구현 가이드 | TimeMachine 통합 명세

TimeMachine 통합 API는 Access Code의 가상 시간 관리와 TimeMachine 도메인과의 연동을 위한 기능을 제공합니다.

3.5.1 TimeMachine 상태 조회​

  • HTTP 메서드: GET
  • 경로: /v1/access-codes/time-machine/status
  • Headers:
    • Authorization: Bearer {token}
응답 (200 OK)​
{
  "integratedWithTimeMachine": true,
  "totalVirtualTimeAccessCodes": 45,
  "activeVirtualTimeAccessCodes": 32,
  "totalUserRegistrationsWithVirtualTime": 28,
  "averageVirtualTimeOffset": {
    "days": 15,
    "hours": 6,
    "minutes": 30
  }
}

3.5.2 특정 코드의 TimeMachine 정보 조회​

  • HTTP 메서드: GET
  • 경로: /v1/access-codes/time-machine/{codeId}
  • Headers:
    • Authorization: Bearer {token}
응답 (200 OK)​
{
  "codeId": "code_789",
  "timeMachineEnabled": true,
  "virtualTimeStartDate": 1710924000000,
  "expirationBasedOnVirtualTime": true,
  "createdAt": 1710924000000,
  "expiresAt": 1713602400000,
  "realCreatedAt": 1713171600000,
  "realExpiresAt": 1715850000000,
  "virtualTimeOffset": {
    "days": -26,
    "hours": 0,
    "minutes": 0
  },
  "associatedUserRegistration": {
    "userId": "user_123",
    "timeMachineEnabled": true,
    "virtualTimeStartDate": 1710924000000
  }
}

4. 에러 코드​

4.1 공통 에러 코드​

HTTP 상태 코드오류 코드메시지설명대응 방법
4001000INVALID_INPUT입력 데이터가 유효하지 않음입력 데이터를 확인하고 다시 시도
4011001UNAUTHORIZED인증 정보가 제공되지 않음Bearer 토큰을 제공하거나 관리자에게 문의
4031002FORBIDDEN요청한 작업에 대한 권한이 없음권한을 확인하거나 관리자에게 문의

4.2 권한 관련 에러 코드​

HTTP 상태 코드오류 코드메시지설명대응 방법
4032001INVALID_PERMISSION요청한 작업에 대한 권한이 없음권한을 확인하거나 관리자에게 문의
4032002PERMISSION_EXPIRED권한이 만료됨권한을 갱신하거나 관리자에게 문의
4002003INVALID_SCOPE권한 범위가 유효하지 않음권한 범위를 확인하고 다시 시도
4042004SCOPE_NOT_FOUND요청한 권한 범위가 존재하지 않음권한 범위를 확인하고 다시 시도

4.3 Access Code 관련 에러 코드​

HTTP 상태 코드오류 코드메시지설명대응 방법
4003001INVALID_CODE입력한 코드가 유효하지 않음코드를 확인하고 다시 시도
4003002CODE_ALREADY_USED입력한 코드가 이미 사용됨다른 코드를 사용하거나 관리자에게 문의
4003003CODE_EXPIRED입력한 코드가 만료됨새로운 코드를 발급받거나 관리자에게 문의
4093004DUPLICATE_CODE입력한 코드가 이미 존재함고유한 코드를 생성하거나 관리자에게 문의

4.4 TimeMachine 관련 에러 코드​

HTTP 상태 코드오류 코드메시지설명대응 방법
4004001INVALID_VIRTUAL_TIME가상 시간 설정이 유효하지 않음유효한 시간을 설정하고 다시 시도
4094002TIME_MACHINE_DISABLEDTimeMachine 기능이 비활성화됨TimeMachine 기능을 활성화하거나 관리자에게 문의
4004003FUTURE_VIRTUAL_TIME현재보다 미래의 가상 시간으로 설정 불가현재 시간보다 이전 시간으로 설정
4004004VIRTUAL_TIME_TOO_OLD설정 가능한 범위보다 오래된 가상 시간허용된 범위 내의 시간으로 설정
4004005TIME_MACHINE_SYNC_ERRORTimeMachine과의 동기화 중 오류 발생잠시 후 다시 시도하거나 관리자에게 문의

4.5 시스템 에러 코드​

HTTP 상태 코드오류 코드메시지설명대응 방법
5005001DATABASE_ERROR데이터베이스와의 통신 중 오류 발생잠시 후 다시 시도하거나 관리자에게 문의
5035002SERVICE_UNAVAILABLE서비스가 일시적으로 불가능함잠시 후 다시 시도

5. 변경 이력​

버전날짜작성자변경 내용
0.1.02025-03-16bok@weltcorp.com최초 작성
0.2.02025-04-31bok@weltcorp.comauth 도메인 문서 형식에 맞추어 구조 및 스타일 변경
0.3.02025-04-31bok@weltcorp.comAPI 엔드포인트 순서 변경 (Access Code 관리 -> 권한 관리)
0.4.02025-04-31bok@weltcorp.comAPI 엔드포인트 순서 변경 (권한 관리 -> Access Code 관리)
0.5.02025-04-31bok@weltcorp.comPrivacy-Policy-Version 헤더 값 형식을 날짜 기반(2025-04-16)으로 변경
0.6.02025-04-31bok@weltcorp.com개인정보 동의 수집 시점을 코드 생성에서 코드 사용(회원가입) 시점으로 변경
0.7.02025-04-31bok@weltcorp.com회원가입 시 수집하는 동의 항목을 구체적인 독일어 문구 2가지(필수/선택)로 변경