---
title: "Connettore Typeform"
description: "Guida completa all'integrazione di Typeform per sincronizzare risposte ai form, sondaggi e raccolta dati conversazionale con Brevo tramite Tajo."
url: https://tajo.io/it/docs/connectors/custom/typeform/
markdown: https://tajo.io/it/docs/connectors/custom/typeform.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 Typeform

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 Typeform a Brevo tramite Tajo per sincronizzare automaticamente le risposte ai form, catturare lead dai form conversazionali e attivare automazioni marketing basate su invii di sondaggi e risultati di quiz.

## Panoramica

| Proprietà | Valore |
| --- | --- |
| **Piattaforma** | Typeform |
| **Categoria** | Forms & Surveys (Custom) |
| **Complessità di setup** | Facile |
| **Integrazione ufficiale** | No |
| **Dati sincronizzati** | Risposte, Contatti, Eventi, Form |
| **Metodo di autenticazione** | OAuth 2.0 / Personal Access Token |

## Funzionalità

- **Sync risposte in real-time** - Cattura automaticamente gli invii dei form tramite webhook
- **Creazione contatti** - Crea o aggiorna contatti Brevo dalle risposte ai form
- **Lead scoring** - Usa i punteggi dei quiz e i dati dei form per la qualificazione dei lead
- **Hidden Fields** - Passa i dati cliente tramite Hidden Fields per form personalizzati
- **Mapping condizionale** - Mappa campi form diversi in base alla logica di risposta
- **Supporto multi-form** - Collega più typeform a liste Brevo diverse

## Prerequisiti

Prima di iniziare, assicurati di avere:

1. Un account Typeform (piano Basic o superiore per i webhook)
2. Un Personal Access Token da [Typeform Account Settings](https://admin.typeform.com/account#/section/tokens)
3. Un account Brevo con accesso API
4. Un account Tajo con permessi sui connettori

## Autenticazione

### Personal Access Token

```bash
# Genera un token su https://admin.typeform.com/account#/section/tokens
export TYPEFORM_ACCESS_TOKEN=tfp_your_personal_access_token
export TAJO_API_KEY=your_tajo_api_key
export BREVO_API_KEY=your_brevo_api_key
```

### OAuth 2.0

```javascript
// Flusso di autorizzazione OAuth 2.0
const authUrl = 'https://api.typeform.com/oauth/authorize?' +
  new URLSearchParams({
    client_id: process.env.TYPEFORM_CLIENT_ID,
    redirect_uri: 'https://your-app.com/callback',
    scope: 'forms:read responses:read webhooks:write accounts:read',
    state: generateState()
  });

// Scambia l'authorization code per un access token
const tokenResponse = await fetch('https://api.typeform.com/oauth/token', {
  method: 'POST',
  headers: { 'Content-Type': 'application/x-www-form-urlencoded' },
  body: new URLSearchParams({
    grant_type: 'authorization_code',
    code: authorizationCode,
    client_id: process.env.TYPEFORM_CLIENT_ID,
    client_secret: process.env.TYPEFORM_CLIENT_SECRET,
    redirect_uri: 'https://your-app.com/callback'
  })
});
```

## Configurazione

### Setup di base

```yaml
connectors:
  typeform:
    enabled: true
    access_token: "${TYPEFORM_ACCESS_TOKEN}"

    forms:
      - form_id: "abc123"
        list_id: 5
        mapping:
          email_field: "email"
          name_field: "full_name"
      - form_id: "xyz789"
        list_id: 6
        mapping:
          email_field: "work_email"

    sync:
      responses: true
      contacts: true
      events: true

    webhook:
      enabled: true
      secret: "${TYPEFORM_WEBHOOK_SECRET}"
```

### Mapping dei campi

```yaml
field_mapping:
  # Mappa i reference dei campi Typeform sugli attributi Brevo
  email: email
  name: FIRSTNAME
  company: COMPANY
  phone: SMS
  score: LEAD_SCORE
  quiz_result: QUIZ_SCORE
  nps_rating: NPS_SCORE
  feedback: LAST_FEEDBACK
```

## Endpoint API

| Endpoint | Metodo | Descrizione |
| --- | --- | --- |
| `https://api.typeform.com/forms` | GET | Elenca tutti i form |
| `https://api.typeform.com/forms/{form_id}` | GET | Recupera un form |
| `https://api.typeform.com/forms` | POST | Crea un form |
| `https://api.typeform.com/forms/{form_id}` | PUT | Aggiorna un form |
| `https://api.typeform.com/forms/{form_id}/responses` | GET | Recupera le risposte |
| `https://api.typeform.com/forms/{form_id}/responses` | DELETE | Elimina le risposte |
| `https://api.typeform.com/forms/{form_id}/webhooks/{tag}` | PUT | Crea/aggiorna webhook |
| `https://api.typeform.com/forms/{form_id}/webhooks/{tag}` | GET | Ottieni un webhook |
| `https://api.typeform.com/forms/{form_id}/webhooks` | GET | Elenca i webhook |

## 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('typeform', {
  accessToken: process.env.TYPEFORM_ACCESS_TOKEN,
  forms: ['abc123', 'xyz789']
});
```

### Recuperare le risposte ai form

```javascript
// Recupera le risposte usando la Responses API
const response = await fetch(
  'https://api.typeform.com/forms/abc123/responses?' +
    new URLSearchParams({
      page_size: 25,
      since: '2024-01-01T00:00:00Z',
      completed: 'true'
    }),
  {
    headers: {
      'Authorization': `Bearer ${process.env.TYPEFORM_ACCESS_TOKEN}`
    }
  }
);

