예약

예약과 공간(방·좌석)을 조회하고, 예약을 등록·변경·취소하며 입장 처리를 합니다.

예약 목록 조회

GET

https://api.superplace.so

/space/v1/reservations

OAuth 2.0

from~to 구간에 걸치는 예약을 돌려줍니다. 생략하면 오늘부터 7일 뒤까지입니다. 시작 시각 기준 최신순이 기본입니다. externalRef를 보내면 그 외부 예약번호의 예약 한 건만 돌려주고 from·to·userId는 무시됩니다.

필요 권한: 예약 보기(space:reservations:read)

MCP 도구: space_get_reservations

예약 목록 조회 › query Parameters

from

string · date-time

조회 구간의 시작 시각입니다. RFC3339 형식입니다.

to

string · date-time

조회 구간의 끝 시각입니다. RFC3339 형식입니다.

userId

string · uuid

손님 계정의 ID입니다. 그 사람의 예약만 돌려줍니다.

externalRef

string

외부 예약 번호입니다. 그 예약 한 건을 돌려주고, 없으면 빈 목록입니다.

filter

string

조건 JSON입니다. 공간을 고르려면 {"resourceId":"…"} 또는 {"resourceId":{"in":["…","…"]}}, 매장을 고르려면 {"placeId":"…"}를 보냅니다.

page

integer · min: 1

페이지 번호입니다. 1부터 시작합니다.

Default: 1

perPage

integer · min: 1 · max: 200

한 페이지에 담을 건수입니다. 생략하면 서버 기본값이 적용됩니다.

Default: 20

start

integer · min: 0

범위 조회의 시작 위치입니다. end와 함께 보내며, page·perPage를 함께 보내면 무시됩니다.

end

integer · min: 0

범위 조회의 끝 위치입니다. 이 값은 포함되지 않습니다. 한 번에 200건까지 조회할 수 있습니다.

sort

string · enum

정렬 기준입니다. startsAt만 지원합니다.

Enum values:

startsAt

Default: startsAt

order

string · enum

정렬 방향입니다. asc는 오름차순, desc는 내림차순입니다.

Enum values:

asc

desc

Default: desc

예약 목록 조회 › Responses

요청이 처리됐습니다. 결과는 data에 담겨 옵니다.

success

boolean · enum · required

Enum values:

object[] · required

total

integer · int64 · required

GET/space/v1/reservations

curl https://api.superplace.so/space/v1/reservations \
  --header 'Authorization: Bearer <token>'

Example Responses

{
  "success": true,
  "data": [
    {
      "id": "01932b1e-4c3a-7f10-9a2b-5d6e7f800051",
      "resourceId": "01932b1e-4c3a-7f10-9a2b-5d6e7f800041",
      "resourceName": "611호",
      "userId": "01932b1e-4c3a-7f10-9a2b-5d6e7f800003",
      "phone": "+821000001234",
      "name": "김손님",
      "startsAt": "2026-11-03T05:00:00Z",
      "endsAt": "2026-11-03T07:00:00Z",
      "status": "confirmed",
      "price": 20000,
      "memo": "",
      "partySize": 2,
      "occupiedStartsAt": "2026-11-03T05:00:00Z",
      "occupiedEndsAt": "2026-11-03T07:10:00Z",
      "paymentId": "01932b1e-4c3a-7f10-9a2b-5d6e7f800101",
      "createdAt": "2026-11-01T02:00:00Z"
    }
  ],
  "total": 1
}

json

application/json

예약 등록

POST

https://api.superplace.so

/space/v1/reservations

OAuth 2.0

손님 한 명의 방이나 좌석을 시간대로 예약합니다. 이미 있는 예약과 겹치면 거절됩니다. 정리 시간, 운영 시간, 길이 같은 사항은 예약은 되지만 응답의 timeWarnings로 알려 줍니다. 전화 없이 현장에서 바로 입실하는 손님은 walkIn을 true로 보냅니다. 성공하면 201입니다.

