손님

손님 명단과 회원권을 조회·등록하고, 회원권을 발급·수정·해지·일시정지·재개합니다. 다른 시스템의 명부 반입도 여기 있습니다.

손님 검색

GET

https://api.superplace.so

/space/v1/customers

OAuth 2.0

Bearer (JWT)

이름이나 전화번호 일부로 손님을 검색합니다. q가 없으면 최근 갱신순으로 돌려줍니다. view로 신규, 단골, 휴면 같은 고정 보기를 고를 수 있습니다.

MCP 도구: space_get_customers

손님 검색 › query Parameters

q

string

이름이나 전화번호의 일부입니다.

view

string · enum

고정 보기입니다. all, new(신규), prospect(가망), loyal(단골), dormant(휴면), consented(광고 수신 동의), opted_out(수신 거부), benefit_expiring(30일 안에 만료되는 혜택 보유)을 고릅니다. all 외의 보기는 점주·매니저 권한이 필요합니다.

Enum values:

all

new

prospect

loyal

dormant

consented

opted_out

benefit_expiring

page

integer · min: 1

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

perPage

integer · min: 1 · max: 200

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

sort

string · enum

정렬 기준입니다. 기본은 updatedAt입니다. lastVisitAt은 방문 기록이 없는 손님이 뒤로 갑니다.

Enum values:

updatedAt

createdAt

name

visitCount

lastVisitAt

phone

Default: updatedAt

order

string · enum

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

Enum values:

asc

desc

filter

string

조건 JSON입니다. 차단한 손님만 보려면 {"blocked":true}, 매장을 고르려면 {"placeId":"…"}를 보냅니다.

start

integer · min: 0

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

end

integer · min: 0

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

손님 검색 › Responses

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

success

boolean · enum · required

Enum values:

object[] · required

total

integer · int64 · required

손님 등록

POST

https://api.superplace.so

/space/v1/customers

OAuth 2.0

Bearer (JWT)

전화번호가 이미 있으면 새로 만들지 않고 그 손님의 정보를 갱신합니다. 생략한 항목은 기존 값이 유지됩니다.

손님 등록 › Request Body

phone

string · required

손님 연락처입니다. 국제 표기로 정리되어 저장됩니다.

placeId

string · uuid

조직 키로 호출할 때만 필요한 매장 ID입니다. 매장 키에서는 보내지 않습니다.

name

string

손님 이름입니다.

language

string · enum

손님 언어입니다. ko, en, ja, zh, fr 중 하나이고, 안내 문자가 이 언어로 발송됩니다.

Enum values:

memo

string

매장 내부 비고입니다. 생략하면 유지하고, 빈 문자열을 보내면 지웁니다.

marketingConsent

boolean

false를 보내면 광고 수신을 중지합니다. 수신 동의는 손님 본인만 켤 수 있어 true는 409로 거절됩니다.

손님 등록 › Responses

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

success

boolean

data

POST/space/v1/customers

curl https://api.superplace.so/space/v1/customers \
  --request POST \
  --header 'Content-Type: application/json' \
  --header 'Authorization: Bearer <token>' \
  --data '{
  "phone": "01012345678",
  "name": "홍길동"
}'

Example Request Body

{
  "phone": "01012345678",
  "name": "홍길동"
}

json

application/json

Example Responses

{
  "success": true,
  "data": {
    "userId": "01932b1e-4c3a-7f10-9a2b-5d6e7f800003",
    "phone": "+821000001234",
    "name": "김손님",
    "memo": "",
    "language": "ko",
    "marketingConsent": false,
    "visitCount": 3,
    "blocked": false,
    "lastVisitAt": "2026-11-02T09:30:00Z",
    "createdAt": "2026-10-20T03:00:00Z",
    "updatedAt": "2026-11-02T09:30:00Z"
  }
}

json

application/json

손님 일괄 등록

POST

https://api.superplace.so

/space/v1/customers/import

