---
title: "Connettore Freshdesk"
description: "Guida completa all'integrazione di Freshdesk per sincronizzare ticket di supporto, contatti e dati degli agent con Brevo tramite Tajo."
url: https://tajo.io/it/docs/connectors/support/freshdesk/
markdown: https://tajo.io/it/docs/connectors/support/freshdesk.md
lang: it-IT
robots: noindex
---

Richiedi l’accesso anticipato

Inserisci il tuo nome e indirizzo email aziendale. Ti invieremo un link per confermare la richiesta di accesso a Tajo.

# Connettore Freshdesk

Stato del connettore: Pianificato Non ancora realizzato. Oggi Tajo non esegue questo connettore.

| Campo di origine | Campo di destinazione | Valore di esempio |
| --- | --- | --- |
| `record.id` | `source_id` | `record_1042` |
| `record.updated_at` | `updated_at` | `2026-10-18T08:00:00Z` |
| `record.value` | `value` | `sample_value` |

Collega Freshdesk a Brevo tramite Tajo per unificare i dati di supporto e marketing. Sincronizza ticket di supporto clienti, profili contatto e punteggi di soddisfazione per alimentare comunicazioni mirate basate sulle interazioni di supporto.

## Panoramica

| Proprietà | Valore |
| --- | --- |
| **Piattaforma** | Freshdesk |
| **Categoria** | Supporto |
| **Complessità di setup** | Facile |
| **Integrazione ufficiale** | No |
| **Dati sincronizzati** | Ticket, Contatti, Agent, Aziende |
| **Skill disponibili** | 6 |

## Funzionalità

- **Sync dei contatti** - Sync bidirezionale dei contatti Freshdesk alle liste contatti Brevo
- **Tracciamento eventi ticket** - Inoltra eventi di creazione, aggiornamento e risoluzione ticket a Brevo
- **Sync CSAT** - Sincronizza i punteggi di soddisfazione clienti come attributi di contatto Brevo
- **Sync delle aziende** - Mappa le aziende Freshdesk alla segmentazione contatti Brevo
- **Dati agent** - Traccia le assegnazioni agent per l’automazione del workflow interno
- **Campi personalizzati** - Mappa i campi personalizzati di ticket e contatto Freshdesk agli attributi Brevo

## Prerequisiti

Prima di iniziare, assicurati di avere:

1. Un account Freshdesk con accesso admin
2. La tua chiave API Freshdesk (in Profile Settings)
3. Il tuo dominio Freshdesk (es. `yourcompany.freshdesk.com`)
4. Un account Brevo con accesso API
5. Un account Tajo con credenziali API

## Autenticazione

### Autenticazione con chiave API

Freshdesk utilizza l’autenticazione con chiave API tramite HTTP Basic Auth. La chiave API è usata come username con qualsiasi stringa (tipicamente `X`) come password.

```bash
curl -u "YOUR_API_KEY:X" \
  https://yourcompany.freshdesk.com/api/v2/tickets
```

Oppure usando la codifica Base64 nell’header Authorization:

```bash
curl https://yourcompany.freshdesk.com/api/v2/tickets \
  -H "Authorization: Basic BASE64_ENCODED_API_KEY:X" \
  -H "Content-Type: application/json"
```

### Trovare la tua chiave API

1. Accedi al tuo account Freshdesk
2. Clicca sull’immagine del tuo profilo nell’angolo in alto a destra
3. Vai in **Profile Settings**
4. La tua chiave API è visualizzata sul lato destro

## Configurazione

### Setup di base

```yaml
connectors:
  freshdesk:
    enabled: true
    domain: "yourcompany.freshdesk.com"
    api_key: "your-freshdesk-api-key"

    # Data sync options
    sync:
      contacts: true
      tickets: true
      companies: true
      satisfaction_ratings: true

    # Brevo list assignment
    lists:
      all_support_contacts: 30
      open_tickets: 31
      resolved_tickets: 32
```

