매출

결제 내역과 매출 요약, 기간별 매출 추이를 조회합니다.

결제 목록 조회

GET

https://api.superplace.so

/pay/v1/payments

OAuth 2.0

결제 내역과 상태를 돌려줍니다. 조회만 가능합니다. 기본은 최신순이고 page·perPage(기본 20)로 넘깁니다. q로 결제자 이름, 전화번호, 원천 번호를 검색하고 filter로 상태와 수단, 기간을 좁힙니다. 금액은 원 단위 정수입니다.

필요 권한: 결제 건별 내역 보기(pay:payments:read)

MCP 도구: pay_get_payments

결제 목록 조회 › 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입니다. payerName은 결제자 이름 순이고, 이름이 없으면 전화번호로 정렬합니다.

Enum values:

createdAt

effectiveAt

amount

payerName

Default: createdAt

order

string · enum

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

Enum values:

asc

desc

Default: desc

q

string

결제자 이름, 전화번호, 원천 번호에서 찾을 검색어입니다.

filter

string

조건 JSON입니다. status(awaiting, paid, rejected, expired), source, method(cash, van, pg, transfer, wallet, manual), currency, effectiveAt({"gte":…,"lt":…}), refundAmount·walletAmount·discount({"gt":0})를 쓸 수 있습니다. id와 sourceRef는 목록(in, 최대 200개)으로 보낼 수 있습니다.

결제 목록 조회 › Responses

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

success

boolean · enum · required

Enum values:

object[] · required

total

integer · min: 0 · required

GET/pay/v1/payments

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

Example Responses

{
  "success": true,
  "data": [
    {
      "id": "01932b1e-4c3a-7f10-9a2b-5d6e7f800101",
      "placeId": "01932b1e-4c3a-7f10-9a2b-5d6e7f800010",
      "source": "space.reservation",
      "sourceRef": "01932b1e-4c3a-7f10-9a2b-5d6e7f800051",
      "method": "pg",
      "status": "paid",
      "amount": 20000,
      "currency": "KRW",
      "phone": "+821000001234",
      "payerName": "김손님",
      "createdAt": "2026-11-01T02:00:00Z",
      "effectiveAt": "2026-11-01T02:01:00Z",
      "refundAmount": 0,
      "discount": 0,
      "walletAmount": 0
    }
  ],
  "total": 1
}

json

application/json

매출 요약 조회

GET

https://api.superplace.so

/pay/v1/reports/sales

OAuth 2.0

기간의 확정 결제 매출 합계를 돌려줍니다. 기간을 보내지 않으면 최근 30일입니다. 응답에는 합계(totals), 날짜별(byDay), 결제 수단별(byMethod), 매장별(byPlace)이 담기고 각 줄에 건수, 취소 건수, 총액(gross), 할인, 선불 사용, 환불, 순매출(net), 공급가액, 부가세가 있습니다. 선불 충전 결제는 제외됩니다.

필요 권한: 매출 합계 보기(pay:sales:read)

MCP 도구: pay_get_reports_sales

매출 요약 조회 › query Parameters

scope

string · enum

플랫폼 운영 계정 전용 값입니다. 매장·조직 계정에서는 사용하지 않습니다.

Enum values:

all

filter

string

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

from

string · date

시작 날짜입니다. 매장 기준 날짜이고 이 날짜를 포함합니다. 생략하면 to의 29일 전입니다.

to

string · date

끝 날짜입니다. 매장 기준 날짜이고 이 날짜를 포함합니다. 생략하면 오늘입니다.

tz

string

날짜를 나누는 시간대입니다. 기본은 Asia/Seoul입니다.

Default: Asia/Seoul

매출 요약 조회 › Responses

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

success

boolean

data

GET/pay/v1/reports/sales

curl https://api.superplace.so/pay/v1/reports/sales \
  --header 'Authorization: Bearer <token>'

Example Responses