필요 권한: 예약 처리(생성·변경·취소)(space:reservations:write)

MCP 도구: space_post_reservations

예약 등록 › Request Body

resourceId

string · uuid · required

예약할 공간 ID입니다. 공간 목록의 id입니다.

startsAt

string · date-time · required

이용 시작 시각입니다. RFC3339 형식입니다.

endsAt

string · date-time · required

이용 종료 시각입니다. 시작보다 늦어야 합니다.

placeId

string · uuid

조직 계정으로 호출할 때만 필요한 매장 ID입니다.

phone

string

손님 연락처입니다. walkIn이 true이면 무시됩니다.

walkIn

boolean

전화 없이 현장에서 입실하는 경우 true입니다. 예약과 동시에 입실 처리됩니다.

Default: false

name

string

손님 이름입니다.

memo

string

매장 내부 비고입니다.

partySize

integer · min: 1

이용 인원입니다. 생략하면 1명입니다. guests가 있으면 1명과 guests 수를 더한 값입니다.

object[]

함께 오는 손님 목록입니다. 공간 정원 안이어야 하고, 예약자나 중복 연락처는 409, 공간의 나이 기준보다 어리면 409입니다.

예약 등록 › Responses

요청이 처리됐습니다. 결과는 data에 담겨 옵니다.

success

boolean

data

POST/space/v1/reservations

curl https://api.superplace.so/space/v1/reservations \
  --request POST \
  --header 'Content-Type: application/json' \
  --header 'Authorization: Bearer <token>' \
  --data '{
  "resourceId": "01932b1e-4c3a-7f10-9a2b-5d6e7f800041",
  "phone": "01000001234",
  "name": "김손님",
  "startsAt": "2026-11-03T14:00:00+09:00",
  "endsAt": "2026-11-03T16:00:00+09:00",
  "partySize": 2
}'

Example Request Body

{
  "resourceId": "01932b1e-4c3a-7f10-9a2b-5d6e7f800041",
  "phone": "01000001234",
  "name": "김손님",
  "startsAt": "2026-11-03T14:00:00+09:00",
  "endsAt": "2026-11-03T16:00:00+09:00",
  "partySize": 2
}

json

application/json

Example Responses

{
  "success": true,
  "data": {
    "id": "01932b1e-4c3a-7f10-9a2b-5d6e7f800051",
    "resourceId": "01932b1e-4c3a-7f10-9a2b-5d6e7f800041",
    "resourceName": "611호",
    "userId": "01932b1e-4c3a-7f10-9a2b-5d6e7f800003",
    "phone": "+821000001234",
    "name": "김손님",
    "startsAt": "2026-11-03T05:00:00Z",
    "endsAt": "2026-11-03T07:00:00Z",
    "status": "confirmed",
    "price": 20000,
    "memo": "",
    "partySize": 2,
    "occupiedStartsAt": "2026-11-03T05:00:00Z",
    "occupiedEndsAt": "2026-11-03T07:10:00Z",
    "paymentId": "01932b1e-4c3a-7f10-9a2b-5d6e7f800101",
    "createdAt": "2026-11-01T02:00:00Z",
    "timeWarnings": []
  }
}

json

application/json

예약 상세 조회

GET

https://api.superplace.so

/space/v1/reservations/{id}

OAuth 2.0

예약 한 건의 공간, 시간, 손님, 금액, 상태를 돌려줍니다. 결제 내역(charges)이 함께 담길 수 있습니다. include=devices를 보내면 예약한 공간과 공용 공간의 기기 목록이 더해집니다.

필요 권한: 예약 보기(space:reservations:read)

MCP 도구: space_get_reservations_id

예약 상세 조회 › path Parameters

id

string · uuid · required

예약 ID입니다.

예약 상세 조회 › query Parameters

include

string · enum

함께 담을 정보입니다. devices를 보내면 손님이 쓸 수 있는 기기 목록이 더해집니다.

Enum values:

