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

액세스 코드 관리 API

참고: 이 문서에 설명된 모든 API는 dta-wir-medi-api 애플리케이션에 구현되어 있습니다. (Go)

개요​

액세스 코드 관리 API는 환자가 앱에 접근하기 위한 액세스 코드를 생성, 발송, 관리하는 기능을 제공합니다.

주요 기능​

  • 액세스 코드 생성: 환자 등록을 위한 액세스 코드 생성
  • 액세스 코드 생성 및 알림 전송: 액세스 코드를 생성하고 이메일/SMS로 전송
  • 액세스 코드 상태 업데이트: 액세스 코드 활성화/비활성화
[POST] /v1/accesscodes - 액세스 코드 생성

액세스 코드 생성

환자 등록을 위한 액세스 코드를 생성합니다.

  • HTTP Method: POST
  • 인증: 액세스 토큰 (accessToken) 필요

Headers​

HeaderTypeDescriptionRequired
AuthorizationBearer {accessToken}사용자 인증을 통해 발급받은 액세스 토큰 입니다.✔
Content-Typeapplication/json요청 본문 형식✔

Request Body​

필드타입설명RequiredDefault
accountIdnumber담당 의료진 계정 ID✔-
siteIdnumber사이트 ID✔-
groupIdnumber그룹 ID✔-
registrationChannelIdnumber등록 채널 ID✗1 (SleepQDashboard)
validDaysnumber유효 기간 (일)✗-

Request Body 예시​

{
  "accountId": 10,
  "siteId": 1,
  "groupId": 5,
  "registrationChannelId": 1,
  "validDays": 30
}

Responses​

Http Status Code설명Error Code(s)
200 OK액세스 코드 생성 성공-
400 Bad Request잘못된 요청BAD_REQUEST (40000)
401 Unauthorized인증 실패UNAUTHORIZED (40100)
500 Internal Server Error서버 내부 오류INTERNAL_SERVER_ERROR (50000)
200 OK - 성공
{
  "accesscode": "ABC123XYZ",
  "expiresAt": "2024-02-15 10:30:00 +0000 UTC"
}
필드타입설명
accesscodestring생성된 액세스 코드
expiresAtstring만료 일시 (UTC)
400 Bad Request - 잘못된 요청
{
  "status": 400,
  "code": 40000,
  "message": "요청한 정보가 유효하지 않습니다."
}
401 Unauthorized - 인증 실패
{
  "status": 401,
  "code": 40100,
  "message": "UNAUTHORIZED"
}
500 Internal Server Error - 서버 내부 오류
{
  "status": 500,
  "code": 50000,
  "message": "INTERNAL_SERVER_ERROR"
}
[POST] /v1/accesscodes/notification - 액세스 코드 생성 및 알림 전송

액세스 코드 생성 및 알림 전송

환자 등록을 위한 액세스 코드를 생성하고 이메일 또는 SMS로 전송합니다.

  • HTTP Method: POST
  • 인증: 액세스 토큰 (accessToken) 필요

Headers​

HeaderTypeDescriptionRequired
AuthorizationBearer {accessToken}사용자 인증을 통해 발급받은 액세스 토큰 입니다.✔
Content-Typeapplication/json요청 본문 형식✔

Request Body​

필드타입설명RequiredDefault
accountIdnumber담당 의료진 계정 ID✔-
siteIdnumber사이트 ID✔-
groupIdnumber그룹 ID✔-
emailstring수신자 이메일 (이메일 발송 시)✗-
phonestring수신자 전화번호 (SMS 발송 시)✗-
notificationMethodstring (enum)알림 방법 (EMAIL, SMS, KAKAOTALK)✗EMAIL
registrationChannelIdnumber등록 채널 ID✗1 (SleepQDashboard)
saveAccountIdboolean계정 ID 저장 여부✗-
validDaysnumber유효 기간 (일)✗-

notificationMethod 값:

  • EMAIL (1): 이메일로 발송
  • SMS (2): SMS로 발송
  • KAKAOTALK (3): 카카오톡으로 발송
  • Unknown (0): 기본값 (EMAIL로 처리)

Request Body 예시​

