파트너 키(레거시)

기존 연동만 쓰는 옛 길입니다. 파트너 키를 토큰으로 바꾸고 출입 허가·출입 기록·출입 설정·예약 등록을 다룹니다. 새 연동은 앱 연결 토큰으로 다른 연산을 씁니다.

API 키를 액세스 토큰으로 교환

POST

https://api.superplace.so

/core/v1/auth/apikey/token

발급받은 spk_ 키를 보내면 15분간 유효한 액세스 토큰을 돌려줍니다. 이후 모든 호출에 Authorization: Bearer <액세스 토큰> 헤더를 붙이세요. 만료되면 같은 방법으로 다시 교환하세요. 키가 잘못되면 401, 한 IP에서 지나치게 자주 부르면 429가 옵니다. 응답의 scopes 배열이 이 키로 할 수 있는 범위입니다. 응답의 placeId가 매장 ID입니다.

파트너 키(레거시) 전용입니다. 새 연동은 앱 연결 토큰으로 다른 연산을 씁니다.

API 키를 액세스 토큰으로 교환 › Request Body

key

string · required

발급받은 API 키입니다. 매장 키는 spk_, 조직 키는 sok_로 시작합니다.

placeId

string · uuid

조직 키(sok_)로 교환할 때만 보냅니다. 토큰을 받을 매장의 ID입니다. 생략하면 조직 전체용 토큰이 발급됩니다.

API 키를 액세스 토큰으로 교환 › Responses

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

success

enum · required

Enum values:

data

required

출입 기록 조회

GET

https://api.superplace.so

/space/v1/partner/entry-logs

Bearer (JWT)

누가 언제 어떤 방법(전화·QR)으로 들어왔는지 조회합니다. 최근 30일까지입니다. 출입자 이름은 일부만 보이도록 가려서 담깁니다.

파트너 키(레거시) 전용입니다. 새 연동은 앱 연결 토큰으로 다른 연산을 씁니다.

출입 기록 조회 › query Parameters

sinceDays

integer · min: 1 · max: 30

오늘부터 며칠 전까지 볼지입니다. 최대 30입니다.

limit

integer · min: 1

한 번에 돌려줄 건수입니다.

출입 기록 조회 › Responses

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

success

boolean

data

total

integer

발급한 허가 목록

GET

https://api.superplace.so

/space/v1/partner/entry-permits

Bearer (JWT)

이 API로 발급한 허가만 돌려줍니다. 콘솔에서 발급한 허가는 포함되지 않습니다. 개인정보 보호를 위해 전화번호는 뒤 4자리만 담깁니다.

파트너 키(레거시) 전용입니다. 새 연동은 앱 연결 토큰으로 다른 연산을 씁니다.

발급한 허가 목록 › query Parameters

externalRef

string

허가를 등록할 때 보낸 externalRef입니다. 보내면 그 허가 한 건만 돌려줍니다.

limit

integer · min: 1 · max: 500

한 번에 돌려줄 건수입니다. 최대 500, 기본 100입니다.

Default: 100

offset

integer · min: 0

건너뛸 건수입니다. 기본 0입니다.

Default: 0

발급한 허가 목록 › Responses

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

success

boolean

data

total

integer

출입 허가 발급

POST

https://api.superplace.so

/space/v1/partner/entry-permits

Bearer (JWT)

전화번호와 이용 시간을 보내면 그 시간 동안 손님이 전화·QR로 문을 열 수 있습니다. 응답의 url을 손님에게 문자로 보내면 손님이 QR을 띄웁니다. 이용 시간은 한 건에 최대 30일(720시간)입니다. externalRef가 같은 요청은 새로 만들지 않고 시간을 갱신하므로, 재전송이나 시간 변경도 같은 요청으로 처리하면 됩니다. 새 externalRef에서 doorIds를 생략하거나 null로 보내면 현재 매장의 출입문 전체가 대상입니다. doorIds는 GET /device/v1/devices가 돌려주는 이 매장의 문 id여야 하며, 문이 아닌 기기나 다른 매장의 id가 섞이면 400입니다. 같은 externalRef를 다시 발급할 때 doorIds를 생략하거나 null로 보내면 저장된 문 범위가 유지됩니다. 비어 있지 않은 배열을 보낼 때만 범위가 바뀌며, 빈 배열은 400입니다. 모든 문으로 넓히려면 현재 문 ID 전체를 보내야 합니다.

