API 레퍼런스

매장 검색

키워드·지역·카테고리·신뢰도로 정제된 매장(원셋)을 검색합니다. 기본 정렬은 discovery(질의 적합·최신성·교차검증·완성도를 함께 보는 추천 정렬)이며 페이지네이션됩니다. fields로 받을 필드를 고르세요.

인증 필요 (Bearer / X-API-Key 헤더 권장)

파라미터

• keywordstring선택상호·주소·메뉴명 부분검색 · 예시: 버거킹
• region_codestring선택행정동 코드
• business_categorystring선택카테고리(restaurant/cafe…) · 예시: restaurant
• min_confidencenumber선택최소 신뢰도(0~1) · 예시: 0.6
• sortstring선택discovery(기본·유일) — 추천 정렬. 좌표가 없어 distance는 쓸 수 없습니다. 응답 meta.sort는 '실제로 적용된' 정렬이라 넓은 검색에서는 reviews로 낮아질 수 있습니다. · 예시: discovery
• recommended_forstring선택상황으로 좁히기(콤마, 모두 포함). 자연어도 해석됨: 회식→group_dining, 혼밥→solo_dining, 상견례→formal_gathering. 값: solo_dining·date·group_dining·family·business_meeting·formal_gathering·late_night 등. 전체·별칭은 /api/v1/meta. · 예시: group_dining
• atmospherestring선택분위기(콤마). quiet·lively·view·cozy·trendy·spacious·traditional·clean·work_study·rainy_mood. 조용한→quiet 같은 자연어도 해석. · 예시: quiet
• parkingboolean선택주차 확인된 곳만. 세부 유형은 parking_type. · 예시: true
• parking_typestring선택주차 유형: onsite·valet·partner·nearby·none. 발렛→valet 등 자연어 해석. · 예시: onsite
• reservableboolean선택예약 가능한 곳만(크롤 확인 + 유미 파트너 매장 포함). · 예시: true
• payment_methodsstring선택결제수단 모두 포함(콤마). cash·card·naver_pay·kakao_pay·toss_pay·zero_pay·alipay·wechat_pay 등. · 예시: alipay
• servesstring선택제공 품목(콤마). coffee·alcohol·dessert·vegetarian·vegan. · 예시: alcohol
• dietarystring선택식단(콤마). vegan_options·vegetarian_options·fully_vegan·mixed_group_suitable. 자연어도 해석(비건/vegan/plant-based→vegan_options, 채식/vegetarian→vegetarian_options, 혼합식단/mixed→mixed_group_suitable). '비건 친구랑 같이 먹을 곳'은 mixed_group_suitable — 비건 '식사'가 확인된 곳만 걸린다(비건 음료뿐인 카페는 제외). · 예시: vegan_options
• foreign_languagesstring선택외국어 응대 가능 언어(ISO 639-1, 콤마·모두 포함). en·zh·ja·es·de·fr. 사장님이 확인한 값. '영어→en, 일본어→ja' 같은 자연어도 해석. 예: 외국인 손님용 '영어 되는 곳'. · 예시: en
• pet_friendlyboolean선택그 밖의 boolean presence 필터의 예. 파라미터만 붙이면 =true(있다고 확인된 곳만). 지원 목록 전체(wifi·private_room·outdoor_seating·group_friendly·takeout·delivery·corkage_free·has_promotion 등)는 /api/v1/meta의 filters.boolean. · 예시: true
• open_atstring선택그 시각(또는 그 시간대)에 영업하는 곳만(한국시간). 한 시각: 2026-08-26T19:00 · '2026-08-26 19:00' · '19:00'(오늘) · 'now'. 식사 시간대: 'lunch'·'점심'(11:00~14:00) · 'dinner'·'저녁'(17:30~21:00) · breakfast · brunch · late_night, 직접 범위 '11:00-14:00', 날짜와 조합 '2026-08-29 lunch'. 상대 날짜는 오늘·내일·모레(today/tomorrow)만 해석합니다(그 밖은 절대 날짜로 보내세요). 시간대는 그 구간에 **일부라도** 영업하면 통과하며 응답 meta.openAt.window로 해석한 범위를 돌려줍니다. 정기 영업시간·라스트오더·브레이크타임 기준이며 자정 넘김 영업도 처리합니다. 임시휴무·만석은 알 수 없습니다. 영업시간이 확인되지 않은 매장은 기본 제외되고 meta.openAt.unknownHoursExcluded로 알립니다. · 예시: 2026-08-26T19:00
• include_unknown_hoursboolean선택open_at 전용 탈출구. true면 영업시간이 확인되지 않은 매장도 함께 반환합니다(그 매장은 '그 시각에 영업한다'가 아니라 '모름'입니다). · 예시: true
• reservation_channelstring선택예약 경로(콤마 = OR): yumi(유미 API로 바로 예약 — POST /api/v1/reservations) · external(외부 예약 링크) · phone(전화). '예약을 받는다'와 '그 시각에 자리가 있다'는 다른 문제입니다 — 실제 좌석 가능 여부는 예약 요청으로만 확인됩니다. · 예시: yumi
• fieldsstring선택받을 필드 선택(Field Mask). 콤마 구분 · 등급명(core/contact_hours/quality/edge/media)·all·개별 필드명. 미지정 시 core. 호출 토큰 = 요청 필드 중 최고 등급(요청당 과금, page_size 무관). 사장님 업로드 사진은 photos(media, 최상위 단가 8 — 매장·메뉴 이미지 URL)로 받고, 목록에선 photoCount(quality)로 개수만 싸게 볼 수 있습니다. recommendedFor에는 solo_dining, late_night, late_night_eatery 같은 상황 태그가 포함될 수 있습니다. · 예시: core,rating,accessHints
• pageinteger선택페이지(기본 1) · 예시: 1
• page_sizeinteger선택페이지당 개수(최대 100). 토큰에 영향 없음(요청당 과금). 일반 API는 최대 5,000개 결과창까지만 접근하며, 그 이상은 Bulk Export. · 예시: 20

