예약 현황 API — 오늘·내일 예약자를 반오토로

우리끼리 대시보드가 네이버 예약에서 받아 둔 각 지점의 확정 예약을 반오토가 가져가는 API 입니다. 위탁관리 매니저가 "오늘 이 매장에 누가 몇 시에 오는가"를 미리 알 수 있게 하기 위한 것입니다.

한눈에

항목	값
주소	`GET {대시보드}/api/external/bookings.php?date=2026-09-08`
인증	헤더 `X-API-Key: <발급 키>` — 주소(쿼리)에 키를 넣지 않는다
키 발급	대시보드 서버 `.env` 의 `EXTERNAL_BOOKINGS_API_KEYS="반오토:키"` — 관리자 화면 예약 › 예약관리 › 외부 API 탭에서 보기·복사
날짜	`YYYY-MM-DD` 또는 `today` / `tomorrow` / `yesterday` — 과거 60일 ~ 내일
선택	`business_id=797701` 한 지점만 · `include_cancelled=1` 취소된 예약도 포함
기록	모든 호출(거절 포함)이 대시보드 외부 API 탭의 호출 이력에 남음

데이터는 언제 갱신되는가

네이버 예약의 최종 확정은 이용 다음 날 15시에 납니다. 그래서 오늘·내일은 "확정(RC03)" 예약을 미리 보여 주고, 어제는 15:15 에 "이용 완료(RC08)" 기준으로 굳힙니다. 모두 한국시간입니다.

시각	대상	뜻
09:10	오늘	오늘 이용할 확정 예약. 이 시각 이후 읽으면 된다
15:15	오늘	09:10 이후 추가·취소된 예약 반영
15:15	내일	내일 예약 미리보기 — 다음 날 09:10 에 다시 갱신
15:15	어제	이용 완료 기준 최종본

응답의 nextUpdateAt 이 다음 갱신 예정 시각입니다. 그 사이에 다시 불러도 같은 값이 옵니다.

권장 호출

하루 두 번 — 09:15 에 today, 15:20 에 today + tomorrow. 화면을 열 때마다 부르지 말고 받은 값을 들고 있다가 이 시각에 갱신하면 됩니다.

응답

json

{
  "success": true,
  "date": "2026-09-08",
  "collectedAt": "2026-09-08 09:10:12",
  "sourceCollectedAt": "2026-09-08 09:00:41",
  "collectionSlot": "morning",
  "nextUpdateAt": "2026-09-08 15:15:00",
  "totalCount": 24,
  "bookings": [
    {
      "bookingId": "1332959012",
      "bookingStatusCode": "RC03",
      "status": "CONFIRMED",
      "businessId": 797701,
      "businessName": "스포츠마을 천안두정점",
      "businessFullName": "무인키즈카페 우리끼리 스포츠마을 천안두정점",
      "region": "충남",
      "businessType": "가맹",
      "bizItemId": "4723113",
      "bizItemName": "9월 스포츠마을 천안두정점 대관",
      "name": "홍길동",
      "phone": "01012345678",
      "startDateTime": "2026-09-08 10:00:00",
      "endDateTime": "2026-09-08 14:00:00",
      "durationHours": 4,
      "totalPrice": 147000,
      "refundPrice": 0,
      "coupon": { "count": 0, "discount": 0, "freeMinutes": 0 },
      "firstSeenAt": "2026-09-08 09:10:12",
      "lastSeenAt": "2026-09-08 09:10:12",
      "cancelledAt": null
    }
  ]
}

필드	뜻
`collectedAt`	대시보드가 이 날짜를 마지막으로 반영한 시각
`sourceCollectedAt`	수집 서버가 네이버에서 받은 시각 — 이 값이 오래됐으면 수집 쪽 문제
`collectionSlot`	`morning` 09:10 · `afternoon` 15:15 오늘 갱신 · `preview` 내일 미리보기 · `final` 어제 최종 · `manual` 관리자 수동
`status`	`CONFIRMED` 확정(오늘·내일) · `COMPLETED` 이용 완료(어제 이전) · `CANCELLED` 이전 수집엔 있었으나 사라짐 — `include_cancelled=1` 일 때만
`businessId`	네이버 businessId. 반오토 매장과 맞출 때 이 값을 쓴다 (이름은 바뀔 수 있다)
`firstSeenAt` / `lastSeenAt`	처음 확인된 수집 · 마지막으로 확인된 수집. 15:15 갱신에서 새로 들어온 예약은 `firstSeenAt` 이 15:15
`cancelledAt`	사라진 것을 확인한 수집 시각

시각은 모두 한국시간 YYYY-MM-DD HH:MM:SS 입니다. name · phone 은 개인정보이므로 반오토 쪽에서도 필요한 화면에만 보여 주고 따로 저장하지 않는 것이 좋습니다.

오류

코드	뜻	대응
`401`	키가 없거나 틀림	헤더 이름 `X-API-Key` · 키 값 확인
`400`	날짜 형식·범위 오류	응답 `message` 참고 (과거 60일 ~ 내일)
`200` 인데 `totalCount: 0` 이고 `collectedAt: null`	아직 그 날짜를 수집하지 않음	`nextUpdateAt` 뒤에 다시

대시보드에서 보는 곳 — 예약관리

관리자 화면 사이드 메뉴 예약 › 예약관리. 반오토가 받는 것과 같은 데이터를 지점별로 보여 줍니다.

예약 현황 — 날짜(어제·오늘·내일·직접 지정)·지역·타입·검색으로 거르고, 지점별로 시간·예약자·연락처·상품·결제·쿠폰·상태를 본다. 「추가」는 15:15 갱신에서 새로 들어온 예약, 「취소」는 사라진 예약. 위의 「시간대별 이용 중인 예약」 막대는 그 시간에 매장에 있는 예약 수.
지금 수집 — 자동 수집이 빠졌거나 방금 확정된 예약을 바로 보고 싶을 때. 같은 날짜를 여러 번 수집해도 안전하다.
수집 이력 — 09:10·15:15 자동 수집과 수동 수집의 결과(신규·변경·취소·복원 건수, 실패 사유).
외부 API — 이 문서의 요약, 발급된 키 보기·복사, 반오토 호출 이력.

수집이 실패하면 담당자 휴대폰으로 문자가 갑니다(스탬프 수집 실패 문자와 같은 번호). 원인을 없앤 뒤 예약관리 화면에서 「지금 수집」을 누르면 됩니다.

스탬프 이벤트와는 다른 표

같은 수집 서버를 쓰지만, 스탬프 이벤트는 어제 이용 완료 예약만 다루고 예약관리는 아직 이용 전인 확정 예약을 다룹니다. 두 데이터는 서로 다른 표에 있고, 예약관리 쪽 수집이 실패해도 스탬프 지급에는 영향이 없습니다(반대도 마찬가지).

예약 현황 API — 오늘·내일 예약자를 반오토로 ​

한눈에 ​

데이터는 언제 갱신되는가 ​

응답 ​

오류 ​

대시보드에서 보는 곳 — 예약관리 ​

예약 현황 API — 오늘·내일 예약자를 반오토로

한눈에

데이터는 언제 갱신되는가

응답

오류

대시보드에서 보는 곳 — 예약관리