--- title: "Conector Typeform" description: "Guia completo de integração do Typeform para sincronizar respostas de formulários, pesquisas e coleta de dados conversacional com o Brevo através do Tajo." url: https://tajo.io/pt/docs/connectors/custom/typeform/ markdown: https://tajo.io/pt/docs/connectors/custom/typeform.md lang: pt-BR robots: noindex --- Solicite acesso antecipado Indique o seu nome e endereço de e-mail profissional. Enviaremos um link para confirmar o seu pedido de acesso ao Tajo. # Conector Typeform Status do conector: Planejado Ainda não construído. O Tajo não executa este conector hoje. | Campo de origem | Campo de destino | Valor de exemplo | | --- | --- | --- | | `record.id` | `source_id` | `record_1042` | | `record.updated_at` | `updated_at` | `2026-10-18T08:00:00Z` | | `record.value` | `value` | `sample_value` | Conecte o Typeform ao Brevo através do Tajo para sincronizar automaticamente respostas de formulários, capturar leads de formulários conversacionais e disparar automações de marketing com base em envios de pesquisas e resultados de quizzes. ## Visão geral | Propriedade | Valor | | --- | --- | | **Plataforma** | Typeform | | **Categoria** | Formulários e Pesquisas (Personalizado) | | **Complexidade de configuração** | Fácil | | **Integração oficial** | Não | | **Dados sincronizados** | Respostas, Contatos, Eventos, Formulários | | **Método de autenticação** | OAuth 2.0 / Personal Access Token | ## Recursos - **Sincronização de respostas em tempo real** - Capture automaticamente envios de formulário via webhooks - **Criação de contatos** - Crie ou atualize contatos do Brevo a partir de respostas de formulário - **Lead scoring** - Use pontuações de quiz e dados de formulário para qualificação de leads - **Hidden Fields** - Passe dados do cliente via Hidden Fields para formulários personalizados - **Mapeamento condicional** - Mapeie diferentes campos de formulário com base na lógica de resposta - **Suporte a múltiplos formulários** - Conecte múltiplos typeforms a diferentes listas do Brevo ## Pré-requisitos Antes de começar, certifique-se de ter: 1. Uma conta Typeform (plano Basic ou superior para webhooks) 2. Um Personal Access Token em [Configurações da Conta Typeform](https://admin.typeform.com/account#/section/tokens) 3. Uma conta Brevo com acesso à API 4. Uma conta Tajo com permissões de conector ## Autenticação ### 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' }) }); ``` ## Configuração ### Configuração 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}" ``` ### Mapeamento 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 da API | Endpoint | Método | Descrição | | --- | --- | --- | | `https://api.typeform.com/forms` | GET | Listar todos os formulários | | `https://api.typeform.com/forms/{form_id}` | GET | Recuperar um formulário | | `https://api.typeform.com/forms` | POST | Criar um formulário | | `https://api.typeform.com/forms/{form_id}` | PUT | Atualizar um formulário | | `https://api.typeform.com/forms/{form_id}/responses` | GET | Recuperar respostas | | `https://api.typeform.com/forms/{form_id}/responses` | DELETE | Excluir respostas | | `https://api.typeform.com/forms/{form_id}/webhooks/{tag}` | PUT | Criar/atualizar webhook | | `https://api.typeform.com/forms/{form_id}/webhooks/{tag}` | GET | Obter webhook | | `https://api.typeform.com/forms/{form_id}/webhooks` | GET | Listar webhooks | ## Exemplos de código ### Inicializar o 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'] }); ``` ### Recuperar respostas de formulário ```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 O endereço `example.com` acima é um exemplo provisório até que o endpoint da Tajo esteja disponível. ### Tratar 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'); }); ``` ## Limites de taxa | Endpoint | Limite de taxa | Observações | | --- | --- | --- | | Create API | 2 requisições/seg | Criação e atualizações de formulário | | Responses API | 2 requisições/seg | Recuperação de respostas | | Webhooks API | 2 requisições/seg | Gerenciamento de webhooks | | Todos os endpoints | 120 requisições/min | Limite global de taxa | Paginação de respostas A Responses API retorna no máximo 1.000 respostas por requisição. Use os parâmetros de cursor `before` ou `after` para paginação ao recuperar grandes conjuntos de respostas. ## Solução de problemas | Problema | Causa | Solução | | --- | --- | --- | | Webhook não recebido | Webhook desabilitado | Habilite o webhook no painel do Typeform | | Respostas ausentes | Filtro aplicado | Verifique os parâmetros `since`/`until` e `completed` | | Erro de autenticação 401 | Token expirado | Gere um novo Personal Access Token | | Limite de taxa 429 | Muitas requisições | Implemente throttling de requisições | | Respostas vazias | Campos opcionais | Trate valores null/undefined de respostas | ### Modo de depuração ```yaml connectors: typeform: debug: true log_level: verbose log_webhooks: true log_responses: true ``` ## Melhores práticas 1. **Use webhooks** - Prefira webhooks em vez de polling para captura de respostas em tempo real 2. **Valide assinaturas** - Sempre verifique assinaturas de webhook por segurança 3. **Use Hidden Fields** - Pré-preencha dados conhecidos do cliente em formulários 4. **Mapeie referências de campo** - Use valores `ref` estáveis em vez de IDs de campo 5. **Trate respostas parciais** - Considere perguntas opcionais e puladas 6. **Configure lógica de retry** - Implemente processamento idempotente de webhooks ## Segurança - **OAuth 2.0** - Autenticação baseada em token com escopo definido - **Assinaturas de webhook** - Validação de assinatura HMAC SHA-256 - **Somente HTTPS** - Todos os endpoints da API requerem TLS - **Escopo de token** - Solicite escopos OAuth mínimos necessários - **Gerenciamento de secrets** - Armazene tokens em variáveis de ambiente ou gerenciadores de secrets - **Conformidade com GDPR** - Use a Delete Responses API para solicitações de exclusão de dados ## Recursos relacionados - [Conector Calendly](https://tajo.io/pt/docs/connectors/custom/calendly) - [Conector Zapier](https://tajo.io/pt/docs/connectors/custom/zapier) - [Skill de sincronização de clientes](https://tajo.io/pt/docs/skills/data-sync/customer-sync) - [Documentação para desenvolvedores do Typeform](https://www.typeform.com/developers/)