응답 예시

{
  "success": true,
  "data": [
    {
      "id": "11892345",
      "name": "콩부자 홍제점",
      "category": "restaurant",
      "categoryLabel": "국밥",
      "location": {
        "lat": 37.5891,
        "lng": 126.9436
      },
      "address": {
        "road": "서울 서대문구 통일로 450",
        "jibun": "서울 서대문구 홍제동 330"
      },
      "regionCode": "1141011100",
      "confidence": 0.64,
      "sourceCount": 2,
      "possiblyClosed": false,
      "lastSeenAt": "2026-06-18T03:00:00.000Z"
    }
  ],
  "meta": {
    "total": 5,
    "page": 1,
    "pageSize": 20,
    "totalPages": 1
  }
}

주변 검색

좌표(lat·lng)와 반경(m)으로 주변 매장을 가까운 순으로 찾습니다. 각 결과에 distanceM(중심으로부터 거리)이 붙습니다. sort=discovery면 반경 안에서 추천 정렬로 바뀝니다. fields/토큰은 매장 검색과 동일.

인증 필요 (Bearer / X-API-Key 헤더 권장)

파라미터

• latnumber필수위도 · 예시: 37.5704
• lngnumber필수경도 · 예시: 126.9921
• radiusinteger선택반경 m(기본 1000, 최대 5000) · 예시: 500
• business_categorystring선택카테고리 필터 · 예시: cafe
• keywordstring선택상호·주소·메뉴명 부분검색
• sortstring선택distance(기본·가까운 순) 또는 discovery(반경 안에서 추천 정렬). '내 근처 가장 가까운'은 distance, '이 근처 괜찮은 곳'은 discovery. 응답 meta.sort는 실제로 적용된 정렬입니다(깊은 페이지·넓은 반경에서는 distance로 낮아질 수 있음). · 예시: discovery
• recommended_forstring선택상황으로 좁히기(콤마, 모두 포함). 자연어도 해석됨: 회식→group_dining, 혼밥→solo_dining, 상견례→formal_gathering. 값: solo_dining·date·group_dining·family·business_meeting·formal_gathering·late_night 등. 전체·별칭은 /api/v1/meta. · 예시: group_dining
• atmospherestring선택분위기(콤마). quiet·lively·view·cozy·trendy·spacious·traditional·clean·work_study·rainy_mood. 조용한→quiet 같은 자연어도 해석. · 예시: quiet
• parkingboolean선택주차 확인된 곳만. 세부 유형은 parking_type. · 예시: true
• parking_typestring선택주차 유형: onsite·valet·partner·nearby·none. 발렛→valet 등 자연어 해석. · 예시: onsite
• reservableboolean선택예약 가능한 곳만(크롤 확인 + 유미 파트너 매장 포함). · 예시: true
• payment_methodsstring선택결제수단 모두 포함(콤마). cash·card·naver_pay·kakao_pay·toss_pay·zero_pay·alipay·wechat_pay 등. · 예시: alipay
• servesstring선택제공 품목(콤마). coffee·alcohol·dessert·vegetarian·vegan. · 예시: alcohol
• dietarystring선택식단(콤마). vegan_options·vegetarian_options·fully_vegan·mixed_group_suitable. 자연어도 해석(비건/vegan/plant-based→vegan_options, 채식/vegetarian→vegetarian_options, 혼합식단/mixed→mixed_group_suitable). '비건 친구랑 같이 먹을 곳'은 mixed_group_suitable — 비건 '식사'가 확인된 곳만 걸린다(비건 음료뿐인 카페는 제외). · 예시: vegan_options
• foreign_languagesstring선택외국어 응대 가능 언어(ISO 639-1, 콤마·모두 포함). en·zh·ja·es·de·fr. 사장님이 확인한 값. '영어→en, 일본어→ja' 같은 자연어도 해석. 예: 외국인 손님용 '영어 되는 곳'. · 예시: en
• pet_friendlyboolean선택그 밖의 boolean presence 필터의 예. 파라미터만 붙이면 =true(있다고 확인된 곳만). 지원 목록 전체(wifi·private_room·outdoor_seating·group_friendly·takeout·delivery·corkage_free·has_promotion 등)는 /api/v1/meta의 filters.boolean. · 예시: true
• open_atstring선택그 시각(또는 그 시간대)에 영업하는 곳만(한국시간). 한 시각: 2026-08-26T19:00 · '2026-08-26 19:00' · '19:00'(오늘) · 'now'. 식사 시간대: 'lunch'·'점심'(11:00~14:00) · 'dinner'·'저녁'(17:30~21:00) · breakfast · brunch · late_night, 직접 범위 '11:00-14:00', 날짜와 조합 '2026-08-29 lunch'. 상대 날짜는 오늘·내일·모레(today/tomorrow)만 해석합니다(그 밖은 절대 날짜로 보내세요). 시간대는 그 구간에 **일부라도** 영업하면 통과하며 응답 meta.openAt.window로 해석한 범위를 돌려줍니다. 정기 영업시간·라스트오더·브레이크타임 기준이며 자정 넘김 영업도 처리합니다. 임시휴무·만석은 알 수 없습니다. 영업시간이 확인되지 않은 매장은 기본 제외되고 meta.openAt.unknownHoursExcluded로 알립니다. · 예시: 2026-08-26T19:00
• include_unknown_hoursboolean선택open_at 전용 탈출구. true면 영업시간이 확인되지 않은 매장도 함께 반환합니다(그 매장은 '그 시각에 영업한다'가 아니라 '모름'입니다). · 예시: true
• reservation_channelstring선택예약 경로(콤마 = OR): yumi(유미 API로 바로 예약 — POST /api/v1/reservations) · external(외부 예약 링크) · phone(전화). '예약을 받는다'와 '그 시각에 자리가 있다'는 다른 문제입니다 — 실제 좌석 가능 여부는 예약 요청으로만 확인됩니다. · 예시: yumi
• fieldsstring선택받을 필드 선택(Field Mask). 콤마 구분 · 등급명(core/contact_hours/quality/edge/media)·all·개별 필드명. 미지정 시 core. 호출 토큰 = 요청 필드 중 최고 등급(요청당 과금, page_size 무관). 사장님 업로드 사진은 photos(media, 최상위 단가 8 — 매장·메뉴 이미지 URL)로 받고, 목록에선 photoCount(quality)로 개수만 싸게 볼 수 있습니다. recommendedFor에는 solo_dining, late_night, late_night_eatery 같은 상황 태그가 포함될 수 있습니다. · 예시: core,rating,accessHints
• pageinteger선택페이지(기본 1) · 예시: 1
• page_sizeinteger선택페이지당 개수(최대 100). 토큰에 영향 없음(요청당 과금). 일반 API는 최대 5,000개 결과창까지만 접근하며, 그 이상은 Bulk Export. · 예시: 20