devices

예약 상세 조회 › Responses

요청이 처리됐습니다. 결과는 data에 담겨 옵니다.

success

boolean · enum · required

Enum values:

object · required

GET/space/v1/reservations/{id}

curl https://api.superplace.so/space/v1/reservations/:id \
  --header 'Authorization: Bearer <token>'

Example Responses

{
  "success": true,
  "data": {
    "id": "01932b1e-4c3a-7f10-9a2b-5d6e7f800051",
    "resourceId": "01932b1e-4c3a-7f10-9a2b-5d6e7f800041",
    "resourceName": "611호",
    "userId": "01932b1e-4c3a-7f10-9a2b-5d6e7f800003",
    "phone": "+821000001234",
    "name": "김손님",
    "startsAt": "2026-11-03T05:00:00Z",
    "endsAt": "2026-11-03T07:00:00Z",
    "status": "confirmed",
    "price": 20000,
    "memo": "",
    "partySize": 2,
    "occupiedStartsAt": "2026-11-03T05:00:00Z",
    "occupiedEndsAt": "2026-11-03T07:10:00Z",
    "paymentId": "01932b1e-4c3a-7f10-9a2b-5d6e7f800101",
    "createdAt": "2026-11-01T02:00:00Z"
  }
}

json

application/json

예약 취소

POST

https://api.superplace.so

/space/v1/reservations/{id}/cancel

OAuth 2.0

예약을 취소하고 매장의 환불 정책에 따라 결제를 환불합니다. 환불 금액은 서버가 계산해 응답에 담습니다. 되돌릴 수 없으므로 손님에게 환불 정책을 안내하고 확인을 받은 뒤 호출하세요. 손님이 직접 취소한 경우 cancellationType을 비웁니다. store_fault는 매장 사정으로 취소할 때만 보내며 전액 환불되고 reason이 필요합니다.

필요 권한: 환불(pay:refunds:write)

MCP 도구: space_post_reservations_id_cancel

예약 취소 › path Parameters

id

string · uuid · required

예약 ID입니다.

예약 취소 › Request Body

reason

string

취소 사유입니다. cancellationType이 store_fault이면 필수입니다.

cancellationType

string · enum

매장 사정으로 취소할 때만 store_fault를 보냅니다. 전액 환불됩니다. 손님 취소는 생략합니다.

Enum values:

store_fault

예약 취소 › Responses

요청이 처리됐습니다. 결과는 data에 담겨 옵니다.

success

boolean

data

POST/space/v1/reservations/{id}/cancel

curl https://api.superplace.so/space/v1/reservations/:id/cancel \
  --request POST \
  --header 'Content-Type: application/json' \
  --header 'Authorization: Bearer <token>' \
  --data '{
  "reason": "손님 요청"
}'

Example Request Body

{
  "reason": "손님 요청"
}

json

application/json

Example Responses

{
  "success": true,
  "data": {
    "id": "01932b1e-4c3a-7f10-9a2b-5d6e7f800051",
    "resourceId": "01932b1e-4c3a-7f10-9a2b-5d6e7f800041",
    "resourceName": "611호",
    "userId": "01932b1e-4c3a-7f10-9a2b-5d6e7f800003",
    "phone": "+821000001234",
    "name": "김손님",
    "startsAt": "2026-11-03T05:00:00Z",
    "endsAt": "2026-11-03T07:00:00Z",
    "status": "cancelled",
    "price": 20000,
    "memo": "",
    "partySize": 2,
    "occupiedStartsAt": "2026-11-03T05:00:00Z",
    "occupiedEndsAt": "2026-11-03T07:10:00Z",
    "paymentId": "01932b1e-4c3a-7f10-9a2b-5d6e7f800101",
    "createdAt": "2026-11-01T02:00:00Z",
    "cancelledAt": "2026-11-02T01:00:00Z",
    "cancelReason": "손님 요청",
    "refundPercent": 50,
    "refundAmount": 10000,
    "refundRecorded": true
  }
}