OAuth 2.0

Bearer (JWT)

여러 명을 한 번에 등록합니다. source에 어느 시스템에서 온 명부인지 적고, items에 행을 담습니다. 행마다 따로 처리되므로 일부가 실패해도 나머지는 등록되고, 응답에 행별 결과가 담깁니다. 같은 파일을 다시 올려도 중복이 생기지 않습니다.

손님 일괄 등록 › Request Body

source

string · required

명부가 나온 시스템 이름입니다. 예: excel, 우리시스템

object[] · maxItems: 1000 · required

등록할 손님 행 목록입니다.

placeId

string · uuid

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

손님 일괄 등록 › Responses

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

success

boolean

data

POST/space/v1/customers/import

curl https://api.superplace.so/space/v1/customers/import \
  --request POST \
  --header 'Content-Type: application/json' \
  --header 'Authorization: Bearer <token>' \
  --data '{
  "source": "우리시스템",
  "items": [
    {
      "phone": "01012345678",
      "name": "홍길동"
    },
    {
      "phone": "01098765432",
      "name": "김영희"
    }
  ]
}'

Example Request Body

{
  "source": "우리시스템",
  "items": [
    {
      "phone": "01012345678",
      "name": "홍길동"
    },
    {
      "phone": "01098765432",
      "name": "김영희"
    }
  ]
}

json

application/json

Example Responses

{
  "success": true,
  "data": {
    "imported": 1,
    "failed": 1,
    "total": 2,
    "results": [
      {
        "index": 0,
        "status": "imported",
        "phone": "+821012345678"
      },
      {
        "index": 1,
        "status": "failed",
        "phone": "01098765432",
        "error": "전화번호 형식을 확인해 주세요"
      }
    ]
  }
}

json

application/json

출입 허가 목록 (전체)

GET

https://api.superplace.so

/space/v1/entry-permits

OAuth 2.0

Bearer (JWT)

콘솔에서 발급한 것까지 포함한 매장 전체 출입 허가 목록입니다. page·perPage(기본 20, 최대 200)로 넘기고, filter로 상태와 발급 기간을 좁힙니다. 파트너가 발급한 것만 보려면 /v1/partner/entry-permits를 사용하세요.

출입 허가 목록 (전체) › query Parameters

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

정렬 기준입니다. 기본은 createdAt입니다. bucket은 유효, 대기, 만료, 해지 순이고 firstUsedAt은 한 번도 쓰지 않은 허가가 뒤로 갑니다.

Enum values:

createdAt

name

phone

bucket

startsAt

firstUsedAt

Default: createdAt

order

string · enum

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

Enum values:

asc

desc

Default: desc

filter

string

조건 JSON입니다. bucket(active, pending, expired, revoked 중 하나 또는 in 목록), createdAt({"gte":…,"lt":…}, RFC3339), placeId를 쓸 수 있습니다.

출입 허가 목록 (전체) › Responses

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

success

boolean

data

total

integer

GET/space/v1/entry-permits

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

Example Responses

{
  "success": true,
  "data": [
    {
      "id": "01932b1e-4c3a-7f10-9a2b-5d6e7f800071",
      "placeId": "01932b1e-4c3a-7f10-9a2b-5d6e7f800010",
      "phone": "+821012345678",
      "name": "홍길동",
      "startsAt": "2026-11-04T05:00:00Z",
      "endsAt": "2026-11-04T09:00:00Z",
      "externalRef": "order-1024",
      "memo": "",
      "useCount": 1,
      "doorIds": [
        "01932b1e-4c3a-7f10-9a2b-5d6e7f800031"
      ],
      "createdAt": "2026-11-03T02:00:00Z",
      "entryUrl": "https://go.superplace.so/entry?t=01932b1e-4c3a-7f10-9a2b-5d6e7f800072"
    }
  ],
  "total": 1
}

json

application/json

회원권 목록 조회

GET

