Conector Notion

Conecte seu workspace Notion ao Brevo para workflows de marketing orientados por conteúdo, sincronização de banco de dados CRM e notificações automatizadas através do Tajo.

Visão geral

Recursos

• Sincronização de banco de dados - Sincronize entradas de banco de dados do Notion para contatos e listas do Brevo
• Ponte de CRM - Use bancos de dados do Notion como um CRM leve, sincronizado com o Brevo
• Notificações de conteúdo - Dispare campanhas do Brevo quando páginas do Notion forem publicadas
• Mapeamento de propriedades - Mapeie propriedades de banco de dados do Notion para atributos de contato do Brevo
• Monitoramento de páginas - Acompanhe atualizações de páginas e encaminhe como eventos do Brevo
• Sincronização de diretório de usuários - Sincronize membros de workspace do Notion para contatos do Brevo

Pré-requisitos

Antes de começar, certifique-se de que você tem:

1. Um workspace Notion com acesso de administrador
2. Uma integração interna do Notion ou app OAuth
3. Páginas de banco de dados compartilhadas com a integração
4. Uma conta Brevo com acesso à API
5. Uma conta Tajo com assinatura ativa

Autenticação

O Notion suporta dois métodos de autenticação.

Opção 1: Integração interna (Recomendado para workspace único)

1. Acesse notion.so/my-integrations
2. Clique em New integration
3. Nomeie como “Tajo Integration”
4. Selecione seu workspace
5. Defina as capacidades:

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

User Capabilities:
  Read user information: ✓

6. Copie o Internal Integration Secret (começa com ntn_)

Opção 2: OAuth 2.0 (Integrações públicas)

Para integrações que atendem a múltiplos workspaces, use o fluxo OAuth 2.0:

1. Registre sua integração como uma integração pública
2. Redirecione os usuários para: https://api.notion.com/v1/oauth/authorize?client_id=...
3. Troque o código por um token de acesso em /v1/oauth/token

Conectando ao Tajo

tajo connectors install notion \
  --token $NOTION_TOKEN

Configuração

Configuração básica

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

Mapeamento de campos

Mapeie propriedades de banco de dados do Notion para atributos de contato do 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

Endpoints da API

O Tajo integra-se com os seguintes endpoints da API do Notion:

Exemplos de código

Inicializar o conector

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
});

Sincronizar banco de dados para o 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
// }

Consultar e filtrar

// 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' }
  ]
});

Criar página a partir de evento do 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() } }
      }
    });
  }
});

Limites de taxa

O Notion aplica limites de taxa por integração:

O Notion retorna 429 Too Many Requests quando os limites de taxa são excedidos, com um cabeçalho Retry-After.

Solução de problemas

Problemas comuns

Modo de depuração

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

Testar conexão

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

Melhores práticas

1. Compartilhe bancos de dados explicitamente - Integrações internas só veem conteúdo compartilhado
2. Use consultas de banco de dados em vez de busca - Consultas são mais rápidas e confiáveis para bancos de dados conhecidos
3. Mapeie tipos de propriedade cuidadosamente - O Notion tem muitos tipos de propriedade; combine-os com tipos de atributo do Brevo
4. Trate a paginação - Sempre itere por todas as páginas de cursor para dados completos
5. Sincronize incrementalmente - Use filtros last_edited_time para sincronizar apenas entradas alteradas
6. Configure um agendamento de polling - O Notion não suporta webhooks nativamente; faça polling em intervalos regulares

Segurança

• Autenticação por bearer token - Segredos de integração e tokens OAuth
• Somente HTTPS - Toda comunicação com a API é criptografada via TLS 1.2+
• Acesso com escopo - Integrações acessam apenas conteúdo explicitamente compartilhado
• OAuth 2.0 - Fluxo de autorização seguro para integrações públicas
• Armazenamento criptografado - Tokens criptografados em repouso no Tajo
• Isolamento de workspace - Cada integração tem escopo para um único workspace

Recursos relacionados

• Conector Airtable
• Conector GitHub
• Conector Linear
• API de contatos do Brevo