약나루 API 명세 (앱 · 관리자웹 통합 백엔드) API v1

서비스명, 상태(UP), 서버 현재 시각을 돌려준다. DB 연결은 확인하지 않으며(그건 /actuator/health), 프로세스가 요청을 받는지만 본다. 로그인 불필요.

응답 200

{"success":true,"data":…} — data: object (OK)

오류 응답: 400 잘못된 요청 (필수값 누락, 형식·검증 실패, 알 수 없는 코드값, 깨진 JSON·UTF-8 아닌 인코딩)

앱 로그인 화면(SignIn)과 생체인증/PIN 재로그인(BiometricAuth, PinInput)에서 호출한다. 아이디(memId)와 비밀번호(memPass)를 검증해 access 토큰(30분)과 refresh 토큰(14일), 내 정보(myInfo)를 함께 돌려준다. 아이디·비밀번호 불일치는 AUTH_002, 탈퇴 회원은 MEMBER_004. 로그인 불필요.

요청 본문 application/json — LoginRequest

회원(RN 앱) 로그인 요청 — POST /api/v1/auth/login

응답 200

object (로그인 성공)

{
 "success": true,
 "data": {
  "tokenType": "Bearer",
  "accessToken": "eyJhbGciOiJIUzI1NiJ9.eyJzdWIiOiIxMiIsInVzZXJUeXBlIjoiVVNFUiJ9.xxxxx",
  "refreshToken": "eyJhbGciOiJIUzI1NiJ9.eyJzdWIiOiIxMiIsInR5cCI6InJlZnJlc2gifQ.yyyyy",
  "expiresIn": 1800,
  "myInfo": {
   "id": 12,
   "memId": "hong123",
   "memEmail": "hong@example.com",
   "memName": "홍길동",
   "memBirth": "1990-01-15",
   "memGender": "1",
   "memTel": "010-1234-5678",
   "memPush": "Y",
   "memState": "ACTIVE",
   "roles": [
    "USER"
   ]
  }
 }
}

오류 응답: 401 아이디 또는 비밀번호 불일치 · 403 탈퇴한 회원 · 400 잘못된 요청 (필수값 누락, 형식·검증 실패, 알 수 없는 코드값, 깨진 JSON·UTF-8 아닌 인코딩)

서버는 stateless JWT 라 아무 것도 저장하지 않고 성공만 돌려준다. 앱은 이 호출 후 로컬 토큰을 지우고, 기기 푸시를 끊으려면 /api/v1/push/unsubscribe 를 함께 호출한다. 로그인 불필요.

응답 200

{"success":true,"data":…} — data: object (OK)

오류 응답: 400 잘못된 요청 (필수값 누락, 형식·검증 실패, 알 수 없는 코드값, 깨진 JSON·UTF-8 아닌 인코딩)

앱 네트워크 계층이 access 토큰 만료(401)를 받으면 자동으로 호출한다. refresh 토큰을 검증해 새 access/refresh 토큰 쌍과 내 정보를 다시 발급한다. 위조되었거나 만료된 refresh 토큰은 AUTH_004. 로그인 불필요(본문 refreshToken 만 사용).

요청 본문 application/json — RefreshRequest

회원 토큰 갱신 요청 — POST /api/v1/auth/refresh

응답 200

{"success":true,"data":…} — data: TokenResponse (OK)

오류 응답: 400 잘못된 요청 (필수값 누락, 형식·검증 실패, 알 수 없는 코드값, 깨진 JSON·UTF-8 아닌 인코딩)

NICE 본인인증을 마친 뒤 그 DI(memDi)로 이미 가입된 회원이 있는지 확인한다. 가입 가능하면 {available:true}. 로그인 불필요.

요청 본문 application/json — CheckDiRequest

본인인증 DI 중복 확인 요청 — POST /api/v1/members/check-di (이미 가입된 DI 인지 확인)

응답 200

{"success":true,"data":…} — data: object (OK)

오류 응답: 400 잘못된 요청 (필수값 누락, 형식·검증 실패, 알 수 없는 코드값, 깨진 JSON·UTF-8 아닌 인코딩)

앱 회원가입 화면과 내 정보 수정 화면(EditProfile)에서 호출한다. 사용 가능하면 {available:true}. 로그인 불필요.

요청 본문 application/json — CheckEmailRequest

이메일 중복 확인 요청 — POST /api/v1/members/check-email

응답 200

{"success":true,"data":…} — data: object (OK)

오류 응답: 400 잘못된 요청 (필수값 누락, 형식·검증 실패, 알 수 없는 코드값, 깨진 JSON·UTF-8 아닌 인코딩)

앱 회원가입 정보 입력 화면(SignUpInfo)의 중복확인 버튼. 사용 가능하면 {available:true}, 빈 값이면 false. 로그인 불필요.

요청 본문 application/json — CheckIdRequest

아이디 중복 확인 요청 — POST /api/v1/members/check-id

응답 200

{"success":true,"data":…} — data: object (OK)

오류 응답: 400 잘못된 요청 (필수값 누락, 형식·검증 실패, 알 수 없는 코드값, 깨진 JSON·UTF-8 아닌 인코딩)

앱 회원가입 정보 입력 화면(SignUpInfo)에서 추천인 코드를 입력했을 때 호출한다. 코드를 회원번호로 환산해 해당 회원이 존재하면 {valid:true}. 숫자가 아닌 코드는 서버 오류(COMMON_002)가 나므로 앱에서 숫자만 보낸다. 로그인 불필요.

요청 본문 application/json — CheckRecommendRequest

추천인 코드 확인 요청 — POST /api/v1/members/check-recommend

응답 200

{"success":true,"data":…} — data: object (OK)

오류 응답: 400 잘못된 요청 (필수값 누락, 형식·검증 실패, 알 수 없는 코드값, 깨진 JSON·UTF-8 아닌 인코딩)

앱 더보기(More)·내 정보 수정(EditProfile) 화면에서 호출한다. 로그인 응답의 myInfo 와 같은 형태. 회원 토큰 필요.

응답 200

object (조회 성공)

{
 "success": true,
 "data": {
  "id": 12,
  "memId": "hong123",
  "memEmail": "hong@example.com",
  "memName": "홍길동",
  "memBirth": "1990-01-15",
  "memGender": "1",
  "memTel": "010-1234-5678",
  "memPush": "Y",
  "memState": "ACTIVE",
  "roles": [
   "USER"
  ]
 }
}

{"success":true,"data":…} — data: MemberInfo (조회 성공)

오류 응답: 400 잘못된 요청 (필수값 누락, 형식·검증 실패, 알 수 없는 코드값, 깨진 JSON·UTF-8 아닌 인코딩) · 401 인증 실패 (토큰 없음 AUTH_001 / 만료 AUTH_003 / 위조 AUTH_004) · 403 권한 없음 (역할 부족, 다른 종류의 토큰, 타인 자원 접근)

회원 레코드에 최신 FCM 토큰을 보관한다. 실제 푸시 발송 대상은 /api/v1/push/subscribe 로 등록한 구독 정보를 기준으로 고르므로, 앱은 subscribe 를 반드시 함께 호출해야 한다. 회원 토큰 필요.

요청 본문 application/json — FcmTokenRequest

FCM 토큰 등록 요청 — POST /api/v1/members/me/register-fcm

응답 200

{"success":true,"data":…} — data: object (OK)

오류 응답: 400 잘못된 요청 (필수값 누락, 형식·검증 실패, 알 수 없는 코드값, 깨진 JSON·UTF-8 아닌 인코딩) · 401 인증 실패 (토큰 없음 AUTH_001 / 만료 AUTH_003 / 위조 AUTH_004) · 403 권한 없음 (역할 부족, 다른 종류의 토큰, 타인 자원 접근)

앱 내 정보 수정 화면(EditProfile)에서 호출한다. 이메일·전화·우편번호·주소만 바꿀 수 있고 null 로 보낸 항목은 유지된다. 이메일을 바꾸면 다른 회원과 중복인지 검사해 MEMBER_002 로 거절한다. 회원 토큰 필요.

요청 본문 application/json — UpdateProfileRequest

회원 프로필 수정 요청 — POST /api/v1/members/me/update (null 필드는 미변경)

응답 200

{"success":true,"data":…} — data: MemberInfo (OK)

오류 응답: 400 잘못된 요청 (필수값 누락, 형식·검증 실패, 알 수 없는 코드값, 깨진 JSON·UTF-8 아닌 인코딩) · 401 인증 실패 (토큰 없음 AUTH_001 / 만료 AUTH_003 / 위조 AUTH_004) · 403 권한 없음 (역할 부족, 다른 종류의 토큰, 타인 자원 접근)

앱 비밀번호 변경 화면(ChangePassword)에서 호출한다. 현재 비밀번호(oldPass)가 맞아야 하며 틀리면 AUTH_002. 새 비밀번호는 8~64자. 회원 토큰 필요.

요청 본문 application/json — ChangePasswordRequest

회원 비밀번호 변경 요청 — POST /api/v1/members/me/update-password

응답 200

{"success":true,"data":…} — data: object (OK)

오류 응답: 400 잘못된 요청 (필수값 누락, 형식·검증 실패, 알 수 없는 코드값, 깨진 JSON·UTF-8 아닌 인코딩) · 401 인증 실패 (토큰 없음 AUTH_001 / 만료 AUTH_003 / 위조 AUTH_004) · 403 권한 없음 (역할 부족, 다른 종류의 토큰, 타인 자원 접근)

앱 더보기(More)의 수신동의 토글과 회원가입 직후(SignUpInfo)에 호출한다. memPush 는 Y 또는 N. 이 값은 마케팅 수신 여부만 기록하며 주문·심사 결과 같은 서비스 푸시 발송을 막지는 않는다. 회원 토큰 필요.

요청 본문 application/json — SetPushAgreeRequest

푸시 수신 동의 변경 요청 — POST /api/v1/members/me/update-push

응답 200

{"success":true,"data":…} — data: object (OK)

오류 응답: 400 잘못된 요청 (필수값 누락, 형식·검증 실패, 알 수 없는 코드값, 깨진 JSON·UTF-8 아닌 인코딩) · 401 인증 실패 (토큰 없음 AUTH_001 / 만료 AUTH_003 / 위조 AUTH_004) · 403 권한 없음 (역할 부족, 다른 종류의 토큰, 타인 자원 접근)

앱 탈퇴 확인 화면(WithdrawConfirm)에서 호출한다. 회원 상태를 WITHDRAWN 으로 바꾸고 soft delete 처리하며, 이후 로그인은 MEMBER_004 로 거절된다. 되돌릴 수 없다. 회원 토큰 필요.

응답 200

{"success":true,"data":…} — data: object (OK)

오류 응답: 400 잘못된 요청 (필수값 누락, 형식·검증 실패, 알 수 없는 코드값, 깨진 JSON·UTF-8 아닌 인코딩) · 401 인증 실패 (토큰 없음 AUTH_001 / 만료 AUTH_003 / 위조 AUTH_004) · 403 권한 없음 (역할 부족, 다른 종류의 토큰, 타인 자원 접근)

앱 비밀번호 찾기 화면(ResetPassword)에서 호출한다. 아이디(memId)와 등록 이메일(memEmail)이 일치하면 12자 임시 비밀번호로 바꾸고 그 이메일로 발송한다. 없는 아이디는 MEMBER_001, 이메일 불일치는 AUTH_002, 메일 발송 실패 시 비밀번호 변경도 롤백되고 COMMON_004. 로그인 불필요.

요청 본문 application/json — ResetPasswordRequest

회원 비밀번호 찾기 요청 — POST /api/v1/members/password (아이디+이메일 일치 시 임시 비밀번호 메일 발송)

응답 200

{"success":true,"data":…} — data: object (OK)

오류 응답: 400 잘못된 요청 (필수값 누락, 형식·검증 실패, 알 수 없는 코드값, 깨진 JSON·UTF-8 아닌 인코딩)

앱 회원가입 정보 입력 화면(SignUpInfo)에서 호출한다. 이메일 중복은 MEMBER_002, 본인인증 DI 중복은 MEMBER_003 으로 거절되며, 아이디 중복은 사전에 check-id 로 확인해야 한다. 현재는 memId/memPass/memEmail/memName 만 저장되고 생년월일·성별·전화·추천인은 저장되지 않으므로 필요하면 가입 후 내 정보 수정으로 보완한다. 가입 즉시 로그인과 같은 토큰 쌍을 돌려준다. 로그인 불필요.

요청 본문 application/json — SignUpRequest

회원가입 요청 — POST /api/v1/members/signup

응답 200

{"success":true,"data":…} — data: TokenResponse (OK)

오류 응답: 400 잘못된 요청 (필수값 누락, 형식·검증 실패, 알 수 없는 코드값, 깨진 JSON·UTF-8 아닌 인코딩)

앱 로딩 화면(Loading)이 시작할 때마다 호출한다. platform 은 android 또는 ios(그 외는 COMMON_001). 응답 키는 RN 호환을 위해 snake_case 이며 up_bool/agree_bool/popup_bool/server_bool 값에 따라 앱이 차단 모달을 띄운다. 해당 플랫폼 행이 없으면 모든 플래그가 꺼진 기본 행을 자동 생성해 돌려준다. 로그인 불필요.

파라미터

응답 200

object (조회 성공)

{
 "success": true,
 "data": {
  "platform": "android",
  "up_bool": "yes",
  "up_build": 120,
  "up_img": "/uploads/setting/update.png",
  "up_img_width": 300,
  "up_img_height": 400,
  "agree_bool": "no",
  "agree_no": 3,
  "popup_bool": "no",
  "server_bool": "no"
 }
}

{"success":true,"data":…} — data: AppSettingView (조회 성공)

오류 응답: 400 잘못된 요청 (필수값 누락, 형식·검증 실패, 알 수 없는 코드값, 깨진 JSON·UTF-8 아닌 인코딩)

앱 약국 찾기 화면에서 호출한다. gpsX(경도)와 gpsY(위도)를 함께 주면 거리순으로 정렬되고 각 항목의 distance(미터)가 채워지며, 없으면 이름순. keyword 는 약국명 검색, deliveryYn=Y 면 배송 가능 약국만. effectiveStatus 는 요일별 영업시간과 현재 시각(KST)으로 계산한 실효 상태(영업중/준비중)이며 화면 표시는 이 값을 쓴다. 로그인 불필요.

파라미터

응답 200

object (검색 성공 (Spring Data Page 형태))

{"success":true,"data":…} — data: Page<PharmacyView> (검색 성공 (Spring Data Page 형태))

오류 응답: 400 잘못된 요청 (필수값 누락, 형식·검증 실패, 알 수 없는 코드값, 깨진 JSON·UTF-8 아닌 인코딩)

앱 배송지 관리 화면(AddressManagement)에서 배송지 저장 전에 호출한다. 우편번호(zonecode, 필수) 또는 도로명(roadname) 중 하나라도 비배송 지역 목록과 일치하면 deliveryYn=N 과 사유(reason)를 돌려주고, 둘 다 아니면 deliveryYn=Y. 로그인 불필요.

요청 본문 application/json — CheckDeliveryRequest

비배송(산간/도서) 지역 확인 요청 — POST /api/v1/pharmacies/check-delivery

응답 200

{"success":true,"data":…} — data: CheckDeliveryResponse (OK)

오류 응답: 400 잘못된 요청 (필수값 누락, 형식·검증 실패, 알 수 없는 코드값, 깨진 JSON·UTF-8 아닌 인코딩)

