매장

내 계정, 매장 정보, 영업시간 조회·설정, 공개 일정, 직원, 활동 기록을 다룹니다.

활동 기록 조회

GET

https://api.superplace.so

/core/v1/events

OAuth 2.0

누가 언제 무엇을 했는지 시간순으로 조회합니다. 조직 계정이면 닿는 매장 전체가 포함됩니다. filter로 종류, 행위자, 기간을 좁힙니다. q에 이름이나 전화번호를 보내면 그 사람과 관련된 기록만 돌려줍니다.

필요 권한: 매장 전체 기록 보기(core:activity:read)

MCP 도구: core_get_events

활동 기록 조회 › query Parameters

q

string · maxLength: 64

이름이나 전화번호입니다. 전화번호는 뒷 4자리나 국제 표기로도 찾을 수 있습니다.

facet

string · enum

domain 또는 outcome을 보내면 목록 대신 영역별·결과별 건수만 돌려줍니다.

Enum values:

domain

outcome

filter

string

조건 JSON입니다. type(사건 종류), domain(영역), actor(행위자), resourceId, occurredAt({"gte":…,"lte":…}, RFC3339), placeId를 쓸 수 있습니다.

page

integer · min: 1

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

perPage

integer · min: 1 · max: 200

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

start

integer · min: 0

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

end

integer · min: 0

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

활동 기록 조회 › Responses

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

success

enum · required

Enum values:

data

array · required

total

integer · required

내 정보 조회

GET

https://api.superplace.so

/core/v1/me

OAuth 2.0

연결한 계정의 이름, 연락처, 언어, 이 매장에서의 권한 목록(caps)과 태그를 돌려줍니다. 조직 계정이면 orgId가, 매장 계정이면 placeId가 함께 담깁니다. node를 보내면 그 매장·조직의 홈 화면 구성(homeLayout)이 더해집니다.

MCP 도구: core_get_me

내 정보 조회 › query Parameters

node

string

홈 화면 구성을 읽을 대상입니다. place:{매장 ID} 또는 org:{조직 ID} 형식입니다. 접근할 수 없는 대상은 404입니다.

내 정보 조회 › Responses

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

success

enum · required

Enum values:

data

required

직원 목록 조회

GET

https://api.superplace.so

/core/v1/members

OAuth 2.0

연결한 매장에서 일하는 사람과 AI 직원을 역할과 함께 돌려줍니다. 조직 계정이면 닿는 모든 매장의 직원이 매장별로 담깁니다.

필요 권한: 구성원 목록 보기(core:members:read)

MCP 도구: core_get_members

직원 목록 조회 › query Parameters

filter

string

조건 JSON입니다. 매장 하나로 좁히려면 {"placeId":"…"}를 보냅니다.

직원 목록 조회 › Responses

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

success

enum · required

Enum values:

data

array · required

total

integer · required

매장 정보 조회

GET

https://api.superplace.so

/core/v1/places/{id}

OAuth 2.0

매장 이름, 주소, 업종, 전화번호, 시간대, 영업시간 규칙과 정지 여부(suspended)를 돌려줍니다.

필요 권한: 매장 정보 보기(core:place:read)

MCP 도구: core_get_places_id

매장 정보 조회 › path Parameters

id

string · uuid · required

매장 ID입니다.

매장 정보 조회 › Responses

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

success

enum · required

Enum values:

data

required

GET/core/v1/places/{id}

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

Example Responses

{
  "success": true,
  "data": {
    "id": "01932b1e-4c3a-7f10-9a2b-5d6e7f800010",
    "orgId": "01932b1e-4c3a-7f10-9a2b-5d6e7f800020",
    "name": "슈플 스터디카페 강남점",
    "slug": "gangnam",
    "timezone": "Asia/Seoul",
    "address": "서울 강남구 테헤란로 000",
    "phone": "02-0000-1234",
    "category": "studycafe",
    "country": "KR",
    "tags": [],
    "suspended": false,
    "hours": {
      "timezone": "Asia/Seoul",
      "week": {
        "mon": [
          [
            "09:00",
            "22:00"
          ]
        ],
        "sun": []
      }
    },
    "createdAt": "2026-10-01T00:00:00Z"
  }
}

json

application/json

영업시간 설정

PATCH

https://api.superplace.so

/core/v1/places/{id}

OAuth 2.0

Bearer (JWT)

매장의 주간 영업시간을 저장합니다. API 키로는 영업시간(hours)만 수정할 수 있고, 다른 항목을 보내면 403입니다. 저장하면 영업시간을 기준으로 하는 출입 정책이 바로 이 값에 맞춰 바뀝니다. week의 키는 mon~sun, 값은 [["열림","닫힘"]] 구간 목록이고 빈 배열은 휴무입니다.

영업시간 설정 › path Parameters

id

string · uuid · required

매장 ID입니다. 토큰 교환 응답의 placeId를 넣습니다.

영업시간 설정 › Request Body

publicSlug

string

object

representative

string · maxLength: 60

name

string

address

string

bizRegNo

string

category

string

country

string · pattern: ^[A-Z]{2}$

phone

string

hours

object

영업시간 규칙입니다. week에 요일별 구간을 담습니다. 요일 키는 mon~sun이고, 값은 ["09:00","22:00"] 형태의 구간 목록입니다. 빈 배열은 휴무입니다.

