버전: 0.68.0

관리자 등록 API

참고: 이 문서에 설명된 모든 API는 dta-wi-mono 모노레포의 dta-wi-medi-api 애플리케이션에 구현되어 있습니다.

개요

관리자 등록 API는 사이트(병원) 및 계정 등록 신청의 CRUD 기능을 제공합니다.

주요기능

등록 목록 조회: 페이징, 정렬, 검색, 필터링이 가능한 등록 목록 조회
등록 상세 조회: 특정 등록의 상세 정보 조회
등록 생성: 새로운 사이트 등록 및 계정 등록 생성
등록 승인: 등록 신청 승인 처리

[GET] /v1/admin/registrations - 등록 목록 조회

등록 목록 조회

사이트(병원) 및 계정 등록 신청 목록을 조회합니다.

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

✅ 1.4 Migration 완료

⚠️ 변경 사항

주의: 이전 버전에서 다음 사항이 변경되었습니다. 클라이언트 코드 수정이 필요합니다.

변경된 필드

items[].id: 응답의 id 필드 타입이 number에서 string으로 변경되었습니다.
items[].siteId: 응답의 siteId 필드 타입이 number | null에서 string | null로 변경되었습니다.
orderBy: 파라미터 값이 snake_case에서 camelCase로 변경되었습니다. (예: created_at → createdAt)
approvedBy: 응답의 approvedBy 필드 타입이 number | null에서 string | null로 변경되었습니다.

삭제된 필드

Response:
- items[].uuid: 응답에서 제거되었습니다.

Headers

Header	Type	Description	Required
Authorization	Bearer {accessToken}	사용자 인증을 통해 발급받은 액세스 토큰 입니다.	✔

Query Parameters

파라미터	타입	설명	Required	Default
searchKey	string	검색어 (code, name)	✗	-
limit	number	한 페이지당 조회할 항목 수 (최대 100)	✗	10
page	number	조회할 페이지 번호	✗	1
orderBy	string	정렬 기준 (`createdAt`, `name`, `code`, `status`)	✗	createdAt
orderDirection	string	정렬 방식 (`asc`, `desc`)	✗	desc
filterBy	string	필터 기준 (`approved`, `pending`)	✗	-

Responses

Http Status Code	설명	Error Code(s)
200 `OK`	조회 성공	-
401 `Unauthorized`	인증 실패	1080
500 `Internal Server Error`	서버 내부 오류	1092

200 OK - 성공

{
  "pagination": {
    "page": 1,
    "limit": 10,
    "totalCount": 50,
    "totalPages": 5,
    "next": "?page=2&limit=10"
  },
  "items": [
    {
      "id": "123e4567-e89b-12d3-a456-42661417400",
      "name": "서울대학교병원",
      "code": "103523",
      "status": "PENDING",
      "approvedBy": null,
      "siteId": null,
      "createdAt": "2024-09-30 14:12:08 KST",
      "updatedAt": "2024-09-30 14:12:08 KST"
    }
  ]
}

필드	타입	설명
pagination	object	페이지네이션 정보
pagination.page	number	현재 페이지 번호
pagination.limit	number	페이지당 항목 수
pagination.totalCount	number	총 항목 수
pagination.totalPages	number	총 페이지 수
pagination.next	string \| null	다음 페이지 URL
pagination.previous	string \| null	이전 페이지 URL
items	array	등록 데이터 배열
items[].id	string	등록 ID
items[].name	string	사이트 이름
items[].code	string	사이트 코드 (요양기관등록번호)
items[].status	string	등록 상태 (`PENDING`, `APPROVED`)
items[].approvedBy	string \| null	승인한 계정 ID
items[].siteId	string \| null	승인 후 생성된 사이트 ID
items[].createdAt	string	생성일 (KST)
items[].updatedAt	string	수정일 (KST)

401 Unauthorized - 인증 실패