파트너 키(레거시) 전용입니다. 새 연동은 앱 연결 토큰으로 다른 연산을 씁니다.

출입 허가 발급 › Request Body

phone

string · required

손님 연락처입니다.

startsAt

string · date-time · required

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

endsAt

string · date-time · required

이용 종료 시각입니다. 시작에서 30일을 넘길 수 없습니다.

externalRef

string · required

파트너 쪽 고유 번호입니다. 같은 값으로 다시 보내면 새로 만들지 않고 시간을 갱신합니다.

name

string

손님 이름입니다.

doorIds

array | null · minItems: 1

허용할 문 ID 목록입니다. 생략하거나 null이면 새 허가는 매장의 출입문 전체, 재발급은 저장된 범위를 유지합니다. 빈 배열은 400입니다.

출입 허가 발급 › Responses

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

success

boolean

data

POST/space/v1/partner/entry-permits

curl https://api.superplace.so/space/v1/partner/entry-permits \
  --request POST \
  --header 'Content-Type: application/json' \
  --header 'Authorization: Bearer <token>' \
  --data '{
  "phone": "01012345678",
  "name": "홍길동",
  "startsAt": "2026-09-04T14:00:00+09:00",
  "endsAt": "2026-09-04T18:00:00+09:00",
  "externalRef": "order-1024"
}'

Example Request Body

{
  "phone": "01012345678",
  "name": "홍길동",
  "startsAt": "2026-09-04T14:00:00+09:00",
  "endsAt": "2026-09-04T18:00:00+09:00",
  "externalRef": "order-1024"
}

json

application/json

Example Responses

{
  "success": true,
  "data": {
    "permitId": "01932b1e-4c3a-7f10-9a2b-5d6e7f800071",
    "reservationId": "01932b1e-4c3a-7f10-9a2b-5d6e7f800051",
    "externalRef": "order-1024",
    "entryToken": "01932b1e-4c3a-7f10-9a2b-5d6e7f800072",
    "url": "https://go.superplace.so/entry?t=01932b1e-4c3a-7f10-9a2b-5d6e7f800072",
    "startsAt": "2026-09-04T05:00:00Z",
    "endsAt": "2026-09-04T09:00:00Z"
  }
}

json

application/json

출입 허가 해지

POST

https://api.superplace.so

/space/v1/partner/entry-permits/revoke

Bearer (JWT)

externalRef 또는 permitId로 지정한 허가를 해지합니다. 해지하면 전화·QR이 바로 거절됩니다. reason(선택, 200자)은 기록에 남습니다.

파트너 키(레거시) 전용입니다. 새 연동은 앱 연결 토큰으로 다른 연산을 씁니다.

출입 허가 해지 › Request Body

externalRef

string

등록할 때 보낸 externalRef입니다. permitId와 둘 중 하나를 보냅니다.

permitId

string · uuid

등록 응답의 permitId입니다.

reason

string · maxLength: 200

해지 사유입니다. 200자 이하, 기록용입니다.

출입 허가 해지 › Responses

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

success

boolean

data

허가 단건 조회

GET

https://api.superplace.so

/space/v1/partner/entry-permits/{id}

Bearer (JWT)

이 API로 발급한 허가 한 건을 돌려줍니다. state는 active(이용 가능), pending(시작 전), expired(만료), revoked(해지) 중 하나입니다.

파트너 키(레거시) 전용입니다. 새 연동은 앱 연결 토큰으로 다른 연산을 씁니다.

