DOCS/ideas/250916_네이버웍스_캘린더_API_연동_가이드.md

# 네이버웍스 캘린더 API 연동 가이드

## 핵심 요약

> 네이버웍스 캘린더는 별도의 '에이전트' 개념보다는 **API(Application Programming Interface)**를 통해 외부 애플리케이션이나 봇이 캘린더 데이터를 읽고 수정하도록 허용합니다. 즉, 에이전트 역할을 하는 프로그램이 이 API를 호출하여 기능을 수행하게 됩니다.

**[현재 프로젝트 상태]** 네이버웍스 캘린더 API 연동 미구현 (OAuth2 토큰 관리 로직 없음, skill-calendar 서비스 미존재, auth-server에 Works API 인증 미탑재).

---

## 1. 네이버웍스 캘린더 API 개요

네이버웍스(NAVER WORKS)는 개발자가 자사의 다양한 기능과 리소스에 접근할 수 있도록 **NAVER WORKS API**를 제공합니다. 캘린더 기능 역시 이 API에 포함되어 있으며, 다음 기능을 수행할 수 있습니다.

*   **일정 조회 (View):** 특정 사용자의 기본 캘린더나 공유 캘린더의 일정을 조회합니다.
*   **일정 생성 (Create):** 새로운 일정을 생성하고 참석자, 시간, 장소 등을 설정합니다.
*   **일정 수정 (Modify):** 기존 일정의 정보를 업데이트합니다.
*   **일정 삭제 (Delete):** 일정을 삭제합니다.
*   **캘린더 관리 (Manage):** 캘린더 자체를 생성, 수정, 삭제하고 공유 속성을 관리합니다.

## 2. 에이전트(봇) 구현을 위한 필수 절차

에이전트(봇)가 캘린더 API를 사용하려면 다음 절차를 따라야 합니다.

1.  **개발자 콘솔에서 앱 생성:** [네이버웍스 개발자 콘솔](https://dev.worksmobile.com)에 관리자 계정으로 로그인하여 캘린더 API를 사용할 앱을 생성해야 합니다.
2.  **Access Token 발급:** API 호출을 위해서는 인증(Authentication) 절차를 거쳐 `Access Token`을 발급받아야 합니다. 이 토큰은 API 요청에 대한 권한을 부여하는 역할을 합니다.
3.  **API 스코프(Scope) 설정:** 앱이 캘린더에 접근할 수 있도록 API 권한 관리에서 `calendar` 또는 `calendar.read`와 같은 스코프를 설정해야 합니다.
    *   `calendar.read`: 읽기 전용 권한
    *   `calendar`: 읽기, 쓰기, 수정, 삭제 등 모든 권한
4.  **API 호출:** 발급받은 `Access Token`을 사용하여 HTTP 요청을 보냅니다. API 호출 방식은 일반적으로 RESTful API 형태로 제공되며, `GET`, `POST`, `PUT`, `DELETE` 등의 HTTP 메서드를 사용합니다.

## 3. API 사용 예시 (영문 문서 기반)

네이버웍스 개발자 문서는 영어로도 제공되며, 다음은 주요 API 호출 예시입니다.

### A. 일정 목록 조회 (GET)

특정 사용자의 기본 캘린더 일정을 조회하는 API입니다.

*   **HTTP Request:** `GET /users/{userId}/calendar/events`
*   **Description:** Retrieves a list of events from the default calendar of the target user.
*   **Authorization:** `Bearer {token}` (요청 헤더에 Access Token 포함)

### B. 일정 생성 (POST)

사용자의 기본 캘린더에 새로운 일정을 생성하는 API입니다.

*   **HTTP Request:** `POST /users/{userId}/calendar/events`
*   **Description:** Creates a new event in the target user's default calendar.
*   **Request Body (JSON):** 일정의 제목, 시작/종료 시간, 참석자 등 상세 정보를 JSON 형식으로 담아 보냅니다.

**Request URL:**
`POST https://www.worksapis.com/v1.0/users/{userId}/calendar/events`

**JSON Example:**
```json
{
  "subject": "Team Meeting",
  "start": {
    "date": "2025-09-12",
    "time": "10:00:00"
  },
  "end": {
    "date": "2025-09-12",
    "time": "11:00:00"
  },
  "attendees": [
    {
      "email": "member1@example.com",
      "isOptional": false
    }
  ]
}
```

### C. 일정 수정 (PUT)

기존 일정의 내용을 수정하는 API입니다.

*   **HTTP Request:** `PUT /users/{userId}/calendar/events/{eventId}`
*   **Description:** Updates an event in the target user's default calendar.
*   **Authorization:** `Bearer {token}`
*   **Request Body (JSON):** 수정할 내용이 포함된 JSON 데이터를 보냅니다.

## 4. 에이전트 구현 시 고려사항

*   **인증 (OAuth 2.0):** 네이버웍스 API는 OAuth 2.0 기반 인증을 사용합니다. 에이전트는 이 인증 흐름을 이해하고 Access Token을 관리해야 합니다.
*   **권한 (Scope):** 에이전트의 역할에 따라 필요한 최소한의 권한(예: 읽기 전용)을 설정하여 보안을 강화하는 것이 중요합니다.
*   **사용자 관리:** 봇이 특정 사용자의 캘린더에 접근하려면 해당 사용자의 `userId`를 알아야 합니다.
*   **오류 처리:** API 호출 시 발생할 수 있는 오류(예: `403 Forbidden`, `404 Not Found`)를 적절히 처리하도록 로직을 구현해야 합니다.

## 5. 참고 자료 및 결론

네이버웍스 캘린더 API는 주로 기업 내부 시스템 통합이나 업무 자동화 봇 개발에 사용되므로, 일반 네이버 캘린더 API와 달리 대외적으로 공개된 영상이나 블로그 튜토리얼이 많지 않습니다.

따라서 캘린더 제어 프로그램을 만들고자 한다면, 아래 공식 개발자 문서를 중심으로 학습하는 것이 가장 정확하고 효율적인 방법입니다.

*   **네이버웍스 개발자 센터 (공식 문서):** [developers.worksmobile.com](https://developers.worksmobile.com)
    *   [한국어 캘린더 API 문서](https://developers.worksmobile.com/kr/document/10070?lang=ko)
    *   [영문 캘린더 API 문서](https://developers.worksmobile.com/document/10070?lang=en)
*   **네이버 개발자 포럼:** API 관련 실제 질의응답을 참고할 수 있습니다.
*   **유튜브 튜토리얼:** "네이버웍스 봇 개발"로 검색하면 API 사용의 기본적인 흐름과 인증 절차에 대한 이해를 돕는 영상을 찾을 수 있습니다.

> **결론:** 공식 문서의 예제 코드를 기반으로 직접 코드를 작성하며 기능을 구현하는 것을 추천합니다.