{
  "status": 401,
  "code": 1080,
  "message": "UNAUTHORIZED",
  "detail": "{\"displayText\":\"No token found in Authorization header\"}"
}

[GET] /v1/admin/registrations/{registrationId} - 등록 상세 조회

등록 상세 조회

특정 등록 신청의 상세 정보를 조회합니다.

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

✅ 1.4 Migration 완료

⚠️ 변경 사항

주의: 이전 버전에서 다음 사항이 변경되었습니다. 클라이언트 코드 수정이 필요합니다.

변경된 필드

Response 구조: flat 구조에서 nested 구조로 변경
- 이전: { id, name, code, status, ..., accounts: [...] }
- 현재: { site: {...}, operationUsers: [...] }
accounts: 필드명이 operationUsers로 변경되었습니다.
id: 응답의 id 필드 타입이 number에서 string으로 변경되었습니다.
siteId: 응답의 siteId 필드 타입이 number | null에서 string | null로 변경되었습니다.
approvedBy: 응답의 approvedBy 필드 타입이 number | null에서 string | null로 변경되었습니다.

삭제된 필드

Response:
- uuid: 응답에서 제거되었습니다.
- operationUsers[].position: 응답에서 제거되었습니다.
- operationUsers[].positionId: 응답에서 제거되었습니다.
- operationUsers[].approved: 응답에서 제거되었습니다. status 필드로 확인 가능합니다.
- operationUsers[].authorizedToPrescribe: 응답에서 제거되었습니다.

추가된 필드

Response:
- operationUsers[].roleIds: 계정에 할당된 역할 ID 배열이 추가되었습니다.
- operationUsers[].groupIds: 계정이 속한 그룹명 배열이 추가되었습니다.

Headers

Header	Type	Description	Required
Authorization	Bearer {accessToken}	사용자 인증을 통해 발급받은 액세스 토큰 입니다.	✔

Path Parameters

파라미터	타입	설명	Required
registrationId	string	등록 UUID	✔

Responses

Http Status Code	설명	Error Code(s)
200 `OK`	조회 성공	-
400 `Bad Request`	잘못된 요청	1001
401 `Unauthorized`	인증 실패	1080
403 `Forbidden`	권한 없음	1081
404 `Not Found`	등록을 찾을 수 없음	1072
500 `Internal Server Error`	서버 내부 오류	1092

200 OK - 성공

{
  "site": {
    "id": "123e4567-e89b-12d3-a456-426614174000",
    "name": "서울대학교병원",
    "code": "103523",
    "status": "PENDING",
    "approvedBy": null,
    "siteId": null,
    "createdAt": "2024-09-30 14:12:08 KST",
    "updatedAt": "2024-09-30 14:12:08 KST"
  },
  "operationUsers": [
    {
      "id": "223e4567-e89b-12d3-a456-426614174001",
      "name": "김철수",
      "email": "doctor@weltcorp.com",
      "phoneNumber": "01012345678",
      "birthdate": "1980-01-01",
      "status": "PENDING",
      "approvedBy": null,
      "roleIds": ["role-uuid-1", "role-uuid-2"],
      "groupIds": ["group1", "group2"],
      "siteId": null,
      "createdAt": "2024-09-30 14:12:08 KST",
      "updatedAt": "2024-09-30 14:12:08 KST"
    }
  ]
}