### Mappatura dei campi contatto

Mappa i campi di contatto Freshdesk agli attributi Brevo:

```yaml
contact_mapping:
  email: email
  name: FULLNAME
  phone: SMS
  company_id: COMPANY
  job_title: JOB_TITLE
  twitter_id: TWITTER
  language: LANGUAGE
  time_zone: TIMEZONE

  # Support metrics
  total_tickets: TICKET_COUNT
  open_tickets: OPEN_TICKETS
  avg_csat: CSAT_SCORE
  last_ticket_date: LAST_SUPPORT_DATE

  # Custom fields
  custom_fields.account_type: ACCOUNT_TYPE
  custom_fields.subscription_tier: PLAN
```

### Mappatura eventi ticket

Mappa gli eventi ticket Freshdesk ai trigger di automazione Brevo:

```yaml
ticket_events:
  ticket_created: "support_ticket_created"
  ticket_updated: "support_ticket_updated"
  ticket_resolved: "support_ticket_resolved"
  ticket_closed: "support_ticket_closed"
  ticket_reopened: "support_ticket_reopened"
  satisfaction_rated: "csat_submitted"
  note_added: "support_note_added"
```

## Endpoint API

| Metodo | Endpoint | Descrizione |
| --- | --- | --- |
| `GET` | `/api/v2/tickets` | Elenca tutti i ticket |
| `POST` | `/api/v2/tickets` | Crea un ticket |
| `GET` | `/api/v2/tickets/{id}` | Ottieni un ticket specifico |
| `PUT` | `/api/v2/tickets/{id}` | Aggiorna un ticket |
| `DELETE` | `/api/v2/tickets/{id}` | Elimina un ticket |
| `GET` | `/api/v2/contacts` | Elenca tutti i contatti |
| `POST` | `/api/v2/contacts` | Crea un contatto |
| `PUT` | `/api/v2/contacts/{id}` | Aggiorna un contatto |
| `GET` | `/api/v2/companies` | Elenca tutte le aziende |
| `GET` | `/api/v2/agents` | Elenca tutti gli agent |
| `GET` | `/api/v2/surveys/satisfaction_ratings` | Elenca le valutazioni CSAT |
| `GET` | `/api/v2/search/tickets?query=` | Cerca ticket |

## Esempi di codice

### Inizializza il connettore Freshdesk

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

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

// Connect Freshdesk account
await tajo.connectors.connect('freshdesk', {
  domain: 'yourcompany.freshdesk.com',
  apiKey: process.env.FRESHDESK_API_KEY
});
```

### Sincronizza i contatti su Brevo

```javascript
// Fetch Freshdesk contacts and sync to Brevo
const response = await fetch(
  'https://yourcompany.freshdesk.com/api/v2/contacts?page=1&per_page=100',
  {
    headers: {
      'Authorization': 'Basic ' + btoa(`${API_KEY}:X`),
      'Content-Type': 'application/json'
    }
  }
);

const contacts = await response.json();
// Each contact:
// {
//   "id": 12345,
//   "name": "Jane Kim",
//   "email": "jane@example.com",
//   "phone": "+15551234567",
//   "company_id": 678,
//   "job_title": "Product Manager",
//   "created_at": "2024-01-15T10:30:00Z"
// }
```

### Traccia eventi ticket

```javascript
// Set up Freshdesk webhook to forward ticket events
// Configure in Freshdesk Admin > Automations > Webhook

