--- title: "Typeform конектор" description: "Пълно ръководство за интеграция с Typeform за синхронизация на отговори от форми, анкети и разговорно събиране на данни с Brevo през Tajo." url: https://tajo.io/bg/docs/connectors/custom/typeform/ markdown: https://tajo.io/bg/docs/connectors/custom/typeform.md lang: bg-BG robots: noindex --- Заявете ранен достъп Въведете собственото си име и служебен имейл адрес. Ще ви изпратим връзка за потвърждение на заявката за достъп до Tajo. # Typeform конектор Статус на конектора: Планиран Все още не е изграден. Tajo не изпълнява този конектор днес. | Поле източник | Целево поле | Примерна стойност | | --- | --- | --- | | `record.id` | `source_id` | `record_1042` | | `record.updated_at` | `updated_at` | `2026-10-18T08:00:00Z` | | `record.value` | `value` | `sample_value` | Свържи Typeform с Brevo през Tajo, за да синхронизираш автоматично отговори от форми, да улавяш lead-и от разговорни форми и да задействаш маркетингови автоматизации на базата на изпращания на анкети и резултати от quizове. ## Преглед | Свойство | Стойност | | --- | --- | | **Платформа** | Typeform | | **Категория** | Форми и анкети (персонализирана) | | **Сложност на настройка** | Лесна | | **Официална интеграция** | Не | | **Синхронизирани данни** | Отговори, контакти, събития, форми | | **Метод на автентикация** | OAuth 2.0 / Personal Access Token | ## Функции - **Синхронизация на отговори в реално време** – Автоматично улавяй изпращания на форми чрез уебхуци - **Създаване на контакти** – Създавай или обновявай контакти в Brevo от отговори на форми - **Lead scoring** – Използвай резултати от quizове и данни от форми за квалификация на lead-и - **Hidden Fields** – Предавай клиентски данни чрез Hidden Fields за персонализирани форми - **Условно мапване** – Мапвай различни полета от форми на базата на логика на отговорите - **Поддръжка на множество форми** – Свързвай множество typeform-и към различни списъци в Brevo ## Предварителни условия Преди да започнеш, увери се, че имаш: 1. Акаунт в Typeform (Basic план или по-горе за уебхуци) 2. Personal Access Token от [Typeform Account Settings](https://admin.typeform.com/account#/section/tokens) 3. Акаунт в Brevo с API достъп 4. Акаунт в Tajo с разрешения за конектори ## Автентикация ### 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' }) }); ``` ## Конфигурация ### Основна настройка ```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}" ``` ### Мапване на полета ```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 ``` ## API крайни точки | Крайна точка | Метод | Описание | | --- | --- | --- | | `https://api.typeform.com/forms` | GET | Списък с всички форми | | `https://api.typeform.com/forms/{form_id}` | GET | Получаване на форма | | `https://api.typeform.com/forms` | POST | Създаване на форма | | `https://api.typeform.com/forms/{form_id}` | PUT | Обновяване на форма | | `https://api.typeform.com/forms/{form_id}/responses` | GET | Получаване на отговори | | `https://api.typeform.com/forms/{form_id}/responses` | DELETE | Изтриване на отговори | | `https://api.typeform.com/forms/{form_id}/webhooks/{tag}` | PUT | Създаване/обновяване на уебхук | | `https://api.typeform.com/forms/{form_id}/webhooks/{tag}` | GET | Получаване на уебхук | | `https://api.typeform.com/forms/{form_id}/webhooks` | GET | Списък с уебхуци | ## Примери с код ### Инициализация на конектора ```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'] }); ``` ### Получаване на отговори от форма ```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] }); } } ``` ### Настройка на уебхуци ```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 Адресът `example.com` по-горе е временен пример, докато крайната точка на Tajo стане достъпна. ### Обработка на уебхук събития ```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'); }); ``` ## Ограничения на заявките | Крайна точка | Rate Limit | Бележки | | --- | --- | --- | | Create API | 2 заявки/сек | Създаване и обновяване на форми | | Responses API | 2 заявки/сек | Извличане на отговори | | Webhooks API | 2 заявки/сек | Управление на уебхуци | | Всички крайни точки | 120 заявки/мин | Глобален rate limit | Пагинация на отговорите Responses API връща максимум 1 000 отговора на заявка. Използвай параметрите за курсор `before` или `after` за пагинация при извличане на големи набори от отговори. ## Отстраняване на проблеми | Проблем | Причина | Решение | | --- | --- | --- | | Уебхукът не се получава | Уебхукът е деактивиран | Активирай уебхука в Typeform dashboard | | Липсващи отговори | Приложен филтър | Провери параметрите `since`/`until` и `completed` | | Грешка 401 при автентикация | Token изтекъл | Генерирай нов Personal Access Token | | Rate limit 429 | Твърде много заявки | Внедри throttling на заявките | | Празни отговори | Опционални полета | Обработвай null/undefined стойности на отговорите | ### Режим за дебъг ```yaml connectors: typeform: debug: true log_level: verbose log_webhooks: true log_responses: true ``` ## Добри практики 1. **Използвай уебхуци** – Предпочитай уебхуци пред polling за улавяне на отговори в реално време 2. **Валидирай подписите** – Винаги верифицирай подписите на уебхуци за сигурност 3. **Използвай Hidden Fields** – Предварително попълни известни клиентски данни във формите 4. **Мапвай field references** – Използвай стабилни стойности `ref` на полета вместо field IDs 5. **Обработвай частични отговори** – Съобрази се с опционални и пропуснати въпроси 6. **Настрой retry логика** – Внедри идемпотентна обработка на уебхуци ## Сигурност - **OAuth 2.0** – Scoped token-базирана автентикация - **Подписи на уебхуци** – SHA-256 HMAC валидация на подпис - **Само HTTPS** – Всички API крайни точки изискват TLS - **Token scoping** – Заявявай минимално необходимите OAuth обхвати - **Управление на тайни** – Съхранявай tokens в environment variables или secret managers - **GDPR съвместимост** – Използвай Delete Responses API за заявки за изтриване на данни ## Свързани ресурси - [Calendly конектор](https://tajo.io/bg/docs/connectors/custom/calendly) - [Zapier конектор](https://tajo.io/bg/docs/connectors/custom/zapier) - [Customer Sync скил](https://tajo.io/bg/docs/skills/data-sync/customer-sync) - [Typeform Developer документация](https://www.typeform.com/developers/)