필드	타입	설명
site	object	사이트 등록 정보
site.id	string	등록 ID
site.name	string	사이트 이름
site.code	string	사이트 코드 (요양기관등록번호)
site.status	string	등록 상태 (`PENDING`, `APPROVED`)
site.approvedBy	string \| null	승인한 계정 ID
site.siteId	string \| null	승인 후 생성된 사이트 ID
site.createdAt	string	생성일 (KST)
site.updatedAt	string	수정일 (KST)
operationUsers	array	계정 등록 데이터 배열
operationUsers[].id	string	계정 등록 ID
operationUsers[].name	string	계정 이름
operationUsers[].email	string	계정 이메일
operationUsers[].status	string	등록 상태 (`PENDING`, `APPROVED`)
operationUsers[].approvedBy	string \| null	승인한 계정 ID
operationUsers[].phoneNumber	string	계정 전화번호
operationUsers[].birthdate	string	계정 생년월일 (YYYY-MM-DD)
operationUsers[].roleIds	string[]	역할 ID 배열
operationUsers[].groupIds	string[]	그룹명 배열
operationUsers[].siteId	string \| null	사이트 ID
operationUsers[].createdAt	string	생성일 (KST)
operationUsers[].updatedAt	string	수정일 (KST)

400 Bad Request - 잘못된 요청

{
  "status": 400,
  "code": 1001,
  "message": "Bad Request",
  "detail": "입력 값이 유효하지 않습니다",
  "errors": [
    {
      "field": "name",
      "message": "name must be a string"
    }
  ]
}

401 Unauthorized - 인증 실패

{
  "statusCode": 401,
  "code": 1080,
  "message": "UNAUTHORIZED",
  "detail": "인증되지 않은 요청입니다"
}

403 Forbidden - 권한 없음

{
  "statusCode": 403,
  "code": 1081,
  "message": "FORBIDDEN",
  "detail": "권한이 없습니다"
}

404 Not Found - 등록을 찾을 수 없음

{
  "status": 404,
  "code": 1072,
  "message": "SITE_REGISTRATION_NOT_FOUND",
  "detail": "등록된 기관 신청 정보를 찾을 수 없습니다."
}

[POST] /v1/admin/registrations - 등록 생성

등록 생성

새로운 사이트 등록 및 계정 등록을 생성합니다.

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

✅ 1.4 Migration 완료

⚠️ 변경 사항

주의: 이전 버전에서 다음 사항이 변경되었습니다. 클라이언트 코드 수정이 필요합니다.

변경된 필드

Request Body 구조: flat 구조에서 nested 구조로 변경
- 이전: { name, code, accounts: [...] }
- 현재: { site: { name, code }, operationUsers: [...] }
accounts: 필드명이 operationUsers로 변경되었습니다.
Response 구조: flat 구조에서 nested 구조로 변경
- 이전: { id, name, code, status, ..., accounts: [...] }
- 현재: { site: {...}, operationUsers: [...] }
id: 응답의 id 필드 타입이 string으로 변경되었습니다.

삭제된 필드

Request Body:
- accounts[].positionId: 제거되었습니다.
- accounts[].authorizedToPrescribe: 요청에서 제거되었습니다 (응답에만 존재).
Response:
- uuid: 응답에서 제거되었습니다.
- siteId: 응답에서 제거되었습니다.
- position: 응답에서 제거되었습니다.
- positionId: 응답에서 제거되었습니다.
- approved: 응답에서 제거되었습니다. status 필드로 확인 가능합니다.

Headers

Header	Type	Description	Required
Authorization	Bearer {accessToken}	사용자 인증을 통해 발급받은 액세스 토큰 입니다.	✔
Content-Type	application/json	요청 본문 형식	✔

Request Body

필드	타입	설명	Required
site	object	사이트 등록 정보	✔
site.name	string	사이트 이름	✔
site.code	string	사이트 코드 (요양기관등록번호)	✗
operationUsers	array	계정 등록 데이터 배열	✔
operationUsers[].name	string	계정 이름	✔
operationUsers[].email	string	계정 이메일	✔
operationUsers[].phoneNumber	string	계정 전화번호	✗
operationUsers[].birthdate	string	계정 생년월일 (YYYY-MM-DD)	✗

Request Body 예시

{
  "site": {
    "name": "서울대학교병원",
    "code": "103523"
  },
  "operationUsers": [
    {
      "name": "김철수",
      "email": "doctor@weltcorp.com",
      "phoneNumber": "01012345678",
      "birthdate": "1980-01-01"
    }
  ]
}