// Webhook handler
app.post('/webhooks/freshdesk', async (req, res) => {
  const { ticket, event_type } = req.body;

  await tajo.connectors.handleWebhook('freshdesk', {
    topic: event_type,
    payload: {
      ticketId: ticket.id,
      subject: ticket.subject,
      status: ticket.status,
      priority: ticket.priority,
      requesterEmail: ticket.requester.email,
      createdAt: ticket.created_at
    }
  });

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

### Cerca ticket per cliente

```javascript
// Search for all tickets from a specific customer
const query = encodeURIComponent('"email:jane@example.com"');
const response = await fetch(
  `https://yourcompany.freshdesk.com/api/v2/search/tickets?query=${query}`,
  {
    headers: {
      'Authorization': 'Basic ' + btoa(`${API_KEY}:X`)
    }
  }
);

const { results, total } = await response.json();
```

## Limiti di velocità

| Piano | Limite | Dettagli |
| --- | --- | --- |
| **Sprout** | 50 richieste/min | Piano gratuito |
| **Blossom** | 200 richieste/min | Piano Starter |
| **Garden** | 400 richieste/min | Piano Growth |
| **Estate** | 700 richieste/min | Piano Pro |
| **Forest** | 1.000 richieste/min | Piano Enterprise |

Limiti aggiuntivi:

| Risorsa | Limite |
| --- | --- |
| **Endpoint elenco** | 30 pagine per query |
| **Per pagina** | Massimo 100 record |
| **Search API** | 2 richieste/sec |
| **Operazioni bulk** | 10 record/richiesta |

Header dei limiti di velocità

Freshdesk restituisce le informazioni sui limiti di velocità negli header di risposta. Monitora `X-RateLimit-Remaining` e implementa il backoff quando ti avvicini ai limiti.

## Risoluzione dei problemi

| Problema | Causa | Soluzione |
| --- | --- | --- |
| `401 Unauthorized` | Chiave API non valida | Verifica la chiave API in Freshdesk Profile Settings |
| `403 Forbidden` | Permessi insufficienti | Assicurati che la chiave API appartenga a un account admin |
| Contatti non sincronizzati | Campo email mancante | I contatti Freshdesk richiedono un indirizzo email |
| Ticket non visualizzati | Dominio errato | Verifica che l’URL del tuo dominio Freshdesk sia corretto |
| Ricerca restituisce vuoto | Errore di sintassi della query | Usa la sintassi di query Freshdesk con doppie virgolette |
| `429 Too Many Requests` | Limite di velocità superato | Implementa il rate limiting basato sul tier del piano |
| Campi personalizzati mancanti | Campo non abilitato | Assicurati che i campi personalizzati siano abilitati in Freshdesk admin |

## Best practice

1. **Usa i webhook per la sync in tempo reale** - Configura le Automations Freshdesk per attivare webhook su eventi ticket
2. **Sincronizza i punteggi CSAT** - Traccia le valutazioni di soddisfazione clienti come attributi Brevo per la segmentazione
3. **Mappa lo stato del ticket alle liste** - Sposta automaticamente i contatti tra liste Brevo in base allo stato del ticket
4. **Traccia le metriche di supporto** - Sincronizza conteggio ticket, tempo medio di risposta e tasso di risoluzione per contatto
5. **Usa la search API con parsimonia** - La search API ha limiti di velocità più stringenti; metti in cache i risultati quando possibile
6. **Pagina le esportazioni grandi** - Usa la paginazione con i parametri `page` e `per_page` per la sync iniziale

## Sicurezza

- **Autenticazione con chiave API** - HTTP Basic Auth semplice con chiave API
- **Solo HTTPS** - Tutte le comunicazioni API richiedono cifratura TLS
- **IP whitelisting** - Disponibile sui piani Estate e Forest
- **Accesso basato sui ruoli** - Permessi della chiave API legati al ruolo agent
- **SOC 2 Type II** - Freshdesk è certificato SOC 2 Type II
- **Conformità GDPR** - Supporta richieste di esportazione ed eliminazione dati

## Risorse correlate

- [Connettore Brevo](https://tajo.io/it/docs/connectors/marketing/brevo)
- [Skill Customer Sync](https://tajo.io/it/docs/skills/data-sync/customer-sync)
- [Connettore Shopify](https://tajo.io/it/docs/connectors/ecommerce/shopify)
- [API Contatti Brevo](https://tajo.io/it/docs/contact-management)