---
title: "Notion 커넥터"
description: "Tajo를 통해 Notion 데이터베이스, 페이지, 워크스페이스 콘텐츠를 Brevo와 동기화하는 완전한 통합 가이드입니다."
url: https://tajo.io/kr/docs/connectors/custom/notion/
markdown: https://tajo.io/kr/docs/connectors/custom/notion.md
lang: ko-KR
robots: noindex
---

Tajo 사전 이용 신청

이름과 회사 이메일 주소를 입력하세요. Tajo 이용 신청을 확인할 수 있는 링크를 이메일로 보내드립니다.

# Notion 커넥터

커넥터 상태: 예정 아직 구축되지 않았습니다. Tajo는 현재 이 커넥터를 실행하지 않습니다.

| 원본 필드 | 대상 필드 | 예시 값 |
| --- | --- | --- |
| `record.id` | `source_id` | `record_1042` |
| `record.updated_at` | `updated_at` | `2026-10-18T08:00:00Z` |
| `record.value` | `value` | `sample_value` |

Tajo를 통해 Notion 워크스페이스를 Brevo에 연결하여 콘텐츠 기반 마케팅 워크플로, CRM 데이터베이스 동기화, 자동화된 알림을 구현하십시오.

## 개요

| 속성 | 값 |
| --- | --- |
| **플랫폼** | Notion |
| **카테고리** | Custom |
| **설정 복잡도** | 쉬움 |
| **공식 통합** | 아니오 |
| **동기화 데이터** | 데이터베이스, 페이지, 사용자 |
| **API 유형** | REST API |
| **인증** | 내부 통합 토큰 / OAuth 2.0 |
| **Base URL** | `https://api.notion.com` |
| **API 버전** | `2022-06-28` (`Notion-Version` 헤더를 통해) |

## 기능

- **데이터베이스 동기화** - Notion 데이터베이스 항목을 Brevo 연락처 및 목록으로 동기화
- **CRM 브리지** - Notion 데이터베이스를 경량 CRM으로 사용하여 Brevo와 동기화
- **콘텐츠 알림** - Notion 페이지가 게시될 때 Brevo 캠페인 트리거
- **속성 매핑** - Notion 데이터베이스 속성을 Brevo 연락처 속성에 매핑
- **페이지 모니터링** - 페이지 업데이트를 추적하여 Brevo 이벤트로 전달
- **사용자 디렉터리 동기화** - Notion 워크스페이스 멤버를 Brevo 연락처로 동기화

## 사전 요구 사항

시작하기 전에 다음이 준비되어 있는지 확인하십시오.

1. 관리자 접근 권한이 있는 Notion 워크스페이스
2. Notion 내부 통합 또는 OAuth 앱
3. 통합과 공유된 데이터베이스 페이지
4. API 접근이 가능한 Brevo 계정
5. 활성 구독이 있는 Tajo 계정

## 인증

Notion은 두 가지 인증 방법을 지원합니다.

### 옵션 1: 내부 통합 (단일 워크스페이스에 권장)