응답 예시

{
  "success": true,
  "data": [
    {
      "id": "11892345",
      "name": "콩부자 홍제점",
      "category": "restaurant",
      "categoryLabel": "국밥",
      "location": {
        "lat": 37.5891,
        "lng": 126.9436
      },
      "address": {
        "road": "서울 서대문구 통일로 450",
        "jibun": "서울 서대문구 홍제동 330"
      },
      "regionCode": "1141011100",
      "confidence": 0.64,
      "sourceCount": 2,
      "possiblyClosed": false,
      "lastSeenAt": "2026-06-18T03:00:00.000Z",
      "distanceM": 0
    }
  ],
  "meta": {
    "total": 12,
    "page": 1,
    "pageSize": 20,
    "totalPages": 1,
    "center": {
      "lat": 37.5704,
      "lng": 126.9921
    },
    "radius": 500
  }
}

매장 상세

단일 매장. fields로 필요한 등급만 받으세요(fields=all 시 영업시간·메뉴·접근성·추천맥락까지 전부).

인증 필요 (Bearer / X-API-Key 헤더 권장)

파라미터

• idstring필수매장 ID(canonical) · 예시: 11782345
• fieldsstring선택받을 필드 선택(Field Mask). 콤마 구분 · 등급명(core/contact_hours/quality/edge/media)·all·개별 필드명. 미지정 시 core. 호출 토큰 = 요청 필드 중 최고 등급(요청당 과금, page_size 무관). 사장님 업로드 사진은 photos(media, 최상위 단가 8 — 매장·메뉴 이미지 URL)로 받고, 목록에선 photoCount(quality)로 개수만 싸게 볼 수 있습니다. recommendedFor에는 solo_dining, late_night, late_night_eatery 같은 상황 태그가 포함될 수 있습니다. · 예시: core,rating,accessHints

