---
title: "Connettore Zendesk"
description: "Guida completa all'integrazione di Zendesk per sincronizzare ticket, utenti, organizzazioni ed eventi di supporto con Brevo tramite Tajo."
url: https://tajo.io/it/docs/connectors/support/zendesk/
markdown: https://tajo.io/it/docs/connectors/support/zendesk.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 Zendesk

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 la tua istanza Zendesk Support a Brevo tramite Tajo per dati di supporto cliente unificati, segmentazione basata sui ticket, scoring di soddisfazione e marketing automation attivata dal supporto.

## Panoramica

| Proprietà | Valore |
| --- | --- |
| **Piattaforma** | Zendesk |
| **Categoria** | Supporto |
| **Complessità di setup** | Media |
| **Integrazione ufficiale** | Sì |
| **Dati sincronizzati** | Ticket, Utenti, Organizzazioni, Eventi |
| **API Base URL** | `https://{subdomain}.zendesk.com/api/v2` |

## Funzionalità

- **Sync degli utenti** - Sincronizza utenti finali e agent Zendesk con i contatti Brevo
- **Tracciamento ticket** - Sincronizza i dati dei ticket per la segmentazione marketing consapevole del supporto
- **Mappatura organizzazioni** - Associa i contatti alle organizzazioni per workflow B2B
- **Punteggi di soddisfazione** - Sincronizza i dati CSAT e NPS agli attributi Brevo
- **Eventi ticket** - Traccia creazione, risoluzione ed escalation dei ticket per i trigger di automazione
- **Integrazione help center** - Traccia le visualizzazioni degli articoli e il comportamento di ricerca
- **Supporto multi-canale** - Sincronizza dati da canali email, chat, voice e messaggistica
- **Campi personalizzati** - Mappa campi personalizzati di ticket e utente Zendesk a Brevo

## Prerequisiti

Prima di iniziare, assicurati di avere:

1. Un account Zendesk Support (Team, Professional o Enterprise)
2. Accesso admin alla tua istanza Zendesk
3. Un API token o un’app OAuth configurata
4. Un account Brevo con accesso API
5. Un account Tajo

## Autenticazione

### Autenticazione con API token

Usa l’autenticazione email/token per un setup rapido.

```bash
curl https://{subdomain}.zendesk.com/api/v2/users.json \
  -u {email}/token:{api_token} \
  -H "Content-Type: application/json"
```

Genera un API token da Zendesk Admin > Apps and Integrations > APIs > Zendesk API.

### OAuth 2.0

Usa OAuth per integrazioni multi-istanza con accesso utente delegato.

```bash
# Authorization URL
https://{subdomain}.zendesk.com/oauth/authorizations/new?
  response_type=code&
  client_id={client_id}&
  redirect_uri={redirect_uri}&
  scope=read%20write
```

#### Scope richiesti

```
read          # Read access to all resources
write         # Write access to all resources
tickets:read  # Read tickets (granular)
users:read    # Read users (granular)
organizations:read  # Read organizations (granular)
```

## Configurazione

### Setup di base

```yaml
connectors:
  zendesk:
    enabled: true
    subdomain: "yourcompany"
    auth:
      email: "admin@yourcompany.com"
      api_token: "${ZENDESK_API_TOKEN}"

    # Data sync options
    sync:
      users: true
      tickets: true
      organizations: true
      satisfaction_ratings: true

    # Brevo list assignment
    lists:
      all_customers: 30
      active_tickets: 31
      satisfied_customers: 32
```

### Mappatura dei campi

Mappa i campi utente Zendesk agli attributi di contatto Brevo:

#### Mappature predefinite

| Parameter | Type | Description |
| --- | --- | --- |
| `email` required | string | Indirizzo email dell'utente (identificatore univoco) |
| `name` optional | string | Nome completo, suddiviso in FIRSTNAME/LASTNAME |
| `phone` optional | string | Mappato all'attributo SMS per WhatsApp/SMS |
| `organization_id` optional | integer | Organizzazione associata per la mappatura B2B |
| `role` optional | string | Ruolo utente (end-user, agent, admin) |
| `tags` optional | array | Tag utente da Zendesk |
| `ticket_restriction` optional | string | Livello di accesso ai ticket |
| `custom_fields` optional | object | Valori dei campi utente personalizzati |

