# 시작하기

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

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

## 기본 주소

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

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

## 자격

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

## 첫 호출

1. [앱 연결](/docs/auth-oauth)로 액세스 토큰을 받습니다.
2. 예약 목록을 읽습니다.

```bash
curl https://api.superplace.so/space/v1/reservations \
  -H "Authorization: Bearer $ACCESS_TOKEN"
```

3. 문을 엽니다. `Idempotency-Key`는 필수입니다.

```bash
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`입니다. 자세한 내용은 [기기](/docs/devices)에 있습니다.

## 응답 형식

```text
성공: {"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 레퍼런스](/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`가 옵니다.

## 다음

- [앱 연결](/docs/auth-oauth)
- [API 범위](/docs/scope)
- [기기](/docs/devices)
- [API 레퍼런스](/api)

예전에 파트너 키로 연동한 곳은 [파트너 키(레거시)](/docs/legacy-partner-key)를 보세요.