Sidetalk사용자 가이드
사이드톡 홈페이지 ↗대시보드 열기

예약 내역 조회 API

목적

이 API는 특정 예약 폼에 등록된 예약 내역을 등록일 기준 최신순으로 조회합니다.
limit과 page를 사용하여 예약 내역을 페이지 단위로 조회할 수 있습니다.

URL

Plain Text
https://api.sidetalk.ai/v1/reservations

HTTP 메서드

Plain Text
GET

헤더

헤더값설명
AuthorizationBearer <api_key>사이드톡 대시보드의 설정 메뉴에서 발급한 API KEY를 사용합니다.

파라미터(Query String)

파라미터타입필수설명
reservationsIdString예조회할 예약 폼의 고유 ID입니다.
limitNumber아니요한 페이지에서 조회할 예약 개수입니다. 기본값은 50입니다.
pageNumber아니요조회할 페이지 번호입니다. 기본값은 1입니다.

요청 예시

최신 예약 10개 조회

Shell
curl -X GET \
  "https://api.sidetalk.ai/v1/reservations?reservationsId=${RESERVATIONS_ID}&limit=10&page=1" \
  -H "Authorization: Bearer ${API_KEY}"

두 번째 페이지 조회

Shell
curl -X GET \
  "https://api.sidetalk.ai/v1/reservations?reservationsId=${RESERVATIONS_ID}&limit=10&page=2" \
  -H "Authorization: Bearer ${API_KEY}"

기본값으로 조회

limit과 page를 생략하면 첫 번째 페이지의 예약 내역을 20개 조회합니다.
Shell
curl -X GET \
  "https://api.sidetalk.ai/v1/reservations?reservationsId=${RESERVATIONS_ID}" \
  -H "Authorization: Bearer ${API_KEY}"

응답 형식

응답은 JSON 형식으로 제공됩니다.
예약 내역은 created_at을 기준으로 최신순으로 반환됩니다.

응답 본문

JavaScript
{
  "success": true,
  "reservations_id": "019e48dc-4f3f-7c9f-9d4f-9b4aa42c2caa",
  "reservations_name": "상담 예약",
  "page": 1,
  "limit": 10,
  "total_count": 25,
  "reservations": [
    {
      "reservation_id": "019e48dc-8a20-72e1-9ab3-0ed7bb45f821",
      "reservation_no": "R202607300001",
      "customer_name": "홍길동",
      "customer_phone": "010-1234-5678",
      "customer_email": "user@example.com",
      "party_size": 2,
      "reservation_date": "2026-08-01",
      "reservation_time": "14:30",
      "request_note": "창가 자리",
      "status": "confirmed",
      "created_at": "2026-07-30T03:00:00.000Z",
      "updated_at": "2026-07-30T03:10:00.000Z"
    }
  ]
}

응답 필드 설명

조회 결과

필드타입설명
successBoolean요청 성공 여부입니다.
reservations_idString조회한 예약 폼의 고유 ID입니다.
reservations_nameString예약 폼의 이름입니다.
pageNumber현재 페이지 번호입니다.
limitNumber페이지당 조회 개수입니다.
total_countNumber해당 예약 폼에 등록된 전체 예약 개수입니다.
reservationsArray조회된 예약 내역 목록입니다.

예약 내역(reservations)

필드타입설명
reservation_idString예약 내역의 고유 ID입니다.
reservation_noString고객에게 발급된 예약번호입니다.
customer_nameString예약자 이름입니다.
customer_phoneString예약자 전화번호입니다.
customer_emailString예약자 이메일입니다.
party_sizeNumber예약 인원입니다.
reservation_dateString예약 날짜입니다. YYYY-MM-DD 형식입니다.
reservation_timeString예약 시간입니다. HH:mm 형식입니다.
statusString예약 상태입니다.
sourceString예약이 등록된 경로입니다.
custom_fieldsObject예약 폼에 추가된 사용자 정의 필드 값입니다.
created_atString예약 내역이 등록된 일시입니다.
updated_atString예약 내역이 마지막으로 수정된 일시입니다.

예약 상태

상태설명
pending예약 접수 또는 승인 대기
confirmed예약 확정
cancelled예약 취소
noshow노쇼 처리
completed예약 완료

예시 코드(JavaScript)

JavaScript
async function getReservations(
    reservationsId,
    limit = 20,
    page = 1
) {
    const baseUrl = "https://api.sidetalk.ai/v1/reservations";

    const params = new URLSearchParams({
        reservationsId,
        limit: String(limit),
        page: String(page)
    });

    try {
        const response = await fetch(
            `${baseUrl}?${params.toString()}`,
            {
                method: "GET",
                headers: {
                    Authorization: "Bearer [API_KEY]"
                }
            }
        );

        const result = await response.json();

        if (!response.ok || !result.success) {
            console.error(
                "Server Error:",
                result.error || "Unknown error"
            );
            return;
        }

        console.log(`현재 페이지: ${result.page}`);
        console.log(`전체 예약 수: ${result.total_count}`);

        result.reservations.forEach((reservation) => {
            console.log(
                `[${reservation.created_at}]`,
                reservation.reservation_no,
                reservation.customer_name,
                reservation.reservation_date,
                reservation.reservation_time
            );
        });

        return result;
    } catch (error) {
        console.error("Error fetching reservations:", error);
    }
}
최신 예약 10개 조회:
JavaScript
getReservations("RESERVATIONS_ID", 10, 1);
두 번째 페이지 조회:
JavaScript
getReservations("RESERVATIONS_ID", 10, 2);

오류 응답

요청 처리 중 오류가 발생하면 다음과 같은 응답이 반환됩니다.
Plain Text
{
  "success": false,
  "error": "Reservation form not found."
}

HTTP 상태 코드

상태 코드설명
200예약 내역 조회 성공
400파라미터가 잘못되었거나 필수값이 누락됨
403API KEY 인증 실패
404예약 폼을 찾을 수 없거나 API KEY가 해당 예약 폼에 접근할 수 없음
500예약 내역 조회 중 서버 오류 발생

주의사항

  • reservationsId는 필수입니다.
  • reservationsId는 UUID 형식이어야 합니다.
  • page의 기본값은 1이며 1 이상의 정수여야 합니다.
  • 예약 내역은 등록일인 created_at을 기준으로 최신순으로 반환됩니다.
  • API KEY가 소유한 사이트의 예약 폼만 조회할 수 있습니다.
  • 다른 사이트의 reservationsId를 요청하면 404 오류가 반환됩니다.
  • 응답에는 고객 이름, 전화번호, 이메일 등 개인정보가 포함될 수 있습니다.
  • API KEY 보호를 위해 브라우저보다 서버에서 이 API를 호출하는 것을 권장합니다.
  • API KEY를 프런트엔드 코드 또는 공개 저장소에 노출하지 마세요.