Connettore Pipedrive

Connettore Pipedrive

Collega Pipedrive a Brevo tramite Tajo per unire la tua sales pipeline all’automazione marketing. Sincronizza contatti, deal, organizzazioni e attività per alimentare campagne di lifecycle attivate dai cambiamenti di stage del CRM.

Panoramica

Funzionalità

• Sync contatti - Sincronizzazione bidirezionale delle persone Pipedrive con i contatti Brevo
• Tracciamento stage deal - Attiva automazioni Brevo basate sui cambiamenti di stage della pipeline
• Sync organizzazioni - Mappa le organizzazioni Pipedrive agli attributi azienda di Brevo
• Tracciamento attività - Inoltra le attività Pipedrive (chiamate, email, riunioni) come eventi Brevo
• Campi personalizzati - Mappa i campi personalizzati Pipedrive agli attributi di contatto Brevo
• Reportistica pipeline - Estrai i dati della pipeline deal per l’attribuzione marketing
• Sync lead - Importa i lead Pipedrive in Brevo per le campagne di nurture
• Automazione webhook - Aggiornamenti in tempo reale tramite i webhook di Pipedrive

Prerequisiti

Prima di iniziare, assicurati di avere:

1. Un account Pipedrive con accesso admin
2. Il tuo Pipedrive API Token (lo trovi in Settings > Personal preferences > API)
3. Per le app OAuth: un’app Pipedrive registrata con Client ID e Client Secret
4. Un account Brevo con accesso API
5. Un account Tajo con credenziali API

Autenticazione

API Token

Il metodo di autenticazione più semplice. Trova il tuo API Token in Pipedrive sotto Settings > Personal preferences > API.

curl "https://api.pipedrive.com/v1/persons?api_token=YOUR_API_TOKEN"

OAuth 2.0 (consigliato per le app)

Per le applicazioni in produzione, usa OAuth 2.0:

# Authorization URL
https://oauth.pipedrive.com/oauth/authorize?client_id=CLIENT_ID&redirect_uri=REDIRECT_URI

# Token exchange
curl -X POST https://oauth.pipedrive.com/oauth/token \
  -d "grant_type=authorization_code" \
  -d "code=AUTH_CODE" \
  -d "redirect_uri=REDIRECT_URI" \
  -u "CLIENT_ID:CLIENT_SECRET"

Dopo aver ottenuto l’access token:

curl "https://api.pipedrive.com/v1/persons" \
  -H "Authorization: Bearer ACCESS_TOKEN"

Configurazione

Setup di base

connectors:
  pipedrive:
    enabled: true
    api_token: "your-pipedrive-api-token"
    company_domain: "yourcompany"  # yourcompany.pipedrive.com

    # Data sync options
    sync:
      persons: true
      deals: true
      organizations: true
      activities: true
      leads: true

    # Brevo list assignment
    lists:
      all_contacts: 60
      qualified_leads: 61
      customers: 62
      churned: 63

Mappatura campi persona

Mappa i campi persona di Pipedrive agli attributi di contatto Brevo:

person_mapping:
  email: email
  name: FULLNAME
  first_name: FIRSTNAME
  last_name: LASTNAME
  phone: SMS
  org_id.name: COMPANY

  # Deal-related computed fields
  won_deals_count: WON_DEALS
  lost_deals_count: LOST_DEALS
  open_deals_count: OPEN_DEALS
  closed_deals_count: CLOSED_DEALS
  total_revenue: LTV

  # Custom fields (use Pipedrive field key)
  custom_fields.lead_source: LEAD_SOURCE
  custom_fields.industry: INDUSTRY
  custom_fields.company_size: COMPANY_SIZE

Mappatura stage deal

Mappa gli stage della pipeline Pipedrive alle assegnazioni di liste Brevo:

deal_stage_mapping:
  # stage_id -> brevo_list_id
  1: 61   # Lead In
  2: 61   # Contact Made
  3: 62   # Proposal Made
  4: 62   # Negotiations Started
  "won": 63   # Won -> Customers list
  "lost": 64   # Lost -> Win-back list