#### Mappatura dei campi personalizzati

```yaml
field_mapping:
  # Standard fields
  email: email
  name: FULLNAME
  phone: SMS

  # Support metrics
  open_tickets: OPEN_TICKETS
  total_tickets: TOTAL_TICKETS
  avg_satisfaction: CSAT_SCORE
  last_ticket_date: LAST_SUPPORT_DATE

  # Organization fields
  organization.name: COMPANY_NAME
  organization.tags: COMPANY_TAGS

  # Custom fields
  user_fields.customer_type: CUSTOMER_TYPE
  user_fields.account_tier: ACCOUNT_TIER
```

## Endpoint API

### API Ticketing

| Metodo | Endpoint | Descrizione |
| --- | --- | --- |
| `GET` | `/api/v2/tickets` | Elenca i ticket |
| `POST` | `/api/v2/tickets` | Crea un ticket |
| `PUT` | `/api/v2/tickets/{id}` | Aggiorna un ticket |
| `GET` | `/api/v2/tickets/{id}` | Mostra un ticket |
| `GET` | `/api/v2/search.json?query={query}` | Cerca ticket |

### API Utenti

| Metodo | Endpoint | Descrizione |
| --- | --- | --- |
| `GET` | `/api/v2/users` | Elenca gli utenti |
| `POST` | `/api/v2/users` | Crea un utente |
| `PUT` | `/api/v2/users/{id}` | Aggiorna un utente |
| `GET` | `/api/v2/users/{id}` | Mostra un utente |
| `GET` | `/api/v2/users/search.json?query={query}` | Cerca utenti |

### API Organizzazioni

| Metodo | Endpoint | Descrizione |
| --- | --- | --- |
| `GET` | `/api/v2/organizations` | Elenca le organizzazioni |
| `POST` | `/api/v2/organizations` | Crea un’organizzazione |
| `GET` | `/api/v2/organizations/{id}/users` | Elenca i membri dell’organizzazione |

### API Satisfaction Rating

| Metodo | Endpoint | Descrizione |
| --- | --- | --- |
| `GET` | `/api/v2/satisfaction_ratings` | Elenca i rating di soddisfazione |
| `GET` | `/api/v2/satisfaction_ratings/{id}` | Mostra un rating |

## Eventi

### Eventi ticket

| Evento | Trigger | Caso d’uso |
| --- | --- | --- |
| `ticket.created` | Nuovo ticket inviato | Conferma di supporto |
| `ticket.updated` | Stato del ticket modificato | Notifica di stato |
| `ticket.solved` | Ticket marcato come risolto | Trigger sondaggio CSAT |
| `ticket.reopened` | Ticket risolto riaperto | Avviso di escalation |

### Eventi utente

| Evento | Trigger | Caso d’uso |
| --- | --- | --- |
| `user.created` | Nuovo utente registrato | Benvenuto al supporto |
| `user.updated` | Profilo utente modificato | Sync attributi |
| `user.merged` | Utenti uniti | Deduplicazione |

### Eventi di soddisfazione

| Evento | Trigger | Caso d’uso |
| --- | --- | --- |
| `satisfaction_rating.created` | CSAT inviato | Elaborazione feedback |
| `satisfaction_rating.bad` | Rating negativo | Outreach di recupero |
| `satisfaction_rating.good` | Rating positivo | Campagne di advocacy |

## Esempi di codice

### Inizializza il connettore

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

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

// Connect Zendesk
await tajo.connectors.connect('zendesk', {
  subdomain: 'yourcompany',
  email: 'admin@yourcompany.com',
  apiToken: process.env.ZENDESK_API_TOKEN
});
```

### Sincronizza utenti e ticket

```javascript
// Full sync of users and ticket data
await tajo.connectors.sync('zendesk', {
  type: 'full',
  resources: ['users', 'tickets', 'organizations'],
  since: '2023-01-01'
});