앱 약국 상세/선택 화면에서 호출한다. 식별자는 쿼리 code(약국 코드, 예 PH-001). 없는 코드는 COMMON_003. distance 는 채워지지 않는다. 로그인 불필요.

파라미터

응답 200

{"success":true,"data":…} — data: PharmacyView (OK)

오류 응답: 400 잘못된 요청 (필수값 누락, 형식·검증 실패, 알 수 없는 코드값, 깨진 JSON·UTF-8 아닌 인코딩)

앱 배송지 관리 화면(AddressManagement)과 약 주문 시작 화면(OrderMedicineMain)의 배송지 선택에서 호출한다. 삭제되지 않은 본인 배송지만 반환하며 기본 배송지(isDefault=true)가 먼저, 그다음 최근 등록순이다. 회원 토큰 필요.

응답 200

object (조회 성공)

{
 "success": true,
 "data": [
  {
   "deliveryAddressSeq": 5,
   "deliveryAddressName": "홍길동",
   "deliveryAddressPhone": "010-1234-5678",
   "deliveryAddressZipcode": "06578",
   "deliveryAddress": "서울특별시 서초구 반포대로 45",
   "deliveryDetailAddress": "101동 202호",
   "roadName": "반포대로",
   "isDefault": true
  },
  {
   "deliveryAddressSeq": 3,
   "deliveryAddressName": "홍길동(회사)",
   "deliveryAddressPhone": "010-1234-5678",
   "deliveryAddressZipcode": "06236",
   "deliveryAddress": "서울특별시 강남구 테헤란로 123",
   "deliveryDetailAddress": "7층",
   "roadName": "테헤란로",
   "isDefault": false
  }
 ]
}

{"success":true,"data":…} — data: array<AddressView> (조회 성공)

오류 응답: 400 잘못된 요청 (필수값 누락, 형식·검증 실패, 알 수 없는 코드값, 깨진 JSON·UTF-8 아닌 인코딩) · 401 인증 실패 (토큰 없음 AUTH_001 / 만료 AUTH_003 / 위조 AUTH_004) · 403 권한 없음 (역할 부족, 다른 종류의 토큰, 타인 자원 접근)

앱 배송지 등록 화면(AddressEdit)에서 호출한다. 받는 분 이름과 연락처는 필수. 회원의 첫 배송지이거나 isDefault=true 로 보내면 기본 배송지가 되고, 기존 기본 배송지는 자동 해제된다. 회원 토큰 필요.

요청 본문 application/json — CreateRequest

관리자 계정 생성 요청 — POST /api/v1/admin/admin-users/create (SYSTEM_ADMIN 전용)

응답 200

{"success":true,"data":…} — data: AddressView (OK)

오류 응답: 400 잘못된 요청 (필수값 누락, 형식·검증 실패, 알 수 없는 코드값, 깨진 JSON·UTF-8 아닌 인코딩) · 401 인증 실패 (토큰 없음 AUTH_001 / 만료 AUTH_003 / 위조 AUTH_004) · 403 권한 없음 (역할 부족, 다른 종류의 토큰, 타인 자원 접근)

앱 배송지 관리 화면(AddressManagement)에서 호출한다. 대상은 본문 addressId. 실제 삭제가 아닌 soft delete 이며, 삭제한 배송지가 기본 배송지였다면 남은 배송지 중 첫 번째가 자동으로 기본 배송지가 된다. 회원 토큰 필요.

요청 본문 application/json — DeleteRequest

배송지 삭제 요청 — POST /api/v1/addresses/delete

응답 200

{"success":true,"data":…} — data: object (OK)

오류 응답: 400 잘못된 요청 (필수값 누락, 형식·검증 실패, 알 수 없는 코드값, 깨진 JSON·UTF-8 아닌 인코딩) · 401 인증 실패 (토큰 없음 AUTH_001 / 만료 AUTH_003 / 위조 AUTH_004) · 403 권한 없음 (역할 부족, 다른 종류의 토큰, 타인 자원 접근)

앱 배송지 수정 화면(AddressEdit)에서 호출한다. 대상은 본문 addressId 로 식별하며 본인 배송지가 아니면 COMMON_003. null 로 보낸 필드는 변경하지 않는다. isDefault=true 면 기본 배송지로 승격하고 다른 배송지의 기본 표시를 해제한다(기본 해제는 불가). 회원 토큰 필요.

요청 본문 application/json — UpdateRequest

앱 구동 설정 갱신 요청 — POST /api/v1/app/setting/update (관리자, null 필드는 미변경)

응답 200

{"success":true,"data":…} — data: AddressView (OK)

오류 응답: 400 잘못된 요청 (필수값 누락, 형식·검증 실패, 알 수 없는 코드값, 깨진 JSON·UTF-8 아닌 인코딩) · 401 인증 실패 (토큰 없음 AUTH_001 / 만료 AUTH_003 / 위조 AUTH_004) · 403 권한 없음 (역할 부족, 다른 종류의 토큰, 타인 자원 접근)

앱 홈(Home)의 최근 주문과 주문 내역 화면(OrderHistory)에서 호출한다. 본인 처방전을 최신순으로 페이징한 뒤 접수일(targetDate, yyyy-MM-dd) 별로 묶어 RN SectionList 형태로 돌려준다. 목록의 medicineList 는 항상 빈 배열이며 약품 목록은 상세에서만 제공된다. 회원 토큰 필요.

파라미터

응답 200

object (조회 성공)

{
 "success": true,
 "data": [
  {
   "targetDate": "2026-09-10",
   "deliveryList": [
    {
     "prescriptionSeq": 41,
     "prescriptionStatus": "06",
     "prescriptionStatusName": "배송중",
     "prescriptionRegdate": "2026-09-10",
     "prescriptionPrice": 12500,
     "totalPrice": 15500,
     "receiveType": "onLine",
     "pharmacyCode": "PH-001",
     "pharmacyName": "약나루약국",
     "medicineList": []
    }
   ]
  },
  {
   "targetDate": "2026-09-03",
   "deliveryList": [
    {
     "prescriptionSeq": 37,
     "prescriptionStatus": "03",
     "prescriptionStatusName": "조제불가",
     "prescriptionRegdate": "2026-09-03",
     "unavailableReason": "재고 없음",
     "receiveType": "offLine",
     "pharmacyCode": "PH-002",
     "pharmacyName": "건강약국",
     "medicineList": []
    }
   ]
  }
 ]
}

{"success":true,"data":…} — data: array<OrderHistoryGroup> (조회 성공)

오류 응답: 400 잘못된 요청 (필수값 누락, 형식·검증 실패, 알 수 없는 코드값, 깨진 JSON·UTF-8 아닌 인코딩) · 401 인증 실패 (토큰 없음 AUTH_001 / 만료 AUTH_003 / 위조 AUTH_004) · 403 권한 없음 (역할 부족, 다른 종류의 토큰, 타인 자원 접근)

앱 주문 진행 화면(MedicineOrder)과 주문 상세 화면(MedicineOrderDetail)에서 호출한다. 식별자는 쿼리 id(처방전 id). 본인 처방전이 아니면 AUTH_005, 없으면 COMMON_003. 처방전 인식 정보(partnerInfo)가 연결된 경우 약품 목록(medicineList)과 병원·의사 정보가 함께 오고, 03 조제불가 건은 pharmacyCode 로 거절 약국을 식별해 다른 약국 선택 흐름에 쓴다. 회원 토큰 필요.

파라미터

응답 200

object (조회 성공)

{
 "success": true,
 "data": {
  "prescriptionSeq": 41,
  "prescriptionStatus": "06",
  "prescriptionStatusName": "배송중",
  "reqDate": "2026-09-10T09:12:33.481",
  "receiveType": "onLine",
  "prescriptionPrice": 12500,
  "deliveryPrice": 3000,
  "totalPrice": 15500,
  "medicineDirection": "1일 3회 식후 30분 복용",
  "medicineList": [
   {
    "drgCd": "641102470",
    "drgNm": "타이레놀정500밀리그램",
    "dosage": "1",
    "daysTotal": "3"
   }
  ],
  "pharmacyCode": "PH-001",
  "pharmacyName": "약나루약국",
  "pharmacyPhone": "02-1234-5678",
  "pharmacyAddress": "서울특별시 강남구 테헤란로 123 1층",
  "deliveryName": "홍길동",
  "deliveryPhone": "010-1234-5678",
  "deliveryAddress": "서울특별시 서초구 반포대로 45",
  "deliveryDetailAddress": "101동 202호",
  "deliveryNumber": "123456789012",
  "deliveryCompany": "CJ대한통운",
  "partnerInfo": {
   "seq": 15,
   "hospitalName": "서울내과의원",
   "doctorName": "이의사",
   "patientName": "홍길동",
   "prescriptionDate": "2026-09-10",
   "useDays": "3"
  }
 }
}

{"success":true,"data":…} — data: OrderDetail (조회 성공)

오류 응답: 400 잘못된 요청 (필수값 누락, 형식·검증 실패, 알 수 없는 코드값, 깨진 JSON·UTF-8 아닌 인코딩) · 401 인증 실패 (토큰 없음 AUTH_001 / 만료 AUTH_003 / 위조 AUTH_004) · 403 권한 없음 (역할 부족, 다른 종류의 토큰, 타인 자원 접근)

앱 처방전 미리보기 화면(PrescPreview)에서 약국 선택까지 마친 뒤 호출한다. pharmacyCode(필수), receiveType(onLine 택배 / offLine 방문), 배송지 스냅샷, 업로드 이미지 경로, qrValue(필수), medicineSeq 를 한 번에 저장하며, 상태 01 발송으로 생성되고 약국명·전화·주소가 스냅샷으로 복사된다. 없는 약국 코드는 COMMON_003. 이 시점에는 푸시가 나가지 않는다. 회원 토큰 필요.

요청 본문 application/json — CreatePrescriptionRequest

처방전 등록(주문 생성) 요청 — POST /api/v1/prescriptions (이미지 업로드·QR/OCR 콜백 결과를 묶어 저장)

응답 200

object (등록 성공 (상태 01 발송))

{
 "success": true,
 "data": {
  "id": 42,
  "status": "01",
  "statusName": "발송",
  "receiveType": "onLine",
  "qrValue": "OCR",
  "prescriptionImageUrl": "/uploads/prescription/12/2026-09-11/3f2a9c__rx.jpg",
  "pharmacyName": "약나루약국",
  "pharmacyPhone": "02-1234-5678",
  "pharmacyAddress": "서울특별시 강남구 테헤란로 123 1층",
  "memId": "hong123",
  "memName": "홍길동",
  "deliveryName": "홍길동",
  "deliveryPhone": "010-1234-5678",
  "deliveryAddress": "서울특별시 서초구 반포대로 45",
  "deliveryDetailAddress": "101동 202호",
  "reqDate": "2026-09-11T10:15:30.123",
  "medicineList": [
   {
    "drgCd": "641102470",
    "drgNm": "타이레놀정500밀리그램"
   }
  ],
  "partnerInfo": {
   "seq": 16,
   "hospitalName": "서울내과의원",
   "doctorName": "이의사",
   "patientName": "홍길동",
   "prescriptionDate": "2026-09-11"
  }
 }
}

{"success":true,"data":…} — data: PrescriptionView (등록 성공 (상태 01 발송))

오류 응답: 400 잘못된 요청 (필수값 누락, 형식·검증 실패, 알 수 없는 코드값, 깨진 JSON·UTF-8 아닌 인코딩) · 401 인증 실패 (토큰 없음 AUTH_001 / 만료 AUTH_003 / 위조 AUTH_004) · 403 권한 없음 (역할 부족, 다른 종류의 토큰, 타인 자원 접근)

식별자는 쿼리 id(처방전 id). 본인 처방전이 아니면 AUTH_005, 없으면 COMMON_003. 단계별 진입 시각(readyAt/paidAt 등)과 약품 목록, 인식 정보(partnerInfo)를 포함한다. 앱 주문 화면은 주로 /api/v1/orders/detail 을 쓰고, 이 API 는 처방전 원본 관점(이미지 URL, 약사 메모 등)이 필요할 때 쓴다. 회원 토큰 필요.

파라미터

응답 200

{"success":true,"data":…} — data: PrescriptionView (OK)

오류 응답: 400 잘못된 요청 (필수값 누락, 형식·검증 실패, 알 수 없는 코드값, 깨진 JSON·UTF-8 아닌 인코딩) · 401 인증 실패 (토큰 없음 AUTH_001 / 만료 AUTH_003 / 위조 AUTH_004) · 403 권한 없음 (역할 부족, 다른 종류의 토큰, 타인 자원 접근)

앱 처방전 미리보기 화면(PrescPreview)에서 CLOVA OCR 로 파싱한 결과(ocr: 교부번호·환자·병원·의사·교부일·약품코드)를 보내면 처방전 발급 정보를 저장하고 medicineSeq 를 돌려준다. 이 값을 처방전 등록 요청의 medicineSeq 로 전달해야 상세에 약품 목록과 병원 정보가 붙는다. 약품명은 OCR 인식값을 쓰지 않고 약품코드로 약품 마스터(없으면 대체약품 자료)를 조회해 채운다. prsEnc(QR) 경로는 EDB 연동 중단으로 현재 사용하지 않으며, ocr 이 없으면 success=false 로 응답한다. 회원 토큰 필요.

요청 본문 application/json — QrCallbackRequest

처방전 QR/OCR 콜백 요청 — POST /api/v1/prescriptions/qr-callback (현재는 ocr 파싱 결과 전송, prsEnc 는 구 QR 경로)

응답 200

{"success":true,"data":…} — data: QrCallbackResponse (OK)

오류 응답: 400 잘못된 요청 (필수값 누락, 형식·검증 실패, 알 수 없는 코드값, 깨진 JSON·UTF-8 아닌 인코딩) · 401 인증 실패 (토큰 없음 AUTH_001 / 만료 AUTH_003 / 위조 AUTH_004) · 403 권한 없음 (역할 부족, 다른 종류의 토큰, 타인 자원 접근)

앱 주문 진행 화면(MedicineOrder)과 결제 화면(MedicineOrderNicePay)에서 회원 측 상태 전이(예: 결제 완료 후 04, 수령 완료 010)에 호출한다. 대상은 본문 prescriptionId 이며 본인 처방전만 가능(아니면 AUTH_005). status 는 상태코드 문자열이고 알 수 없는 코드는 COMMON_001. 03 조제불가로 바꿀 때만 unavailableReason 이 저장된다. 회원이 바꾼 상태는 푸시를 발송하지 않는다(푸시는 관리자 처방전 갱신에서만). 회원 토큰 필요.

요청 본문 application/json — ChangeStatusRequest

처방전 상태 변경 요청 — POST /api/v1/prescriptions/update-status (회원 취소/수령완료 등)

응답 200

{"success":true,"data":…} — data: PrescriptionView (OK)

오류 응답: 400 잘못된 요청 (필수값 누락, 형식·검증 실패, 알 수 없는 코드값, 깨진 JSON·UTF-8 아닌 인코딩) · 401 인증 실패 (토큰 없음 AUTH_001 / 만료 AUTH_003 / 위조 AUTH_004) · 403 권한 없음 (역할 부족, 다른 종류의 토큰, 타인 자원 접근)