json

application/json

예약 입실 처리

POST

https://api.superplace.so

/space/v1/reservations/{id}/check-in

OAuth 2.0

손님이 도착했음을 기록합니다. 확정 상태의 예약만 입실 처리할 수 있습니다.

필요 권한: 예약 처리(생성·변경·취소)(space:reservations:write)

MCP 도구: space_post_reservations_id_check_in

예약 입실 처리 › path Parameters

id

string · required

예약 ID입니다.

예약 입실 처리 › Responses

요청이 처리됐습니다. 결과는 data에 담겨 옵니다.

success

boolean

data

POST/space/v1/reservations/{id}/check-in

curl https://api.superplace.so/space/v1/reservations/:id/check-in \
  --request POST \
  --header 'Authorization: Bearer <token>'

Example Responses

{
  "success": true,
  "data": {
    "id": "01932b1e-4c3a-7f10-9a2b-5d6e7f800051",
    "resourceId": "01932b1e-4c3a-7f10-9a2b-5d6e7f800041",
    "resourceName": "611호",
    "userId": "01932b1e-4c3a-7f10-9a2b-5d6e7f800003",
    "phone": "+821000001234",
    "name": "김손님",
    "startsAt": "2026-11-03T05:00:00Z",
    "endsAt": "2026-11-03T07:00:00Z",
    "status": "confirmed",
    "price": 20000,
    "memo": "",
    "partySize": 2,
    "occupiedStartsAt": "2026-11-03T05:00:00Z",
    "occupiedEndsAt": "2026-11-03T07:10:00Z",
    "paymentId": "01932b1e-4c3a-7f10-9a2b-5d6e7f800101",
    "createdAt": "2026-11-01T02:00:00Z",
    "checkedInAt": "2026-11-03T05:02:00Z"
  }
}

json

application/json

예약 퇴실 처리

POST

https://api.superplace.so

/space/v1/reservations/{id}/check-out

OAuth 2.0

손님이 나갔음을 기록합니다. 입실 처리된 예약만 퇴실 처리할 수 있습니다. settle을 true로 보내면 정산과 수납까지 함께 진행하고, 응답에 totalDue, needsPayment, paymentId, discount, walletAmount가 더해집니다.

필요 권한: 예약 처리(생성·변경·취소)(space:reservations:write)

MCP 도구: space_post_reservations_id_check_out

예약 퇴실 처리 › path Parameters

id

string · required

예약 ID입니다.

예약 퇴실 처리 › Request Body

settle

boolean

true이면 정산과 수납까지 진행합니다.

payMethod

string · enum

정산할 때 수납 수단입니다. cash, van(카드 단말), pg(결제 링크), transfer(계좌이체) 중 하나입니다. cash는 직원이 받았다고 확인할 때까지 대기합니다.

Enum values:

cash

van

transfer

object

손님이 사용할 혜택입니다.

예약 퇴실 처리 › Responses

요청이 처리됐습니다. 결과는 data에 담겨 옵니다.

success

boolean

data

POST/space/v1/reservations/{id}/check-out

curl https://api.superplace.so/space/v1/reservations/:id/check-out \
  --request POST \
  --header 'Content-Type: application/json' \
  --header 'Authorization: Bearer <token>' \
  --data '{
  "settle": true,
  "payMethod": "cash"
}'

Example Request Body

{
  "settle": true,
  "payMethod": "cash"
}

json

application/json

Example Responses

