CLUe API 가이드

이 문서를 통해 슈프리마 CLUe API를 빠르고 간편하게 연동할 수 있습니다. API 키 발급 방법부터 요청/응답 형식, 오류 코드, 호출 제한까지 CLUe API 사용에 필요한 기본 정보를 안내합니다. CLUe API는 슈프리마 CLUe 웹 포털 설정과 함께 동작하므로, CLUe 웹 포털 계정이 없다면 먼저 계정을 요청하세요.

CLUe API 사용에 대한 자세한 내용을 확인하세요.

API 키란

CLUe API를 호출하려면 API 키가 필요합니다. 공간 그룹의 관리자 메뉴에서 발급받을 수 있습니다. CLUe API는 요청 헤더에 Bearer 토큰으로 API 키를 필수로 포함해야 합니다. API 키는 CLUe 웹 포털에서 발급하고 관리할 수 있습니다.

회원 가입을 하려면 상위 관리자 또는 같은 공간 그룹의 관리자로부터 초대를 받아야 합니다.

공간(Place)과 공간 그룹(Place Group)이란?

CLUe는 멀티 테넌트 시스템을 지원하므로, 공간은 회사나 지점(branch)처럼 독립된 단위를 의미하며, 공간 그룹은 여러 공간을 묶어 관리하는 상위 개념입니다.

API 키 발급

1. CLUe 웹 포털에 로그인하세요.

2. API 연동을 위한 공간 그룹을 선택하세요.

3. 화면 오른쪽 상단의 → 상세 설정을 클릭하세요.

   

4. 화면 왼쪽 사이드바에서 관리자를 클릭하세요.

   

5. API Key 관리 섹션에서 + 신규 발급을 클릭하세요.

6. 원하는 유효 기간을 선택하세요.

   

   직접 입력을 선택하면 유효 기간을 최대 365,000일까지 설정할 수 있습니다.

7. 새 API 키를 발급하려면 생성 버튼을 클릭하세요.

8. 새 API 키가 생성되면 복사 버튼을 클릭해 CLUe API 호출 시 Bearer 토큰으로 사용하세요.

   

주의

API 키는 CLUe API에 대한 접근 권한을 그대로 부여하므로 외부에 노출되지 않도록 안전하게 보관하세요. 오남용으로 발생하는 문제에 대해 슈프리마는 책임지지 않습니다.

CLUe API 기본

Base URL

모든 API 요청을 보내는 기본 URL은 https://api.moon.supremainc.com/v1입니다. 모든 API 요청은 HTTPS를 통해 전송해야 합니다.

CLUe API는 가능한 한 RESTful 원칙을 따르며, 페이지 및 데이터베이스 리소스에 대한 대부분의 작업을 GET, POST, PATCH, DELETE 요청으로 수행합니다. 요청 본문과 응답 본문은 모두 JSON 형식으로 인코딩됩니다.

API 성공 응답

응답에 성공하면 다음 상태가 반환됩니다.

HTTP 상태 코드: 200

필드	설명	선택 여부
code	API 응답 코드
status	API 응답 상태
message	API 응답 메시지	true
data	API 응답 데이터	true

API 실패 응답

응답에 실패하면 다음 상태 중 하나가 반환됩니다.

HTTP 상태 코드: 400 / 500

필드	설명	선택 여부
errors	API 실패 응답
errors.code	실패 오류 코드
errors.message	실패 참조 메시지
errors.details	실패 상세 정보	true

일반 오류 코드

코드	설명
e1000	내부 서버 오류
e1001	권한 거부
e1002	지원하지 않음
e1003	잘못된 형식
e1004	JSON 파싱 오류
e1005	잘못된 메서드 인자
e1006	잘못된 요청
e1007	존재하지 않는 리소스
e1008	메서드 인자 타입 불일치
e1009	요청 헤더 누락

API 호출 제한

주의

CLUe는 API별로 5분당 300회의 호출 제한을 두고 있으며, 이 제한은 호출 소스 단위로 적용됩니다. 다만 얼굴 이미지를 추가하는 API는 템플릿 추출 및 생성과 같이 처리 시간이 필요한 작업이 포함되므로, 호출 사이에 약간의 대기 시간을 두는 것을 권장합니다.