응답 예시

{
  "success": true,
  "data": {
    "id": "11892345",
    "name": "콩부자 홍제점",
    "category": "restaurant",
    "categoryLabel": "국밥",
    "location": {
      "lat": 37.5891,
      "lng": 126.9436
    },
    "address": {
      "road": "서울 서대문구 통일로 450",
      "jibun": "서울 서대문구 홍제동 330"
    },
    "regionCode": "1141011100",
    "confidence": 0.64,
    "sourceCount": 2,
    "possiblyClosed": false,
    "lastSeenAt": "2026-06-18T03:00:00.000Z",
    "rating": null,
    "reviewCount": 10731,
    "latestReviewDate": "2026-06-15",
    "freshnessScore": 0.82,
    "dataQuality": {
      "veracity": 5,
      "completeness": 1,
      "confidence": 0.64,
      "recency": 0.99,
      "last_verified_days_ago": 4
    },
    "price": {
      "level": 2,
      "avg": 8000,
      "min": 4500,
      "max": 12000
    },
    "menuSummary": {
      "count": 12,
      "items": [
        "콩나물국밥",
        "수육",
        "모둠전"
      ]
    },
    "openNow": {
      "open": true,
      "reason": "open",
      "lastOrderPassed": false
    },
    "closureSignal": null,
    "promotion": null,
    "nearestStation": {
      "station": "홍제",
      "walkMin": 5
    },
    "photoCount": 5,
    "photos": {
      "count": 5,
      "main": "https://<supabase>/storage/v1/object/public/owner-photos/<uid>/11892345/1718000000000.jpg",
      "gallery": [
        {
          "category": "interior",
          "url": "https://<supabase>/storage/v1/object/public/owner-photos/<uid>/11892345/1718000000000.jpg",
          "isMain": true
        },
        {
          "category": "exterior",
          "url": "https://<supabase>/storage/v1/object/public/owner-photos/<uid>/11892345/1718000000001.jpg",
          "isMain": false
        }
      ],
      "menu": [
        {
          "menuItem": "콩나물국밥",
          "url": "https://<supabase>/storage/v1/object/public/owner-photos/<uid>/11892345/1718000000002.jpg"
        }
      ],
      "menuBoard": [
        "https://<supabase>/storage/v1/object/public/owner-photos/<uid>/11892345/1718000000003.jpg"
      ]
    },
    "phone": "02-123-4567",
    "homepage": null,
    "bookingUrl": null,
    "yumiReservable": false,
    "reservationChannels": [
      "phone"
    ],
    "snsLinks": null,
    "businessHours": [
      {
        "day": "mon",
        "closed": false,
        "open": "00:00",
        "close": "24:00",
        "endsNextDay": false,
        "breaks": [],
        "lastOrder": null
      }
    ],
    "is24h": true,
    "accessHints": {
      "subway": [
        {
          "station": "홍제",
          "lines": [
            "3호선"
          ],
          "distanceM": 360,
          "walkMin": 5
        },
        {
          "station": "무악재",
          "lines": [
            "3호선"
          ],
          "distanceM": 920,
          "walkMin": 13
        }
      ]
    },
    "recommendedFor": [
      "solo_dining",
      "late_night",
      "late_night_eatery"
    ],
    "atmosphere": [
      "캐주얼",
      "빠른"
    ],
    "menu": [
      {
        "name": "콩나물국밥",
        "price": 8000,
        "recommend": true,
        "isNew": false,
        "description": "24시간 끓인 진한 국물에 아삭한 콩나물."
      },
      {
        "name": "매생이굴국밥",
        "price": 9500,
        "recommend": false,
        "isNew": true
      }
    ],
    "serviceAttributes": {
      "parking": true,
      "parking_type": "onsite",
      "parking_fee": "paid",
      "parking_note": "매장 주차 가능(유료)",
      "dine_in": true,
      "reservable": true,
      "foreign_languages": [
        "en"
      ],
      "dietary": {
        "fully_vegan": false,
        "vegan_options": true,
        "vegetarian_options": true,
        "mixed_group_suitable": true,
        "vegan_menu_count": 3,
        "vegan_main_count": 2,
        "non_vegan_menu_count": 8,
        "confidence": 0.62,
        "note": "비건 메뉴와 일반 메뉴가 함께 있어 비건과 비(非)비건이 같이 가기 좋아요. 조리 분리는 확인이 필요해요."
      }
    },
    "atmosphereScores": {
      "late_night": 6,
      "late_night_eatery": 8,
      "quiet": 6.5,
      "lively": 4
    },
    "aiSummary": "홍제역 근처 캐주얼 국밥집, 혼밥·심야식당 수요에 적합."
  }
}