앱 처방전 미리보기 화면(PrescPreview)에서 촬영본을 먼저 올릴 때 호출한다. multipart 파트명은 file, 허용 형식 jpeg/png/pdf, 최대 20MB. 응답의 storagePath 를 처방전 등록 요청의 prescriptionImagePath 로 그대로 전달한다. 파일만 저장하고 DB 레코드는 만들지 않는다. 회원 토큰 필요.

요청 본문 multipart/form-data

응답 200

{"success":true,"data":…} — data: UploadImageResponse (OK)

오류 응답: 400 잘못된 요청 (필수값 누락, 형식·검증 실패, 알 수 없는 코드값, 깨진 JSON·UTF-8 아닌 인코딩) · 401 인증 실패 (토큰 없음 AUTH_001 / 만료 AUTH_003 / 위조 AUTH_004) · 403 권한 없음 (역할 부족, 다른 종류의 토큰, 타인 자원 접근)

앱 약 배송 자격 화면(DeliveryEligibility)에서 호출한다. multipart 로 documentTypes(카테고리 코드 1개: ltc65plus 65세 이상 장기요양등급자 / disabled 장애인 / infectiousDisease 감염병 환자 / rareDisease 희귀질환자)와 files(1개 이상, jpg/jpeg/gif/png/pdf, 각 20MB 이하)를 보낸다. 심사중(I) 상태의 신청 1건이 새로 만들어지며 이전 신청을 덮어쓰지 않는다. 회원 토큰 필요.

파라미터

요청 본문 multipart/form-data

응답 200

{"success":true,"data":…} — data: EligibilityDetail (OK)

오류 응답: 400 잘못된 요청 (필수값 누락, 형식·검증 실패, 알 수 없는 코드값, 깨진 JSON·UTF-8 아닌 인코딩) · 401 인증 실패 (토큰 없음 AUTH_001 / 만료 AUTH_003 / 위조 AUTH_004) · 403 권한 없음 (역할 부족, 다른 종류의 토큰, 타인 자원 접근)

앱 약 배송 자격 화면(DeliveryEligibility)과 배송지 관리 화면(AddressManagement)의 택배 가능 여부 판단에서 호출한다. 본인 신청 중 가장 최근 1건을 첨부 문서 목록과 함께 돌려주며, 신청 이력이 없으면 data 가 없다(null). state: I 심사중 / S 승인 / R 반려(rejectDesc 에 사유). 회원 토큰 필요.

응답 200

object (조회 성공 (이력 없으면 data 생략))

{
 "success": true,
 "data": {
  "summary": {
   "id": 9,
   "memberId": 12,
   "state": "I",
   "documentTypes": "ltc65plus",
   "documentCount": 1,
   "createdAt": "2026-09-11T10:15:30.123",
   "updatedAt": "2026-09-11T10:15:30.123"
  },
  "documents": [
   {
    "id": 21,
    "fileName": "인정서.jpg",
    "fileSize": 184233,
    "mimeType": "image/jpeg",
    "fileUrl": "/uploads/eligibility/9/2026-09-11/8c1d2e__인정서.jpg"
   }
  ]
 }
}

{"success":true,"data":…} — data: EligibilityDetail (조회 성공 (이력 없으면 data 생략))

오류 응답: 400 잘못된 요청 (필수값 누락, 형식·검증 실패, 알 수 없는 코드값, 깨진 JSON·UTF-8 아닌 인코딩) · 401 인증 실패 (토큰 없음 AUTH_001 / 만료 AUTH_003 / 위조 AUTH_004) · 403 권한 없음 (역할 부족, 다른 종류의 토큰, 타인 자원 접근)

앱 건강샵 주문 내역에서 호출한다. 본인 주문을 최신순으로 돌려주며 status 는 PAID/SHIPPING/DELIVERED, statusLabel 은 한글 라벨. 회원 토큰 필요.

응답 200

{"success":true,"data":…} — data: array<OrderView> (OK)

오류 응답: 400 잘못된 요청 (필수값 누락, 형식·검증 실패, 알 수 없는 코드값, 깨진 JSON·UTF-8 아닌 인코딩) · 401 인증 실패 (토큰 없음 AUTH_001 / 만료 AUTH_003 / 위조 AUTH_004) · 403 권한 없음 (역할 부족, 다른 종류의 토큰, 타인 자원 접근)

앱 건강샵 결제가 끝난 뒤 호출한다. 서버는 결제를 검증하지 않으며 items 의 productId 로 상품을 다시 조회해 단가와 배송비(정책 기준)를 재계산한 뒤 결제 완료(PAID) 상태로 저장한다. 수량은 1~99 로 보정되고 없는 상품은 COMMON_003. 주문번호는 SO-YYYYMMDD-### 형식. 회원 토큰 필요.

요청 본문 application/json — OrderCreateRequest