1. [notion.so/my-integrations](https://www.notion.so/my-integrations)로 이동
2. **New integration**을 클릭
3. 이름을 “Tajo Integration”으로 지정
4. 워크스페이스 선택
5. 기능 설정:

```
콘텐츠 기능:
  콘텐츠 읽기: ✓
  콘텐츠 업데이트: ✓
  콘텐츠 삽입: ✓

사용자 기능:
  사용자 정보 읽기: ✓
```

6. **Internal Integration Secret**(`ntn_`으로 시작)을 복사

페이지 공유 필요

내부 통합은 명시적으로 공유된 페이지 및 데이터베이스에만 접근할 수 있습니다. ”…” 메뉴 > “Connections” > 통합 선택을 통해 각 대상 데이터베이스를 통합과 공유하십시오.

### 옵션 2: OAuth 2.0 (공개 통합)

여러 워크스페이스에 서비스하는 통합의 경우 OAuth 2.0 흐름을 사용하십시오.

1. 통합을 공개 통합으로 등록
2. 사용자를 다음으로 리디렉션: `https://api.notion.com/v1/oauth/authorize?client_id=...`
3. `/v1/oauth/token`에서 코드를 액세스 토큰으로 교환

### Tajo에 연결

```bash
tajo connectors install notion \
  --token $NOTION_TOKEN
```

## 구성

### 기본 설정

```yaml
connectors:
  notion:
    enabled: true
    api_version: "2022-06-28"

    sync:
      databases: true
      pages: false
      users: true

    databases:
      - id: "abc123def456"
        name: "Customers"
        sync_to_list: 25
      - id: "ghi789jkl012"
        name: "Leads"
        sync_to_list: 26
```

### 필드 매핑

Notion 데이터베이스 속성을 Brevo 연락처 속성에 매핑합니다.

```yaml
field_mapping:
  # Notion 속성 -> Brevo 속성
  Name:
    type: title
    target: FIRSTNAME
  Email:
    type: email
    target: email
  Phone:
    type: phone_number
    target: SMS
  Company:
    type: rich_text
    target: COMPANY
  Status:
    type: select
    target: LEAD_STATUS
  Deal Value:
    type: number
    target: DEAL_VALUE
  Last Contact:
    type: date
    target: LAST_CONTACT_DATE
  Tags:
    type: multi_select
    target: TAGS
```

## API 엔드포인트

Tajo는 다음 Notion API 엔드포인트와 통합됩니다.

| 엔드포인트 | 메서드 | 목적 |
| --- | --- | --- |
| `/v1/databases/{id}/query` | POST | 데이터베이스 항목 쿼리 |
| `/v1/databases/{id}` | GET | 데이터베이스 스키마 가져오기 |
| `/v1/pages` | POST | 새 페이지 생성 |
| `/v1/pages/{id}` | GET | 페이지 속성 가져오기 |
| `/v1/pages/{id}` | PATCH | 페이지 속성 업데이트 |
| `/v1/blocks/{id}/children` | GET | 블록의 하위 항목 가져오기 |
| `/v1/users` | GET | 모든 워크스페이스 사용자 목록 |
| `/v1/users/{id}` | GET | 사용자 가져오기 |
| `/v1/search` | POST | 워크스페이스 전체 검색 |

## 코드 예제

### 커넥터 초기화

```javascript
import { TajoClient } from '@tajo/sdk';

const tajo = new TajoClient({
  apiKey: process.env.TAJO_API_KEY,
  brevoApiKey: process.env.BREVO_API_KEY
});

await tajo.connectors.connect('notion', {
  token: process.env.NOTION_TOKEN
});
```

### 데이터베이스를 Brevo로 동기화

```javascript
// Notion 데이터베이스를 Brevo 목록으로 동기화
await tajo.connectors.sync('notion', {
  type: 'full',
  resources: ['databases'],
  databaseId: 'abc123def456',
  targetList: 25
});

const status = await tajo.connectors.status('notion');
console.log(status);
// {
//   connected: true,
//   lastSync: '2024-03-15T14:30:00Z',
//   databasesSynced: 2,
//   pagesTracked: 1450,
//   usersCount: 32
// }
```

### 쿼리 및 필터링

```javascript
// 필터로 Notion 데이터베이스 쿼리
const results = await tajo.connectors.query('notion', {
  databaseId: 'abc123def456',
  filter: {
    property: 'Status',
    select: { equals: 'Active' }
  },
  sorts: [
    { property: 'Last Contact', direction: 'descending' }
  ]
});
```

### Brevo 이벤트에서 페이지 생성

```javascript
// Brevo 연락처가 마일스톤에 도달하면 Notion 페이지 생성
tajo.events.on('contact.attribute_updated', async (event) => {
  if (event.attribute === 'LIFECYCLE_STAGE' && event.value === 'customer') {
    await tajo.connectors.create('notion', {
      databaseId: 'ghi789jkl012',
      properties: {
        Name: { title: [{ text: { content: event.contact.name } }] },
        Email: { email: event.contact.email },
        'Converted Date': { date: { start: new Date().toISOString() } }
      }
    });
  }
});
```

## 속도 제한

Notion은 통합당 속도 제한을 적용합니다.

| 제한 유형 | 값 |
| --- | --- |
| **속도 제한** | 통합당 초당 3 요청 |
| **버스트 제한** | 짧은 버스트 허용 후 제한 |
| **페이지 크기** | 페이지 요청당 최대 100개 항목 |

커서 기반 페이지네이션

Notion은 커서 기반 페이지네이션을 사용합니다. Tajo는 `has_more`가 `false`를 반환할 때까지 `next_cursor` 매개변수를 사용하여 모든 페이지를 자동으로 반복합니다.

속도 제한을 초과하면 Notion은 `Retry-After` 헤더와 함께 `429 Too Many Requests`를 반환합니다.

## 문제 해결

### 일반적인 문제

| 문제 | 원인 | 해결 방법 |
| --- | --- | --- |
| 401 Unauthorized | 잘못되거나 만료된 토큰 | 통합 토큰 재생성 |
| 403 Forbidden | 페이지가 통합과 공유되지 않음 | Connections를 통해 페이지/데이터베이스를 통합과 공유 |
| 404 Object not found | 데이터베이스 ID가 잘못되었거나 공유되지 않음 | 데이터베이스 ID와 공유 설정 확인 |
| 속성 누락 | 스키마 불일치 | 데이터베이스 스키마를 재동기화하고 필드 매핑 업데이트 |
| 속도 제한 초과 | 너무 많은 빠른 요청 | 동기화 빈도나 배치 크기 줄이기 |

### 디버그 모드

```yaml
connectors:
  notion:
    debug: true
    log_level: verbose
    log_api_calls: true
```

### 연결 테스트

```bash
tajo connectors test notion
# ✓ API 인증 성공
# ✓ 데이터베이스 접근 확인
# ✓ 사용자 목록 접근 가능
# ✓ 검색 작동 중
# ✓ 페이지 생성 가능
```

## 모범 사례

1. **데이터베이스 명시적 공유** - 내부 통합은 공유된 콘텐츠만 볼 수 있음
2. **검색보다 데이터베이스 쿼리 사용** - 알려진 데이터베이스의 경우 쿼리가 더 빠르고 안정적
3. **속성 유형 신중하게 매핑** - Notion에는 다양한 속성 유형이 있음; Brevo 속성 유형과 일치시키기
4. **페이지네이션 처리** - 완전한 데이터를 위해 항상 모든 커서 페이지를 반복
5. **증분 동기화** - `last_edited_time` 필터를 사용하여 변경된 항목만 동기화
6. **폴링 일정 설정** - Notion은 웹훅을 기본적으로 지원하지 않음; 정기적인 간격으로 폴링

## 보안

- **Bearer 토큰 인증** - 통합 시크릿 및 OAuth 토큰
- **HTTPS 전용** - 모든 API 통신이 TLS 1.2+를 통해 암호화됨
- **범위 지정 접근** - 통합은 명시적으로 공유된 콘텐츠에만 접근
- **OAuth 2.0** - 공개 통합을 위한 보안 인증 흐름
- **암호화된 저장** - Tajo에서 토큰이 저장 시 암호화됨
- **워크스페이스 격리** - 각 통합은 단일 워크스페이스로 범위 지정됨

## 관련 리소스

- [Airtable 커넥터](https://tajo.io/kr/docs/connectors/custom/airtable)
- [GitHub 커넥터](https://tajo.io/kr/docs/connectors/custom/github)
- [Linear 커넥터](https://tajo.io/kr/docs/connectors/custom/linear)
- [Brevo Contacts API](https://tajo.io/kr/docs/contact-management)