허가 단건 조회 › path Parameters

id

string · required

발급 응답의 permitId입니다.

허가 단건 조회 › Responses

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

success

boolean

data

출입 설정 조회

GET

https://api.superplace.so

/space/v1/partner/gate-config

Bearer (JWT)

전화 인증 사용 여부(phoneEnabled), 손님이 걸 출입 전화번호(entryPhone), 허가 한 건의 최대 길이(entryPermitMaxHours)를 돌려줍니다. 출입 전화번호가 아직 배정되지 않았으면 entryPhone은 없습니다.

파트너 키(레거시) 전용입니다. 새 연동은 앱 연결 토큰으로 다른 연산을 씁니다.

출입 설정 조회 › Responses

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

success

boolean

data

예약 등록

POST

https://api.superplace.so

/space/v1/partner/reservations

Bearer (JWT)

방(공간)을 시간 단위로 예약합니다. resourceName에 "611호"처럼 이름을 넣어도 됩니다. externalRef는 파트너 쪽 예약번호이고, 같은 값을 다시 보내면 중복 등록되지 않습니다. phone을 넣으면 그 시간 동안 전화·QR 입장이 되고, 생략하면 입장 자격이 없는 자리표시 예약으로 등록됩니다. 한 예약은 48시간을 넘을 수 없습니다. 새로 만들면 201, 같은 externalRef를 다시 보내면 200입니다. status를 "cancelled"로 보내면 externalRef의 예약이 취소됩니다. 입장 링크가 닫히고 자리가 풀리며, 손님에게 알림은 발송되지 않습니다. 이미 취소됐거나 없는 externalRef도 200입니다.

파트너 키(레거시) 전용입니다. 새 연동은 앱 연결 토큰으로 다른 연산을 씁니다.

예약 등록 › Request Body

resourceId

string · uuid

방 ID입니다. resourceName보다 우선합니다.

resourceName

string

방 이름입니다. 예: 611호

startsAt

string · date-time

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

endsAt

string · date-time

이용 종료 시각입니다.

phone

string

손님 연락처입니다. 있으면 전화·QR 입장이 되고 예약 조회에도 연결됩니다.

name

string

손님 이름입니다.

externalRef

string

파트너 쪽 예약번호입니다. 중복 등록을 막는 키입니다.

status

string · enum

confirmed(기본) 또는 cancelled입니다. cancelled이면 externalRef의 예약을 취소하고 시간·방 항목은 무시합니다.

Enum values:

confirmed

cancelled

Default: confirmed

예약 등록 › Responses

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

success

boolean

data

POST/space/v1/partner/reservations

curl https://api.superplace.so/space/v1/partner/reservations \
  --request POST \
  --header 'Content-Type: application/json' \
  --header 'Authorization: Bearer <token>' \
  --data '{
  "resourceName": "611호",
  "startsAt": "2026-09-04T14:00:00+09:00",
  "endsAt": "2026-09-04T16:00:00+09:00",
  "phone": "01012345678",
  "name": "홍길동",
  "externalRef": "resv-2048"
}'

Example Request Body

{
  "resourceName": "611호",
  "startsAt": "2026-09-04T14:00:00+09:00",
  "endsAt": "2026-09-04T16:00:00+09:00",
  "phone": "01012345678",
  "name": "홍길동",
  "externalRef": "resv-2048"
}

json

application/json

Example Responses

{
  "success": true,
  "data": {
    "reservationId": "01932b1e-4c3a-7f10-9a2b-5d6e7f800051",
    "entryToken": "01932b1e-4c3a-7f10-9a2b-5d6e7f800073",
    "url": "https://go.superplace.so/entry?t=01932b1e-4c3a-7f10-9a2b-5d6e7f800073",
    "startsAt": "2026-09-04T05:00:00Z",
    "endsAt": "2026-09-04T07:00:00Z"
  }
}

json

application/json

기기