Configurazione webhook

webhooks:
  - event_action: "added"
    event_object: "person"
    brevo_event: "contact_created"
  - event_action: "updated"
    event_object: "person"
    brevo_event: "contact_updated"
  - event_action: "added"
    event_object: "deal"
    brevo_event: "deal_created"
  - event_action: "updated"
    event_object: "deal"
    brevo_event: "deal_updated"
  - event_action: "merged"
    event_object: "person"
    brevo_event: "contact_merged"
  - event_action: "added"
    event_object: "activity"
    brevo_event: "activity_logged"

Endpoint API

Esempi di codice

Inizializza il connettore Pipedrive

import { TajoClient } from '@tajo/sdk';

const tajo = new TajoClient({
  apiKey: process.env.TAJO_API_KEY,
  brevoApiKey: process.env.BREVO_API_KEY
});

// Connect Pipedrive account
await tajo.connectors.connect('pipedrive', {
  apiToken: process.env.PIPEDRIVE_API_TOKEN,
  companyDomain: 'yourcompany'
});

Sincronizza le persone con Brevo

// Fetch persons from Pipedrive
const response = await fetch(
  `https://api.pipedrive.com/v1/persons?start=0&limit=100&api_token=${API_TOKEN}`
);

const { data, additional_data } = await response.json();
// data: [{ id, name, first_name, last_name, email, phone, org_id, ... }]
// additional_data.pagination: { start, limit, more_items_in_collection }

Traccia cambiamenti di stage deal

// Webhook handler for deal updates
app.post('/webhooks/pipedrive', async (req, res) => {
  const { meta, current, previous } = req.body;

  if (meta.object === 'deal' && meta.action === 'updated') {
    // Detect stage change
    if (current.stage_id !== previous.stage_id) {
      await tajo.connectors.handleWebhook('pipedrive', {
        topic: 'deal.stage_changed',
        payload: {
          dealId: current.id,
          dealTitle: current.title,
          previousStage: previous.stage_id,
          newStage: current.stage_id,
          personId: current.person_id,
          value: current.value,
          currency: current.currency
        }
      });
    }
  }

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

Ricerca globale in Pipedrive

// Global search across persons, deals, and organizations
const query = encodeURIComponent('[email protected]');
const response = await fetch(
  `https://api.pipedrive.com/v1/itemSearch?term=${query}&item_types=person,deal&api_token=${API_TOKEN}`
);

const { data } = await response.json();
// Returns matching persons, deals, and organizations

Limiti di velocità

Limiti aggiuntivi:

Risoluzione dei problemi

Best practice

1. Usa OAuth per la produzione - Preferisci OAuth 2.0 agli API token per le applicazioni in produzione
2. Traccia i cambiamenti di stage deal - Usa i webhook per attivare automazioni Brevo sulle transizioni di stage
3. Mappa i campi personalizzati - Usa le field key di Pipedrive (non i nomi) per una mappatura affidabile
4. Gestisci la paginazione - Usa i parametri start e limit; controlla more_items_in_collection
5. Usa l’endpoint Recents - Interroga /v1/recents per sync incrementali invece di export completi
6. Deduplica prima della sync - Unisci le persone duplicate in Pipedrive prima di sincronizzare con Brevo
7. Usa account sandbox - Crea un account developer sandbox per testare le integrazioni

Sicurezza

• Autenticazione API token - Accesso semplice basato su token per uso personale
• OAuth 2.0 - Accesso delegato sicuro per applicazioni di terze parti
• Solo HTTPS - Tutte le comunicazioni API richiedono cifratura TLS
• Webhook HTTPS - I webhook vengono consegnati solo a endpoint HTTPS
• Accesso basato sui ruoli - I permessi Pipedrive rispettano i ruoli utente
• Certificazione SOC 2 - Pipedrive mantiene la conformità SOC 2
• Conformità GDPR - Supporta export dati e richieste di cancellazione

Risorse correlate

• Connettore Brevo
• Connettore Shopify
• Skill Customer Sync
• API Contatti Brevo