{
  "success": true,
  "data": {
    "id": "01932b1e-4c3a-7f10-9a2b-5d6e7f800051",
    "resourceId": "01932b1e-4c3a-7f10-9a2b-5d6e7f800041",
    "resourceName": "611호",
    "userId": "01932b1e-4c3a-7f10-9a2b-5d6e7f800003",
    "phone": "+821000001234",
    "name": "김손님",
    "startsAt": "2026-11-03T05:00:00Z",
    "endsAt": "2026-11-03T07:00:00Z",
    "status": "confirmed",
    "price": 20000,
    "memo": "",
    "partySize": 2,
    "occupiedStartsAt": "2026-11-03T05:00:00Z",
    "occupiedEndsAt": "2026-11-03T07:10:00Z",
    "paymentId": "01932b1e-4c3a-7f10-9a2b-5d6e7f800102",
    "createdAt": "2026-11-01T02:00:00Z",
    "checkedInAt": "2026-11-03T05:02:00Z",
    "checkedOutAt": "2026-11-03T07:05:00Z",
    "totalDue": 20000,
    "needsPayment": true,
    "discount": 0,
    "walletAmount": 0
  }
}

json

application/json

예약 노쇼 처리

POST

https://api.superplace.so

/space/v1/reservations/{id}/no-show

OAuth 2.0

손님이 오지 않은 확정 예약을 노쇼로 처리합니다. 확정 상태의 예약만 처리할 수 있습니다.

필요 권한: 예약 처리(생성·변경·취소)(space:reservations:write)

MCP 도구: space_post_reservations_id_no_show

예약 노쇼 처리 › path Parameters

id

string · uuid · required

예약 ID입니다.

예약 노쇼 처리 › Responses

요청이 처리됐습니다. 결과는 data에 담겨 옵니다.

success

boolean

data

POST/space/v1/reservations/{id}/no-show

curl https://api.superplace.so/space/v1/reservations/:id/no-show \
  --request POST \
  --header 'Authorization: Bearer <token>'

Example Responses

{
  "success": true,
  "data": {
    "id": "01932b1e-4c3a-7f10-9a2b-5d6e7f800051",
    "resourceId": "01932b1e-4c3a-7f10-9a2b-5d6e7f800041",
    "resourceName": "611호",
    "userId": "01932b1e-4c3a-7f10-9a2b-5d6e7f800003",
    "phone": "+821000001234",
    "name": "김손님",
    "startsAt": "2026-11-03T05:00:00Z",
    "endsAt": "2026-11-03T07:00:00Z",
    "status": "no_show",
    "price": 20000,
    "memo": "",
    "partySize": 2,
    "occupiedStartsAt": "2026-11-03T05:00:00Z",
    "occupiedEndsAt": "2026-11-03T07:10:00Z",
    "paymentId": "01932b1e-4c3a-7f10-9a2b-5d6e7f800101",
    "createdAt": "2026-11-01T02:00:00Z"
  }
}

json

application/json

예약 변경

POST

https://api.superplace.so

/space/v1/reservations/{id}/reschedule

OAuth 2.0

예약의 시간이나 공간을 바꾸거나 이용 시간을 늘립니다. 새 금액이 더 높으면 추가 요금을 안내하고 409로 응답합니다. 추가 요금을 받고 바꾸려면 acceptPriceChange를 true로, 받지 않으려면 waiveIncrease를 true로 다시 보냅니다. preview를 true로 보내면 변경하지 않고 현재 금액, 새 금액, 차액만 돌려줍니다.

필요 권한: 예약 처리(생성·변경·취소)(space:reservations:write)

MCP 도구: space_post_reservations_id_reschedule

예약 변경 › path Parameters

id

string · uuid · required

예약 ID입니다.

예약 변경 › Request Body

startsAt

string · date-time · required

새 시작 시각입니다. RFC3339 형식입니다.

endsAt

string · date-time · required

새 종료 시각입니다.

resourceId

string · uuid

옮길 공간 ID입니다. 비우면 현재 공간을 유지합니다.

preview

boolean

true이면 변경하지 않고 변경 전후 금액과 차액만 조회합니다.

adjustmentType

string · enum

공간 고장으로 옮길 때 store_fault를 보냅니다. 이용 시간은 그대로이고, 추가 요금은 면제되며 줄어든 차액은 환불됩니다.

Enum values:

store_fault

reason

string

공간 고장으로 옮기는 사유입니다.