매장 시계열

일자별 평점·활동 최신성(freshnessScore) 추이(스냅샷 누적). 매장 활동량 변화를 직접 판단할 수 있는 재료입니다.

인증 필요 (Bearer / X-API-Key 헤더 권장)

파라미터

• idstring필수매장 ID(canonical) · 예시: 11782345

응답 예시

{
  "success": true,
  "data": [
    {
      "date": "2026-06-18",
      "reviewCount": 10731,
      "rating": null,
      "latestReviewDate": "2026-06-15",
      "freshnessScore": 0.82
    }
  ]
}

지역 조회 · 동네 이름 해석

동네 이름을 코드·좌표로 풀어줍니다(좌표가 없을 때의 위치 해석). 동 이름은 유일하지 않아(예: 홍제동=서울 서대문구 + 강원 강릉) 후보 목록을 시도/시군구로 구분해 매장수·대표좌표(center)와 함께 돌려줍니다. 고른 후보의 center로 /places/nearby 반경검색을 돌리면 인접 동네까지 커버됩니다. dong 없이 호출하면 매장 보유 지역 전체.

인증 필요 (Bearer / X-API-Key 헤더 권장)

파라미터

• dongstring선택동네 이름(예: 홍제동) — 후보들을 반환 · 예시: 홍제동
• sigungustring선택시군구로 후보 좁히기(예: 서대문구)
• sidostring선택시도로 후보 좁히기(예: 서울특별시)
• region_codestring선택특정 지역코드 단건 조회
• include_emptyboolean선택매장 0인 미수집 지역도 포함(기본 false)

응답 예시

{
  "success": true,
  "data": [
    {
      "regionCode": "1141011100",
      "sido": "서울특별시",
      "sigungu": "서대문구",
      "dong": "홍제동",
      "fullName": "서울특별시 서대문구 홍제동",
      "center": {
        "lat": 37.577976,
        "lng": 126.938483
      },
      "placeCount": 280
    }
  ]
}

카테고리 목록

원셋 보유 카테고리별 매장 수.

인증 필요 (Bearer / X-API-Key 헤더 권장)

파라미터

파라미터 없음

응답 예시