profile

object

영업시간 설정 › Responses

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

success

enum · required

Enum values:

data

required

PATCH/core/v1/places/{id}

curl https://api.superplace.so/core/v1/places/:id \
  --request PATCH \
  --header 'Content-Type: application/json' \
  --header 'Authorization: Bearer <token>' \
  --data '{
  "hours": {
    "week": {
      "mon": [
        [
          "09:00",
          "22:00"
        ]
      ],
      "tue": [
        [
          "09:00",
          "22:00"
        ]
      ],
      "wed": [
        [
          "09:00",
          "22:00"
        ]
      ],
      "thu": [
        [
          "09:00",
          "22:00"
        ]
      ],
      "fri": [
        [
          "09:00",
          "22:00"
        ]
      ],
      "sat": [
        [
          "10:00",
          "18:00"
        ]
      ],
      "sun": []
    }
  }
}'

Example Request Body

{
  "hours": {
    "week": {
      "mon": [
        [
          "09:00",
          "22:00"
        ]
      ],
      "tue": [
        [
          "09:00",
          "22:00"
        ]
      ],
      "wed": [
        [
          "09:00",
          "22:00"
        ]
      ],
      "thu": [
        [
          "09:00",
          "22:00"
        ]
      ],
      "fri": [
        [
          "09:00",
          "22:00"
        ]
      ],
      "sat": [
        [
          "10:00",
          "18:00"
        ]
      ],
      "sun": []
    }
  }
}

json

application/json

Example Responses

{
  "success": true,
  "data": {
    "id": "01932b1e-4c3a-7f10-9a2b-5d6e7f800010",
    "name": "슈플 스터디카페 강남점",
    "timezone": "Asia/Seoul",
    "hours": {
      "week": {
        "mon": [
          [
            "09:00",
            "22:00"
          ]
        ],
        "sun": []
      }
    }
  }
}

json

application/json

매장 활동 기록 조회

GET

https://api.superplace.so

/core/v1/places/{id}/events

OAuth 2.0

Bearer (JWT)

개문, 허가 발급·해지처럼 매장에서 일어난 일을 시간순으로 조회합니다. filter와 page로 좁힐 수 있습니다. q에 이름이나 전화번호(010-…, +8210…, 뒷 4자리)를 보내면 그 사람과 관련된 기록만 돌려줍니다.

매장 활동 기록 조회 › path Parameters

id

string · uuid · required

매장 ID입니다. 토큰 교환 응답의 placeId를 그대로 넣습니다. 문 ID가 아닙니다.

매장 활동 기록 조회 › query Parameters

q

string · maxLength: 64

이름이나 전화번호입니다. 전화번호는 뒷 4자리나 국제 표기(+8210…)로도 찾을 수 있습니다.

facet

string · enum

domain 또는 outcome을 보내면 목록 대신 영역별·결과별 건수만 돌려줍니다. 생략하면 목록입니다.

Enum values:

domain

outcome

filter

string

조건을 담은 JSON입니다. type(사건 종류), domain(영역), actor(행위자), resourceId, occurredAt({"gte":…,"lte":…}, RFC3339)를 쓸 수 있습니다. 예: {"type":"door.opened"}

page

integer · min: 1

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

perPage

integer · min: 1 · max: 200

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

start

integer · min: 0

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

end

integer · min: 0

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

매장 활동 기록 조회 › Responses

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

success

enum · required

Enum values:

data

array · required

total

integer · required

영업시간 조회

GET

https://api.superplace.so

/core/v1/places/{id}/schedule

OAuth 2.0

정기 휴무, 공휴일, 임시 휴무를 반영한 날짜별 실제 영업 구간을 돌려줍니다. from부터 days일치입니다. 날짜마다 closed(휴무 여부)와 open(영업 구간), source(적용된 규칙)가 담깁니다.

필요 권한: 매장 정보 보기(core:place:read)

MCP 도구: core_get_places_id_schedule

영업시간 조회 › path Parameters

id

string · uuid · required

매장 ID입니다.

영업시간 조회 › query Parameters

from

string · date

시작 날짜입니다. YYYY-MM-DD 형식이고, 생략하면 오늘입니다.

days

integer · min: 1 · max: 366

조회할 일수입니다. 1~366, 기본 7입니다.

Default: 7

영업시간 조회 › Responses

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

success

enum · required

Enum values:

data

array · required

total

integer · required

영업시간 조회 (해석본)

GET

https://api.superplace.so

/core/v1/public/places/{id}/schedule

정기 휴무, 공휴일, 특정일 예외까지 반영한 그날의 실제 영업 구간을 날짜별로 돌려줍니다. from(YYYY-MM-DD)과 days로 기간을 정합니다. 인증 없이 호출할 수 있습니다.

영업시간 조회 (해석본) › path Parameters

id

string · uuid · required

매장 ID입니다. 토큰 교환 응답의 placeId를 넣습니다.

영업시간 조회 (해석본) › query Parameters

from

string · date

조회를 시작할 날짜입니다. YYYY-MM-DD 형식이고, 생략하면 오늘입니다.

days

integer · min: 1 · max: 366

조회할 일수입니다. 1~366, 기본 7입니다.

Default: 7

영업시간 조회 (해석본) › Responses

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

success

enum · required

Enum values:

data

array · required

total

integer · required

예약