등록 목록 조회 API
참고: 이 문서에 설명된 모든 API는
dta-wir-medi-api애플리케이션에 구현되어 있습니다. (Go)
개요
등록 목록 조회 API는 액세스 코드 및 의무 등록 번호의 발급 이력을 조회하는 기능을 제공합니다.
주요 기능
- 등록 목록 조회: 액세스 코드와 의무 등록 번호의 발급 이력 조회
[GET] /v1/users/registrations - 등록 목록 조회
등록 목록 조회
특정 사이트의 액세스 코드 및 의무 등록 번호 발급 이력을 조회합니다.
- HTTP Method:
GET - 인증: 액세스 토큰 (
accessToken) 필요
[클라이언트 수정 필요]
asis:/v1/patients/registrations
tobe:/v1/users/registrations
Headers
| Header | Type | Description | Required |
|---|---|---|---|
| Authorization | Bearer {accessToken} | 사용자 인증을 통해 발급받은 액세스 토큰 입니다. | ✔ |
Query Parameters
| 필드 | 타입 | 설명 | Required | Default |
|---|---|---|---|---|
| siteId | number | 사이트 ID | ✔ | - |
| filter | string | 필터 조건 (검색 키워드) | ✗ | - |
| page | number | 페이지 번호 (1부터 시작) | ✗ | 1 |
| limit | number | 한 페이지당 항목 수 | ✗ | 10 |
| orderBy | string | 정렬 기준 필드 | ✗ | createdAt |
| desc | boolean | 내림차순 정렬 여부 (true: 내림차순) | ✗ | false |
Request 예시
GET /v1/patients/registrations?siteId=1&page=1&limit=20&orderBy=createdAt&desc=true
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 - 성공
{
"total": 50,
"count": 20,
"data": [
{
"type": "accesscode",
"id": 123,
"data": "patient@example.com",
"accountId": 10,
"accountName": "김의사",
"createdById": 5,
"createdByName": "관리자",
"createdAt": "2024-01-15T10:30:00Z",
"status": 1,
"code": "ABC123XYZ",
"expiresAt": "2024-02-15T10:30:00Z"
},
{
"type": "medical_registration_number",
"id": 456,
"data": "MRN-20240115-001",
"accountId": 10,
"accountName": "김의사",
"createdById": 5,
"createdByName": "관리자",
"createdAt": "2024-01-14T09:20:00Z",
"status": 1
}
]
}
| 필드 | 타입 | 설명 |
|---|---|---|
| total | number | 전체 항목 수 |
| count | number | 현재 페이지 항목 수 |
| data | array | 등록 목록 |
data 배열의 각 항목:
| 필드 | 타입 | 설명 |
|---|---|---|
| type | string | 등록 타입 (accesscode, medical_registration_number) |
| id | number | 등록 항목 ID |
| data | string | 등록 데이터 (이메일, 전화번호, 등록번호 등) |
| accountId | number | 담당 의료진 계정 ID |
| accountName | string | 담당 의료진 이름 |
| createdById | number | 생성자 계정 ID |
| createdByName | string | 생성자 이름 |
| createdAt | string | 생성 일시 (ISO 8601 형식) |
| status | number | 상태 (1: 활성, 0: 비활성) |
| code | string | 액세스 코드 (type이 accesscode인 경우만) |
| expiresAt | string | 만료 일시 (type이 accesscode인 경우만) |
type 값:
accesscode: 액세스 코드 발급 이력medical_registration_number: 의무 등록 번호 발급 이력
data 필드 내용:
- 액세스 코드: 발송된 이메일 또는 전화번호
- 의무 등록 번호: 등록 번호 자체
400 Bad Request - 잘못된 요청
{
"status": 400,
"code": 40000,
"message": "siteId is required"
}
발생 가능한 에러 메시지:
"siteId is required"- siteId가 제공되지 않음"요청한 정보가 유효하지 않습니다."- 잘못된 페이지 번호나 limit 값
401 Unauthorized - 인증 실패
{
"status": 401,
"code": 40100,
"message": "UNAUTHORIZED"
}
액세스 토큰이 유효하지 않거나 만료된 경우 발생합니다.
500 Internal Server Error - 서버 내부 오류
{
"status": 500,
"code": 50000,
"message": "INTERNAL_SERVER_ERROR"
}
사용 사례
최근 발급 이력 조회
최근에 발급된 액세스 코드와 의무 등록 번호를 확인하고 싶을 때:
GET /v1/patients/registrations?siteId=1&page=1&limit=50&orderBy=createdAt&desc=true
특정 의료진이 발급한 이력 조회
특정 의료진(accountId=10)이 발급한 이력을 확인하고 싶을 때 (클라이언트 측 필터링 필요):
GET /v1/patients/registrations?siteId=1&page=1&limit=100&orderBy=createdAt&desc=true
응답 후 클라이언트에서 accountId === 10 조건으로 필터링
검색 기능
특정 키워드로 등록 이력을 검색하고 싶을 때 (이메일, 전화번호, 등록번호 등):
GET /v1/patients/registrations?siteId=1&filter=patient@example.com&page=1&limit=20
정렬 옵션
orderBy 사용 가능한 필드
| 필드 | 설명 | 비고 |
|---|---|---|
| createdAt | 생성 일시 | 기본값 (Default) |
| id | ID | 발급 순서 |
| status | 상태 | 활성/비활성 기준 정렬 |
정렬 예시
최신순 정렬 (기본):
?orderBy=createdAt&desc=true
오래된 순 정렬:
?orderBy=createdAt&desc=false
ID 순 정렬:
?orderBy=id&desc=false
상태 코드
| 코드 | 설명 | 비고 |
|---|---|---|
| 0 | 비활성 | 사용 불가 (만료, 취소 등) |
| 1 | 활성 | 정상 사용 가능 |
권한 관리
- 일반 의료진: 자신이 소속된 사이트의 등록 이력만 조회 가능
- 관리자: 모든 사이트의 등록 이력 조회 가능
- 사이트 간 접근 제한: 다른 사이트의 등록 이력 조회 시 권한 오류 발생