{
  "success": true,
  "data": [
    {
      "category": "restaurant",
      "count": 82140
    }
  ]
}

데이터 통계

전체 매장 수·지역 수·멀티소스 비율·평균 신뢰도·카테고리 분포.

인증 필요 (Bearer / X-API-Key 헤더 권장)

파라미터

파라미터 없음

응답 예시

{
  "success": true,
  "data": {
    "totalPlaces": 143027,
    "totalRegions": 512,
    "multiSourcePlaces": 70118,
    "avgConfidence": 0.72,
    "byCategory": [
      {
        "category": "restaurant",
        "count": 82140
      },
      {
        "category": "cafe",
        "count": 51730
      },
      {
        "category": "bar",
        "count": 9157
      }
    ]
  }
}

필터·필드 어휘

키 없이 호출(과금 없음, 1시간 캐시). 지원하는 속성 필터·값·자연어 별칭(aliases)과 필드 등급을 그대로 돌려줍니다. 필터 어휘의 단일 진실원천이라, MCP·SDK가 이걸 읽어 자동 동기화합니다.

키 없이 호출 · 과금 없음

파라미터

파라미터 없음

응답 예시

{
  "version": 1,
  "filters": {
    "boolean": [
      "wifi",
      "parking",
      "outdoor_seating",
      "pet_friendly",
      "group_friendly",
      "kids_friendly",
      "reservable",
      "takeout",
      "delivery",
      "dine_in",
      "catering",
      "corkage_free",
      "wheelchair_accessible",
      "high_chair",
      "no_kids_zone",
      "smoking_area",
      "restroom_gender_separated",
      "power_outlets",
      "stroller_storage",
      "deposit_required",
      "restroom_clean",
      "waiting_expected",
      "leftover_packing",
      "repeat_customers",
      "private_room",
      "has_promotion"
    ],
    "enum": {
      "parking_type": [
        "onsite",
        "valet",
        "partner",
        "nearby",
        "none"
      ]
    },
    "array": {
      "payment_methods": [
        "cash",
        "card",
        "toss_pay",
        "kakao_pay",
        "naver_pay",
        "zero_pay",
        "local_gift",
        "gov_support",
        "alipay",
        "wechat_pay"
      ],
      "serves": [
        "coffee",
        "alcohol",
        "dessert",
        "vegetarian",
        "vegan"
      ],
      "dietary": [
        "vegan_options",
        "vegetarian_options",
        "fully_vegan",
        "mixed_group_suitable"
      ],
      "foreign_languages": [
        "en",
        "zh",
        "ja",
        "es",
        "de",
        "fr"
      ],
      "recommended_for": [
        "solo_dining",
        "solo_drinking",
        "date",
        "group_dining",
        "group_drinking",
        "family",
        "business_meeting",
        "formal_gathering",
        "late_night",
        "late_night_eatery"
      ],
      "atmosphere": [
        "cozy",
        "quiet",
        "lively",
        "spacious",
        "view",
        "trendy",
        "traditional",
        "clean",
        "work_study",
        "rainy_mood"
      ]
    },
    "aliases": {
      "recommended_for": {
        "회식": "group_dining",
        "혼밥": "solo_dining",
        "상견례": "formal_gathering"
      },
      "atmosphere": {
        "조용한": "quiet",
        "뷰맛집": "view"
      },
      "parking_type": {
        "발렛": "valet"
      },
      "foreign_languages": {
        "영어": "en",
        "일본어": "ja"
      }
    }
  },
  "fields": {
    "tiers": {
      "core": 1,
      "contact_hours": 2,
      "quality": 2,
      "edge": 4,
      "media": 8
    },
    "byField": {
      "name": "core",
      "rating": "quality",
      "serviceAttributes": "edge",
      "photos": "media"
    }
  }
}

예약 요청

유미 파트너 매장(상세의 yumiReservable=true)에 테이블 예약을 요청합니다. 선입금 없음. 요청이 생성되면 사장님 앱으로 즉시 푸시가 가고, 응답은 status='pending'(아직 확정 아님)으로 시작합니다. 사장님이 승인하면 confirmed, 거절하면 cancelled, 무응답이면 expired(약 5분). 확정 결과는 상태조회(GET)로 확인하세요. 손님은 전화번호로 진행 상황을 알림톡/SMS로 받습니다. 파트너가 아니면 422 reservation_not_available(재시도 금지 — bookingUrl/전화 등 외부 예약 안내). idempotencyKey로 같은 요청을 안전하게 재시도(중복 예약 방지)할 수 있습니다.