{
  "success": true,
  "data": {
    "from": "2026-10-04",
    "to": "2026-11-02",
    "placeIds": [
      "01932b1e-4c3a-7f10-9a2b-5d6e7f800010"
    ],
    "totals": [
      {
        "currency": "KRW",
        "count": 120,
        "cancelCount": 3,
        "gross": 2400000,
        "discount": 50000,
        "wallet": 100000,
        "refund": 60000,
        "net": 2290000,
        "supply": 2081818,
        "vat": 208182
      }
    ],
    "byDay": [
      {
        "date": "2026-11-02",
        "currency": "KRW",
        "count": 4,
        "cancelCount": 0,
        "gross": 80000,
        "discount": 0,
        "wallet": 0,
        "refund": 0,
        "net": 80000,
        "supply": 72727,
        "vat": 7273
      }
    ],
    "byMethod": [
      {
        "method": "pg",
        "currency": "KRW",
        "count": 80,
        "cancelCount": 2,
        "gross": 1600000,
        "discount": 30000,
        "wallet": 0,
        "refund": 40000,
        "net": 1530000,
        "supply": 1390909,
        "vat": 139091
      }
    ],
    "byPlace": [
      {
        "placeId": "01932b1e-4c3a-7f10-9a2b-5d6e7f800010",
        "currency": "KRW",
        "count": 120,
        "cancelCount": 3,
        "gross": 2400000,
        "discount": 50000,
        "wallet": 100000,
        "refund": 60000,
        "net": 2290000,
        "supply": 2081818,
        "vat": 208182
      }
    ]
  }
}

json

application/json

매출 추이 조회

GET

https://api.superplace.so

/pay/v1/reports/sales-trend

OAuth 2.0

기간의 확정 결제 매출을 날짜, 주, 월 단위로 묶어 돌려줍니다. 합계(totals)에는 객단가(avgTicket)가 있고, 시간대별(byHour), 발생 원천별(bySource), 결제 수단별(byMethod) 집계와 선불권 판매 원금(passSales)이 함께 담깁니다. 순매출(net)은 총액에 선불 사용분을 더하고 환불을 뺀 값입니다.

필요 권한: 매출 합계 보기(pay:sales:read)

MCP 도구: pay_get_reports_sales_trend

매출 추이 조회 › query Parameters

from

string · date

시작 날짜입니다. 매장 기준 날짜이고 이 날짜를 포함합니다. 생략하면 to의 29일 전입니다.

to

string · date

끝 날짜입니다. 매장 기준 날짜이고 이 날짜를 포함합니다. 생략하면 오늘입니다.

bucket

string · enum

묶는 단위입니다. day(기본), week, month 중 하나입니다.

Enum values:

day

week

month

Default: day

tz

string

날짜를 나누는 시간대입니다. 기본은 Asia/Seoul입니다. 묶음의 경계가 이 시간대로 정해집니다.

Default: Asia/Seoul

filter

string

조건 JSON입니다. 매장 하나로 좁히려면 {"placeId":"…"}를 보냅니다. 생략하면 조직 계정은 닿는 모든 매장을 합칩니다.

매출 추이 조회 › Responses

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

success

boolean

data

GET/pay/v1/reports/sales-trend

curl https://api.superplace.so/pay/v1/reports/sales-trend \
  --header 'Authorization: Bearer <token>'

Example Responses

{
  "success": true,
  "data": {
    "from": "2026-10-04",
    "to": "2026-11-02",
    "bucket": "day",
    "timezone": "Asia/Seoul",
    "totals": [
      {
        "currency": "KRW",
        "count": 120,
        "gross": 2400000,
        "refunded": 60000,
        "wallet": 100000,
        "discount": 50000,
        "net": 2440000,
        "avgTicket": 20833
      }
    ],
    "series": [
      {
        "bucket": "2026-11-02",
        "currency": "KRW",
        "count": 4,
        "gross": 80000,
        "refunded": 0,
        "wallet": 0,
        "discount": 0,
        "net": 80000
      }
    ],
    "bySource": [
      {
        "source": "space.reservation",
        "currency": "KRW",
        "count": 100,
        "gross": 2000000,
        "refunded": 50000,
        "wallet": 0,
        "discount": 0,
        "net": 1950000
      }
    ],
    "byMethod": [
      {
        "method": "pg",
        "currency": "KRW",
        "count": 80,
        "gross": 1600000,
        "refunded": 40000,
        "wallet": 0,
        "discount": 0,
        "net": 1560000
      }
    ],
    "byHour": [
      {
        "hour": 14,
        "currency": "KRW",
        "count": 12,
        "gross": 240000,
        "refunded": 0,
        "net": 240000,
        "wallet": 0,
        "discount": 0
      }
    ],
    "passSales": [],
    "generatedAt": "2026-11-03T00:00:00Z"
  }
}

json

application/json

메시지 상품