Typeform konektor
Poveži Typeform sa Brevo putem Tajo da automatski sinhronizuješ odgovore na formulare, hvataj potencijalne kupce iz konverzacionih formulara i pokreći marketing automatizacije na osnovu slanja anketa i rezultata kvizova.
Pregled
| Svojstvo | Vrednost |
|---|---|
| Platforma | Typeform |
| Kategorija | Formulari i ankete (Prilagođeno) |
| Složenost podešavanja | Lako |
| Zvanična integracija | Ne |
| Sinhronizovani podaci | Odgovori, Kontakti, Događaji, Formulari |
| Metod autentifikacije | OAuth 2.0 / Personal Access Token |
Karakteristike
- Sinhronizacija odgovora u realnom vremenu - Automatsko hvatanje slanja formulara putem webhook-ova
- Kreiranje kontakata - Kreiranje ili ažuriranje Brevo kontakata iz odgovora na formulare
- Ocenjivanje potencijalnih kupaca - Korišćenje rezultata kvizova i podataka formulara za kvalifikaciju potencijalnih kupaca
- Skrivena polja - Prosleđivanje podataka kupaca putem skrivenih polja za personalizovane formulare
- Uslovno mapiranje - Mapiranje različitih polja formulara prema logici odgovora
- Podrška za više formulara - Povezivanje više typeforma na različite Brevo liste
Preduslovi
Pre nego što započneš, proveri da imaš:
- Typeform nalog (Basic plan ili viši za webhook-ove)
- Personal Access Token iz Typeform Account Settings
- Brevo nalog sa API pristupom
- Tajo nalog sa dozvolama konektora
Autentifikacija
Personal Access Token
# Generate a token at https://admin.typeform.com/account#/section/tokensexport TYPEFORM_ACCESS_TOKEN=tfp_your_personal_access_tokenexport TAJO_API_KEY=your_tajo_api_keyexport BREVO_API_KEY=your_brevo_api_keyOAuth 2.0
// OAuth 2.0 Authorization Flowconst 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 tokenconst 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' })});Konfiguracija
Osnovno podešavanje
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}"Mapiranje polja
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_FEEDBACKAPI endpointi
| Endpoint | Metoda | Opis |
|---|---|---|
https://api.typeform.com/forms | GET | Listanje svih formulara |
https://api.typeform.com/forms/{form_id} | GET | Dohvatanje formulara |
https://api.typeform.com/forms | POST | Kreiranje formulara |
https://api.typeform.com/forms/{form_id} | PUT | Ažuriranje formulara |
https://api.typeform.com/forms/{form_id}/responses | GET | Dohvatanje odgovora |
https://api.typeform.com/forms/{form_id}/responses | DELETE | Brisanje odgovora |
https://api.typeform.com/forms/{form_id}/webhooks/{tag} | PUT | Kreiranje/ažuriranje webhook-a |
https://api.typeform.com/forms/{form_id}/webhooks/{tag} | GET | Dohvatanje webhook-a |
https://api.typeform.com/forms/{form_id}/webhooks | GET | Listanje webhook-ova |
Primeri koda
Inicijalizacija konektora
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']});Dohvatanje odgovora na formulare
// Fetch responses using the Responses APIconst 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 Brevofor (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] }); }}Podešavanje webhook-ova
// Register a webhook for real-time response notificationsawait 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.tajo.io/webhooks/typeform', enabled: true, secret: process.env.TYPEFORM_WEBHOOK_SECRET }) });Obrada webhook događaja
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');});Ograničenja brzine
| Endpoint | Ograničenje brzine | Napomene |
|---|---|---|
| Create API | 2 zahteva/sek | Kreiranje i ažuriranje formulara |
| Responses API | 2 zahteva/sek | Dohvatanje odgovora |
| Webhooks API | 2 zahteva/sek | Upravljanje webhook-ovima |
| Svi endpointi | 120 zahteva/min | Globalno ograničenje brzine |
Paginacija odgovora
Responses API vraća maksimalno 1.000 odgovora po zahtevu. Koristi parametre kursora before ili after za paginaciju pri dohvatanju velikih skupova odgovora.
Rešavanje problema
| Problem | Uzrok | Rešenje |
|---|---|---|
| Webhook nije primljen | Webhook onemogućen | Omogući webhook u Typeform dashboard-u |
| Nedostaju odgovori | Primenjen filter | Proveri parametre since/until i completed |
| Greška autentifikacije 401 | Token istekao | Generiši novi Personal Access Token |
| Ograničenje brzine 429 | Previše zahteva | Implementiraj prigušivanje zahteva |
| Prazni odgovori | Opcijska polja | Obradi null/undefined vrednosti odgovora |
Debug režim
connectors: typeform: debug: true log_level: verbose log_webhooks: true log_responses: trueNajbolje prakse
- Koristi webhook-ove - Preferiraj webhook-ove umesto ispitivanja za hvatanje odgovora u realnom vremenu
- Validiraj potpise - Uvek verifikuj potpise webhook-ova radi bezbednosti
- Koristi skrivena polja - Unapred popuni poznate podatke o korisniku u formularima
- Mapiraj reference polja - Koristi stabilne vrednosti
refpolja umesto ID-ova polja - Obradi delimične odgovore - Uzmi u obzir opcijska i preskočena pitanja
- Postavi logiku ponovnog pokušaja - Implementiraj idempotentnu obradu webhook-ova
Bezbednost
- OAuth 2.0 - Autentifikacija zasnovana na tokenima sa skopovima
- Potpisi webhook-ova - SHA-256 HMAC validacija potpisa
- Samo HTTPS - Svi API endpointi zahtevaju TLS
- Skopovanje tokena - Zahtevaj minimalne potrebne OAuth skopove
- Upravljanje tajnama - Čuvaj tokene u env varijablama ili menadžerima tajni
- GDPR usklađenost - Koristi Delete Responses API za zahteve za brisanje podataka