인증 필요 (Bearer / X-API-Key 헤더 권장)

파라미터

파라미터 없음

요청 바디 (JSON)

• placeIdstring필수예약할 매장 ID(canonical). 검색으로 먼저 확보. · 예시: 11782345
• reservationTimestring필수예약 일시 ISO8601(타임존 포함, 미래). 한국은 +09:00. · 예시: 2026-09-01T19:00:00+09:00
• guestCountinteger필수인원수(1 이상). · 예시: 2
• guestPhonestring필수손님 연락처(필수) — 진행 상황 통지(알림톡/SMS) + 노쇼 시 사장님 연락. 없으면 guest_phone_required. · 예시: 010-1234-5678
• guestNamestring선택손님 이름(권장) — 사장님이 누가 오는지 알 수 있게. · 예시: 홍길동
• notestring선택사장님께 남길 메모(좌석 선호·기념일·알레르기 등).
• idempotencyKeystring선택같은 예약을 안전하게 재시도할 안정 키. 생략 시 자동 생성.

응답 예시

{
  "success": true,
  "data": {
    "reservationId": "b1f2c3d4-0000-0000-0000-000000000000",
    "status": "pending",
    "placeId": "11782345",
    "expiresAt": "2026-09-01T10:05:00.000Z"
  }
}

예약 상태 조회 (롱폴링)

예약의 현재 상태를 조회합니다. status: pending(대기)·confirmed(확정)·cancelled(거절)·expired(시간초과)·no_show. ?wait=초(최대 25)를 주면 확정/거절/만료가 되는 순간 즉시 반환하는 롱폴링 — 아직 pending이면 다시 호출해 약 5분 창을 채우고 settled=true가 되면 최종 결과를 사용자에게 알리세요.

인증 필요 (Bearer / X-API-Key 헤더 권장)

파라미터

• idstring필수예약 요청이 돌려준 reservationId. · 예시: b1f2c3d4-0000-0000-0000-000000000000
• waitinteger선택롱폴링 대기 초(0~25). 생략=즉시 1회 조회. · 예시: 25

응답 예시

{
  "success": true,
  "data": {
    "reservationId": "b1f2c3d4-0000-0000-0000-000000000000",
    "placeId": "11782345",
    "status": "confirmed",
    "settled": true,
    "reservationTime": "2026-09-01T19:00:00+09:00",
    "guestCount": 2,
    "approvedAt": "2026-09-01T10:02:11.000Z",
    "createdAt": "2026-09-01T10:00:00.000Z",
    "expiresAt": "2026-09-01T10:05:00.000Z"
  }
}

실시간 문의 (지금 되는지 매장에 물어봄)

지도·리뷰·정적 데이터로는 답할 수 없고 하루 중에도 바뀌는 휘발성 질문을 사장님에게 직접 보냅니다 — (A) 지금 그 메뉴 되는지·오늘 재료·품절(kind=item), (D) 지금 웨이팅 얼마나(kind=wait), (E) 지금 N명 바로 되는지(kind=seats, 인원 필수). 예약과 같은 레일입니다: 승인된 사장님(유미 파트너스 앱 사용) 매장이면 앱으로 즉시 푸시가 가고 status='pending'(5분 응답창)으로 시작합니다. 사장님이 한 번 탭으로 답하면 available·limited·unavailable·soon·not_offered로 확정되고, 결과는 GET /api/v1/live-status/{queryId}로 조회(롱폴링)합니다. 사장님을 다시 안 귀찮게 하려고, 같은 매장·주제에 유효한 답이 이미 있으면 새 질문 없이 그 답을 즉시 재사용하고(reused=true), 대기 중인 같은 질문이 있으면 거기 붙습니다. '지금'이 확인된 영업시간 밖이면 사장님을 깨우지 않고 blocked='closed_now'로 즉시 돌려줍니다(재시도 금지 — 영업시간을 안내). 사장님이 아직 안 쓰는 매장은 422 live_status_not_available. 영업시간·주차·반려동물 같은 정적 정보엔 쓰지 말고 검색으로 답하세요.

인증 필요 (Bearer / X-API-Key 헤더 권장)

파라미터

