숙소정보 데이터 타입입니다. 숙소정보 조회·등록 및 수정 API, 상품 등록·수정 요청과 상품번호로 조회한 상품 조회 응답의 accommodation 필드에서 사용합니다. 요청과 응답의 형식이 같습니다.
주소는 국내 숙소와 해외 숙소의 입력 항목이 다릅니다. countryCode 가 비어 있으면 국내, 있으면 해외 숙소로 처리합니다.
- 국내: address 필수, zipcode·addressDetail 선택. 좌표(longitude, latitude)는 선택이지만, 없으면 상품 상세에 숙소 지도가 표시되지 않습니다(WGS84 경위도). 법정동 코드(bCode)·행정동 코드(hCode)·지역명·지번 주소와 좌표는 카카오 로컬 API 주소 검색 응답 값을 그대로 입력하면 됩니다. 응답 필드와의 대응은 아래 필드 상세를 참고해 주세요.
- 해외: countryCode(대문자 ISO 3166-1 alpha-2, 예: US)·address·city·zipcode 필수, addressDetail·stateProvince 선택. 사업자번호(businessNumber)와 국내 숙소 전용 항목은 보내지 않습니다.
필드 제약사항
필수 항목
- 숙소상품 카테고리 상품은 숙소정보를 반드시 입력해야 합니다. 없으면 상품 등록·수정이 오류(accommodation.required)로 거절됩니다. 수정 요청에서 accommodation 을 빼거나 null 로 보내면 기존 숙소정보가 유지되므로, 이미 숙소정보가 있는 상품은 다시 보내지 않아도 됩니다.
- 숙소정보의 필수 항목은 숙박 유형(type)·숙소명(name)·주소(address)·체크인/체크아웃 시각(checkInTime·checkOutTime)이며, 나머지는 선택입니다. 해외 숙소는 countryCode·city·zipcode 도 필수입니다.
저장 방식
- 요청 내용 전체로 저장하므로 보내지 않은 선택 항목(guide, addressDetail, amenityCodes, amenitiesText 등)은 삭제됩니다.
- 상품 수정 요청에서 accommodation 을 빼거나 null 로 보내면 기존 숙소정보는 그대로 유지됩니다.
- 조회 응답을 그대로 수정 요청에 사용할 수 있지만, 조회 응답의 amenityCodes 에 사용이 중지된 코드가 남아 있으면 오류(accommodation.amenity_code.invalid)가 나므로 부대시설 코드 목록 조회에 없는 코드는 빼고 보내 주세요.
# 숙박 유형 코드
- 숙박 유형 목록 조회 API의 code 만 입력할 수 있습니다.
# 체크인·체크아웃 시각
- HH:mm 형식이며, 분은 00 또는 30 만 가능합니다.
# 숙소 안내사항
- 최대 1,000자까지 입력할 수 있습니다.
- 입력한 그대로(공백, 줄바꿈 등) 상품 상세 화면에 노출됩니다.
# 부대시설
- 부대시설 코드 목록 조회 API의 코드(amenityCodes)로 선택합니다.
- 목록에 없는 시설은 amenitiesText 에 쉼표(,)로 구분해 입력합니다. 입력한 순서대로 상품상세에 노출됩니다.
amenitiesText 의 항목마다 100자 이내, 한글/영문/숫자/공백만 입력할 수 있습니다.
# 좌표(국내 숙소)
- 경도(longitude)는 -180~180, 위도(latitude)는 -90~90 이며 소수 10자리까지 저장합니다(넘으면 반올림).
- 좌표는 선택이지만, 없으면 상품 상세에 숙소 지도가 표시되지 않습니다.
- 주소 검색 결과값을 자르지 말고 그대로 보내주세요. 소수 6자리 이상을 권장합니다.
# 숙박시설 사업자번호
- 하이픈(-) 없는 숫자 10자리로 입력합니다.
필드 상세
| 필드명 | 타입 | 필수여부 | 설명 |
|---|---|---|---|
| type | String | 필수 | 숙박 유형 코드(숙박 유형 목록 조회 API의 code) |
| name | String | 필수 | 숙소명. 70자 이내 |
| checkInTime | String | 필수 | 체크인 시각. HH:mm |
| checkOutTime | String | 필수 | 체크아웃 시각. HH:mm |
| guide | String | 선택 | 숙소 안내사항. 1,000자 이내 |
| countryCode | String | 해외 필수 | 국가코드. 해외 숙소는 대문자 ISO 3166-1 alpha-2(2자리, 예시: US). 국내 숙소는 KR 도 넣지 않고 비워 둡니다. |
| zipcode | String | 해외 필수 | 우편번호. 10자 이내(국내 숙소는 카카오 road_address.zone_no) |
| address | String | 필수 | 주소(해외는 주소1). 500자 이내 |
| addressDetail | String | 선택 | 상세주소(해외는 주소2). 100자 이내 |
| city | String | 해외 필수 | 도시. 60자 이내. 해외 숙소만 |
| stateProvince | String | 선택 | 주/도. 60자 이내. 해외 숙소만 |
| jibunAddress | String | 선택 | 지번 주소. 국내 숙소만(카카오 address.address_name) |
| bCode | String | 선택 | 법정동 코드(10자리). 국내 숙소만(카카오 address.b_code) |
| hCode | String | 선택 | 행정동 코드(10자리). 국내 숙소만(카카오 address.h_code) |
| region1DepthName | String | 선택 | 시/도 이름. 국내 숙소만(카카오 address.region_1depth_name) |
| region2DepthName | String | 선택 | 시/군/구 이름. 국내 숙소만(카카오 address.region_2depth_name) |
| region3DepthName | String | 선택 | 읍/면/동 이름. 국내 숙소만(카카오 address.region_3depth_name) |
| longitude | BigDecimal | 선택 | 경도. -180~180, 소수 10자리까지 저장(넘으면 반올림). 없으면 지도 미표시. 국내 숙소만(카카오 x) |
| latitude | BigDecimal | 선택 | 위도. -90~90, 소수 10자리까지 저장(넘으면 반올림). 없으면 지도 미표시. 국내 숙소만(카카오 y) |
| businessNumber | String | 선택 | 숙박시설 사업자번호. 하이픈 없는 숫자 10자리. 국내 숙소만 해당(해외 숙소는 보내지 않습니다) |
| amenityCodes | Array<String> | 선택 | 부대시설 코드 목록(부대시설 코드 목록 조회 API의 code) |
| amenitiesText | String | 선택 | 목록에 없는 부대시설. 쉼표(,)로 구분 |
<국내 숙소 샘플>
{
"type": "HOTEL",
"name": "제주 오션뷰 호텔",
"checkInTime": "15:00",
"checkOutTime": "11:00",
"guide": "체크인 시 신분증을 확인합니다.",
"zipcode": "63535",
"address": "제주특별자치도 서귀포시 예시로 123",
"addressDetail": "본관",
"businessNumber": "1234567890",
"amenityCodes": [
"WIFI",
"PARKING",
"BREAKFAST"
],
"amenitiesText": "오션뷰 라운지, 키즈 클럽"
}
<해외 숙소 샘플>
{
"type": "HOTEL",
"name": "Sample Hotel New York",
"checkInTime": "15:00",
"checkOutTime": "12:00",
"countryCode": "US",
"address": "350 5th Ave",
"addressDetail": "Suite 100",
"city": "New York",
"stateProvince": "NY",
"zipcode": "10118",
"amenityCodes": [
"WIFI"
],
"amenitiesText": ""
}