// Check sync status
const status = await tajo.connectors.status('zendesk');
console.log(status);
// {
//   connected: true,
//   lastSync: '2024-01-15T10:30:00Z',
//   usersSynced: 8400,
//   ticketsSynced: 34200,
//   organizationsSynced: 1200
// }
```

### Gestisci i webhook Zendesk

```javascript
app.post('/webhooks/zendesk', async (req, res) => {
  const signature = req.get('X-Zendesk-Webhook-Signature');

  // Verify webhook signature
  if (!verifyZendeskSignature(req.body, signature)) {
    return res.status(401).send('Unauthorized');
  }

  await tajo.connectors.handleWebhook('zendesk', {
    type: req.body.type,
    ticketId: req.body.ticket_id,
    userId: req.body.user_id,
    payload: req.body
  });

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

## Limiti di velocità

I limiti di velocità Zendesk variano in base al piano:

| Piano | Limite | Dettagli |
| --- | --- | --- |
| Team | 200 richieste/minuto | Per API token |
| Professional | 400 richieste/minuto | Per API token |
| Enterprise | 700 richieste/minuto | Per API token |
| High Volume Add-on | 2.500 richieste/minuto | Per API token |

Limiti aggiuntivi:

- **Search API**: 6 richieste/minuto per anonimi, 100/minuto per autenticati
- **Esportazioni incrementali**: 10 richieste/minuto
- **Batch API**: 100 record per richiesta batch
- **Consegna webhook**: Retry automatico con backoff esponenziale

Header dei limiti di velocità

Monitora gli header `X-Rate-Limit-Remaining` e `Retry-After` per gestire il tuo utilizzo dell’API.

## Risoluzione dei problemi

### Problemi comuni

| Problema | Causa | Soluzione |
| --- | --- | --- |
| 401 Unauthorized | API token non valido | Rigenera il token in Zendesk Admin |
| 403 Forbidden | Permessi insufficienti | Controlla i requisiti del ruolo agent o admin |
| Utente non sincronizzato | L’utente è un agent, non un end-user | Filtra per ruolo nella configurazione di sync |
| Webhook non ricevuto | Trigger/target non configurato | Configura il target webhook in Zendesk Admin |
| La ricerca restituisce vuoto | Ritardo di indicizzazione | Attendi 1-2 minuti per l’aggiornamento dell’indice di ricerca |

### Modalità debug

Abilita il logging dettagliato:

```yaml
connectors:
  zendesk:
    debug: true
    log_level: verbose
    log_webhooks: true
```

### Testa la connessione

```bash
tajo connectors test zendesk
# ✓ API connection successful
# ✓ Users readable
# ✓ Tickets readable
# ✓ Organizations readable
# ✓ Webhooks configured
```

## Best practice

1. **Usa le esportazioni incrementali** - Usa l’Incremental API per la sync di dati su larga scala
2. **Filtra solo gli end-user** - Escludi agent e admin dalla sync dei contatti Brevo
3. **Sincronizza i dati CSAT** - Usa i punteggi di soddisfazione per la segmentazione customer health
4. **Mappa le organizzazioni** - Sfrutta i dati delle organizzazioni per campagne marketing B2B
5. **Implementa retry sui webhook** - Gestisci i fallimenti temporanei in modo elegante
6. **Usa il side-loading** - Includi record correlati nelle risposte API per ridurre il numero di richieste

## Sicurezza

- **Autenticazione con API token** - Accesso basato su token legato all’email admin
- **OAuth 2.0** - Accesso delegato basato su token con controlli scope
- **Firma webhook** - Verifica della firma HMAC per i payload webhook
- **Cifratura TLS** - Tutte le comunicazioni API cifrate via HTTPS
- **IP whitelisting** - Limita l’accesso API per intervallo IP

## Risorse correlate

- [Documentazione API Zendesk](https://developer.zendesk.com/api-reference)
- [Guida ai webhook Zendesk](https://developer.zendesk.com/api-reference/webhooks/introduction/)
- [Connettore Intercom](https://tajo.io/it/docs/connectors/support/intercom)
- [Skill Customer Sync](https://tajo.io/it/docs/skills/data-sync/customer-sync)
- [API Contatti Brevo](https://tajo.io/it/docs/contact-management)