Responses

Http Status Code	설명	Error Code(s)
200 `OK`	생성 성공	-
401 `Unauthorized`	인증 실패	1080
500 `Internal Server Error`	서버 내부 오류	1092

200 OK - 성공

{
  "site": {
    "id": "1",
    "name": "서울대학교병원",
    "code": "103523",
    "status": "PENDING",
    "approvedBy": null,
    "createdAt": "2024-09-30 14:12:08 KST",
    "updatedAt": "2024-09-30 14:12:08 KST"
  },
  "operationUsers": [
    {
      "id": "1",
      "name": "김철수",
      "email": "doctor@weltcorp.com",
      "phoneNumber": "01012345678",
      "birthdate": "1980-01-01",
      "status": "PENDING",
      "approvedBy": null,
      "authorizedToPrescribe": false,
      "createdAt": "2024-09-30 14:12:08 KST",
      "updatedAt": "2024-09-30 14:12:08 KST"
    }
  ]
}

[POST] /v1/admin/registrations/approve - 등록 승인

등록 승인

등록 신청을 승인 처리합니다. 사이트 등록과 계정 등록을 함께 승인하며, 승인 후 실제 사이트와 계정이 생성됩니다.

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

✅ 1.4 Migration 완료

⚠️ 변경 사항

주의: 이전 버전에서 다음 사항이 변경되었습니다. 클라이언트 코드 수정이 필요합니다.

변경된 필드

Request Body 구조:
- accountRegistrationIds → operationUserRegistrationIds: 필드명이 변경되었습니다.
Response 구조: flat 구조에서 nested 구조로 변경
- 이전: { id, name, code, status, ..., accounts: [...] }
- 현재: { site: {...}, operationUsers: [...] }
accounts: 응답 필드명이 operationUsers로 변경되었습니다.
id: 응답의 id 필드 타입이 number에서 string으로 변경되었습니다.
siteId: 응답의 siteId 필드 타입이 number | null에서 string | null로 변경되었습니다.
approvedBy: 응답의 approvedBy 필드 타입이 number | null에서 string | null로 변경되었습니다.
operationUsers[].id: 응답의 계정 ID 타입이 number에서 string으로 변경되었습니다.
operationUsers[].siteId: 응답의 사이트 ID 타입이 number | null에서 string | null로 변경되었습니다.

삭제된 필드

Response:
- uuid: 응답에서 제거되었습니다.
- operationUsers[].uuid: 응답에서 제거되었습니다.
- operationUsers[].position: 응답에서 제거되었습니다.
- operationUsers[].positionId: 응답에서 제거되었습니다.
- operationUsers[].approved: 응답에서 제거되었습니다. status 필드로 확인 가능합니다.

추가된 필드

Response:
- operationUsers[].roleIds: 계정에 할당된 역할 ID 배열이 추가되었습니다.
- operationUsers[].groupIds: 계정이 속한 그룹명 배열이 추가되었습니다.

Headers

Header	Type	Description	Required
Authorization	Bearer {accessToken}	사용자 인증을 통해 발급받은 액세스 토큰 입니다.	✔
Content-Type	application/json	요청 본문 형식	✔

Request Body

필드	타입	설명	Required
siteRegistrationId	string	사이트 등록 Id	✔
operationUserRegistrationIds	string[]	승인할 계정 등록 Id 배열	✗

Request Body 예시

{
  "siteRegistrationId": "123e4567-e89b-12d3-a456-426614174000",
  "operationUserRegistrationIds": ["223e4567-e89b-12d3-a456-426614174001", "323e4567-e89b-12d3-a456-426614174002"]
}

Responses

Http Status Code	설명	Error Code(s)
200 `OK`	승인 성공	-
401 `Unauthorized`	인증 실패	1080
500 `Internal Server Error`	서버 내부 오류	1092

