# iCal URL 설정 가이드
이 문서는 각 예약 플랫폼에서 iCal (iCalendar) URL을 얻는 방법을 안내합니다.
## 📌 iCal이란?
iCal (iCalendar)은 캘린더 데이터를 표준 형식으로 공유하는 방법입니다. 대부분의 예약 플랫폼은 예약 정보를 iCal 형식으로 내보낼 수 있는 기능을 제공합니다.
## 🔗 플랫폼별 iCal URL 얻는 방법
### 1. 에어비앤비 (Airbnb)
1. **호스트 계정 로그인**
- https://www.airbnb.co.kr 접속
- 호스트 모드로 전환
2. **캘린더 설정 접근**
- 상단 메뉴: `호스팅` → `캘린더`
- 또는 직접 접속: https://www.airbnb.co.kr/hosting/calendar
3. **iCal URL 복사**
- 우측 상단 또는 캘린더 설정에서 `캘린더 내보내기` 또는 `다른 캘린더와 동기화` 클릭
- `캘린더 주소 내보내기` 또는 `iCal 링크` 복사
- URL 형식: `https://www.airbnb.com/calendar/ical/[숙소ID].ics?s=[비밀키]`
**참고:**
- 각 숙소마다 별도의 iCal URL이 있습니다
- 여러 숙소가 있다면 각각의 URL을 얻어야 합니다
---
### 2. 스페이스클라우드 (Spacecloud)
1. **호스트 계정 로그인**
- https://www.spacecloud.kr 접속
- 호스트 센터 이동
2. **공간 관리**
- `내 공간 관리` → 공간 선택
- `예약 관리` 또는 `캘린더` 메뉴
3. **iCal 설정**
- `외부 캘린더 연동` 또는 `캘린더 내보내기` 찾기
- iCal URL 복사
- URL 형식: `https://www.spacecloud.kr/calendar/ical/[공간ID]`
**참고:**
- 플랫폼 정책에 따라 iCal 기능이 제한될 수 있습니다
- 자세한 내용은 스페이스클라우드 고객센터에 문의하세요
---
### 3. 네이버 예약
1. **네이버 예약 관리자 로그인**
- https://booking.naver.com/my/bookings (소비자용)
- https://booking-manager.naver.com (사업자용)
2. **캘린더 설정**
- `예약 관리` → `캘린더 보기`
- 설정 메뉴에서 `외부 캘린더 연동` 또는 `iCal 내보내기` 찾기
3. **iCal URL 복사**
- iCal 주소 복사
- URL 형식: `https://booking.naver.com/booking/ical/[업체ID].ics`
**참고:**
- 네이버 예약은 플랫폼 정책에 따라 iCal 기능 제공 여부가 다를 수 있습니다
- 일부 카테고리만 지원할 수 있습니다
---
### 4. 야놀자 (Yanolja)
1. **야놀자 호스트 로그인**
- https://partner.yanolja.com 접속
2. **예약 관리**
- `예약 관리` → `캘린더`
- 또는 `객실 관리` 메뉴
3. **캘린더 내보내기**
- 설정에서 `외부 캘린더 연동` 또는 `iCal 링크` 찾기
- URL 복사
**참고:**
- 야놀자는 iCal 기능을 제한적으로 제공할 수 있습니다
- 제공 여부는 파트너 계약에 따라 다를 수 있습니다
---
### 5. 카카오 예약
1. **카카오 비즈니스 로그인**
- https://business.kakao.com 접속
2. **예약 관리 도구**
- `예약` → `예약 관리`
- 또는 카카오톡 채널 관리자 센터
3. **캘린더 설정**
- `캘린더 내보내기` 또는 `외부 연동` 메뉴 찾기
- iCal URL 복사
**참고:**
- 카카오 예약은 비즈니스 계정이 필요합니다
- iCal 기능 제공 여부는 서비스 유형에 따라 다를 수 있습니다
---
## ⚙️ 환경 변수 설정 방법
### 1. .env 파일 생성
```bash
cp .env.example .env
```
### 2. .env 파일 편집
```bash
# .env 파일 열기
nano .env # 또는 vim, code 등 원하는 에디터 사용
```
### 3. iCal URL 입력
```env
# 플랫폼 iCal URLs
AIRBNB_ICAL_URL=https://www.airbnb.com/calendar/ical/12345678.ics?s=abcdef123456
SPACECLOUD_ICAL_URL=https://www.spacecloud.kr/calendar/ical/your-space-id
NAVER_ICAL_URL=https://booking.naver.com/booking/ical/your-store-id.ics
YANOLJA_ICAL_URL=https://partner.yanolja.com/calendar/ical/your-property-id
KAKAO_ICAL_URL=https://business.kakao.com/calendar/ical/your-channel-id
```
**주의사항:**
- iCal URL은 민감한 정보입니다. 외부에 공개하지 마세요!
- URL에 포함된 비밀키가 유출되면 누구나 예약 정보를 볼 수 있습니다
- .env 파일은 절대 Git에 커밋하지 마세요 (.gitignore에 포함됨)
---
## 🔄 동기화 설정
### 자동 동기화 활성화
```env
ICAL_SYNC_ENABLED=true
ICAL_SYNC_INTERVAL=3600 # 1시간마다 동기화 (초 단위)
```
### 동기화 주기 조정
- `3600` = 1시간 (기본값, 권장)
- `1800` = 30분
- `7200` = 2시간
- `86400` = 24시간
**권장 설정:**
- 예약이 많은 경우: 1시간 (3600초)
- 예약이 적은 경우: 2-4시간
- 너무 짧게 설정하면 플랫폼 서버에 부담을 줄 수 있습니다
---
## 🧪 테스트 방법
### 1. 서버 시작 시 확인
서버를 시작하면 자동으로 동기화가 시작됩니다:
```bash
python -m src.server
```
출력 예시:
```
======================================================================
🎯 예약 플랫폼 통합 관리 MCP 서버
======================================================================
🚀 백그라운드 자동 동기화 활성화
동기화 주기: 3600초 (60분)
📥 초기 동기화 수행 중...
🔄 Syncing airbnb...
✅ airbnb: 12건 동기화 완료
🔄 Syncing naver...
✅ naver: 5건 동기화 완료
✅ 총 2개 플랫폼에서 17건의 예약을 동기화했습니다.
✅ 백그라운드 동기화 스레드 시작됨
```
### 2. MCP Tool로 수동 동기화
```python
# Claude나 MCP 클라이언트에서
sync_platform_ical(platform="airbnb", ical_url="https://...")
```
---
## ❓ 문제 해결
### iCal URL을 찾을 수 없어요
- 각 플랫폼의 고객센터나 도움말에서 "iCal", "캘린더 내보내기", "외부 캘린더 연동" 키워드로 검색하세요
- 일부 플랫폼은 특정 요금제나 계정 유형에서만 iCal을 제공합니다
- 플랫폼 고객센터에 직접 문의하는 것이 가장 정확합니다
### 동기화가 안 돼요
1. iCal URL이 올바른지 확인
- 브라우저에서 URL 직접 접속 시 .ics 파일이 다운로드되는지 확인
2. 환경 변수 확인
```bash
cat .env | grep ICAL
```
3. 서버 로그 확인
- 동기화 실패 메시지가 있는지 확인
4. 네트워크 확인
- 서버에서 외부 URL에 접근할 수 있는지 확인
```bash
curl -I "iCal_URL"
```
### URL에 특수문자가 있어요
.env 파일에서 URL을 큰따옴표로 감싸세요:
```env
AIRBNB_ICAL_URL="https://www.airbnb.com/calendar/ical/12345.ics?s=abc&xyz=123"
```
---
## 🔒 보안 주의사항
1. **iCal URL 보호**
- URL에는 비밀키가 포함되어 있습니다
- GitHub 등에 절대 업로드하지 마세요
- .env 파일을 안전하게 보관하세요
2. **.gitignore 확인**
- .env 파일이 .gitignore에 포함되어 있는지 확인
```bash
cat .gitignore | grep .env
```
3. **URL 갱신**
- 보안상 문제가 생기면 플랫폼에서 iCal URL을 재생성할 수 있습니다
- URL이 변경되면 .env 파일을 업데이트하세요
---
## 📞 지원
문제가 계속되면 각 플랫폼의 고객센터에 문의하거나, 이 프로젝트의 이슈를 등록해주세요.