건강샵 주문 생성 요청 — POST /api/v1/shop/orders/create (결제 승인 후 호출, 주문번호 SO-YYYYMMDD-### 자동 채번)

응답 200

{"success":true,"data":…} — data: OrderView (OK)

오류 응답: 400 잘못된 요청 (필수값 누락, 형식·검증 실패, 알 수 없는 코드값, 깨진 JSON·UTF-8 아닌 인코딩) · 401 인증 실패 (토큰 없음 AUTH_001 / 만료 AUTH_003 / 위조 AUTH_004) · 403 권한 없음 (역할 부족, 다른 종류의 토큰, 타인 자원 접근)

앱 건강샵 탭 진입 시 호출한다. 관리자가 노출(visible=true)로 둔 삭제되지 않은 상품만 등록순으로 돌려준다. id 는 상품 코드(HP-001 형식)이며 주문 시 productId 로 쓴다. 회원 토큰 필요.

응답 200

object (조회 성공)

{
 "success": true,
 "data": [
  {
   "id": "HP-001",
   "category": "비타민",
   "emoji": "🍊",
   "name": "비타민C 1000",
   "brand": "약나루헬스",
   "brief": "하루 한 알 고함량 비타민C",
   "price": 15900,
   "originalPrice": 19900,
   "badge": "BEST",
   "visible": true,
   "functionality": "항산화 및 면역 기능 유지에 도움",
   "intake": "1일 1회, 1회 1정을 물과 함께 섭취",
   "caution": "특정 질환이 있는 경우 전문가와 상담",
   "image": "/uploads/shop/hp-001.jpg",
   "detailImages": [
    "/uploads/shop/hp-001-d1.jpg"
   ]
  }
 ]
}

{"success":true,"data":…} — data: array<ProductView> (조회 성공)

오류 응답: 400 잘못된 요청 (필수값 누락, 형식·검증 실패, 알 수 없는 코드값, 깨진 JSON·UTF-8 아닌 인코딩) · 401 인증 실패 (토큰 없음 AUTH_001 / 만료 AUTH_003 / 위조 AUTH_004) · 403 권한 없음 (역할 부족, 다른 종류의 토큰, 타인 자원 접근)

앱 장바구니·결제 화면에서 배송비 계산에 쓴다. deliveryFee(기본 배송비)와 freeThreshold(무료배송 기준 금액)를 돌려준다. 회원 토큰 필요.

응답 200

{"success":true,"data":…} — data: SettingView (OK)

오류 응답: 400 잘못된 요청 (필수값 누락, 형식·검증 실패, 알 수 없는 코드값, 깨진 JSON·UTF-8 아닌 인코딩) · 401 인증 실패 (토큰 없음 AUTH_001 / 만료 AUTH_003 / 위조 AUTH_004) · 403 권한 없음 (역할 부족, 다른 종류의 토큰, 타인 자원 접근)

앱 알림 목록 화면(PushList)에서 호출한다. 본인에게 보낸 메시지와 전체 공지(broadcast, memberId 없음)를 최신순으로 페이징한다. readAt 이 없으면 미읽음. relatedType(prescription_approved / prescription_rejected / order / delivery / eligibility / notice / qna)과 relatedId, payload(JSON 문자열)로 화면 이동에 쓴다. 회원 토큰 필요.

파라미터

응답 200

object (조회 성공 (Spring Data Page 형태))

{
 "success": true,
 "data": {
  "content": [
   {
    "id": 88,
    "memberId": 12,
    "title": "배송이 시작되었습니다",
    "body": "약이 배송 출발했습니다. 배송 조회로 위치를 확인하세요.",
    "payload": "{\"pharmacyName\":\"약나루약국\",\"pharmacyCode\":\"PH-001\",\"deliveryNumber\":\"123456789012\",\"deliveryCompany\":\"CJ대한통운\"}",
    "relatedType": "delivery",
    "relatedId": 41,
    "createdAt": "2026-09-11T08:30:01.204"
   },
   {
    "id": 80,
    "title": "새 공지가 등록되었습니다",
    "body": "추석 연휴 배송 안내",
    "relatedType": "notice",
    "relatedId": 7,
    "readAt": "2026-09-09T12:00:10.5",
    "createdAt": "2026-09-09T11:00:00.1"
   }
  ],
  "pageable": {
   "pageNumber": 0,
   "pageSize": 20,
   "sort": {
    "empty": false,
    "sorted": true,
    "unsorted": false
   },
   "offset": 0,
   "paged": true,
   "unpaged": false
  },
  "last": true,
  "totalElements": 2,
  "totalPages": 1,
  "size": 20,
  "number": 0,
  "sort": {
   "empty": false,
   "sorted": true,
   "unsorted": false
  },
  "first": true,
  "numberOfElements": 2,
  "empty": false
 }
}

{"success":true,"data":…} — data: Page<MessageInfo> (조회 성공 (Spring Data Page 형태))

오류 응답: 400 잘못된 요청 (필수값 누락, 형식·검증 실패, 알 수 없는 코드값, 깨진 JSON·UTF-8 아닌 인코딩) · 401 인증 실패 (토큰 없음 AUTH_001 / 만료 AUTH_003 / 위조 AUTH_004) · 403 권한 없음 (역할 부족, 다른 종류의 토큰, 타인 자원 접근)

앱 알림 목록 화면(PushList)의 삭제. 대상은 본문 pushId. 본인에게 온 메시지만 지울 수 있고 전체 공지(broadcast)나 타인 메시지는 AUTH_005. 회원 토큰 필요.

요청 본문 application/json — MessageDeleteRequest

알림 1건 삭제 요청 — POST /api/v1/push/messages/delete

응답 200

{"success":true,"data":…} — data: object (OK)

오류 응답: 400 잘못된 요청 (필수값 누락, 형식·검증 실패, 알 수 없는 코드값, 깨진 JSON·UTF-8 아닌 인코딩) · 401 인증 실패 (토큰 없음 AUTH_001 / 만료 AUTH_003 / 위조 AUTH_004) · 403 권한 없음 (역할 부족, 다른 종류의 토큰, 타인 자원 접근)

앱 알림 목록 화면(PushList)에서 항목을 열 때 호출한다. 대상은 본문 pushId. 타인의 메시지는 AUTH_005, 없으면 COMMON_003. 전체 공지도 읽음 처리할 수 있다. 회원 토큰 필요.

요청 본문 application/json — MessageReadRequest

알림 1건 읽음 처리 요청 — POST /api/v1/push/messages/read

응답 200

{"success":true,"data":…} — data: object (OK)

오류 응답: 400 잘못된 요청 (필수값 누락, 형식·검증 실패, 알 수 없는 코드값, 깨진 JSON·UTF-8 아닌 인코딩) · 401 인증 실패 (토큰 없음 AUTH_001 / 만료 AUTH_003 / 위조 AUTH_004) · 403 권한 없음 (역할 부족, 다른 종류의 토큰, 타인 자원 접근)

앱 알림 목록 화면(PushList)의 모두 읽음 버튼. 본인 미읽음 메시지를 한 번에 읽음 처리하고 처리 건수를 {updated} 로 돌려준다. 회원 토큰 필요.

응답 200

{"success":true,"data":…} — data: object (OK)

오류 응답: 400 잘못된 요청 (필수값 누락, 형식·검증 실패, 알 수 없는 코드값, 깨진 JSON·UTF-8 아닌 인코딩) · 401 인증 실패 (토큰 없음 AUTH_001 / 만료 AUTH_003 / 위조 AUTH_004) · 403 권한 없음 (역할 부족, 다른 종류의 토큰, 타인 자원 접근)

앱 홈(Home) 화면의 알림 뱃지용. 본인 메시지와 전체 공지 중 readAt 이 없는 건수를 {count} 로 돌려준다. 회원 토큰 필요.

응답 200

{"success":true,"data":…} — data: object (OK)

오류 응답: 400 잘못된 요청 (필수값 누락, 형식·검증 실패, 알 수 없는 코드값, 깨진 JSON·UTF-8 아닌 인코딩) · 401 인증 실패 (토큰 없음 AUTH_001 / 만료 AUTH_003 / 위조 AUTH_004) · 403 권한 없음 (역할 부족, 다른 종류의 토큰, 타인 자원 접근)

앱이 로그인 후(FcmEffect) FCM 토큰을 얻을 때마다 호출한다. 같은 토큰이 이미 있으면 회원·기기(deviceId)·플랫폼(platform) 정보만 갱신한다. 푸시 발송 시 회원별로 가장 최근에 갱신된 토큰 1개(마지막 로그인 폰)에만 보내므로, 토큰이 바뀌면 반드시 다시 호출해야 한다. 회원 토큰 필요.

요청 본문 application/json — SubscribeRequest

푸시 토큰 구독 요청 — POST /api/v1/push/subscribe (동일 토큰 재전송 시 메타 갱신)

응답 200

{"success":true,"data":…} — data: SubscriptionInfo (OK)

오류 응답: 400 잘못된 요청 (필수값 누락, 형식·검증 실패, 알 수 없는 코드값, 깨진 JSON·UTF-8 아닌 인코딩) · 401 인증 실패 (토큰 없음 AUTH_001 / 만료 AUTH_003 / 위조 AUTH_004) · 403 권한 없음 (역할 부족, 다른 종류의 토큰, 타인 자원 접근)

앱 로그아웃 직전에 호출해 이 기기의 토큰(본문 fcmToken)을 구독 목록에서 지운다. 이후 이 기기로는 푸시가 오지 않는다. 회원 토큰 필요.

요청 본문 application/json — UnsubscribeRequest

푸시 토큰 구독 해제 요청 — POST /api/v1/push/unsubscribe

응답 200

{"success":true,"data":…} — data: object (OK)

오류 응답: 400 잘못된 요청 (필수값 누락, 형식·검증 실패, 알 수 없는 코드값, 깨진 JSON·UTF-8 아닌 인코딩) · 401 인증 실패 (토큰 없음 AUTH_001 / 만료 AUTH_003 / 위조 AUTH_004) · 403 권한 없음 (역할 부족, 다른 종류의 토큰, 타인 자원 접근)

앱 FAQ 화면(Faq)의 카테고리 탭 구성용. 활성 카테고리만 정렬순(sort)으로 돌려준다. 로그인 불필요.

응답 200

{"success":true,"data":…} — data: array<CategoryView> (OK)

오류 응답: 400 잘못된 요청 (필수값 누락, 형식·검증 실패, 알 수 없는 코드값, 깨진 JSON·UTF-8 아닌 인코딩)

앱 FAQ 화면(Faq)과 관리자웹 FAQ 관리에서 호출한다. 각 항목에 categoryId 와 categoryName 이 포함되어 앱이 카테고리 탭으로 묶어 보여준다. categoryId 를 주면 그 카테고리만, 안 주면 전체를 돌려준다(관리자웹 카테고리 필터). 기본 페이지 크기 50. 로그인 불필요.

파라미터

응답 200

{"success":true,"data":…} — data: Page<PostView> (OK)

오류 응답: 400 잘못된 요청 (필수값 누락, 형식·검증 실패, 알 수 없는 코드값, 깨진 JSON·UTF-8 아닌 인코딩)

앱 공지사항 목록 화면(NoticeList)에서 호출한다. 삭제되지 않은 공지를 페이징해 돌려주며 contents(본문)도 포함된다. 로그인 불필요.

파라미터

응답 200

object (조회 성공 (Spring Data Page 형태))

{
 "success": true,
 "data": {
  "content": [
   {
    "id": 7,
    "boardType": "notice",
    "subject": "추석 연휴 배송 안내",
    "contents": "9/24~9/27 은 택배 배송이 중단됩니다.",
    "viewCount": 132,
    "regDate": "2026-09-09T11:00:00.1"
   }
  ],
  "pageable": {
   "pageNumber": 0,
   "pageSize": 20,
   "sort": {
    "empty": true,
    "sorted": false,
    "unsorted": true
   },
   "offset": 0,
   "paged": true,
   "unpaged": false
  },
  "last": true,
  "totalElements": 1,
  "totalPages": 1,
  "size": 20,
  "number": 0,
  "sort": {
   "empty": true,
   "sorted": false,
   "unsorted": true
  },
  "first": true,
  "numberOfElements": 1,
  "empty": false
 }
}

{"success":true,"data":…} — data: Page<PostView> (조회 성공 (Spring Data Page 형태))

오류 응답: 400 잘못된 요청 (필수값 누락, 형식·검증 실패, 알 수 없는 코드값, 깨진 JSON·UTF-8 아닌 인코딩)

앱 공지 상세 화면(NoticeDetail)에서 호출한다. 식별자는 쿼리 id. 호출할 때마다 조회수(viewCount)가 1 증가한다. 삭제된 글이나 공지가 아닌 글은 COMMON_003. 로그인 불필요.

파라미터

응답 200

{"success":true,"data":…} — data: PostView (OK)

오류 응답: 400 잘못된 요청 (필수값 누락, 형식·검증 실패, 알 수 없는 코드값, 깨진 JSON·UTF-8 아닌 인코딩)

앱 문의 작성 화면(QnaWrite)에 들어갈 때 호출한다. 활성 Q&A 카테고리를 정렬순으로 돌려준다. 회원 토큰 필요.

응답 200

{"success":true,"data":…} — data: array<CategoryView> (OK)

오류 응답: 400 잘못된 요청 (필수값 누락, 형식·검증 실패, 알 수 없는 코드값, 깨진 JSON·UTF-8 아닌 인코딩) · 401 인증 실패 (토큰 없음 AUTH_001 / 만료 AUTH_003 / 위조 AUTH_004) · 403 권한 없음 (역할 부족, 다른 종류의 토큰, 타인 자원 접근)

앱 문의 내역 화면(QnaList)에서 호출한다. 본인이 작성한 문의만 페이징하며 status 는 한글 라벨(답변대기/답변완료)이다. 회원 토큰 필요.

파라미터

응답 200

{"success":true,"data":…} — data: Page<QnaView> (OK)

오류 응답: 400 잘못된 요청 (필수값 누락, 형식·검증 실패, 알 수 없는 코드값, 깨진 JSON·UTF-8 아닌 인코딩) · 401 인증 실패 (토큰 없음 AUTH_001 / 만료 AUTH_003 / 위조 AUTH_004) · 403 권한 없음 (역할 부족, 다른 종류의 토큰, 타인 자원 접근)

앱 문의 작성 화면(QnaWrite)에서 호출한다. question(2~4000자) 필수, categoryId 는 선택이며 없는 카테고리면 COMMON_001. 답변대기 상태로 저장되고, 관리자가 답변을 달면 회원에게 FCM 푸시(문의 답변 도착)가 온다. 회원 토큰 필요.

요청 본문 application/json — QnaWriteRequest

1:1 문의 작성 요청 — POST /api/v1/bbs/qnas (회원)

응답 200

{"success":true,"data":…} — data: QnaView (OK)

오류 응답: 400 잘못된 요청 (필수값 누락, 형식·검증 실패, 알 수 없는 코드값, 깨진 JSON·UTF-8 아닌 인코딩) · 401 인증 실패 (토큰 없음 AUTH_001 / 만료 AUTH_003 / 위조 AUTH_004) · 403 권한 없음 (역할 부족, 다른 종류의 토큰, 타인 자원 접근)

개발자가 테스트 데이터를 비울 때 직접 호출한다. eligibility_file(첨부 서류)과 eligibility_info(자격 신청)를 모두 DELETE 하고 테이블별 삭제 건수를 돌려준다. 업로드된 실제 파일은 지우지 않는다. 되돌릴 수 없다. 로그인 불필요.

응답 200

{"success":true,"data":…} — data: object (OK)

오류 응답: 400 잘못된 요청 (필수값 누락, 형식·검증 실패, 알 수 없는 코드값, 깨진 JSON·UTF-8 아닌 인코딩)

개발자가 테스트 데이터를 비울 때 직접 호출한다. order_info(처방전/주문), issue_drug(인식 약품), issue_info(처방전 인식 정보) 테이블을 FK 순서대로 모두 DELETE 하고 테이블별 삭제 건수를 돌려준다. 되돌릴 수 없다. 로그인 불필요.

응답 200

{"success":true,"data":…} — data: object (OK)

오류 응답: 400 잘못된 요청 (필수값 누락, 형식·검증 실패, 알 수 없는 코드값, 깨진 JSON·UTF-8 아닌 인코딩)

관리자웹 로그인 화면에서 호출한다. adminId + adminPass 검증 후 access 토큰(30분)/refresh 토큰(14일)과 adminInfo(역할 포함)를 돌려주고 마지막 로그인 시각을 갱신한다. 계정 상태에 따라 거절된다: 가입 검토 대기(PENDING)와 정지(SUSPENDED)는 AUTH_005, 탈퇴(WITHDRAWN)는 MEMBER_004, 아이디·비밀번호 불일치는 AUTH_002. 로그인 불필요.

요청 본문 application/json — AdminLoginRequest

관리자(약사/시스템 운영자) 로그인 요청 — POST /api/v1/admin/auth/login

응답 200

object (로그인 성공)

{
 "success": true,
 "data": {
  "tokenType": "Bearer",
  "accessToken": "eyJhbGciOiJIUzI1NiJ9.eyJzdWIiOiIzMSIsInVzZXJUeXBlIjoiQURNSU4ifQ.xxxxx",
  "refreshToken": "eyJhbGciOiJIUzI1NiJ9.eyJzdWIiOiIzMSIsInR5cCI6InJlZnJlc2gifQ.yyyyy",
  "expiresIn": 1800,
  "adminInfo": {
   "id": 31,
   "adminId": "pharm_kim",
   "adminName": "김약사",
   "adminEmail": "kim@pharmacy.kr",
   "adminTel": "010-1111-2222",
   "adminState": "ACTIVE",
   "roles": [
    "PHARMACY_ADMIN"
   ]
  }
 }
}

오류 응답: 401 아이디 또는 비밀번호 불일치 · 403 가입 검토 대기 또는 정지된 계정 · 400 잘못된 요청 (필수값 누락, 형식·검증 실패, 알 수 없는 코드값, 깨진 JSON·UTF-8 아닌 인코딩)

관리자웹 요청 계층이 access 토큰 만료(401)를 받으면 자동으로 호출한다. 관리자용(userType=ADMIN) refresh 토큰만 받으며 회원 토큰이나 위조·만료 토큰은 AUTH_004. 새 access/refresh 토큰 쌍과 adminInfo 를 다시 돌려준다. 로그인 불필요(본문 refreshToken 만 사용).

요청 본문 application/json — AdminRefreshRequest

관리자 토큰 갱신 요청 — POST /api/v1/admin/auth/refresh

응답 200

{"success":true,"data":…} — data: AdminTokenResponse (OK)

오류 응답: 400 잘못된 요청 (필수값 누락, 형식·검증 실패, 알 수 없는 코드값, 깨진 JSON·UTF-8 아닌 인코딩)

관리자웹 로그인 화면의 비밀번호 찾기 모달에서 호출한다. adminId 와 등록 이메일(adminEmail)이 일치하면 12자 임시 비밀번호로 바꾸고 그 이메일로 발송한다. 불일치는 AUTH_002, 탈퇴 계정은 MEMBER_004, 메일 발송 실패 시 비밀번호 변경도 롤백되고 COMMON_004. 로그인 불필요.

요청 본문 application/json — AdminResetPasswordRequest

관리자 비밀번호 찾기 요청 — POST /api/v1/admin/auth/reset-password (아이디+이메일 일치 시 임시 비밀번호 메일 발송)

응답 200

{"success":true,"data":…} — data: object (OK)

오류 응답: 400 잘못된 요청 (필수값 누락, 형식·검증 실패, 알 수 없는 코드값, 깨진 JSON·UTF-8 아닌 인코딩)

관리자웹 회원가입 화면(signup)의 중복확인 버튼. 관리자 계정 전체(약사·운영자)를 대상으로 검사해 {adminId, available} 를 돌려준다. 빈 값이면 available=false. 로그인 불필요.

파라미터

응답 200

{"success":true,"data":…} — data: object (OK)

오류 응답: 400 잘못된 요청 (필수값 누락, 형식·검증 실패, 알 수 없는 코드값, 깨진 JSON·UTF-8 아닌 인코딩)

관리자웹 회원가입 화면(signup)에서 호출한다. multipart 로 payload(약사·약국·계좌 정보 JSON 문자열)와 businessLicense(사업자등록증 파일, 필수)를 보낸다. 한 트랜잭션으로 약사 계정(PHARMACY_ADMIN, 상태 PENDING) + 약국(코드 PH-### 자동 채번, 배송 가능 Y 로 즉시 앱 약국 목록에 노출) + 약사-약국 매핑 + 사업자등록증 첨부를 만든다. 아이디 중복이나 payload 형식 오류, 파일 누락은 COMMON_001. PENDING 동안 로그인은 AUTH_005 로 거절되며 운영자가 /api/v1/admin/pharmacies/approve 로 승인하면 ACTIVE 가 된다. 로그인 불필요.

요청 본문 multipart/form-data

응답 200

object (신청 접수 (검토 대기))

{
 "success": true,
 "data": {
  "adminUserId": 31,
  "pharmacyCode": "PH-012",
  "adminId": "pharm_kim",
  "pharmacyName": "약나루약국",
  "state": "PENDING"
 }
}

{"success":true,"data":…} — data: PharmacistSignUpResponse (신청 접수 (검토 대기))

오류 응답: 400 잘못된 요청 (필수값 누락, 형식·검증 실패, 알 수 없는 코드값, 깨진 JSON·UTF-8 아닌 인코딩)

관리자웹 헤더와 내 정보 메뉴(myProfile)에서 호출한다. 역할(roles), 상태, 마지막 로그인 시각, 약사 생년월일(adminBirth, PHARMACY_ADMIN 만 의미)을 포함한다. 관리자 토큰 필요.

응답 200

object (조회 성공)

{
 "success": true,
 "data": {
  "id": 31,
  "adminId": "pharm_kim",
  "adminName": "김약사",
  "adminEmail": "kim@pharmacy.kr",
  "adminTel": "010-1111-2222",
  "adminBirth": "1985-03-02",
  "adminState": "ACTIVE",
  "roles": [
   "PHARMACY_ADMIN"
  ],
  "lastLoginAt": "2026-09-11T09:02:11.53",
  "createdAt": "2026-08-20T14:10:00.2"
 }
}

{"success":true,"data":…} — data: MeInfo (조회 성공)

오류 응답: 400 잘못된 요청 (필수값 누락, 형식·검증 실패, 알 수 없는 코드값, 깨진 JSON·UTF-8 아닌 인코딩) · 401 인증 실패 (토큰 없음 AUTH_001 / 만료 AUTH_003 / 위조 AUTH_004) · 403 권한 없음 (역할 부족, 다른 종류의 토큰, 타인 자원 접근)

관리자웹 약국정보 메뉴(pharmacyInfo, 약사 전용)에서 호출한다. 본인에게 매핑된 약국을 영업시간·약사·계좌 정보까지 포함해 돌려준다. 매핑이 없으면 빈 배열(SYSTEM_ADMIN 도 매핑이 있으면 표시). 관리자 토큰 필요.

응답 200

{"success":true,"data":…} — data: array<PharmacyView> (OK)

오류 응답: 400 잘못된 요청 (필수값 누락, 형식·검증 실패, 알 수 없는 코드값, 깨진 JSON·UTF-8 아닌 인코딩) · 401 인증 실패 (토큰 없음 AUTH_001 / 만료 AUTH_003 / 위조 AUTH_004) · 403 권한 없음 (역할 부족, 다른 종류의 토큰, 타인 자원 접근)

관리자웹 약국정보 메뉴(pharmacyInfo)의 저장 버튼. 대상은 본문 pharmacyCode 이며 본인에게 매핑된 약국이 아니면 AUTH_005. null 로 보낸 항목은 유지된다. 주소(address)가 바뀌었는데 gpsLat/gpsLon 을 주지 않으면 카카오 지오코딩으로 위경도를 자동 산출한다. 영업시간은 요일별 'HH:mm~HH:mm' 또는 '휴무'. 감사기록 ADMIN_ME_PHARMACY_UPDATE 를 남긴다. 관리자 토큰 필요.

요청 본문 application/json — AdminPharmacyUpdateRequest

약국 부분 수정 요청 — POST /api/v1/admin/pharmacies/update (null 필드는 미변경)

응답 200

{"success":true,"data":…} — data: PharmacyView (OK)

오류 응답: 400 잘못된 요청 (필수값 누락, 형식·검증 실패, 알 수 없는 코드값, 깨진 JSON·UTF-8 아닌 인코딩) · 401 인증 실패 (토큰 없음 AUTH_001 / 만료 AUTH_003 / 위조 AUTH_004) · 403 권한 없음 (역할 부족, 다른 종류의 토큰, 타인 자원 접근)

관리자웹 내 정보 메뉴의 수정 모달에서 호출한다. 이름·이메일·전화·생년월일만 바꿀 수 있고 null 로 보낸 항목은 유지된다. 변경 전/후 값으로 감사기록 ADMIN_ME_UPDATE 를 남긴다. 관리자 토큰 필요.

요청 본문 application/json — UpdateMeRequest

관리자 내 프로필 부분 수정 요청 — POST /api/v1/admin/me/update (null 필드는 미변경, adminId/roles/state 는 본인 변경 불가)

응답 200

{"success":true,"data":…} — data: MeInfo (OK)

오류 응답: 400 잘못된 요청 (필수값 누락, 형식·검증 실패, 알 수 없는 코드값, 깨진 JSON·UTF-8 아닌 인코딩) · 401 인증 실패 (토큰 없음 AUTH_001 / 만료 AUTH_003 / 위조 AUTH_004) · 403 권한 없음 (역할 부족, 다른 종류의 토큰, 타인 자원 접근)

관리자웹 내 정보 메뉴의 비밀번호 변경에서 호출한다. currentPassword 가 맞아야 하며 틀리면 AUTH_002. 새 비밀번호는 6~64자. 감사기록 ADMIN_ME_PASSWORD_UPDATE 를 남기되 비밀번호 값은 기록하지 않는다. 관리자 토큰 필요.

요청 본문 application/json — ChangePasswordRequest

회원 비밀번호 변경 요청 — POST /api/v1/members/me/update-password

응답 200

{"success":true,"data":…} — data: object (OK)

오류 응답: 400 잘못된 요청 (필수값 누락, 형식·검증 실패, 알 수 없는 코드값, 깨진 JSON·UTF-8 아닌 인코딩) · 401 인증 실패 (토큰 없음 AUTH_001 / 만료 AUTH_003 / 위조 AUTH_004) · 403 권한 없음 (역할 부족, 다른 종류의 토큰, 타인 자원 접근)

관리자웹 홈(대시보드) 진입 시 호출한다. counts: todayNew(오늘 접수된 01 발송 건, 최근 100건 내에서 집계) / paymentWaiting(02 조제가능) / shipping(06 배송중), monthRevenue·monthOrderCount(이번 달 1일~오늘, 010 수령완료 기준 매출·건수), recent(최근 처방전 5건, 상태 무관), asOf(집계 시각), period(집계 기간). 약국 범위는 토큰 역할로 자동 적용되며 매핑 약국이 없는 약사는 모두 0/빈 배열. 관리자 토큰 필요.

응답 200

object (집계 성공)

{
 "success": true,
 "data": {
  "counts": {
   "todayNew": 3,
   "paymentWaiting": 5,
   "shipping": 2
  },
  "monthRevenue": 1250000,
  "monthOrderCount": 48,
  "recent": [
   {
    "id": 42,
    "status": "01",
    "statusName": "발송",
    "receiveType": "onLine",
    "pharmacyName": "약나루약국",
    "pharmacyPhone": "02-1234-5678",
    "pharmacyAddress": "서울특별시 강남구 테헤란로 123 1층",
    "memId": "hong123",
    "memName": "홍길동",
    "deliveryName": "홍길동",
    "deliveryPhone": "010-1234-5678",
    "deliveryAddress": "서울특별시 서초구 반포대로 45",
    "reqDate": "2026-09-11T10:15:30.123",
    "medicineList": []
   }
  ],
  "asOf": "2026-09-11T10:20:01.554",
  "period": {
   "from": "2026-09-01",
   "to": "2026-09-11"
  }
 }
}

{"success":true,"data":…} — data: DashboardSummary (집계 성공)

오류 응답: 400 잘못된 요청 (필수값 누락, 형식·검증 실패, 알 수 없는 코드값, 깨진 JSON·UTF-8 아닌 인코딩) · 401 인증 실패 (토큰 없음 AUTH_001 / 만료 AUTH_003 / 위조 AUTH_004) · 403 권한 없음 (역할 부족, 다른 종류의 토큰, 타인 자원 접근)

관리자웹 처방전 관리 메뉴의 목록. status(상태코드 01~010)와 keyword 로 거르고 약국 범위(scope)는 토큰의 역할로 자동 적용된다. PHARMACY_ADMIN 인데 매핑 약국이 없으면 빈 목록. 각 행에 회원 아이디·이름(memId/memName)과 약품 목록, 인식 정보가 포함된다. perPage 는 1~100. 관리자 토큰 필요.

파라미터

응답 200

{"success":true,"data":…} — data: Page<PrescriptionView> (OK)

오류 응답: 400 잘못된 요청 (필수값 누락, 형식·검증 실패, 알 수 없는 코드값, 깨진 JSON·UTF-8 아닌 인코딩) · 401 인증 실패 (토큰 없음 AUTH_001 / 만료 AUTH_003 / 위조 AUTH_004) · 403 권한 없음 (역할 부족, 다른 종류의 토큰, 타인 자원 접근)

관리자웹 처방전 관리 메뉴의 상세/크게보기 모달에서 호출한다. 식별자는 쿼리 id(처방전 id). 없으면 COMMON_003, 소속 약국 밖이면 AUTH_005. 이미지 URL, 약사 메모, 단계별 진입 시각(readyAt/paidAt/preparedAt/inTransitAt/deliveredAt/pickedUpAt), 약품 목록, 병원·의사 인식 정보(partnerInfo)를 모두 포함한다. 관리자 토큰 필요.

파라미터

응답 200

object (조회 성공)

{"success":true,"data":…} — data: PrescriptionView (조회 성공)

오류 응답: 400 잘못된 요청 (필수값 누락, 형식·검증 실패, 알 수 없는 코드값, 깨진 JSON·UTF-8 아닌 인코딩) · 401 인증 실패 (토큰 없음 AUTH_001 / 만료 AUTH_003 / 위조 AUTH_004) · 403 권한 없음 (역할 부족, 다른 종류의 토큰, 타인 자원 접근)

관리자웹 처방전 관리 상세 모달의 저장/상태 변경 버튼. 대상은 본문 prescriptionId. status(상태코드), 조제비·배송비, 복약안내(medicineDirection), 송장번호·택배사, 조제불가 사유, 약사 내부 메모(pharmacistMemo, 회원 미노출)를 부분 수정하며 null 은 유지. status 가 실제로 바뀌면 회원에게 FCM 푸시가 자동 발송된다(02 조제가능·03 조제불가·04 결제완료·05 조제완료·06 배송중·07 배송완료·010 수령완료). 알 수 없는 코드는 COMMON_001. 변경 전/후 값으로 감사기록 PRESCRIPTION_UPDATE. 관리자 토큰 필요(소속 약국 밖은 AUTH_005).

요청 본문 application/json — AdminUpdatePrescriptionRequest

관리자 처방전 부분 수정 요청 — POST /api/v1/admin/prescriptions/update (null 필드는 미변경)

응답 200

{"success":true,"data":…} — data: PrescriptionView (OK)

오류 응답: 400 잘못된 요청 (필수값 누락, 형식·검증 실패, 알 수 없는 코드값, 깨진 JSON·UTF-8 아닌 인코딩) · 401 인증 실패 (토큰 없음 AUTH_001 / 만료 AUTH_003 / 위조 AUTH_004) · 403 권한 없음 (역할 부족, 다른 종류의 토큰, 타인 자원 접근)

관리자웹 처방전 관리 상세 모달에서 OCR 오인식된 병원·의사·환자·진단코드·교부일·약품을 약사가 바로잡을 때 호출한다. 대상은 본문 prescriptionId. 모든 필드는 보낸 값 그대로 저장되고(빈 문자열은 null), 인식 정보가 없던 처방전이면 ADMIN 유형으로 새로 만들어 연결한다. medicines 를 리스트로 보내면 기존 약품을 전부 교체하며(null 이면 유지) 약품명은 보낸 값을 무시하고 코드로 약품 마스터를 조회해 채운다. 푸시는 없다. 감사기록 PRESCRIPTION_PARTNER_INFO_UPDATE. 관리자 토큰 필요.

요청 본문 application/json — AdminUpdatePartnerInfoRequest

관리자 처방전 발급정보 수정 요청 — POST /api/v1/admin/prescriptions/update-partner-info (OCR 오인식 보정, 전송값 그대로 저장·빈 문자열은 null)

응답 200

{"success":true,"data":…} — data: PrescriptionView (OK)

오류 응답: 400 잘못된 요청 (필수값 누락, 형식·검증 실패, 알 수 없는 코드값, 깨진 JSON·UTF-8 아닌 인코딩) · 401 인증 실패 (토큰 없음 AUTH_001 / 만료 AUTH_003 / 위조 AUTH_004) · 403 권한 없음 (역할 부족, 다른 종류의 토큰, 타인 자원 접근)

관리자웹 주문 관리 메뉴의 목록. status(상태코드), pharmacyId(약국 PK), 접수일 범위 dateFrom~dateTo(yyyy-MM-dd, dateTo 당일 포함)로 거르고 약국 범위는 토큰 역할로 자동 적용된다. 행은 Excel 변환이 쉬운 평탄한 형태(회원명·연락처는 배송지 스냅샷). perPage 는 1~100. 관리자 토큰 필요.

파라미터

응답 200

{"success":true,"data":…} — data: Page<AdminOrderRow> (OK)

오류 응답: 400 잘못된 요청 (필수값 누락, 형식·검증 실패, 알 수 없는 코드값, 깨진 JSON·UTF-8 아닌 인코딩) · 401 인증 실패 (토큰 없음 AUTH_001 / 만료 AUTH_003 / 위조 AUTH_004) · 403 권한 없음 (역할 부족, 다른 종류의 토큰, 타인 자원 접근)

관리자웹 주문 관리 메뉴의 상세 모달에서 호출한다. 식별자는 쿼리 id(처방전 id). 앱 주문 상세와 같은 형태이며 없으면 COMMON_003, 소속 약국 밖이면 AUTH_005. 관리자 토큰 필요.

파라미터

응답 200

{"success":true,"data":…} — data: OrderDetail (OK)

오류 응답: 400 잘못된 요청 (필수값 누락, 형식·검증 실패, 알 수 없는 코드값, 깨진 JSON·UTF-8 아닌 인코딩) · 401 인증 실패 (토큰 없음 AUTH_001 / 만료 AUTH_003 / 위조 AUTH_004) · 403 권한 없음 (역할 부족, 다른 종류의 토큰, 타인 자원 접근)

관리자웹 주문 관리 메뉴의 Excel 버튼. 검색과 같은 필터를 받되 페이징 없이 최대 100,000 행을 xlsx 파일(orders-yyyy-MM-dd.xlsx, Content-Disposition attachment)로 내려준다. 응답은 공통 JSON 래퍼가 아닌 바이너리다. 관리자 토큰 필요.

파라미터

응답 200

바이너리 파일 application/vnd.openxmlformats-officedocument.spreadsheetml.sheet — xlsx 파일

오류 응답: 400 잘못된 요청 (필수값 누락, 형식·검증 실패, 알 수 없는 코드값, 깨진 JSON·UTF-8 아닌 인코딩) · 401 인증 실패 (토큰 없음 AUTH_001 / 만료 AUTH_003 / 위조 AUTH_004) · 403 권한 없음 (역할 부족, 다른 종류의 토큰, 타인 자원 접근)

관리자웹 매출 정산 메뉴에서 호출한다. status 기본값은 010(수령완료)이며 날짜 범위(접수일 기준)를 비우면 전체 기간. 약국별 주문 수·총액·조제비 합·배송비 합(rows)과 전체 합계(totalOrderCount, totalRevenueSum)를 돌려준다. 약국 범위는 토큰 역할로 자동 적용. 관리자 토큰 필요.

파라미터

응답 200

object (집계 성공)

{
 "success": true,
 "data": {
  "rows": [
   {
    "pharmacyId": 3,
    "pharmacyName": "약나루약국",
    "orderCount": 31,
    "totalSum": 842000,
    "prescriptionSum": 749000,
    "deliverySum": 93000
   },
   {
    "pharmacyId": 5,
    "pharmacyName": "건강약국",
    "orderCount": 17,
    "totalSum": 408000,
    "prescriptionSum": 372000,
    "deliverySum": 36000
   }
  ],
  "totalOrderCount": 48,
  "totalRevenueSum": 1250000,
  "dateFrom": "2026-09-01",
  "dateTo": "2026-09-30",
  "status": "010"
 }
}

{"success":true,"data":…} — data: AdminRevenueSummary (집계 성공)

오류 응답: 400 잘못된 요청 (필수값 누락, 형식·검증 실패, 알 수 없는 코드값, 깨진 JSON·UTF-8 아닌 인코딩) · 401 인증 실패 (토큰 없음 AUTH_001 / 만료 AUTH_003 / 위조 AUTH_004) · 403 권한 없음 (역할 부족, 다른 종류의 토큰, 타인 자원 접근)

관리자웹 매출 정산 메뉴의 Excel 버튼. 매출 정산 조회와 같은 집계를 xlsx 파일(revenue-yyyy-MM-dd.xlsx)로 내려준다. 응답은 공통 JSON 래퍼가 아닌 바이너리다. 관리자 토큰 필요.

파라미터

응답 200

바이너리 파일 application/vnd.openxmlformats-officedocument.spreadsheetml.sheet — xlsx 파일

오류 응답: 400 잘못된 요청 (필수값 누락, 형식·검증 실패, 알 수 없는 코드값, 깨진 JSON·UTF-8 아닌 인코딩) · 401 인증 실패 (토큰 없음 AUTH_001 / 만료 AUTH_003 / 위조 AUTH_004) · 403 권한 없음 (역할 부족, 다른 종류의 토큰, 타인 자원 접근)

관리자웹 약 배송 자격 메뉴의 목록. state 로 I(심사중)/S(승인)/R(반려)만 거르거나 비우면 전체. 각 행에 회원 아이디·이름(memberLoginId/memberName)과 첨부 수(documentCount)가 포함된다. 잘못된 state 값은 COMMON_001. perPage 는 1~100. 관리자 토큰 필요.

파라미터

응답 200

{"success":true,"data":…} — data: Page<EligibilitySummary> (OK)

오류 응답: 400 잘못된 요청 (필수값 누락, 형식·검증 실패, 알 수 없는 코드값, 깨진 JSON·UTF-8 아닌 인코딩) · 401 인증 실패 (토큰 없음 AUTH_001 / 만료 AUTH_003 / 위조 AUTH_004) · 403 권한 없음 (역할 부족, 다른 종류의 토큰, 타인 자원 접근)

관리자웹 약 배송 자격 상세 모달의 승인 버튼. 대상은 본문 eligibilityId(없으면 COMMON_003). 상태를 S 로 바꾸고 신청 회원에게 FCM 푸시(약 배송 자격 승인)를 보내며 변경 전/후 값으로 감사기록 ELIGIBILITY_APPROVE 를 남긴다. /api/v1/eligibility/approve 와 같은 동작. 관리자 토큰 필요.

요청 본문 application/json — ApproveRequest

자격 승인 요청 — POST /api/v1/admin/eligibility/approve (상태 I → S)

응답 200

{"success":true,"data":…} — data: EligibilitySummary (OK)

오류 응답: 400 잘못된 요청 (필수값 누락, 형식·검증 실패, 알 수 없는 코드값, 깨진 JSON·UTF-8 아닌 인코딩) · 401 인증 실패 (토큰 없음 AUTH_001 / 만료 AUTH_003 / 위조 AUTH_004) · 403 권한 없음 (역할 부족, 다른 종류의 토큰, 타인 자원 접근)

관리자웹 약 배송 자격 메뉴의 상세 모달에서 호출한다. 식별자는 쿼리 id(신청 id). 첨부 서류 목록(fileUrl 은 /uploads/... 경로)을 포함하며 없으면 COMMON_003. 관리자 토큰 필요.

파라미터

응답 200

{"success":true,"data":…} — data: EligibilityDetail (OK)

오류 응답: 400 잘못된 요청 (필수값 누락, 형식·검증 실패, 알 수 없는 코드값, 깨진 JSON·UTF-8 아닌 인코딩) · 401 인증 실패 (토큰 없음 AUTH_001 / 만료 AUTH_003 / 위조 AUTH_004) · 403 권한 없음 (역할 부족, 다른 종류의 토큰, 타인 자원 접근)

관리자웹 약 배송 자격 상세 모달의 반려 버튼. 대상은 본문 eligibilityId, reason 을 비우면 '사유 미입력' 으로 저장된다. 상태를 R 로 바꾸고 rejectDesc 에 사유를 남기며 신청 회원에게 FCM 푸시(약 배송 자격 반려, payload 에 reason)를 보낸다. 회원은 앱에서 재신청할 수 있다. 감사기록 ELIGIBILITY_REJECT. /api/v1/eligibility/reject 와 같은 동작. 관리자 토큰 필요.

요청 본문 application/json — RejectRequest

자격 반려 요청 — POST /api/v1/admin/eligibility/reject (상태 I → R, 사유 회원 노출)

응답 200

{"success":true,"data":…} — data: EligibilitySummary (OK)

오류 응답: 400 잘못된 요청 (필수값 누락, 형식·검증 실패, 알 수 없는 코드값, 깨진 JSON·UTF-8 아닌 인코딩) · 401 인증 실패 (토큰 없음 AUTH_001 / 만료 AUTH_003 / 위조 AUTH_004) · 403 권한 없음 (역할 부족, 다른 종류의 토큰, 타인 자원 접근)

관리자웹 회원 관리(앱) 메뉴의 목록. keyword 와 state(ACTIVE/DORMANT/SUSPENDED/WITHDRAWN)로 거르고 withDeleted=true 면 탈퇴 회원도 포함한다. perPage 는 1~100 으로 보정. SYSTEM_ADMIN 토큰 필요.

파라미터

응답 200

object (검색 성공 (Spring Data Page 형태))

{
 "success": true,
 "data": {
  "content": [
   {
    "id": 12,
    "memId": "hong123",
    "memName": "홍길동",
    "memEmail": "hong@example.com",
    "memTel": "010-1234-5678",
    "memState": "ACTIVE",
    "roles": [
     "USER"
    ],
    "createdAt": "2026-08-01T10:00:00.123"
   }
  ],
  "pageable": {
   "pageNumber": 0,
   "pageSize": 20,
   "sort": {
    "empty": true,
    "sorted": false,
    "unsorted": true
   },
   "offset": 0,
   "paged": true,
   "unpaged": false
  },
  "last": true,
  "totalElements": 1,
  "totalPages": 1,
  "size": 20,
  "number": 0,
  "sort": {
   "empty": true,
   "sorted": false,
   "unsorted": true
  },
  "first": true,
  "numberOfElements": 1,
  "empty": false
 }
}

{"success":true,"data":…} — data: Page<AdminMemberSummary> (검색 성공 (Spring Data Page 형태))

오류 응답: 400 잘못된 요청 (필수값 누락, 형식·검증 실패, 알 수 없는 코드값, 깨진 JSON·UTF-8 아닌 인코딩) · 401 인증 실패 (토큰 없음 AUTH_001 / 만료 AUTH_003 / 위조 AUTH_004) · 403 권한 없음 (역할 부족, 다른 종류의 토큰, 타인 자원 접근)

관리자웹 회원 관리(앱) 메뉴의 상세 모달에서 호출한다. 식별자는 쿼리 id(회원 PK). 앱의 내 정보와 같은 형태이며 없으면 MEMBER_001. SYSTEM_ADMIN 토큰 필요.

파라미터

응답 200

{"success":true,"data":…} — data: MemberInfo (OK)

오류 응답: 400 잘못된 요청 (필수값 누락, 형식·검증 실패, 알 수 없는 코드값, 깨진 JSON·UTF-8 아닌 인코딩) · 401 인증 실패 (토큰 없음 AUTH_001 / 만료 AUTH_003 / 위조 AUTH_004) · 403 권한 없음 (역할 부족, 다른 종류의 토큰, 타인 자원 접근)

관리자웹 회원 관리(앱) 메뉴의 상세 모달에서 호출한다. 대상은 본문 memberId, state 는 ACTIVE / DORMANT / SUSPENDED / WITHDRAWN (대소문자 무관, 그 외는 COMMON_001). WITHDRAWN 으로 바꾸면 soft delete 도 함께 처리되어 회원은 더 이상 로그인할 수 없다. 변경 전/후 값으로 감사기록 MEMBER_STATE_UPDATE. SYSTEM_ADMIN 토큰 필요.

요청 본문 application/json — AdminMemberStateRequest

회원 상태 변경 요청 — POST /api/v1/admin/members/update-state (SYSTEM_ADMIN)

응답 200

{"success":true,"data":…} — data: AdminMemberSummary (OK)

오류 응답: 400 잘못된 요청 (필수값 누락, 형식·검증 실패, 알 수 없는 코드값, 깨진 JSON·UTF-8 아닌 인코딩) · 401 인증 실패 (토큰 없음 AUTH_001 / 만료 AUTH_003 / 위조 AUTH_004) · 403 권한 없음 (역할 부족, 다른 종류의 토큰, 타인 자원 접근)

관리자웹 약국 관리 상세 모달의 약사 회원정보 카드에서 호출한다. 식별자는 쿼리 code(약국 코드). 매핑된 관리자 계정을 상태(PENDING/ACTIVE 등)와 함께 돌려주며 각 항목의 pharmacies 는 비어 있다. SYSTEM_ADMIN 토큰 필요.

파라미터

응답 200

{"success":true,"data":…} — data: array<AdminUserSummary> (OK)

오류 응답: 400 잘못된 요청 (필수값 누락, 형식·검증 실패, 알 수 없는 코드값, 깨진 JSON·UTF-8 아닌 인코딩) · 401 인증 실패 (토큰 없음 AUTH_001 / 만료 AUTH_003 / 위조 AUTH_004) · 403 권한 없음 (역할 부족, 다른 종류의 토큰, 타인 자원 접근)

관리자웹 약국 관리 상세 모달의 승인 버튼. 대상은 본문 pharmacyCode. 이 약국에 매핑된 PENDING 약사 계정을 모두 ACTIVE 로 바꾸고(affectedAdminCount), 각 약사에게 승인 안내 메일을 보낸다(메일 실패는 무시). reviewMemo 를 주면 검토 메모도 저장한다. 감사기록 PHARMACY_APPROVE. SYSTEM_ADMIN 토큰 필요.

요청 본문 application/json — AdminPharmacyApproveRequest

약사 회원가입 승인 요청 — POST /api/v1/admin/pharmacies/approve (매핑 약사 PENDING → ACTIVE)

응답 200

object (승인 처리 결과)

{
 "success": true,
 "data": {
  "pharmacyCode": "PH-012",
  "affectedAdminCount": 1,
  "result": "APPROVED"
 }
}

{"success":true,"data":…} — data: AdminPharmacyReviewResponse (승인 처리 결과)

오류 응답: 400 잘못된 요청 (필수값 누락, 형식·검증 실패, 알 수 없는 코드값, 깨진 JSON·UTF-8 아닌 인코딩) · 401 인증 실패 (토큰 없음 AUTH_001 / 만료 AUTH_003 / 위조 AUTH_004) · 403 권한 없음 (역할 부족, 다른 종류의 토큰, 타인 자원 접근)

관리자웹 약국 관리 메뉴의 신규 등록 모달에서 운영자가 직접 약국을 만들 때 호출한다(약사 회원가입 경로는 자동 채번). pharmacyCode 를 직접 지정하며 이미 있으면 COMMON_001. deliveryYn 은 Y/N(미지정 시 N), 영업시간 7종은 'HH:mm~HH:mm' 또는 '휴무'. 감사기록 PHARMACY_CREATE. SYSTEM_ADMIN 토큰 필요.

요청 본문 application/json — AdminPharmacyCreateRequest

약국 등록 요청 — POST /api/v1/admin/pharmacies/create (SYSTEM_ADMIN)

응답 200

{"success":true,"data":…} — data: PharmacyView (OK)

오류 응답: 400 잘못된 요청 (필수값 누락, 형식·검증 실패, 알 수 없는 코드값, 깨진 JSON·UTF-8 아닌 인코딩) · 401 인증 실패 (토큰 없음 AUTH_001 / 만료 AUTH_003 / 위조 AUTH_004) · 403 권한 없음 (역할 부족, 다른 종류의 토큰, 타인 자원 접근)

관리자웹 약국 관리 상세 모달의 사업자등록증/기타 서류 카드에서 호출한다. 식별자는 쿼리 code(약국 코드). 약사 회원가입 때 올린 사업자등록증 등을 fileUrl(/uploads/...)과 함께 등록순으로 돌려준다. SYSTEM_ADMIN 토큰 필요.

파라미터

응답 200

{"success":true,"data":…} — data: array<PharmacyDocumentView> (OK)

오류 응답: 400 잘못된 요청 (필수값 누락, 형식·검증 실패, 알 수 없는 코드값, 깨진 JSON·UTF-8 아닌 인코딩) · 401 인증 실패 (토큰 없음 AUTH_001 / 만료 AUTH_003 / 위조 AUTH_004) · 403 권한 없음 (역할 부족, 다른 종류의 토큰, 타인 자원 접근)

관리자웹 약국 관리 상세 모달의 반려 버튼. 대상은 본문 pharmacyCode, reviewMemo(반려 사유)는 필수. 매핑된 PENDING 약사 계정을 모두 SUSPENDED 로 바꾸고(affectedAdminCount) 사유를 담은 반려 메일을 보낸다(메일 실패는 무시). 약국 레코드 자체는 삭제하지 않는다. 감사기록 PHARMACY_REJECT. SYSTEM_ADMIN 토큰 필요.

요청 본문 application/json — AdminPharmacyRejectRequest

약사 회원가입 반려 요청 — POST /api/v1/admin/pharmacies/reject (매핑 약사 PENDING → SUSPENDED, 사유 메일 통보)

응답 200

{"success":true,"data":…} — data: AdminPharmacyReviewResponse (OK)

오류 응답: 400 잘못된 요청 (필수값 누락, 형식·검증 실패, 알 수 없는 코드값, 깨진 JSON·UTF-8 아닌 인코딩) · 401 인증 실패 (토큰 없음 AUTH_001 / 만료 AUTH_003 / 위조 AUTH_004) · 403 권한 없음 (역할 부족, 다른 종류의 토큰, 타인 자원 접근)

관리자웹 약국 관리 상세 모달의 저장 버튼. 대상은 본문 pharmacyCode(없으면 COMMON_003). 기본 정보·배송 가능 여부·약사/계좌 정보·영업시간·수수료·검토 메모를 부분 수정하며 null 은 유지. 여기서는 지오코딩을 하지 않으므로 주소를 바꾸면 gpsLat/gpsLon 도 함께 보내야 한다. 변경 전/후 값으로 감사기록 PHARMACY_UPDATE. SYSTEM_ADMIN 토큰 필요.

요청 본문 application/json — AdminPharmacyUpdateRequest

약국 부분 수정 요청 — POST /api/v1/admin/pharmacies/update (null 필드는 미변경)

응답 200

{"success":true,"data":…} — data: PharmacyView (OK)

오류 응답: 400 잘못된 요청 (필수값 누락, 형식·검증 실패, 알 수 없는 코드값, 깨진 JSON·UTF-8 아닌 인코딩) · 401 인증 실패 (토큰 없음 AUTH_001 / 만료 AUTH_003 / 위조 AUTH_004) · 403 권한 없음 (역할 부족, 다른 종류의 토큰, 타인 자원 접근)

관리자웹 약국 관리 상세 모달의 수수료 저장 버튼. 대상은 본문 pharmacyCode, pharmacyCharge 는 % 값이며 다른 항목은 건드리지 않는다. 변경 전/후 값으로 감사기록 PHARMACY_CHARGE_UPDATE. SYSTEM_ADMIN 토큰 필요.

요청 본문 application/json — AdminPharmacyChargeRequest

약국 중개 수수료율 저장 요청 — POST /api/v1/admin/pharmacies/update-charge (SYSTEM_ADMIN)

응답 200

{"success":true,"data":…} — data: PharmacyView (OK)

오류 응답: 400 잘못된 요청 (필수값 누락, 형식·검증 실패, 알 수 없는 코드값, 깨진 JSON·UTF-8 아닌 인코딩) · 401 인증 실패 (토큰 없음 AUTH_001 / 만료 AUTH_003 / 위조 AUTH_004) · 403 권한 없음 (역할 부족, 다른 종류의 토큰, 타인 자원 접근)

관리자웹 약국 관리 상세 모달의 검토 메모 저장 버튼. 대상은 본문 pharmacyCode. 운영자 내부 메모(reviewMemo)만 바꾸고 lastReviewedAt 이 갱신된다. 변경 전/후 값으로 감사기록 PHARMACY_REVIEW_MEMO_UPDATE. SYSTEM_ADMIN 토큰 필요.

요청 본문 application/json — AdminPharmacyReviewMemoRequest

약국 검토 메모 저장 요청 — POST /api/v1/admin/pharmacies/update-review-memo (SYSTEM_ADMIN, lastReviewedAt 갱신)

응답 200

{"success":true,"data":…} — data: PharmacyView (OK)

오류 응답: 400 잘못된 요청 (필수값 누락, 형식·검증 실패, 알 수 없는 코드값, 깨진 JSON·UTF-8 아닌 인코딩) · 401 인증 실패 (토큰 없음 AUTH_001 / 만료 AUTH_003 / 위조 AUTH_004) · 403 권한 없음 (역할 부족, 다른 종류의 토큰, 타인 자원 접근)

관리자웹 관리자 계정 메뉴의 목록. keyword(아이디·이름 등), role, state 로 거르고 withDeleted=true 면 탈퇴 계정도 포함한다. 각 행에 매핑 약국 목록(pharmacies, 첨부 서류 수 포함)이 채워진다. SYSTEM_ADMIN 토큰 필요.

파라미터

응답 200

{"success":true,"data":…} — data: Page<AdminUserSummary> (OK)

오류 응답: 400 잘못된 요청 (필수값 누락, 형식·검증 실패, 알 수 없는 코드값, 깨진 JSON·UTF-8 아닌 인코딩) · 401 인증 실패 (토큰 없음 AUTH_001 / 만료 AUTH_003 / 위조 AUTH_004) · 403 권한 없음 (역할 부족, 다른 종류의 토큰, 타인 자원 접근)

관리자웹 관리자 계정 메뉴의 신규 등록 모달에서 호출한다. roles 에 SYSTEM_ADMIN 이 있으면 운영자, 아니면 약사 계정으로 만들며 상태는 즉시 ACTIVE. PHARMACY_ADMIN 은 pharmacyCodes 로 초기 약국 매핑을 함께 걸 수 있다(없는 코드는 COMMON_003). 아이디 중복은 COMMON_001. 감사기록 ADMIN_USER_CREATE. SYSTEM_ADMIN 토큰 필요.

요청 본문 application/json — CreateRequest

관리자 계정 생성 요청 — POST /api/v1/admin/admin-users/create (SYSTEM_ADMIN 전용)

응답 200

{"success":true,"data":…} — data: AdminUserSummary (OK)

오류 응답: 400 잘못된 요청 (필수값 누락, 형식·검증 실패, 알 수 없는 코드값, 깨진 JSON·UTF-8 아닌 인코딩) · 401 인증 실패 (토큰 없음 AUTH_001 / 만료 AUTH_003 / 위조 AUTH_004) · 403 권한 없음 (역할 부족, 다른 종류의 토큰, 타인 자원 접근)

관리자웹 관리자 계정 메뉴의 상세/수정 모달에서 호출한다. 식별자는 쿼리 id(관리자 PK). 매핑 약국 목록을 포함하며 없으면 COMMON_003. SYSTEM_ADMIN 토큰 필요.

파라미터

응답 200

{"success":true,"data":…} — data: AdminUserSummary (OK)

오류 응답: 400 잘못된 요청 (필수값 누락, 형식·검증 실패, 알 수 없는 코드값, 깨진 JSON·UTF-8 아닌 인코딩) · 401 인증 실패 (토큰 없음 AUTH_001 / 만료 AUTH_003 / 위조 AUTH_004) · 403 권한 없음 (역할 부족, 다른 종류의 토큰, 타인 자원 접근)

관리자웹 헤더 뱃지가 주기적으로 호출한다. 상태 PENDING 인 관리자 계정 수를 {count} 로 돌려주며 60초 인메모리 캐시라 승인/반려 직후 최대 60초 늦게 반영될 수 있다. SYSTEM_ADMIN 토큰 필요.

응답 200

{"success":true,"data":…} — data: object (OK)

오류 응답: 400 잘못된 요청 (필수값 누락, 형식·검증 실패, 알 수 없는 코드값, 깨진 JSON·UTF-8 아닌 인코딩) · 401 인증 실패 (토큰 없음 AUTH_001 / 만료 AUTH_003 / 위조 AUTH_004) · 403 권한 없음 (역할 부족, 다른 종류의 토큰, 타인 자원 접근)

관리자웹 관리자 계정 상세에서 약국을 연결할 때 호출한다. 본문 adminId(관리자 PK) + pharmacyCode. 이미 매핑돼 있으면 그대로 두고, 없는 약국 코드는 COMMON_003. 응답은 갱신된 매핑 목록 전체. 감사기록 ADMIN_USER_PHARMACY_ADD. SYSTEM_ADMIN 토큰 필요.

요청 본문 application/json — PharmacyMappingRequest

관리자-약국 매핑 추가 요청 — POST /api/v1/admin/admin-users/pharmacies/add

응답 200

{"success":true,"data":…} — data: array<PharmacyMappingItem> (OK)

오류 응답: 400 잘못된 요청 (필수값 누락, 형식·검증 실패, 알 수 없는 코드값, 깨진 JSON·UTF-8 아닌 인코딩) · 401 인증 실패 (토큰 없음 AUTH_001 / 만료 AUTH_003 / 위조 AUTH_004) · 403 권한 없음 (역할 부족, 다른 종류의 토큰, 타인 자원 접근)

관리자웹 관리자 계정 상세에서 약국 연결을 끊을 때 호출한다. 본문 adminId(관리자 PK) + pharmacyId(약국 PK, 코드 아님). 응답은 갱신된 매핑 목록 전체. 매핑이 모두 없어진 약사는 처방전·주문 메뉴에서 아무 것도 보지 못한다. 감사기록 ADMIN_USER_PHARMACY_REMOVE. SYSTEM_ADMIN 토큰 필요.

요청 본문 application/json — PharmacyMappingRemoveRequest

관리자-약국 매핑 해제 요청 — POST /api/v1/admin/admin-users/pharmacies/remove

응답 200

{"success":true,"data":…} — data: array<PharmacyMappingItem> (OK)

오류 응답: 400 잘못된 요청 (필수값 누락, 형식·검증 실패, 알 수 없는 코드값, 깨진 JSON·UTF-8 아닌 인코딩) · 401 인증 실패 (토큰 없음 AUTH_001 / 만료 AUTH_003 / 위조 AUTH_004) · 403 권한 없음 (역할 부족, 다른 종류의 토큰, 타인 자원 접근)

관리자웹 관리자 계정 메뉴에서 운영자가 다른 계정의 비밀번호를 바로 바꿀 때 호출한다. 대상은 본문 adminId, 현재 비밀번호 검증 없이 newPassword(6~64자)로 교체한다. 감사기록 ADMIN_USER_PASSWORD_RESET 을 남기되 비밀번호 값은 기록하지 않는다. SYSTEM_ADMIN 토큰 필요.

요청 본문 application/json — ResetPasswordByAdminRequest

관리자 비밀번호 초기화 요청 — POST /api/v1/admin/admin-users/reset-password (SYSTEM_ADMIN 이 타 계정 비밀번호 재설정)

응답 200

{"success":true,"data":…} — data: object (OK)

오류 응답: 400 잘못된 요청 (필수값 누락, 형식·검증 실패, 알 수 없는 코드값, 깨진 JSON·UTF-8 아닌 인코딩) · 401 인증 실패 (토큰 없음 AUTH_001 / 만료 AUTH_003 / 위조 AUTH_004) · 403 권한 없음 (역할 부족, 다른 종류의 토큰, 타인 자원 접근)

관리자웹 관리자 계정 메뉴의 수정 모달에서 호출한다. 대상은 본문 adminId(PK). 이름·이메일·전화·역할(roles)·상태(adminState: ACTIVE/SUSPENDED/WITHDRAWN)를 부분 수정하며 null 은 유지. 본인 계정의 역할·상태 변경은 락아웃 방지를 위해 COMMON_001 로 거절된다. 변경 전/후 값으로 감사기록 ADMIN_USER_UPDATE. SYSTEM_ADMIN 토큰 필요.

요청 본문 application/json — UpdateRequest

앱 구동 설정 갱신 요청 — POST /api/v1/app/setting/update (관리자, null 필드는 미변경)

응답 200

{"success":true,"data":…} — data: AdminUserSummary (OK)

오류 응답: 400 잘못된 요청 (필수값 누락, 형식·검증 실패, 알 수 없는 코드값, 깨진 JSON·UTF-8 아닌 인코딩) · 401 인증 실패 (토큰 없음 AUTH_001 / 만료 AUTH_003 / 위조 AUTH_004) · 403 권한 없음 (역할 부족, 다른 종류의 토큰, 타인 자원 접근)

관리자웹 처방전 상세(크게보기)에서 약품코드 입력 시 약품명 자동 조회와 약품 마스터 메뉴의 검색에서 호출한다. 식별자는 쿼리 code(EDI 9자리 보험코드, 공백은 COMMON_001). 약품 마스터를 먼저 찾고(source=MASTER) 없으면 대체약품 자료의 원처방 약품명으로 대신하며(SUBSTITUTE), 둘 다 없으면 NONE. 같은 코드의 대체약품 목록(substitutes)을 항상 함께 돌려준다. 관리자 토큰 필요.

파라미터

응답 200

object (조회 성공 (미등록 코드도 200 + source=NONE))

{
 "success": true,
 "data": {
  "ediCode": "641102470",
  "name": "타이레놀정500밀리그램",
  "company": "한국얀센",
  "price": 51,
  "source": "MASTER",
  "substitutes": []
 }
}

{"success":true,"data":…} — data: DrugLookupView (조회 성공 (미등록 코드도 200 + source=NONE))

오류 응답: 400 잘못된 요청 (필수값 누락, 형식·검증 실패, 알 수 없는 코드값, 깨진 JSON·UTF-8 아닌 인코딩) · 401 인증 실패 (토큰 없음 AUTH_001 / 만료 AUTH_003 / 위조 AUTH_004) · 403 권한 없음 (역할 부족, 다른 종류의 토큰, 타인 자원 접근)

관리자웹 약품 마스터 메뉴 상단 현황 카드에서 호출한다. 적재된 약품 수(count)와 가장 최근 적재 시각(lastLoadedAt, 없으면 생략)을 돌려준다. 관리자 토큰(SYSTEM_ADMIN 또는 PHARMACY_ADMIN) 필요.

응답 200

{"success":true,"data":…} — data: StatusView (OK)

오류 응답: 400 잘못된 요청 (필수값 누락, 형식·검증 실패, 알 수 없는 코드값, 깨진 JSON·UTF-8 아닌 인코딩) · 401 인증 실패 (토큰 없음 AUTH_001 / 만료 AUTH_003 / 위조 AUTH_004) · 403 권한 없음 (역할 부족, 다른 종류의 토큰, 타인 자원 접근)

관리자웹 약품 마스터 메뉴의 업로드 버튼. multipart 파트명 file 로 심평원 약제급여목록 및 급여상한금액표 엑셀을 올린다. 상단 30행에서 '제품코드'와 '제품명' 헤더 행을 자동으로 찾고(못 찾으면 COMMON_001), 제품코드가 9자리 숫자인 행만 적재하며 중복 코드는 뒤 행이 이긴다. 기존 마스터를 모두 지운 뒤 다시 넣는 전체 교체라 실패하면 롤백된다. 응답 loaded/skipped/total. 감사기록 DRUG_MASTER_UPLOAD. SYSTEM_ADMIN 토큰 필요.

요청 본문 multipart/form-data

응답 200

{"success":true,"data":…} — data: UploadResult (OK)

오류 응답: 400 잘못된 요청 (필수값 누락, 형식·검증 실패, 알 수 없는 코드값, 깨진 JSON·UTF-8 아닌 인코딩) · 401 인증 실패 (토큰 없음 AUTH_001 / 만료 AUTH_003 / 위조 AUTH_004) · 403 권한 없음 (역할 부족, 다른 종류의 토큰, 타인 자원 접근)

keyword(약품명·코드·업체 부분 일치)와 hasSubstitute(true 면 대체약이 있는 행만)로 거른 페이징 목록. 관리자웹에 전용 화면은 아직 없다. perPage 는 1~100. 관리자 토큰 필요.

파라미터

응답 200

{"success":true,"data":…} — data: Page<SubstituteMedicineView> (OK)

오류 응답: 400 잘못된 요청 (필수값 누락, 형식·검증 실패, 알 수 없는 코드값, 깨진 JSON·UTF-8 아닌 인코딩) · 401 인증 실패 (토큰 없음 AUTH_001 / 만료 AUTH_003 / 위조 AUTH_004) · 403 권한 없음 (역할 부족, 다른 종류의 토큰, 타인 자원 접근)

식별자는 쿼리 id(대체약품 행 id). 원처방 약품·3개월/월 사용량·대체 약품·수수료율을 한 행으로 돌려주며 없으면 COMMON_003. 관리자 토큰 필요.

파라미터

응답 200

{"success":true,"data":…} — data: SubstituteMedicineView (OK)

오류 응답: 400 잘못된 요청 (필수값 누락, 형식·검증 실패, 알 수 없는 코드값, 깨진 JSON·UTF-8 아닌 인코딩) · 401 인증 실패 (토큰 없음 AUTH_001 / 만료 AUTH_003 / 위조 AUTH_004) · 403 권한 없음 (역할 부족, 다른 종류의 토큰, 타인 자원 접근)

관리자웹 처방전 상세의 대체약 조회 팝업에서 호출한다. 쿼리 medicineCode(처방전 약품코드 = 품목코드)와 정확히 일치하는 원처방 행을 모두 돌려주며, 각 행의 substitute* 필드가 대체 약품이다(hasSubstitute=false 면 대체약 없음). 빈 값이면 빈 배열. 관리자 토큰 필요.

파라미터

응답 200

{"success":true,"data":…} — data: array<SubstituteMedicineView> (OK)

오류 응답: 400 잘못된 요청 (필수값 누락, 형식·검증 실패, 알 수 없는 코드값, 깨진 JSON·UTF-8 아닌 인코딩) · 401 인증 실패 (토큰 없음 AUTH_001 / 만료 AUTH_003 / 위조 AUTH_004) · 403 권한 없음 (역할 부족, 다른 종류의 토큰, 타인 자원 접근)

관리자웹 건강샵 주문 관리 메뉴의 목록. 모든 회원의 주문을 최신순으로 돌려준다(페이징 없음). id 는 주문번호(SO-YYYYMMDD-###), memberId 는 회원 로그인 아이디. SYSTEM_ADMIN 토큰 필요.

응답 200

object (조회 성공)

{
 "success": true,
 "data": [
  {
   "id": "SO-20260911-001",
   "date": "2026-09-11",
   "memberId": "hong123",
   "status": "PAID",
   "statusLabel": "결제 완료",
   "deliveryFee": 3000,
   "total": 18900,
   "items": [
    {
     "productId": "HP-001",
     "productName": "비타민C 1000",
     "quantity": 1,
     "price": 15900
    }
   ],
   "delivery": {
    "name": "홍길동",
    "phone": "010-1234-5678",
    "zipcode": "06578",
    "address": "서울특별시 서초구 반포대로 45",
    "detailAddress": "101동 202호",
    "memo": "문 앞에 놓아주세요"
   }
  }
 ]
}

{"success":true,"data":…} — data: array<OrderView> (조회 성공)

오류 응답: 400 잘못된 요청 (필수값 누락, 형식·검증 실패, 알 수 없는 코드값, 깨진 JSON·UTF-8 아닌 인코딩) · 401 인증 실패 (토큰 없음 AUTH_001 / 만료 AUTH_003 / 위조 AUTH_004) · 403 권한 없음 (역할 부족, 다른 종류의 토큰, 타인 자원 접근)

관리자웹 건강샵 주문 관리 메뉴의 상태 변경. 대상은 본문 orderNo, status 는 PAID(결제 완료) / SHIPPING(배송 중) / DELIVERED(배송 완료) 중 하나(그 외는 COMMON_001). 상태 순서 검증이나 회원 푸시는 없다. 감사기록 SHOP_ORDER_STATUS_UPDATE. SYSTEM_ADMIN 토큰 필요.

요청 본문 application/json — StatusUpdateRequest

건강샵 주문 상태 변경 요청 — POST /api/v1/admin/shop/orders/update-status

응답 200

{"success":true,"data":…} — data: OrderView (OK)

오류 응답: 400 잘못된 요청 (필수값 누락, 형식·검증 실패, 알 수 없는 코드값, 깨진 JSON·UTF-8 아닌 인코딩) · 401 인증 실패 (토큰 없음 AUTH_001 / 만료 AUTH_003 / 위조 AUTH_004) · 403 권한 없음 (역할 부족, 다른 종류의 토큰, 타인 자원 접근)

관리자웹 상품 관리 메뉴의 목록. 숨김(visible=false) 상품까지 포함해 최신 등록순으로 돌려주되 삭제된 상품은 제외한다. SYSTEM_ADMIN 토큰 필요.

응답 200

{"success":true,"data":…} — data: array<ProductView> (OK)

오류 응답: 400 잘못된 요청 (필수값 누락, 형식·검증 실패, 알 수 없는 코드값, 깨진 JSON·UTF-8 아닌 인코딩) · 401 인증 실패 (토큰 없음 AUTH_001 / 만료 AUTH_003 / 위조 AUTH_004) · 403 권한 없음 (역할 부족, 다른 종류의 토큰, 타인 자원 접근)

관리자웹 상품 관리 메뉴의 등록 모달. category, name, price 필수. 상품 코드는 HP-### 로 자동 채번되고 visible 을 비우면 노출된다. 정가(originalPrice)는 할인 표시용이라 판매가(price)보다 커야 하며 아니면 COMMON_001. 감사기록 SHOP_PRODUCT_CREATE. SYSTEM_ADMIN 토큰 필요.

요청 본문 application/json — ProductCreateRequest

상품 등록 요청 — POST /api/v1/admin/shop/products/create (상품 코드 HP-### 자동 채번)

응답 200

{"success":true,"data":…} — data: ProductView (OK)

오류 응답: 400 잘못된 요청 (필수값 누락, 형식·검증 실패, 알 수 없는 코드값, 깨진 JSON·UTF-8 아닌 인코딩) · 401 인증 실패 (토큰 없음 AUTH_001 / 만료 AUTH_003 / 위조 AUTH_004) · 403 권한 없음 (역할 부족, 다른 종류의 토큰, 타인 자원 접근)

관리자웹 상품 관리 메뉴의 삭제 버튼. 대상은 본문 productCode. soft delete 라 앱·관리자 목록에서 사라지지만 기존 주문의 상품 스냅샷에는 영향이 없다. 감사기록 SHOP_PRODUCT_DELETE. SYSTEM_ADMIN 토큰 필요.

요청 본문 application/json — ProductDeleteRequest

상품 삭제 요청 — POST /api/v1/admin/shop/products/delete

응답 200

{"success":true,"data":…} — data: object (OK)

오류 응답: 400 잘못된 요청 (필수값 누락, 형식·검증 실패, 알 수 없는 코드값, 깨진 JSON·UTF-8 아닌 인코딩) · 401 인증 실패 (토큰 없음 AUTH_001 / 만료 AUTH_003 / 위조 AUTH_004) · 403 권한 없음 (역할 부족, 다른 종류의 토큰, 타인 자원 접근)

관리자웹 상품 관리 메뉴의 수정 모달. 대상은 본문 productCode(HP-###, 없거나 삭제된 상품은 COMMON_003). 보낸 항목만 바꾸고 null 은 유지하며 정가 > 판매가 검증은 수정 후 값 기준으로 다시 한다. visible=false 로 두면 앱 목록에서 즉시 사라진다. 감사기록 SHOP_PRODUCT_UPDATE. SYSTEM_ADMIN 토큰 필요.

요청 본문 application/json — ProductUpdateRequest

상품 부분 수정 요청 — POST /api/v1/admin/shop/products/update (null 필드는 미변경)

응답 200

{"success":true,"data":…} — data: ProductView (OK)

오류 응답: 400 잘못된 요청 (필수값 누락, 형식·검증 실패, 알 수 없는 코드값, 깨진 JSON·UTF-8 아닌 인코딩) · 401 인증 실패 (토큰 없음 AUTH_001 / 만료 AUTH_003 / 위조 AUTH_004) · 403 권한 없음 (역할 부족, 다른 종류의 토큰, 타인 자원 접근)

관리자웹 운영 설정 메뉴에서 호출한다. 앱과 같은 값(deliveryFee, freeThreshold)을 돌려준다. SYSTEM_ADMIN 토큰 필요.

응답 200

{"success":true,"data":…} — data: SettingView (OK)

오류 응답: 400 잘못된 요청 (필수값 누락, 형식·검증 실패, 알 수 없는 코드값, 깨진 JSON·UTF-8 아닌 인코딩) · 401 인증 실패 (토큰 없음 AUTH_001 / 만료 AUTH_003 / 위조 AUTH_004) · 403 권한 없음 (역할 부족, 다른 종류의 토큰, 타인 자원 접근)

관리자웹 운영 설정 메뉴의 저장 버튼. deliveryFee(기본 배송비), freeThreshold(무료배송 기준 금액) 중 보낸 항목만 바꾸며 음수는 COMMON_001. 이후 생성되는 주문부터 새 배송비가 적용된다. 변경 전/후 값으로 감사기록 SHOP_SETTING_UPDATE. SYSTEM_ADMIN 토큰 필요.

요청 본문 application/json — SettingUpdateRequest

건강샵 운영 설정 변경 요청 — POST /api/v1/admin/shop/settings/update (null 필드는 미변경)

응답 200

{"success":true,"data":…} — data: SettingView (OK)

오류 응답: 400 잘못된 요청 (필수값 누락, 형식·검증 실패, 알 수 없는 코드값, 깨진 JSON·UTF-8 아닌 인코딩) · 401 인증 실패 (토큰 없음 AUTH_001 / 만료 AUTH_003 / 위조 AUTH_004) · 403 권한 없음 (역할 부족, 다른 종류의 토큰, 타인 자원 접근)

관리자웹 카테고리 메뉴의 삭제 버튼. 대상은 본문 categoryId. 행을 지우지 않고 active=false 로 바꿔 앱 목록에서만 숨기며, 그 카테고리를 쓰던 글은 그대로 남는다. 감사기록 BBS_CATEGORY_DELETE. SYSTEM_ADMIN 토큰 필요.

요청 본문 application/json — AdminCategoryDeleteRequest

게시판 카테고리 삭제(비활성) 요청 — POST /api/v1/admin/bbs/categories/delete

응답 200

{"success":true,"data":…} — data: object (OK)

오류 응답: 400 잘못된 요청 (필수값 누락, 형식·검증 실패, 알 수 없는 코드값, 깨진 JSON·UTF-8 아닌 인코딩) · 401 인증 실패 (토큰 없음 AUTH_001 / 만료 AUTH_003 / 위조 AUTH_004) · 403 권한 없음 (역할 부족, 다른 종류의 토큰, 타인 자원 접근)

관리자웹 카테고리 메뉴의 수정 모달. 대상은 본문 categoryId(없으면 COMMON_003). name / sort / active 중 보낸 항목만 바꾸고 null 은 유지. 게시판 종류는 바꿀 수 없다. 감사기록 BBS_CATEGORY_UPDATE. SYSTEM_ADMIN 토큰 필요.

요청 본문 application/json — AdminCategoryUpdateRequest

게시판 카테고리 부분 수정 요청 — POST /api/v1/admin/bbs/categories/update (null 필드는 미변경)

응답 200

{"success":true,"data":…} — data: CategoryView (OK)

오류 응답: 400 잘못된 요청 (필수값 누락, 형식·검증 실패, 알 수 없는 코드값, 깨진 JSON·UTF-8 아닌 인코딩) · 401 인증 실패 (토큰 없음 AUTH_001 / 만료 AUTH_003 / 위조 AUTH_004) · 403 권한 없음 (역할 부족, 다른 종류의 토큰, 타인 자원 접근)

관리자웹 FAQ 관리 메뉴의 등록 모달. subject(질문), contents(답변) 필수, categoryId 는 앱 탭 분류용이며 없는 카테고리면 COMMON_001. 공지와 달리 푸시는 나가지 않는다. 감사기록 BBS_FAQ_CREATE. SYSTEM_ADMIN 토큰 필요.

요청 본문 application/json — AdminPostCreateRequest

공지/FAQ 작성 요청 — POST /api/v1/admin/bbs/notices, /faqs

응답 200

{"success":true,"data":…} — data: PostView (OK)

오류 응답: 400 잘못된 요청 (필수값 누락, 형식·검증 실패, 알 수 없는 코드값, 깨진 JSON·UTF-8 아닌 인코딩) · 401 인증 실패 (토큰 없음 AUTH_001 / 만료 AUTH_003 / 위조 AUTH_004) · 403 권한 없음 (역할 부족, 다른 종류의 토큰, 타인 자원 접근)

관리자웹 FAQ 관리 메뉴의 삭제 버튼. 대상은 본문 postId. soft delete. 감사기록 BBS_FAQ_DELETE. SYSTEM_ADMIN 토큰 필요.

요청 본문 application/json — AdminPostDeleteRequest

공지/FAQ 삭제 요청 — POST /api/v1/admin/bbs/notices/delete, /faqs/delete

응답 200

{"success":true,"data":…} — data: object (OK)

오류 응답: 400 잘못된 요청 (필수값 누락, 형식·검증 실패, 알 수 없는 코드값, 깨진 JSON·UTF-8 아닌 인코딩) · 401 인증 실패 (토큰 없음 AUTH_001 / 만료 AUTH_003 / 위조 AUTH_004) · 403 권한 없음 (역할 부족, 다른 종류의 토큰, 타인 자원 접근)

관리자웹 FAQ 관리 메뉴의 수정 모달. 대상은 본문 postId(FAQ 가 아니거나 삭제된 글은 COMMON_003). 보낸 항목만 바꾸고 null 은 유지. 감사기록 BBS_FAQ_UPDATE. SYSTEM_ADMIN 토큰 필요.

요청 본문 application/json — AdminPostUpdateRequest

공지/FAQ 부분 수정 요청 — POST /api/v1/admin/bbs/notices/update, /faqs/update (null 필드는 미변경)

응답 200

{"success":true,"data":…} — data: PostView (OK)

오류 응답: 400 잘못된 요청 (필수값 누락, 형식·검증 실패, 알 수 없는 코드값, 깨진 JSON·UTF-8 아닌 인코딩) · 401 인증 실패 (토큰 없음 AUTH_001 / 만료 AUTH_003 / 위조 AUTH_004) · 403 권한 없음 (역할 부족, 다른 종류의 토큰, 타인 자원 접근)

관리자웹 공지 관리 메뉴의 등록 모달. subject, contents 필수, categoryId 는 선택(없는 카테고리면 COMMON_001). 저장 즉시 전체 회원에게 FCM 푸시(새 공지가 등록되었습니다, relatedType=notice)가 broadcast 되므로 임시 저장 용도로 쓰면 안 된다. 감사기록 BBS_NOTICE_CREATE. SYSTEM_ADMIN 토큰 필요.

요청 본문 application/json — AdminPostCreateRequest

공지/FAQ 작성 요청 — POST /api/v1/admin/bbs/notices, /faqs

응답 200

{"success":true,"data":…} — data: PostView (OK)

오류 응답: 400 잘못된 요청 (필수값 누락, 형식·검증 실패, 알 수 없는 코드값, 깨진 JSON·UTF-8 아닌 인코딩) · 401 인증 실패 (토큰 없음 AUTH_001 / 만료 AUTH_003 / 위조 AUTH_004) · 403 권한 없음 (역할 부족, 다른 종류의 토큰, 타인 자원 접근)

관리자웹 공지 관리 메뉴의 삭제 버튼. 대상은 본문 postId. soft delete 라 앱 목록·상세에서 즉시 사라지지만 DB 행은 남는다. 감사기록 BBS_NOTICE_DELETE. SYSTEM_ADMIN 토큰 필요.

요청 본문 application/json — AdminPostDeleteRequest

공지/FAQ 삭제 요청 — POST /api/v1/admin/bbs/notices/delete, /faqs/delete

응답 200

{"success":true,"data":…} — data: object (OK)

오류 응답: 400 잘못된 요청 (필수값 누락, 형식·검증 실패, 알 수 없는 코드값, 깨진 JSON·UTF-8 아닌 인코딩) · 401 인증 실패 (토큰 없음 AUTH_001 / 만료 AUTH_003 / 위조 AUTH_004) · 403 권한 없음 (역할 부족, 다른 종류의 토큰, 타인 자원 접근)

관리자웹 공지 관리 메뉴의 수정 모달. 대상은 본문 postId(공지가 아니거나 삭제된 글은 COMMON_003). subject/contents/categoryId 중 보낸 항목만 바꾸고 null 은 유지. 푸시는 다시 나가지 않는다. 감사기록 BBS_NOTICE_UPDATE. SYSTEM_ADMIN 토큰 필요.

요청 본문 application/json — AdminPostUpdateRequest

공지/FAQ 부분 수정 요청 — POST /api/v1/admin/bbs/notices/update, /faqs/update (null 필드는 미변경)

응답 200

{"success":true,"data":…} — data: PostView (OK)

오류 응답: 400 잘못된 요청 (필수값 누락, 형식·검증 실패, 알 수 없는 코드값, 깨진 JSON·UTF-8 아닌 인코딩) · 401 인증 실패 (토큰 없음 AUTH_001 / 만료 AUTH_003 / 위조 AUTH_004) · 403 권한 없음 (역할 부족, 다른 종류의 토큰, 타인 자원 접근)

관리자웹 QnA 답변 메뉴의 목록. status 로 WAITING(답변대기)/ANSWERED(답변완료)만 거르거나 비우면 전체(그 외 값은 COMMON_001). 응답의 status 는 한글 라벨. perPage 는 1~100. SYSTEM_ADMIN 토큰 필요.

파라미터

응답 200

{"success":true,"data":…} — data: Page<QnaView> (OK)

오류 응답: 400 잘못된 요청 (필수값 누락, 형식·검증 실패, 알 수 없는 코드값, 깨진 JSON·UTF-8 아닌 인코딩) · 401 인증 실패 (토큰 없음 AUTH_001 / 만료 AUTH_003 / 위조 AUTH_004) · 403 권한 없음 (역할 부족, 다른 종류의 토큰, 타인 자원 접근)

관리자웹 QnA 답변 메뉴의 답변 저장 버튼. 대상은 본문 postId, answer 필수. 답변을 저장하고 상태를 답변완료(ANSWERED)로 바꾸며 답변 시각을 기록한다. 질문한 회원에게 FCM 푸시(문의 답변 도착, relatedType=qna)를 보낸다(이미 답변된 글을 수정해도 다시 발송). 변경 전/후 값으로 감사기록 BBS_QNA_ANSWER. SYSTEM_ADMIN 토큰 필요.

요청 본문 application/json — AdminQnaAnswerRequest

1:1 문의 관리자 답변 요청 — POST /api/v1/admin/bbs/qnas/answer (답변 저장 시 상태 답변완료)

응답 200

{"success":true,"data":…} — data: QnaView (OK)

오류 응답: 400 잘못된 요청 (필수값 누락, 형식·검증 실패, 알 수 없는 코드값, 깨진 JSON·UTF-8 아닌 인코딩) · 401 인증 실패 (토큰 없음 AUTH_001 / 만료 AUTH_003 / 위조 AUTH_004) · 403 권한 없음 (역할 부족, 다른 종류의 토큰, 타인 자원 접근)

관리자웹 QnA 답변 메뉴의 답변 모달에서 호출한다. 식별자는 쿼리 id(문의 글 id). 질문·기존 답변·작성 회원 id 를 돌려주며 삭제되었거나 QnA 가 아니면 COMMON_003. SYSTEM_ADMIN 토큰 필요.

파라미터

응답 200

{"success":true,"data":…} — data: QnaView (OK)

오류 응답: 400 잘못된 요청 (필수값 누락, 형식·검증 실패, 알 수 없는 코드값, 깨진 JSON·UTF-8 아닌 인코딩) · 401 인증 실패 (토큰 없음 AUTH_001 / 만료 AUTH_003 / 위조 AUTH_004) · 403 권한 없음 (역할 부족, 다른 종류의 토큰, 타인 자원 접근)

관리자웹 카테고리 메뉴와 FAQ/QnA 등록 모달의 선택 목록. 경로의 board 는 faq 또는 qna. includeInactive=true 면 비활성 카테고리도 포함한다. SYSTEM_ADMIN 토큰 필요.

파라미터

응답 200

{"success":true,"data":…} — data: array<CategoryView> (OK)

오류 응답: 400 잘못된 요청 (필수값 누락, 형식·검증 실패, 알 수 없는 코드값, 깨진 JSON·UTF-8 아닌 인코딩) · 401 인증 실패 (토큰 없음 AUTH_001 / 만료 AUTH_003 / 위조 AUTH_004) · 403 권한 없음 (역할 부족, 다른 종류의 토큰, 타인 자원 접근)

관리자웹 카테고리 메뉴의 등록 모달. 경로의 board 는 faq 또는 qna, 본문 name 필수, sort 는 정렬 순서(기본 0). 활성 상태로 만들어진다. 감사기록 BBS_CATEGORY_CREATE. SYSTEM_ADMIN 토큰 필요.

파라미터

요청 본문 application/json — AdminCategoryCreateRequest

게시판 카테고리 생성 요청 — POST /api/v1/admin/bbs/{board}-categories/create (board = faq / qna 는 path)