> This is a page from the ElevenLabs documentation. For an index of the documentation, fetch https://elevenlabs.io/docs/llms.txt.

# Hostaway

아래 [웹훅 도구](/docs/ko/reception-ai/integrations/webhooks)를 사용하면 접수 담당자가 발신자가 문의한 날짜의 Hostaway 숙소 캘린더를 확인하고, 캐빈 또는 객실의 이용 가능 여부, 1박 요금, 최소 숙박 일수를 알려줄 수 있습니다. Hostaway의 공개 API는 24개월 동안 유효한 액세스 토큰을 발급하므로, 이 도구는 Hostaway를 직접 호출합니다.

> **Note**
>
> 접수 담당자는 예약을 생성하거나 기존 예약을 조회할 수 없습니다. 캘린더를 확인하고 예약 요청을
> 접수하면, 팀에서 [통화 후 요약](/docs/ko/reception-ai/features/notifications)을 통해 숙박을 확정합니다.

## 시작하기 전에

### API 키 만들기

Hostaway 대시보드에서 **Settings** → **Hostaway API**를 열고 새 API 키를 만드세요. 이름은 `Reception.ai`로 지정하고, 파트너는 **Hostaway Public API**를 선택하세요. 키는 Hostaway에서 한 번만 표시하므로 복사해 두세요. **Settings**에도 표시되는 **Account ID**를 확인하세요.

### 액세스 토큰 받기

터미널에서 키를 액세스 토큰으로 교환하세요. `ACCOUNT_ID`와 `API_KEY`를 바꾸어 입력합니다.

```bash
curl -X POST 'https://api.hostaway.com/v1/accessTokens' \
  -H 'Content-type: application/x-www-form-urlencoded' \
  -d 'grant_type=client_credentials&client_id=ACCOUNT_ID&client_secret=API_KEY&scope=general'
```

응답에서 `access_token` 값을 복사하세요. 24개월 동안 유효합니다.

> **Warning**
>
> 액세스 토큰으로는 게스트 정보와 도어 코드 등을 포함해 Hostaway 계정의 모든 항목을 읽고 변경할 수 있습니다.
> 공유 문서나 온라인 도구에 붙여넣지 마세요. 유출된 경우 토큰을 취소하고 Hostaway에서 API 키를
> 삭제하세요.

### 숙소 ID 찾기

토큰을 사용해 숙소 목록을 조회하세요. `YOUR_TOKEN`을 바꾸어 입력합니다.

```bash
curl 'https://api.hostaway.com/v1/listings?limit=100' \
  -H 'Authorization: Bearer YOUR_TOKEN'
```

응답의 각 숙소에는 `id`와 `name`이 있습니다. 접수 담당자가 확인해야 하는 각 숙소의 ID를 기록하세요.

## 도구 만들기

**Integrations**로 이동해 **Add integration**을 선택하고 **Webhook Tool**을 고르세요.

| 필드           | 값                                                                                                                                   |
| ------------ | ----------------------------------------------------------------------------------------------------------------------------------- |
| **이름**       | `check_hostaway_calendar`                                                                                                           |
| **설명**       | "발신자가 요청한 날짜에 숙소 중 하나를 이용할 수 있는지, 1박 요금과 최소 숙박 일수는 얼마인지 확인합니다. 발신자에게 숙소 이용이 가능하다고 말하기 전에 사용하세요."                                    |
| **메서드**      | GET                                                                                                                                 |
| **URL**      | `https://api.hostaway.com/v1/listings/{listing_id}/calendar`                                                                        |
| **요청 헤더**    | `Authorization`: `Bearer ` 뒤에 액세스 토큰을 입력하고, **Type**은 **Secret**으로 설정                                                               |
| **경로 매개변수**  | `listing_id`(문자열, 필수): "Cedar Cabin에는 `11111`, Lakeside Cabin에는 `22222`를 사용하세요."                                                    |
| **쿼리 매개변수**  | `startDate`(문자열, 필수): "YYYY-MM-DD 형식의 도착일입니다."  `endDate`(문자열, 필수): "YYYY-MM-DD 형식의 마지막 숙박일입니다."  `includeResources`(문자열, 고정값): `0` |
| **에이전트에 할당** | **Receptionist**                                                                                                                    |

캐빈 이름과 ID를 실제 값으로 바꾸고, 숙소마다 한 줄씩 추가하세요. **Enable**을 선택하세요.

Hostaway는 숙박일별로 항목 하나를 반환합니다. `status`가 `available`이면 해당 숙박일을 이용할 수 있습니다. 각 숙박일에는 `price`와 `minimumStay`도 표시됩니다.

> **Warning**
>
> `includeResources`는 `0`으로 고정하세요. `1`로 설정하면 Hostaway가 게스트 이름, 전화번호, 이메일을 포함한
> 각 숙박일의 예약 정보를 접수 담당자가 보는 데이터에 추가합니다.

### 테스트

예약된 것으로 알고 있는 날짜와 비어 있는 것으로 알고 있는 날짜의 캐빈을 요청하며 [접수 담당자를 테스트](/docs/ko/reception-ai/receptionist/testing)하세요. 답변을 Hostaway 캘린더와 비교하세요.

> **Tip**
>
> 숙박 요청용 [절차](/docs/ko/reception-ai/receptionist/rules-and-procedures)를 추가하세요. 숙소, 도착일과 출발일,
> 게스트 수를 물어본 후 캘린더를 확인하고, 팀을 위해 발신자의 이름, 전화번호, 이메일을 받도록 합니다. 접수 담당자가
> 숙박 예약이 확정되었다고 절대 약속하지 않도록 규칙을 추가하세요.

## 제한 사항

* 접수 담당자는 예약을 생성, 변경 또는 취소할 수 없습니다. 각 숙박은 팀에서 확정합니다.
* 한 번에 하나의 숙소만 확인합니다. 다른 캐빈을 제안하려면 각각 순서대로 확인합니다.
* 1박 요금에는 청소비, 세금 또는 할인 금액이 포함되지 않으므로 접수 담당자는 참고용으로만 안내해야 합니다.
* 이 도구는 기존 예약을 조회하지 않습니다. Hostaway의 예약 및 숙소 기록에는 도어 코드와 Wi-Fi 비밀번호가 포함되어 있으므로, 이 가이드에서는 접수 담당자에게 이를 노출하지 않습니다. Zapier의 Hostaway 앱도 같은 기록을 반환하며 예약이나 이용 가능 여부 작업은 제공하지 않습니다.
* 액세스 토큰은 24개월 후에 작동하지 않습니다. 그전에 새 토큰을 만들고 헤더를 업데이트하세요.

## 문제 해결

| 문제                       | 확인할 사항                                                              |
| ------------------------ | ------------------------------------------------------------------- |
| Hostaway에서 401 또는 403 응답 | 헤더 값은 API 키가 아니라 `Bearer`, 공백, 액세스 토큰이어야 합니다. 만료되지 않았는지 확인하세요.      |
| 잘못된 캐빈이 확인됨              | `listing_id` 설명의 숙소 ID가 실제 숙소와 일치하는지 확인하세요.                         |
| 예약된 숙박일이 비어 있는 것으로 표시됨   | Hostaway에서 캘린더를 확인하세요. 차단되었거나 예약된 숙박일의 `status`는 `available`이 아닙니다. |
| 접수 담당자가 너무 짧은 숙박을 제안함    | 도구 설명에서 도착일의 `minimumStay`를 확인하도록 지시하세요.                            |