---
title: "Connettore Notion"
description: "Guida completa all'integrazione di Notion per sincronizzare database, pagine e contenuti del workspace con Brevo tramite Tajo."
url: https://tajo.io/it/docs/connectors/custom/notion/
markdown: https://tajo.io/it/docs/connectors/custom/notion.md
lang: it-IT
robots: noindex
---

Richiedi l’accesso anticipato

Inserisci il tuo nome e indirizzo email aziendale. Ti invieremo un link per confermare la richiesta di accesso a Tajo.

# Connettore Notion

Stato del connettore: Pianificato Non ancora realizzato. Oggi Tajo non esegue questo connettore.

| Campo di origine | Campo di destinazione | Valore di esempio |
| --- | --- | --- |
| `record.id` | `source_id` | `record_1042` |
| `record.updated_at` | `updated_at` | `2026-10-18T08:00:00Z` |
| `record.value` | `value` | `sample_value` |

Collega il tuo workspace Notion a Brevo per flussi di marketing content-driven, sincronizzazione di database CRM e notifiche automatizzate tramite Tajo.

## Panoramica

| Proprietà | Valore |
| --- | --- |
| **Piattaforma** | Notion |
| **Categoria** | Custom |
| **Complessità di setup** | Facile |
| **Integrazione ufficiale** | No |
| **Dati sincronizzati** | Database, Pagine, Utenti |
| **Tipo di API** | REST API |
| **Autenticazione** | Internal Integration Token / OAuth 2.0 |
| **Base URL** | `https://api.notion.com` |
| **Versione API** | `2022-06-28` (via header `Notion-Version`) |

## Funzionalità

- **Sync database** - Sincronizza le voci dei database Notion su contatti e liste Brevo
- **Ponte CRM** - Usa i database Notion come CRM leggero, sincronizzato con Brevo
- **Notifiche sui contenuti** - Attiva campagne Brevo quando vengono pubblicate pagine Notion
- **Mapping proprietà** - Mappa le proprietà dei database Notion sugli attributi dei contatti Brevo
- **Monitoraggio pagine** - Traccia gli aggiornamenti delle pagine e inoltrali come eventi Brevo
- **Sync directory utenti** - Sincronizza i membri del workspace Notion come contatti Brevo

## Prerequisiti

Prima di iniziare, assicurati di avere:

1. Un workspace Notion con accesso admin
2. Un’integrazione interna Notion o un’app OAuth
3. Pagine database condivise con l’integrazione
4. Un account Brevo con accesso API
5. Un account Tajo con abbonamento attivo

## Autenticazione

Notion supporta due metodi di autenticazione.

### Opzione 1: Integrazione interna (consigliata per singolo workspace)

