Notion 커넥터
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 연락처로 동기화
사전 요구 사항
시작하기 전에 다음이 준비되어 있는지 확인하십시오.
- 관리자 접근 권한이 있는 Notion 워크스페이스
- Notion 내부 통합 또는 OAuth 앱
- 통합과 공유된 데이터베이스 페이지
- API 접근이 가능한 Brevo 계정
- 활성 구독이 있는 Tajo 계정
인증
Notion은 두 가지 인증 방법을 지원합니다.
옵션 1: 내부 통합 (단일 워크스페이스에 권장)
- notion.so/my-integrations로 이동
- New integration을 클릭
- 이름을 “Tajo Integration”으로 지정
- 워크스페이스 선택
- 기능 설정:
콘텐츠 기능: 콘텐츠 읽기: ✓ 콘텐츠 업데이트: ✓ 콘텐츠 삽입: ✓
사용자 기능: 사용자 정보 읽기: ✓- Internal Integration Secret(
ntn_으로 시작)을 복사
페이지 공유 필요
내부 통합은 명시적으로 공유된 페이지 및 데이터베이스에만 접근할 수 있습니다. ”…” 메뉴 > “Connections” > 통합 선택을 통해 각 대상 데이터베이스를 통합과 공유하십시오.
옵션 2: OAuth 2.0 (공개 통합)
여러 워크스페이스에 서비스하는 통합의 경우 OAuth 2.0 흐름을 사용하십시오.
- 통합을 공개 통합으로 등록
- 사용자를 다음으로 리디렉션:
https://api.notion.com/v1/oauth/authorize?client_id=... /v1/oauth/token에서 코드를 액세스 토큰으로 교환
Tajo에 연결
tajo connectors install notion \ --token $NOTION_TOKEN구성
기본 설정
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 연락처 속성에 매핑합니다.
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: TAGSAPI 엔드포인트
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 | 워크스페이스 전체 검색 |
코드 예제
커넥터 초기화
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로 동기화
// 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// }쿼리 및 필터링
// 필터로 Notion 데이터베이스 쿼리const results = await tajo.connectors.query('notion', { databaseId: 'abc123def456', filter: { property: 'Status', select: { equals: 'Active' } }, sorts: [ { property: 'Last Contact', direction: 'descending' } ]});Brevo 이벤트에서 페이지 생성
// 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와 공유 설정 확인 |
| 속성 누락 | 스키마 불일치 | 데이터베이스 스키마를 재동기화하고 필드 매핑 업데이트 |
| 속도 제한 초과 | 너무 많은 빠른 요청 | 동기화 빈도나 배치 크기 줄이기 |
디버그 모드
connectors: notion: debug: true log_level: verbose log_api_calls: true연결 테스트
tajo connectors test notion# ✓ API 인증 성공# ✓ 데이터베이스 접근 확인# ✓ 사용자 목록 접근 가능# ✓ 검색 작동 중# ✓ 페이지 생성 가능모범 사례
- 데이터베이스 명시적 공유 - 내부 통합은 공유된 콘텐츠만 볼 수 있음
- 검색보다 데이터베이스 쿼리 사용 - 알려진 데이터베이스의 경우 쿼리가 더 빠르고 안정적
- 속성 유형 신중하게 매핑 - Notion에는 다양한 속성 유형이 있음; Brevo 속성 유형과 일치시키기
- 페이지네이션 처리 - 완전한 데이터를 위해 항상 모든 커서 페이지를 반복
- 증분 동기화 -
last_edited_time필터를 사용하여 변경된 항목만 동기화 - 폴링 일정 설정 - Notion은 웹훅을 기본적으로 지원하지 않음; 정기적인 간격으로 폴링
보안
- Bearer 토큰 인증 - 통합 시크릿 및 OAuth 토큰
- HTTPS 전용 - 모든 API 통신이 TLS 1.2+를 통해 암호화됨
- 범위 지정 접근 - 통합은 명시적으로 공유된 콘텐츠에만 접근
- OAuth 2.0 - 공개 통합을 위한 보안 인증 흐름
- 암호화된 저장 - Tajo에서 토큰이 저장 시 암호화됨
- 워크스페이스 격리 - 각 통합은 단일 워크스페이스로 범위 지정됨