https://api.superplace.so

/space/v1/memberships

OAuth 2.0

Bearer (JWT)

기간권, 횟수권 같은 손님 회원권을 상태와 남은 횟수와 함께 돌려줍니다. phone이나 userId로 한 사람의 회원권만 볼 수 있습니다.

필요 권한: 회원권·출입 허가 보기(space:memberships:read)

MCP 도구: space_get_memberships

회원권 목록 조회 › query Parameters

userId

string · uuid

손님 계정의 ID입니다. 그 사람의 회원권만 돌려줍니다.

phone

string

전화번호입니다. 그 번호를 가진 사람의 회원권만 돌려주고, 없는 번호는 빈 목록입니다.

q

string

이름이나 전화번호의 일부입니다.

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

정렬 기준입니다. 기본은 createdAt입니다. bucket은 이용 중, 만료 임박, 정지, 시작 전, 만료, 해지 순입니다.

Enum values:

createdAt

endsAt

price

name

phone

planName

startsAt

bucket

Default: createdAt

order

string · enum

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

Enum values:

asc

desc

Default: desc

filter

string

조건 JSON입니다. state(active, held, expiring, pending, expired, cancelled), createdAt·endsAt({"gte":…,"lt":…}), placeId를 쓸 수 있습니다.

회원권 목록 조회 › Responses

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

success

boolean

data

total

integer

회원권 발급

POST

https://api.superplace.so

/space/v1/memberships

OAuth 2.0

Bearer (JWT)

기간 안에는 등록된 전화번호로 전화·QR 입장이 됩니다. 손님이 미리 등록돼 있지 않아도 자동으로 등록됩니다. 날짜는 RFC3339 형식입니다. 연장이나 재등록은 새 회원권을 발급합니다. price가 0보다 크면 결제 기록이 함께 만들어지고, 응답에 paymentId가 담깁니다.

회원권 발급 › Request Body

phone

string · required

손님 연락처입니다.

endsAt

string · date-time · required

종료 시각입니다. 상품을 지정하지 않으면 필수입니다.

name

string

손님 이름입니다.

planId

string · uuid

회원권 상품 ID입니다. 보내면 상품의 기간·가격·횟수가 적용되고, endsAt·price는 생략할 수 있습니다. 직접 보낸 값이 우선합니다.

startsAt

string · date-time

시작 시각입니다. 생략하면 지금입니다.

price

integer

판매가(원)입니다. 중도 해지 때 환불 계산의 기준이 됩니다.

method

string · enum

수납 수단입니다. cash(현금, 기본)는 직원이 받았다고 확인할 때까지 대기합니다. transfer(계좌이체)와 pg(결제 링크 문자)도 고를 수 있습니다.

Enum values:

cash

transfer

issuedRef

string

발급 근거입니다. 예: 아파트는 동·호수, 회사는 사번

memo

string

매장 내부 비고입니다.

회원권 발급 › Responses

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

success

boolean

data

POST/space/v1/memberships

curl https://api.superplace.so/space/v1/memberships \
  --request POST \
  --header 'Content-Type: application/json' \
  --header 'Authorization: Bearer <token>' \
  --data '{
  "phone": "01012345678",
  "name": "홍길동",
  "startsAt": "2026-09-04T00:00:00+09:00",
  "endsAt": "2026-10-04T00:00:00+09:00",
  "price": 99000
}'

Example Request Body

{
  "phone": "01012345678",
  "name": "홍길동",
  "startsAt": "2026-09-04T00:00:00+09:00",
  "endsAt": "2026-10-04T00:00:00+09:00",
  "price": 99000
}

json

application/json

Example Responses

