예약 내역 조회 API
목적
이 API는 특정 예약 폼에 등록된 예약 내역을 등록일 기준 최신순으로 조회합니다.
limit과 page를 사용하여 예약 내역을 페이지 단위로 조회할 수 있습니다.URL
Plain Text
https://api.sidetalk.ai/v1/reservationsHTTP 메서드
Plain Text
GET헤더
| 헤더 | 값 | 설명 |
|---|---|---|
| Authorization | Bearer <api_key> | 사이드톡 대시보드의 설정 메뉴에서 발급한 API KEY를 사용합니다. |
파라미터(Query String)
| 파라미터 | 타입 | 필수 | 설명 |
|---|---|---|---|
| reservationsId | String | 예 | 조회할 예약 폼의 고유 ID입니다. |
| limit | Number | 아니요 | 한 페이지에서 조회할 예약 개수입니다. 기본값은 50입니다. |
| page | Number | 아니요 | 조회할 페이지 번호입니다. 기본값은 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"
}
]
}응답 필드 설명
조회 결과
| 필드 | 타입 | 설명 |
|---|---|---|
| success | Boolean | 요청 성공 여부입니다. |
| reservations_id | String | 조회한 예약 폼의 고유 ID입니다. |
| reservations_name | String | 예약 폼의 이름입니다. |
| page | Number | 현재 페이지 번호입니다. |
| limit | Number | 페이지당 조회 개수입니다. |
| total_count | Number | 해당 예약 폼에 등록된 전체 예약 개수입니다. |
| reservations | Array | 조회된 예약 내역 목록입니다. |
예약 내역(reservations)
| 필드 | 타입 | 설명 |
|---|---|---|
| reservation_id | String | 예약 내역의 고유 ID입니다. |
| reservation_no | String | 고객에게 발급된 예약번호입니다. |
| customer_name | String | 예약자 이름입니다. |
| customer_phone | String | 예약자 전화번호입니다. |
| customer_email | String | 예약자 이메일입니다. |
| party_size | Number | 예약 인원입니다. |
| reservation_date | String | 예약 날짜입니다. YYYY-MM-DD 형식입니다. |
| reservation_time | String | 예약 시간입니다. HH:mm 형식입니다. |
| status | String | 예약 상태입니다. |
| source | String | 예약이 등록된 경로입니다. |
| custom_fields | Object | 예약 폼에 추가된 사용자 정의 필드 값입니다. |
| created_at | String | 예약 내역이 등록된 일시입니다. |
| updated_at | String | 예약 내역이 마지막으로 수정된 일시입니다. |
예약 상태
| 상태 | 설명 |
|---|---|
| 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 | 파라미터가 잘못되었거나 필수값이 누락됨 |
| 403 | API KEY 인증 실패 |
| 404 | 예약 폼을 찾을 수 없거나 API KEY가 해당 예약 폼에 접근할 수 없음 |
| 500 | 예약 내역 조회 중 서버 오류 발생 |
주의사항
reservationsId는 필수입니다.reservationsId는 UUID 형식이어야 합니다.page의 기본값은1이며 1 이상의 정수여야 합니다.- 예약 내역은 등록일인
created_at을 기준으로 최신순으로 반환됩니다. - API KEY가 소유한 사이트의 예약 폼만 조회할 수 있습니다.
- 다른 사이트의
reservationsId를 요청하면404오류가 반환됩니다. - 응답에는 고객 이름, 전화번호, 이메일 등 개인정보가 포함될 수 있습니다.
- API KEY 보호를 위해 브라우저보다 서버에서 이 API를 호출하는 것을 권장합니다.
- API KEY를 프런트엔드 코드 또는 공개 저장소에 노출하지 마세요.
