Tutti gli esempi assumono una chiave con lo scope indicato e un piano Pro o Enterprise (vedi
[Piani e limiti](/it/api/plans-and-limits/)). Sostituisci `aa_TUA_CHIAVE_COMPLETA` con la tua chiave reale.

## 1. Sincronizzare i lead verso il tuo CRM

La tua agenzia usa già un CRM (HubSpot, Zoho…) oltre a Nuntius. Invece che noi spingiamo verso il
tuo CRM, la tua integrazione **estrae** i lead nuovi ogni ora con `dateFrom`:

```bash
curl "https://api.nuntius.chat/public/v1/leads?dateFrom=2026-09-01T00:00:00Z" \
  -H "X-API-Key: aa_TUA_CHIAVE_COMPLETA"
```

```python
import requests

resp = requests.get(
    "https://api.nuntius.chat/public/v1/leads",
    params={"dateFrom": "2026-09-01T00:00:00Z"},
    headers={"X-API-Key": "aa_TUA_CHIAVE_COMPLETA"},
)
for lead in resp.json()["data"]:
    sync_to_my_crm(lead)
```

Scope: `tenant:leads.read`.

## 2. Catturare lead dal tuo sito

Hai una landing page fuori dal widget incorporabile di Nuntius e non vuoi montarci il widget di
chat — invia il modulo direttamente all'API:

```javascript
await fetch("https://api.nuntius.chat/public/v1/leads", {
  method: "POST",
  headers: {
    "X-API-Key": "aa_TUA_CHIAVE_COMPLETA",
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    customerPhone: "+34600111222",
    stageId: "...",
    notes: "Modulo della landing page servizi",
  }),
});
```

Scope: `tenant:leads.manage` (oppure `tenant:contacts.manage` se invii il modulo a `/contacts`).

## 3. Mantenere unificato un calendario esterno

Usi già Calendly o Google Calendar come fonte di verità di un altro team — controlla gli slot liberi di
Nuntius prima di offrire un orario, e crea l'appuntamento qui in modo che sia riflesso in entrambi i
posti:

```bash
curl "https://api.nuntius.chat/public/v1/availability?from=2026-09-10&to=2026-09-14" \
  -H "X-API-Key: aa_TUA_CHIAVE_COMPLETA"
```

```python
slot = pick_a_slot(available_slots)
requests.post(
    "https://api.nuntius.chat/public/v1/appointments",
    json={"userId": slot["userId"], "startsAt": slot["startsAt"], "customerId": customer_id},
    headers={"X-API-Key": "aa_TUA_CHIAVE_COMPLETA"},
)
```

Scope: `tenant:appointments.read` (disponibilità) + `tenant:appointments.manage` (creazione).

## 4. Sincronizzare i ticket con il tuo helpdesk

Il tuo proprio Zendesk o Freshdesk (diverso da una nostra integrazione Zendesk) riflette in entrambe le
direzioni lo stato di ogni ticket:

```javascript
const res = await fetch("https://api.nuntius.chat/public/v1/tickets?status=open", {
  headers: { "X-API-Key": "aa_TUA_CHIAVE_COMPLETA" },
});
const { data: openTickets } = await res.json();
```

```bash
curl -X PATCH "https://api.nuntius.chat/public/v1/tickets/TICKET_ID" \
  -H "X-API-Key: aa_TUA_CHIAVE_COMPLETA" \
  -H "Content-Type: application/json" \
  -d '{"status": "resolved"}'
```

Scope: `tenant:tickets.read` (lettura) + `tenant:tickets.manage` (creazione/aggiornamento/commento).

## 5. Automazione low-code (Zapier e simili)

Attiva uno Zap quando arriva un lead nuovo (tramite polling periodico a `GET /leads`, finché non esiste un
webhook) e usa come azione "invia un messaggio WhatsApp da un foglio di calcolo":

```bash
curl -X POST "https://api.nuntius.chat/public/v1/conversations/CONVERSATION_ID/messages" \
  -H "X-API-Key: aa_TUA_CHIAVE_COMPLETA" \
  -H "Content-Type: application/json" \
  -d '{"text": "Il tuo appuntamento è confermato per domani alle 10:00"}'
```

Scope: `tenant:conversations.manage`. **Ricorda**: se il contatto è su WhatsApp e la sua finestra di 24h è
chiusa, questa chiamata risponde `409 WHATSAPP_SESSION_WINDOW_CLOSED` senza tentare l'invio — usa
`POST /conversations/start` con un template approvato per aprire una nuova conversazione. E in ogni caso, il
messaggio inviato **non compare all'istante** nell'inbox della Piattaforma — vedi la nota in
[Iniziare con l'API](/it/api/getting-started/).