API 문서 · Finy

AIPlanner 일정 등록 API

AIPlanner API는 자연어 일정 문장이나 문서/OCR/STT 결과를 보내면 날짜·시간·제목을 파싱해 연결된 Google Calendar에 등록하는 API입니다.

API가 Google 로그인을 새로 받는 구조가 아니라, 개인은 Telegram 봇 DM에서, 단체는 방/토픽의 /setup에서 먼저 연결해 둔 Calendar 설정을 재사용합니다. API token은 그 연결 범위와 생성 권한에 묶입니다.

1. 사용 전 준비

개인 일정: Telegram 봇 DM에서 Google Calendar 연결과 기본 캘린더 선택을 먼저 완료합니다.
단체 일정: 단체방/토픽에 봇을 초대하고 /setup으로 공유 Google Calendar를 연결합니다.
API token: 운영자가 연결된 개인/방/토픽 범위에 맞춰 scoped API client를 발급합니다. 원본 Bearer token은 최초 1회만 표시됩니다.
실제 등록 권한: 캘린더 생성까지 하려면 token에 can_create=true가 있어야 합니다.

2. 기본 사용법

처음에는 parse_only=true로 후보만 확인하고, 확실한 자동화에는 parse_only=false로 실제 Google Calendar 등록을 요청합니다.

문서/이미지/음성 감시: can_parse_only=true, can_create=false — 일정 후보 미리보기만 허용
신뢰 자동화: can_parse_only=true, can_create=true — 운영자가 허용한 캘린더 범위에서만 생성
그룹/토픽: 기본 telegram_chat_id, message_thread_id, 허용 target allowlist로 범위를 고정

3. 엔드포인트

POST https://getfiny.com/api/v1/capture/events

Authorization: Bearer cap_live_...
Content-Type: application/json

미리보기 요청 예시:

{
  "text": "내일 오후 3시 제품 회의",
  "scope": "personal",
  "parse_only": true
}

Google Calendar에 실제 등록하는 요청 예시:

{
  "text": "내일 오후 3시 제품 회의",
  "scope": "personal",
  "parse_only": false,
  "expected_calendar_id": "primary"
}

단체방/토픽에 연결된 공유 캘린더로 등록하는 경우:

{
  "text": "6월 10일 오후 7시 AI 모임",
  "scope": "group",
  "parse_only": false,
  "source_type": "google_doc",
  "source_url": "https://example.com/notice"
}

4. 주요 요청 필드

text: 일정 후보를 찾을 원문 텍스트
scope: auto, personal, group
parse_only: true면 캘린더 생성 없이 후보만 반환
source_type: capture_bot, image_ocr, voice_stt, google_doc, pdf_ocr 등
expected_calendar_id: 실제 생성 전 대상 캘린더가 기대값과 다르면 412로 중단

5. 생성 응답 예시

{
  "ok": true,
  "status": "created",
  "scope": "personal",
  "event_id": 123,
  "google_event_id": "google_event_id_example",
  "title": "제품 회의",
  "event_count": 1,
  "calendar_id": "primary",
  "calendar_name": "업무 캘린더",
  "events": [{
    "title": "제품 회의",
    "start": "2026-06-23T15:00:00+09:00",
    "end": "2026-06-23T16:00:00+09:00",
    "all_day": false
  }]
}

6. 반복 일정

“매주 월요일 오전 9시 주간회의” 같은 요청은 미리보기 응답에 recurrence를 포함합니다. 생성 권한이 있고 parse_only=false인 경우 Google Calendar 반복 일정으로 생성됩니다.

7. 오류 코드

401: Bearer token 누락/오류 또는 비활성 client
403: client 권한 밖 대상이거나 생성/미리보기 권한 없음
404: 그룹/토픽 일정 공간 미설정
409: 대상 캘린더 연결 미완료
412: expected_calendar_id 불일치

8. 발급 문의

API 발급은 운영자가 용도와 범위를 확인한 뒤 진행합니다. 발급이 필요하면 @PlannerSupport_Bot 또는 관리자에게 “사용 목적 / 대상 범위 / 미리보기 전용 여부 / 생성 권한 필요 여부”를 보내주세요.

관리자 로그인에서 발급 관리 →