const data = await response.json();

// Sincronizza ogni risposta su Brevo
for (const item of data.items) {
  const answers = item.answers;
  const email = answers.find(a => a.field.ref === 'email')?.email;

  if (email) {
    await tajo.contacts.sync({
      email,
      attributes: {
        FIRSTNAME: answers.find(a => a.field.ref === 'name')?.text,
        LEAD_SCORE: item.calculated?.score || 0
      },
      listIds: [5]
    });
  }
}
```

### Configurare i webhook

```javascript
// Registra un webhook per notifiche di risposta in real-time
await fetch(
  'https://api.typeform.com/forms/abc123/webhooks/tajo-sync',
  {
    method: 'PUT',
    headers: {
      'Authorization': `Bearer ${process.env.TYPEFORM_ACCESS_TOKEN}`,
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({
      url: 'https://api.example.com/webhooks/typeform',
      enabled: true,
      secret: process.env.TYPEFORM_WEBHOOK_SECRET
    })
  }
);
```

Caution

L’indirizzo `example.com` qui sopra è un segnaposto finché l’endpoint Tajo non sarà disponibile.

### Gestire gli eventi webhook

```javascript
app.post('/webhooks/typeform', async (req, res) => {
  // Verifica la firma del webhook
  const signature = req.headers['typeform-signature'];
  const isValid = verifyTypeformSignature(
    req.rawBody, signature, process.env.TYPEFORM_WEBHOOK_SECRET
  );

  if (!isValid) return res.status(401).send('Unauthorized');

  const { form_response } = req.body;

  await tajo.connectors.handleWebhook('typeform', {
    topic: 'form_response',
    payload: form_response
  });

  res.status(200).send('OK');
});
```

## Limiti di rate

| Endpoint | Rate limit | Note |
| --- | --- | --- |
| Create API | 2 richieste/sec | Creazione e aggiornamento form |
| Responses API | 2 richieste/sec | Recupero risposte |
| Webhooks API | 2 richieste/sec | Gestione webhook |
| Tutti gli endpoint | 120 richieste/min | Rate limit globale |

Paginazione delle risposte

La Responses API restituisce un massimo di 1.000 risposte per richiesta. Usa i parametri cursor `before` o `after` per la paginazione quando recuperi set di risposte grandi.

## Risoluzione dei problemi

| Problema | Causa | Soluzione |
| --- | --- | --- |
| Webhook non ricevuto | Webhook disabilitato | Abilita il webhook nella dashboard Typeform |
| Risposte mancanti | Filtro applicato | Controlla i parametri `since`/`until` e `completed` |
| Errore auth 401 | Token scaduto | Genera un nuovo Personal Access Token |
| Rate limit 429 | Troppe richieste | Implementa throttling delle richieste |
| Risposte vuote | Campi opzionali | Gestisci valori di risposta null/undefined |

### Modalità debug

```yaml
connectors:
  typeform:
    debug: true
    log_level: verbose
    log_webhooks: true
    log_responses: true
```

## Best practice

1. **Usa i webhook** - Preferisci i webhook al polling per la cattura delle risposte in real-time
2. **Valida le firme** - Verifica sempre le firme dei webhook per sicurezza
3. **Usa gli Hidden Fields** - Pre-popola i dati cliente conosciuti nei form
4. **Mappa i reference dei campi** - Usa valori `ref` stabili invece degli ID dei campi
5. **Gestisci le risposte parziali** - Tieni conto delle domande opzionali e saltate
6. **Imposta la logica di retry** - Implementa l’elaborazione idempotente dei webhook

## Sicurezza

- **OAuth 2.0** - Autenticazione basata su token con scope
- **Firme webhook** - Validazione firma HMAC SHA-256
- **Solo HTTPS** - Tutti gli endpoint API richiedono TLS
- **Scoping del token** - Richiedi gli scope OAuth minimi necessari
- **Gestione dei segreti** - Memorizza i token in variabili d’ambiente o secret manager
- **Conformità GDPR** - Usa la Delete Responses API per richieste di cancellazione dati

## Risorse correlate

- [Connettore Calendly](https://tajo.io/it/docs/connectors/custom/calendly)
- [Connettore Zapier](https://tajo.io/it/docs/connectors/custom/zapier)
- [Skill Customer Sync](https://tajo.io/it/docs/skills/data-sync/customer-sync)
- [Documentazione Typeform Developer](https://www.typeform.com/developers/)