1. Vai su [notion.so/my-integrations](https://www.notion.so/my-integrations)
2. Clicca su **New integration**
3. Nominala “Tajo Integration”
4. Seleziona il tuo workspace
5. Imposta le capabilities:

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

User Capabilities:
  Read user information: ✓
```

6. Copia l’**Internal Integration Secret** (inizia con `ntn_`)

Condivisione pagina richiesta

Le integrazioni interne possono accedere solo alle pagine e ai database esplicitamente condivisi con loro. Condividi ogni database target con la tua integrazione tramite il menu ”…” > “Connections” > seleziona la tua integrazione.

### Opzione 2: OAuth 2.0 (integrazioni pubbliche)

Per integrazioni che servono più workspace, usa il flusso OAuth 2.0:

1. Registra la tua integrazione come pubblica
2. Reindirizza gli utenti a: `https://api.notion.com/v1/oauth/authorize?client_id=...`
3. Scambia il code per un access token su `/v1/oauth/token`

### Connessione a Tajo

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

## Configurazione

### Setup di base

```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
```

### Mapping dei campi

Mappa le proprietà del database Notion sugli attributi dei contatti Brevo:

```yaml
field_mapping:
  # Proprietà Notion -> attributo 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
```

## Endpoint API

Tajo si integra con i seguenti endpoint dell’API Notion:

| Endpoint | Metodo | Scopo |
| --- | --- | --- |
| `/v1/databases/{id}/query` | POST | Interroga le voci del database |
| `/v1/databases/{id}` | GET | Recupera lo schema del database |
| `/v1/pages` | POST | Crea una nuova pagina |
| `/v1/pages/{id}` | GET | Recupera le proprietà della pagina |
| `/v1/pages/{id}` | PATCH | Aggiorna le proprietà della pagina |
| `/v1/blocks/{id}/children` | GET | Recupera i figli di un block |
| `/v1/users` | GET | Elenca tutti gli utenti del workspace |
| `/v1/users/{id}` | GET | Recupera un utente |
| `/v1/search` | POST | Cerca nel workspace |

## Esempi di codice

### Inizializzare il connettore

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

### Sincronizzare un database su Brevo

```javascript
// Sincronizza un database Notion su una lista 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
// }
```

### Query e filtri

```javascript
// Interroga un database Notion con filtri
const results = await tajo.connectors.query('notion', {
  databaseId: 'abc123def456',
  filter: {
    property: 'Status',
    select: { equals: 'Active' }
  },
  sorts: [
    { property: 'Last Contact', direction: 'descending' }
  ]
});
```

### Creare una pagina da un evento Brevo

```javascript
// Crea una pagina Notion quando un contatto Brevo raggiunge una 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() } }
      }
    });
  }
});
```

## Limiti di rate

Notion applica limiti di rate per integrazione:

| Tipo di limite | Valore |
| --- | --- |
| **Rate limit** | 3 richieste al secondo per integrazione |
| **Burst limit** | Brevi burst consentiti, poi throttling |
| **Dimensione pagina** | Max 100 elementi per richiesta paginata |

Paginazione basata su cursor

Notion usa la paginazione basata su cursor. Tajo la gestisce automaticamente, iterando su tutte le pagine usando il parametro `next_cursor` finché `has_more` restituisce `false`.

Notion restituisce `429 Too Many Requests` quando vengono superati i limiti di rate, con un header `Retry-After`.

## Risoluzione dei problemi

### Problemi comuni

| Problema | Causa | Soluzione |
| --- | --- | --- |
| 401 Unauthorized | Token non valido o scaduto | Rigenera il token dell’integrazione |
| 403 Forbidden | Pagina non condivisa con l’integrazione | Condividi pagina/database con l’integrazione tramite Connections |
| 404 Object not found | ID database errato o non condiviso | Verifica ID del database e impostazioni di condivisione |
| Proprietà mancanti | Mismatch di schema | Risincronizza lo schema del database e aggiorna il mapping |
| Rate limit superato | Troppe richieste ravvicinate | Riduci la frequenza di sync o la dimensione del batch |

### Modalità debug

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

### Testare la connessione

```bash
tajo connectors test notion
# ✓ Autenticazione API riuscita
# ✓ Accesso al database verificato
# ✓ Elenco utenti accessibile
# ✓ Ricerca operativa
# ✓ Creazione pagina disponibile
```

## Best practice

1. **Condividi i database esplicitamente** - Le integrazioni interne vedono solo i contenuti condivisi
2. **Usa query sul database anziché ricerca** - Le query sono più veloci e affidabili per database conosciuti
3. **Mappa i tipi di proprietà con attenzione** - Notion ha molti tipi di proprietà; fai corrispondere i tipi agli attributi Brevo
4. **Gestisci la paginazione** - Itera sempre su tutte le pagine con cursor per dati completi
5. **Sincronizza in modo incrementale** - Usa filtri su `last_edited_time` per sincronizzare solo le voci modificate
6. **Imposta uno schedule di polling** - Notion non supporta webhook nativamente; effettua polling a intervalli regolari

## Sicurezza

- **Autenticazione Bearer Token** - Secret delle integrazioni e token OAuth
- **Solo HTTPS** - Tutte le comunicazioni API cifrate tramite TLS 1.2+
- **Accesso con scope** - Le integrazioni accedono solo ai contenuti esplicitamente condivisi
- **OAuth 2.0** - Flusso di autorizzazione sicuro per integrazioni pubbliche
- **Archiviazione cifrata** - Token cifrati a riposo in Tajo
- **Isolamento del workspace** - Ogni integrazione è limitata a un singolo workspace

## Risorse correlate

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