200 OK - 성공

{
  "site": {
    "id": "123e4567-e89b-12d3-a456-426614174000",
    "name": "서울대학교병원",
    "code": "103523",
    "status": "APPROVED",
    "approvedBy": "10e4567-e89b-12d3-a456-426614174099",
    "siteId": "5e4567-e89b-12d3-a456-426614174055",
    "createdAt": "2024-09-30 14:12:08 KST",
    "updatedAt": "2024-10-01 10:30:15 KST"
  },
  "operationUsers": [
    {
      "id": "223e4567-e89b-12d3-a456-426614174001",
      "name": "김철수",
      "email": "doctor@weltcorp.com",
      "phoneNumber": "01012345678",
      "birthdate": "1980-01-01",
      "status": "APPROVED",
      "approvedBy": null,
      "roleIds": ["role-uuid-1", "role-uuid-2"],
      "groupIds": ["group1", "group2"],
      "siteId": "5e4567-e89b-12d3-a456-426614174055",
      "createdAt": "2024-09-30 14:12:08 KST",
      "updatedAt": "2024-10-01 10:30:15 KST"
    }
  ]
}

필드	타입	설명
site	object	사이트 등록 정보
site.id	string	등록 ID
site.name	string	사이트 이름
site.code	string	사이트 코드 (요양기관등록번호)
site.status	string	등록 상태 (`PENDING`, `APPROVED`)
site.approvedBy	string \| null	승인한 계정 ID
site.siteId	string \| null	승인 후 생성된 사이트 ID
site.createdAt	string	생성일 (KST)
site.updatedAt	string	수정일 (KST)
operationUsers	array	계정 등록 데이터 배열
operationUsers[].id	string	계정 등록 ID
operationUsers[].name	string	계정 이름
operationUsers[].email	string	계정 이메일
operationUsers[].status	string	등록 상태 (`PENDING`, `APPROVED`)
operationUsers[].approvedBy	string \| null	승인한 계정 ID
operationUsers[].phoneNumber	string	계정 전화번호
operationUsers[].birthdate	string	계정 생년월일 (YYYY-MM-DD)
operationUsers[].roleIds	string[]	역할 ID 배열
operationUsers[].groupIds	string[]	그룹명 배열
operationUsers[].siteId	string \| null	사이트 ID
operationUsers[].createdAt	string	생성일 (KST)
operationUsers[].updatedAt	string	수정일 (KST)

개요​

주요기능​

등록 목록 조회

✅ 1.4 Migration 완료​

⚠️ 변경 사항​

변경된 필드​

삭제된 필드​

Headers​

Query Parameters​

Responses​

등록 상세 조회

✅ 1.4 Migration 완료​

⚠️ 변경 사항​

변경된 필드​

삭제된 필드​

추가된 필드​

Headers​

Path Parameters​

Responses​

등록 생성

✅ 1.4 Migration 완료​

⚠️ 변경 사항​

변경된 필드​

삭제된 필드​

Headers​

Request Body​

Request Body 예시​

Responses​

등록 승인

✅ 1.4 Migration 완료​

⚠️ 변경 사항​

변경된 필드​

삭제된 필드​

추가된 필드​

Headers​

Request Body​

Request Body 예시​

Responses​

개요

주요기능

✅ 1.4 Migration 완료

⚠️ 변경 사항

변경된 필드

삭제된 필드

Headers

Query Parameters

Responses

✅ 1.4 Migration 완료

⚠️ 변경 사항

변경된 필드

삭제된 필드

추가된 필드

Headers

Path Parameters

Responses

✅ 1.4 Migration 완료

⚠️ 변경 사항

변경된 필드

삭제된 필드

Headers

Request Body

Request Body 예시

Responses

✅ 1.4 Migration 완료

⚠️ 변경 사항

변경된 필드

삭제된 필드

추가된 필드

Headers

Request Body

Request Body 예시

Responses