Notion 连接器

通过 Tajo 将您的 Notion 工作区连接到 Brevo，实现内容驱动的营销工作流、CRM 数据库同步和自动通知。

概览

属性	值
平台	Notion
类别	自定义
设置复杂度	简单
官方集成	否
同步数据	数据库、页面、用户
API 类型	REST API
认证方式	内部集成令牌 / OAuth 2.0
基础 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
点击新建集成
命名为”Tajo Integration”
选择您的工作区
设置功能：

Content Capabilities:
  Read content: ✓
  Update content: ✓
  Insert content: ✓

User Capabilities:
  Read user information: ✓

复制内部集成密钥（以 ntn_ 开头）

需要共享页面

内部集成只能访问与其明确共享的页面和数据库。通过”…”菜单 > “连接” > 选择您的集成，将每个目标数据库与集成共享。

选项 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 property -> Brevo attribute
  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	在工作区中搜索

代码示例

初始化连接器

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

// Sync a Notion database to a Brevo list
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
// }

查询和过滤

// Query Notion database with filters
const results = await tajo.connectors.query('notion', {
  databaseId: 'abc123def456',
  filter: {
    property: 'Status',
    select: { equals: 'Active' }
  },
  sorts: [
    { property: 'Last Contact', direction: 'descending' }
  ]
});

从 Brevo 事件创建页面

// Create a Notion page when a Brevo contact reaches a milestone
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 自动处理此操作，使用 next_cursor 参数迭代所有页面，直到 has_more 返回 false。

超出速率限制时，Notion 返回 429 Too Many Requests，并附带 Retry-After 头部。

故障排除

常见问题

问题	原因	解决方案
401 Unauthorized	令牌无效或已过期	重新生成集成令牌
403 Forbidden	页面未与集成共享	通过”连接”将页面/数据库共享给集成
404 Object not found	数据库 ID 错误或未共享	验证数据库 ID 和共享设置
属性缺失	架构不匹配	重新同步数据库架构并更新字段映射
超出速率限制	请求过于频繁	降低同步频率或批次大小

调试模式

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

测试连接

tajo connectors test notion
# ✓ API authentication successful
# ✓ Database access verified
# ✓ User list accessible
# ✓ Search operational
# ✓ Page creation available

最佳实践

明确共享数据库 - 内部集成只能看到共享内容
使用数据库查询而非搜索 - 对于已知数据库，查询更快且更可靠
谨慎映射属性类型 - Notion 有多种属性类型；将其与 Brevo 属性类型匹配
处理分页 - 始终迭代所有游标页面以获取完整数据
增量同步 - 使用 last_edited_time 过滤器只同步已变更的条目
设置轮询计划 - Notion 原生不支持 Webhook；定期按时间间隔轮询

安全

Bearer 令牌认证 - 集成密钥和 OAuth 令牌
仅 HTTPS - 所有 API 通信通过 TLS 1.2+ 加密
范围访问 - 集成只能访问明确共享的内容
OAuth 2.0 - 公共集成的安全授权流程
加密存储 - 令牌在 Tajo 中静态加密
工作区隔离 - 每个集成限定于单个工作区

Notion 连接器

概览

功能

前提条件

认证

选项 1：内部集成（推荐用于单工作区）

选项 2：OAuth 2.0（公共集成）

连接到 Tajo

配置

基础设置

字段映射

API 端点

代码示例

初始化连接器

将数据库同步到 Brevo

查询和过滤

从 Brevo 事件创建页面

速率限制

故障排除

常见问题

调试模式

测试连接

最佳实践

安全

相关资源

Thanks — you're subscribed.

Notion 连接器

概览

功能

前提条件

认证

选项 1：内部集成（推荐用于单工作区）

选项 2：OAuth 2.0（公共集成）

连接到 Tajo

配置

基础设置

字段映射

API 端点

代码示例

初始化连接器

将数据库同步到 Brevo

查询和过滤

从 Brevo 事件创建页面

速率限制

故障排除

常见问题

调试模式

测试连接

最佳实践

安全

相关资源

Subscribe to updates

Thanks — you're subscribed.