{
  "accountId": 10,
  "siteId": 1,
  "groupId": 5,
  "email": "patient@example.com",
  "notificationMethod": "EMAIL",
  "registrationChannelId": 1,
  "saveAccountId": true,
  "validDays": 30
}

Responses​

Http Status Code설명Error Code(s)
200 OK액세스 코드 생성 및 발송 성공-
400 Bad Request잘못된 요청BAD_REQUEST (40000)
401 Unauthorized인증 실패UNAUTHORIZED (40100)
500 Internal Server Error서버 내부 오류INTERNAL_SERVER_ERROR (50000)
200 OK - 성공
{
  "accesscode": "ABC123XYZ",
  "accesscodeCreatedAt": "2024-01-15 10:30:00 +0000 UTC",
  "accesscodeExpiresAt": "2024-02-15 10:30:00 +0000 UTC",
  "sent": true
}
필드타입설명
accesscodestring생성된 액세스 코드
accesscodeCreatedAtstring생성 일시 (UTC)
accesscodeExpiresAtstring만료 일시 (UTC)
sentboolean알림 발송 성공 여부

처리 로직:

  1. 액세스 코드 생성
  2. 지정된 방법(이메일/SMS)으로 알림 전송
  3. saveAccountId가 true인 경우 계정 정보 저장
400 Bad Request - 잘못된 요청
{
  "status": 400,
  "code": 40000,
  "message": "요청한 정보가 유효하지 않습니다."
}

발생 가능한 에러 메시지:

  • 이메일과 전화번호가 모두 제공되지 않은 경우
  • 알림 방법이 유효하지 않은 경우
401 Unauthorized - 인증 실패
{
  "status": 401,
  "code": 40100,
  "message": "UNAUTHORIZED"
}
500 Internal Server Error - 서버 내부 오류
{
  "status": 500,
  "code": 50000,
  "message": "INTERNAL_SERVER_ERROR"
}
[PATCH] /v1/patients/accesscodes/{accesscodeId}/status - 액세스 코드 상태 업데이트

액세스 코드 상태 업데이트

[클라이언트 수정 필요]
asis: /v1/patients/accesscodes/{accesscodeId}/status
tobe: /v1/users/accesscodes/{accesscodeId}/status

액세스 코드의 상태를 활성화 또는 비활성화합니다.

  • HTTP Method: PATCH
  • 인증: 액세스 토큰 (accessToken) 필요

Headers​

HeaderTypeDescriptionRequired
AuthorizationBearer {accessToken}사용자 인증을 통해 발급받은 액세스 토큰 입니다.✔
Content-Typeapplication/json요청 본문 형식✔

Path Parameters​

필드타입설명Required
accesscodeIdnumber액세스 코드 ID✔

Request Body​

필드타입설명Required
statusnumber상태 (1: 활성, 0: 비활성)✔

Request Body 예시​

{
  "status": 0
}

Responses​

Http Status Code설명Error Code(s)
200 OK상태 업데이트 성공-
400 Bad Request잘못된 요청BAD_REQUEST (40000)
401 Unauthorized인증 실패UNAUTHORIZED (40100)
404 Not Found액세스 코드 미발견NOT_FOUND (40400)
500 Internal Server Error서버 내부 오류INTERNAL_SERVER_ERROR (50000)
200 OK - 성공
{
  "success": true
}
필드타입설명
successboolean성공 여부 (true)
400 Bad Request - 잘못된 요청
{
  "status": 400,
  "code": 40000,
  "message": "유효하지 않은 상태 값입니다."
}
401 Unauthorized - 인증 실패
{
  "status": 401,
  "code": 40100,
  "message": "UNAUTHORIZED"
}
404 Not Found - 액세스 코드 미발견
{
  "status": 404,
  "code": 40400,
  "message": "액세스 코드를 찾을 수 없습니다."
}
500 Internal Server Error - 서버 내부 오류
{
  "status": 500,
  "code": 50000,
  "message": "INTERNAL_SERVER_ERROR"
}

등록 채널 ID​

ID채널명설명
1SleepQDashboardSleepQ 대시보드
기타추가 채널-