--- title: "Conector de Typeform" description: "Guía completa de integración con Typeform para sincronizar respuestas de formulario, encuestas y recolección de datos conversacional con Brevo a través de Tajo." url: https://tajo.io/es/docs/connectors/custom/typeform/ markdown: https://tajo.io/es/docs/connectors/custom/typeform.md lang: es-ES robots: noindex --- Solicita acceso anticipado Escribe tu nombre y dirección de correo de trabajo. Te enviaremos un enlace para confirmar tu solicitud de acceso a Tajo. # Conector de Typeform Estado del conector: Planificado Aún no está construido. Tajo no ejecuta este conector hoy. | Campo de origen | Campo de destino | Valor de ejemplo | | --- | --- | --- | | `record.id` | `source_id` | `record_1042` | | `record.updated_at` | `updated_at` | `2026-10-18T08:00:00Z` | | `record.value` | `value` | `sample_value` | Conecta Typeform con Brevo a través de Tajo para sincronizar automáticamente las respuestas de formularios, capturar leads desde formularios conversacionales y activar automatizaciones de marketing basadas en envíos de encuestas y resultados de cuestionarios. ## Resumen | Propiedad | Valor | | --- | --- | | **Plataforma** | Typeform | | **Categoría** | Formularios y encuestas (Personalizada) | | **Complejidad de configuración** | Fácil | | **Integración oficial** | No | | **Datos sincronizados** | Respuestas, Contactos, Eventos, Formularios | | **Método de autenticación** | OAuth 2.0 / Personal Access Token | ## Funcionalidades - **Sincronización de respuestas en tiempo real** - Captura automáticamente los envíos de formulario vía webhooks - **Creación de contactos** - Crea o actualiza contactos de Brevo a partir de las respuestas de formulario - **Puntuación de leads** - Usa puntuaciones de cuestionarios y datos de formulario para calificar leads - **Hidden Fields** - Transmite datos de cliente vía Hidden Fields para formularios personalizados - **Asignación condicional** - Asocia distintos campos de formulario según la lógica de respuesta - **Soporte multiformulario** - Conecta varios typeforms a distintas listas de Brevo ## Requisitos previos Antes de empezar, asegúrate de tener: 1. Una cuenta de Typeform (plan Basic o superior para webhooks) 2. Un Personal Access Token desde [Typeform Account Settings](https://admin.typeform.com/account#/section/tokens) 3. Una cuenta de Brevo con acceso a la API 4. Una cuenta de Tajo con permisos de conector ## Autenticación ### Personal Access Token ```bash # Generate a token at 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 // OAuth 2.0 Authorization Flow 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() }); // Exchange authorization code for 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' }) }); ``` ## Configuración ### Configuración básica ```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}" ``` ### Asignación de campos ```yaml field_mapping: # Map Typeform field references to Brevo attributes email: email name: FIRSTNAME company: COMPANY phone: SMS score: LEAD_SCORE quiz_result: QUIZ_SCORE nps_rating: NPS_SCORE feedback: LAST_FEEDBACK ``` ## Endpoints de la API | Endpoint | Método | Descripción | | --- | --- | --- | | `https://api.typeform.com/forms` | GET | Listar todos los formularios | | `https://api.typeform.com/forms/{form_id}` | GET | Obtener un formulario | | `https://api.typeform.com/forms` | POST | Crear un formulario | | `https://api.typeform.com/forms/{form_id}` | PUT | Actualizar un formulario | | `https://api.typeform.com/forms/{form_id}/responses` | GET | Obtener respuestas | | `https://api.typeform.com/forms/{form_id}/responses` | DELETE | Eliminar respuestas | | `https://api.typeform.com/forms/{form_id}/webhooks/{tag}` | PUT | Crear/actualizar webhook | | `https://api.typeform.com/forms/{form_id}/webhooks/{tag}` | GET | Obtener webhook | | `https://api.typeform.com/forms/{form_id}/webhooks` | GET | Listar webhooks | ## Ejemplos de código ### Inicializar el conector ```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'] }); ``` ### Obtener respuestas del formulario ```javascript // Fetch responses using the 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(); // Sync each response to 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] }); } } ``` ### Configurar webhooks ```javascript // Register a webhook for real-time response notifications 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 La dirección `example.com` de arriba es un marcador de posición hasta que el endpoint de Tajo esté disponible. ### Gestionar eventos de webhook ```javascript app.post('/webhooks/typeform', async (req, res) => { // Verify webhook signature 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'); }); ``` ## Límites de velocidad | Endpoint | Límite de velocidad | Notas | | --- | --- | --- | | Create API | 2 peticiones/s | Creación y actualización de formularios | | Responses API | 2 peticiones/s | Obtención de respuestas | | Webhooks API | 2 peticiones/s | Gestión de webhooks | | Todos los endpoints | 120 peticiones/min | Límite global de velocidad | Paginación de respuestas La Responses API devuelve como máximo 1.000 respuestas por petición. Usa los parámetros de cursor `before` o `after` para paginar al recuperar grandes conjuntos de respuestas. ## Resolución de problemas | Problema | Causa | Solución | | --- | --- | --- | | Webhook no recibido | Webhook desactivado | Activa el webhook en el panel de Typeform | | Respuestas que faltan | Filtro aplicado | Revisa los parámetros `since`/`until` y `completed` | | Error de autenticación 401 | Token expirado | Genera un nuevo Personal Access Token | | Rate limit 429 | Demasiadas peticiones | Implementa throttling de peticiones | | Respuestas vacías | Campos opcionales | Gestiona valores de respuesta null/undefined | ### Modo depuración ```yaml connectors: typeform: debug: true log_level: verbose log_webhooks: true log_responses: true ``` ## Buenas prácticas 1. **Usa webhooks** - Prefiere los webhooks antes que el polling para capturar respuestas en tiempo real 2. **Valida las firmas** - Verifica siempre las firmas de webhook por seguridad 3. **Usa Hidden Fields** - Prepuebla los formularios con datos de cliente conocidos 4. **Asigna por referencias de campo** - Usa los valores `ref` estables de los campos en lugar de los IDs 5. **Gestiona respuestas parciales** - Ten en cuenta las preguntas opcionales y omitidas 6. **Configura lógica de reintentos** - Implementa un procesamiento idempotente de webhooks ## Seguridad - **OAuth 2.0** - Autenticación basada en token con alcance limitado - **Firmas de webhook** - Validación de firma HMAC SHA-256 - **Solo HTTPS** - Todos los endpoints de la API requieren TLS - **Scoping de tokens** - Solicita los scopes de OAuth mínimos necesarios - **Gestión de secretos** - Guarda los tokens en variables de entorno o gestores de secretos - **Cumplimiento de RGPD** - Usa la Delete Responses API para solicitudes de borrado de datos ## Recursos relacionados - [Conector de Calendly](https://tajo.io/es/docs/connectors/custom/calendly) - [Conector de Zapier](https://tajo.io/es/docs/connectors/custom/zapier) - [Skill de sincronización de clientes](https://tajo.io/es/docs/skills/data-sync/customer-sync) - [Documentación para desarrolladores de Typeform](https://www.typeform.com/developers/)