acceptPriceChange

boolean

true이면 금액 변화를 받아들입니다. 늘어난 금액은 별도 결제 뒤 변경하고, 줄어든 금액은 환불한 뒤 변경합니다.

waiveIncrease

boolean

true이면 늘어난 요금을 받지 않습니다. 금액은 그대로이고 결제 없이 바로 바뀝니다.

payMethod

string · enum

추가 요금을 받는 수단입니다. pg(결제 링크) 또는 cash(현금)입니다.

Enum values:

cash

Default: pg

object

추가 요금에 사용할 손님 혜택입니다. couponIssueId(쿠폰), points(포인트), prepaid(선불권), timePasses(시간권)를 담을 수 있습니다.

benefits

boolean

preview와 함께 true로 보내면 손님이 가진 혜택과 사용 견적이 응답의 benefits에 담깁니다.

예약 변경 › Responses

요청이 처리됐습니다. 결과는 data에 담겨 옵니다.

success

boolean

data

입장 링크 다시 보내기

POST

https://api.superplace.so

/space/v1/reservations/{id}/resend-entry

OAuth 2.0

예약의 입장 링크(모바일 키)를 손님 전화번호로 다시 발송합니다. 입장 문자가 도착하지 않았다고 하는 확정 예약 손님에게 사용합니다. 링크 자체는 바뀌지 않습니다. 전화번호가 있는 확정 예약만 보낼 수 있습니다.

필요 권한: 예약 처리(생성·변경·취소)(space:reservations:write)

MCP 도구: space_post_reservations_id_resend_entry

입장 링크 다시 보내기 › path Parameters

id

string · uuid · required

예약 ID입니다.

입장 링크 다시 보내기 › Responses

요청이 처리됐습니다. 결과는 data에 담겨 옵니다.

success

boolean

data

공간 목록 조회

GET

https://api.superplace.so

/space/v1/resources

OAuth 2.0

예약할 수 있는 방, 좌석 같은 공간을 종류, 정원, 활성 여부와 함께 돌려줍니다. busyFrom과 busyTo를 함께 보내면 공간마다 그 구간에 예약할 수 있는지가 time에 담깁니다. blocked가 있으면 그 구간은 예약할 수 없고, warnings는 예약은 되지만 알려야 할 사항입니다.

MCP 도구: space_get_resources

공간 목록 조회 › query Parameters

filter

string

조직 계정으로 연결한 경우 매장 하나를 고르는 JSON입니다. 예: {"placeId":"01932b1e-4c3a-7f10-9a2b-5d6e7f800010"}. 매장 계정에서는 생략합니다.

busyFrom

string · date-time

예약 가능 여부를 확인할 구간의 시작 시각입니다. busyTo와 함께 보냅니다. RFC3339 형식입니다.

busyTo

string · date-time

구간의 끝 시각입니다. RFC3339 형식입니다.

except

string · uuid

구간을 확인할 때 제외할 예약 ID입니다. 예약을 옮길 때 그 예약 자신을 빼려고 사용합니다.

공간 목록 조회 › Responses

요청이 처리됐습니다. 결과는 data에 담겨 옵니다.

success

boolean

data

total

integer

예약 가능 시간 조회

GET

https://api.superplace.so

/space/v1/resources/{id}/availability

OAuth 2.0

공간 하나의 하루 예약 가능 구간을 영업시간과 기존 예약을 반영해 돌려줍니다. date는 매장 기준 날짜이고 생략하면 오늘입니다.

MCP 도구: space_get_resources_id_availability

예약 가능 시간 조회 › path Parameters

id

string · uuid · required

공간 ID입니다. 공간 목록의 id입니다.

예약 가능 시간 조회 › query Parameters

date

string · date

조회할 날짜입니다. YYYY-MM-DD 형식입니다.

예약 가능 시간 조회 › Responses

요청이 처리됐습니다. 결과는 data에 담겨 옵니다.

success

boolean

data

매장 손님