파라미터 없음

요청 바디 (JSON)

• placeIdstring필수질문할 매장 ID(canonical). 검색으로 먼저 확보. · 예시: 11782345
• kindstring필수질문 종류: item(품목·재고) · wait(웨이팅) · seats(즉시 착석, 인원 포함). · 예시: item
• topicstring필수질문 주제를 문장이 아닌 '토큰'으로. 예: '두바이 쫀득 쿠키', '방어', '웨이팅', '10명 입장'. item은 매장 실제 메뉴명으로. · 예시: 두바이 쫀득 쿠키
• questionstring선택손님 원문(선택) — 사장님이 맥락을 보게. · 예시: 지금 두바이 쫀득 쿠키 있어요?

응답 예시

{
  "success": true,
  "data": {
    "queryId": "c2e4f6a8-0000-0000-0000-000000000000",
    "placeId": "11782345",
    "kind": "item",
    "topic": "두바이 쫀득 쿠키",
    "status": "pending",
    "note": null,
    "settled": false,
    "fresh": false,
    "interestedCount": 1,
    "expiresAt": "2026-09-04T00:05:00.000Z"
  }
}

실시간 문의 상태 조회 (롱폴링)

실시간 문의의 현재 상태를 조회합니다. status: pending(대기)·available(가능/있음)·limited(일부·대기)·unavailable(불가/품절)·soon(곧/예정)·not_offered(취급 안 함)·no_response(5분 무응답). ?wait=초(최대 25)를 주면 사장님이 답하거나 5분이 지나 no_response가 되는 순간(=settled) 즉시 반환하는 롱폴링입니다 — 아직 pending이면 다시 호출해 약 5분 창을 채우고, settled=true가 되면 결과를 확인 시각과 함께 손님에게 전하세요. note에 사장님 부가 메모(예: 웨이팅 '20분', '따로 앉으시면 돼요')가 담길 수 있습니다. verifiedAt=확인 시각, validUntil=이 답이 유효한 시각(kind별로 다름) — 그때까지 다른 손님에게 재사용됩니다.

인증 필요 (Bearer / X-API-Key 헤더 권장)

파라미터

• queryIdstring필수실시간 문의가 돌려준 queryId. · 예시: c2e4f6a8-0000-0000-0000-000000000000
• waitinteger선택롱폴링 대기 초(0~25). 생략=즉시 1회 조회. · 예시: 25

응답 예시

{
  "success": true,
  "data": {
    "queryId": "c2e4f6a8-0000-0000-0000-000000000000",
    "placeId": "11782345",
    "kind": "wait",
    "topic": "웨이팅",
    "status": "limited",
    "note": "20분",
    "settled": true,
    "verifiedAt": "2026-09-04T00:02:30.000Z",
    "verifiedBy": "merchant",
    "validUntil": "2026-09-04T00:12:30.000Z",
    "fresh": true,
    "interestedCount": 3,
    "createdAt": "2026-09-04T00:00:00.000Z",
    "expiresAt": "2026-09-04T00:05:00.000Z"
  }
}

확인된 실시간 답 조회 (선택)

placeId + topic으로 사장님이 최근 확인한 '아직 유효한 답'이 있으면 질문 없이 바로 돌려줍니다(found:true + status·note·verifiedAt·validUntil). 없으면 found:false — 그때 POST로 새로 물으세요. 보통은 POST 하나로 충분합니다(POST가 재사용을 알아서 처리) — 아무것도 트리거하지 않고 '방금 확인된 정보'만 보고 싶을 때만 쓰세요.

인증 필요 (Bearer / X-API-Key 헤더 권장)

파라미터

• placeIdstring필수매장 ID(canonical). · 예시: 11782345
• topicstring필수질문 주제 토큰(POST의 topic과 동일). · 예시: 두바이 쫀득 쿠키

응답 예시

{
  "success": true,
  "data": {
    "found": true,
    "queryId": "c2e4f6a8-0000-0000-0000-000000000000",
    "placeId": "11782345",
    "kind": "item",
    "topic": "두바이 쫀득 쿠키",
    "status": "available",
    "note": null,
    "verifiedAt": "2026-09-04T00:02:30.000Z",
    "verifiedBy": "merchant",
    "validUntil": "2026-09-04T00:32:30.000Z",
    "fresh": true,
    "interestedCount": 4
  }
}