{
  "success": true,
  "data": {
    "id": "01932b1e-4c3a-7f10-9a2b-5d6e7f800061",
    "placeId": "01932b1e-4c3a-7f10-9a2b-5d6e7f800010",
    "phone": "+821000001234",
    "name": "김손님",
    "userId": "01932b1e-4c3a-7f10-9a2b-5d6e7f800003",
    "startsAt": "2026-11-01T00:00:00+09:00",
    "endsAt": "2026-11-30T00:00:00+09:00",
    "status": "active",
    "price": 99000,
    "issuedRef": "",
    "memo": "",
    "createdAt": "2026-10-31T06:00:00Z",
    "paymentId": "01932b1e-4c3a-7f10-9a2b-5d6e7f800101"
  }
}

json

application/json

회원권 일괄 반입

POST

https://api.superplace.so

/space/v1/memberships/import

OAuth 2.0

Bearer (JWT)

기존 시스템에서 회원권을 옮겨올 때 사용합니다. 손님과 기간이 같은 회원권이 이미 있으면 건너뛰므로(행 결과에 skipped로 표시) 여러 번 올려도 중복이 생기지 않습니다. 날짜는 YYYY-MM-DD(매장 시간대 자정) 또는 RFC3339입니다. 한 번에 1~1000행을 보낼 수 있습니다.

회원권 일괄 반입 › Request Body

source

string · required

명부가 나온 시스템 이름입니다.

object[] · maxItems: 1000 · required

반입할 회원권 행 목록입니다.

placeId

string · uuid

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

회원권 일괄 반입 › Responses

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

success

boolean

data

POST/space/v1/memberships/import

curl https://api.superplace.so/space/v1/memberships/import \
  --request POST \
  --header 'Content-Type: application/json' \
  --header 'Authorization: Bearer <token>' \
  --data '{
  "source": "우리시스템",
  "items": [
    {
      "phone": "01012345678",
      "name": "홍길동",
      "startsAt": "2026-09-01",
      "endsAt": "2026-09-30"
    }
  ]
}'

Example Request Body

{
  "source": "우리시스템",
  "items": [
    {
      "phone": "01012345678",
      "name": "홍길동",
      "startsAt": "2026-09-01",
      "endsAt": "2026-09-30"
    }
  ]
}

json

application/json

Example Responses

{
  "success": true,
  "data": {
    "imported": 1,
    "skipped": 0,
    "failed": 0,
    "results": [
      {
        "index": 0,
        "status": "imported",
        "phone": "+821012345678",
        "membershipId": "01932b1e-4c3a-7f10-9a2b-5d6e7f800061"
      }
    ]
  }
}

json

application/json

회원권 수정

PATCH

https://api.superplace.so

/space/v1/memberships/{id}

OAuth 2.0

Bearer (JWT)

보낸 항목만 바뀝니다. 기간(startsAt·endsAt), 금액, 발급 근거, 비고를 수정할 수 있습니다. 손님과 전화번호는 바꿀 수 없습니다. 잘못 발급했다면 해지하고 다시 발급하세요.

회원권 수정 › path Parameters

id

string · uuid · required

회원권 ID입니다.

회원권 수정 › Request Body

startsAt

string · date-time

시작 시각입니다.

endsAt

string · date-time

종료 시각입니다.

price

integer

판매가(원)입니다.

issuedRef

string

발급 근거입니다.

memo

string

매장 내부 비고입니다.

회원권 수정 › Responses

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

success

boolean

data

PATCH/space/v1/memberships/{id}

curl https://api.superplace.so/space/v1/memberships/:id \
  --request PATCH \
  --header 'Content-Type: application/json' \
  --header 'Authorization: Bearer <token>' \
  --data '{
  "memo": "연장 협의"
}'

Example Request Body

{
  "memo": "연장 협의"
}

json

application/json

Example Responses

