API 개요

나비잠 API는 사용자와 관리자 두 가지 관점으로 나뉩니다.

서버 정보

환경	Base URL
운영	https://www.nabi-jam.com/api
스테이징	https://stg.nabi-jam.com/api

도메인 주의

운영 환경은 반드시 www.nabi-jam.com을 사용하세요. nabi-jam.com으로 요청하면 301 리다이렉트가 발생하여 POST 요청의 Body가 손실됩니다.

공통 응답 형식

모든 API는 아래 5개 필드를 포함하는 JSON으로 응답합니다.

{
  "status": "success",
  "errorType": null,
  "errorCode": null,
  "message": null,
  "data": { ... }
}

필드	타입	Nullable	설명
status	String	N	"success" 또는 "error"
errorType	String	Y	에러 유형 (정상 시 null)
errorCode	Integer	Y	에러 코드 (정상 시 null)
message	String	Y	에러 메시지 (정상 시 null)
data	Object	Y	응답 데이터 (데이터 없으면 null)

성공 응답 예시

{
  "status": "success",
  "errorType": null,
  "errorCode": null,
  "message": null,
  "data": {
    "orderId": "ORD-20260305-001"
  }
}

에러 응답 예시

{
  "status": "error",
  "errorType": "ResourceNotFoundException",
  "errorCode": null,
  "message": "해당 예약을 찾을 수 없습니다.",
  "data": null
}

에러 유형 (errorType)

errorType	HTTP 상태	설명
IllegalArguemntError	400	잘못된 파라미터
MethodArgumentNotValidException	400	요청 검증 실패 (@Valid)
ResourceNotExistException	400	리소스 없음 (일반)
LoginFailException	401	인증 실패
ResourceTimeOutException	401	세션/인증 만료
AuthorizationException	403	권한 없음
ResourceNotFoundException	404	리소스 조회 실패
InvalidCodeException	409	유효하지 않은 코드
ResourceAlreadyExistException	409	리소스 중복
ResourceUnavailableException	409	리소스 사용 불가 (잠금)
TossDataIntegrityException	409	결제 데이터 불일치
SettingConflictException	409	설정 변경 충돌 (예약 존재)
ResourceValidTimePassedException	410	유효 시간 초과

인증 방식

구분	엔드포인트	인증 방식
사용자	POST /account/login	세션 쿠키 발급 → 이후 요청에 자동 포함
관리자	POST /admin/login	세션 쿠키 발급 → 이후 요청에 자동 포함
결제 진행	-	PAY_SESSIONID / ADMIN_PAY_SESSIONID 쿠키

API 카테고리

사용자

API	설명
예약/결제	슬롯 조회, 결제 진행, 취소, 내역 확인
로그인	카카오 알림톡 인증코드 기반 로그인
도어락 제어	SSE 기반 비동기 도어락 해제

관리자

API	설명
로그인	관리자 인증
예약/결제 제어	조회, 취소, 변경, 대리 예약, 가상계좌
방 비활성화	룸 활성/비활성 토글
도어락 제어	관리자용 도어락 해제
카카오 알림톡	알림톡 재발송
온습도 정보	매장 온습도 조회
냉난방기	원격 냉난방 제어

기타

API	설명
가맹모집	가맹 문의 접수
참고자료	토스 에러코드, 지점 변수값