superplace
Developers
가이드

시작하기

superplace는 공간 운영을 위한 플랫폼입니다. 예약·결제, 손님 출입(문·키오스크), 문의 응대, 매출, 기기 제어를 매장마다 한 콘솔에서 다룹니다. 이 API는 그 콘솔이 하는 일을 앱에서 그대로 하게 합니다.

superplace API는 하나입니다. 앱 연결 토큰으로 호출합니다.

기본 주소

기본 주소는 https://api.superplace.so입니다. 경로 앞머리가 서비스입니다.

접두어서비스
/core인증, 활동 기록, 매장 정보
/space예약, 손님, 회원권, 출입
/device기기, 문
/inbox문의
/msg메시지
/pay매출
/retail상품
/promo프로모션
/workforce직원

자격

앱 연결(OAuth 2.1)로 토큰을 받습니다. 토큰에는 연결한 사람의 권한이 담깁니다. 호출할 수 있는 범위는 API 범위에 있습니다.

첫 호출

  1. 앱 연결로 액세스 토큰을 받습니다.
  2. 예약 목록을 읽습니다.
TerminalCode
curl https://api.superplace.so/space/v1/reservations \
  -H "Authorization: Bearer $ACCESS_TOKEN"
  1. 문을 엽니다. Idempotency-Key는 필수입니다.
TerminalCode
curl -X POST https://api.superplace.so/device/v1/devices/$DOOR/commands \
  -H "Authorization: Bearer $ACCESS_TOKEN" -H "Idempotency-Key: $(uuidgen)" \
  -d '{"capability":"door","command":"open"}'

$DOOR는 GET /device/v1/devices가 돌려주는 문의 id입니다. 자세한 내용은 기기에 있습니다.

응답 형식

Code
성공: {"success":true,"data":…}
목록: {"success":true,"data":[…],"total":n}
실패: {"error":"코드","message":"설명","statusCode":숫자}
상태코드의미
401토큰 만료. 다시 교환합니다.
403권한 없음
404대상 없음
429요청 한도 초과
409규칙 위반, 또는 기기 명령에서 기기 오프라인(details.reason: offline, 명령을 보내지 않음). message에 이유가 있습니다.
502기기가 명령을 거절했습니다(details.reason: refused).
504기기가 답하지 않았습니다(details.reason: noResponse). 실행됐는지 알 수 없으니 같은 Idempotency-Key로 다시 보냅니다.

오류 본문의 error는 AUTH.TOKEN_INVALID처럼 영역.코드 꼴이고, 분기에 쓰는 부가 정보는 details에 담깁니다. 연산마다 돌려주는 코드는 API 레퍼런스의 응답 절에 있습니다.

시각과 목록

  • 시각은 RFC3339 문자열입니다(2026-11-03T14:00:00+09:00, 2026-11-03T05:00:00Z 모두 됩니다). 응답의 시각도 RFC3339이고 오프셋이 붙어 옵니다.
  • 목록은 page·perPage(또는 start·end)로 넘기고 total이 전체 건수입니다. 인자 설명은 연산마다 레퍼런스에 있습니다.
  • 연결된 매장이나 조직은 GET /core/v1/me로 확인합니다. 매장 연결이면 placeId, 조직 연결이면 orgId가 옵니다.

다음

예전에 파트너 키로 연동한 곳은 파트너 키(레거시)를 보세요.

Last modified on
앱 연결(OAuth 2.1)