{
  "success": true,
  "data": {
    "id": "01932b1e-4c3a-7f10-9a2b-5d6e7f800061",
    "placeId": "01932b1e-4c3a-7f10-9a2b-5d6e7f800010",
    "phone": "+821000001234",
    "name": "김손님",
    "userId": "01932b1e-4c3a-7f10-9a2b-5d6e7f800003",
    "startsAt": "2026-11-01T00:00:00+09:00",
    "endsAt": "2026-11-30T00:00:00+09:00",
    "status": "active",
    "price": 99000,
    "issuedRef": "",
    "memo": "연장 협의",
    "createdAt": "2026-10-31T06:00:00Z"
  }
}

json

application/json

회원권 해지

POST

https://api.superplace.so

/space/v1/memberships/{id}/cancel

OAuth 2.0

Bearer (JWT)

회원권을 해지합니다. 기록은 삭제되지 않고 남습니다. reason으로 단순 입력 오류 정정과 실제 해지를 구분합니다. 환불은 결제 쪽에서 별도로 처리됩니다.

회원권 해지 › path Parameters

id

string · uuid · required

회원권 ID입니다.

회원권 해지 › Request Body

reason

string

해지 사유입니다.

회원권 해지 › Responses

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

success

boolean

data

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

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

Example Request Body

{
  "reason": "reason"
}

json

Example Responses

{
  "success": true,
  "data": {
    "id": "01932b1e-4c3a-7f10-9a2b-5d6e7f800061",
    "placeId": "01932b1e-4c3a-7f10-9a2b-5d6e7f800010",
    "phone": "+821000001234",
    "name": "김손님",
    "userId": "01932b1e-4c3a-7f10-9a2b-5d6e7f800003",
    "startsAt": "2026-11-01T00:00:00+09:00",
    "endsAt": "2026-11-30T00:00:00+09:00",
    "status": "cancelled",
    "price": 99000,
    "issuedRef": "",
    "memo": "",
    "createdAt": "2026-10-31T06:00:00Z",
    "cancelledAt": "2026-11-12T01:00:00Z",
    "cancelledReason": "환불"
  }
}

json

application/json

회원권 일시정지

POST

https://api.superplace.so

/space/v1/memberships/{id}/hold

OAuth 2.0

Bearer (JWT)

회원권을 일시정지합니다. 정지는 회원권당 하나만 열 수 있고, 재개하면 정지한 기간만큼 종료일이 늘어납니다. 해지됐거나 만료된 회원권은 409입니다.

회원권 일시정지 › path Parameters

id

string · uuid · required

회원권 ID입니다.

회원권 일시정지 › Request Body

reason

string

정지 사유입니다.

회원권 일시정지 › Responses

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

success

boolean

data

POST/space/v1/memberships/{id}/hold

curl https://api.superplace.so/space/v1/memberships/:id/hold \
  --request POST \
  --header 'Content-Type: application/json' \
  --header 'Authorization: Bearer <token>' \
  --data '{
  "reason": "reason"
}'

Example Request Body

{
  "reason": "reason"
}

json

Example Responses

{
  "success": true,
  "data": {
    "id": "01932b1e-4c3a-7f10-9a2b-5d6e7f800061",
    "placeId": "01932b1e-4c3a-7f10-9a2b-5d6e7f800010",
    "phone": "+821000001234",
    "name": "김손님",
    "userId": "01932b1e-4c3a-7f10-9a2b-5d6e7f800003",
    "startsAt": "2026-11-01T00:00:00+09:00",
    "endsAt": "2026-11-30T00:00:00+09:00",
    "status": "active",
    "price": 99000,
    "issuedRef": "",
    "memo": "",
    "createdAt": "2026-10-31T06:00:00Z",
    "heldSince": "2026-11-10T03:00:00Z"
  }
}

json

application/json

회원권 재개

POST

https://api.superplace.so

/space/v1/memberships/{id}/resume

OAuth 2.0

Bearer (JWT)

일시정지를 끝내고 정지한 기간만큼 종료일을 늘립니다. 정지 중이 아니면 409입니다.

회원권 재개 › path Parameters

id

string · uuid · required

회원권 ID입니다.

회원권 재개 › Responses

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

success

boolean

data

예약 문의