# Accesso API

Un'API (Application Programming Interface) è un modo in cui diversi sistemi software possono comunicare tra loro. L'API <span data-t="appName">Your AI Connector</span> consente a te (o al tuo sviluppatore) di creare contatti, inviare messaggi, gestire elenchi e ricevere messaggi in arrivo da canali personalizzati, il tutto senza utilizzare la dashboard.


**Perché usare l'API?** Se desideri connettere l'app a uno strumento che non dispone di un'integrazione nativa, o se hai bisogno di automatizzare attività ripetitive su larga scala, l'API è la soluzione ideale.

::: note
**Nota:** questa pagina ha una natura più tecnica. Se sei un titolare di azienda e non uno sviluppatore, potresti voler condividere questa pagina con il tuo team tecnico o con uno sviluppatore freelance.
:::


---

## Generazione della tua chiave API

::: note
**Nota:** l'accesso all'API è una funzionalità a pagamento disponibile nei piani idonei. Se il tuo piano non la include, le richieste API verranno rifiutate con una risposta `403`. Controlla il tuo piano o contatta l'assistenza se non sei sicuro che l'accesso all'API sia abilitato.
:::


1. Nella barra laterale sinistra, fai clic su **Impostazioni** (icona a forma di ingranaggio).
2. Nella barra laterale delle Impostazioni, sotto il gruppo **Integrazioni**, fai clic su **Chiave API**.


3. Se non hai ancora una chiave, fai clic su **Genera chiave API**.
4. Se ne hai già una, viene mostrata mascherata sotto **La tua chiave**. Se la tua chiave lo supporta, fai clic su **Mostra** per rivelarla, quindi su **Copia** per copiarla: vedrai apparire un messaggio di conferma.
5. Conserva la chiave in un luogo sicuro: ti servirà per ogni richiesta API.


::: note
**Nota:** Alcuni account visualizzano "La tua chiave non può essere visualizzata" invece del controllo Mostra/Copia: questo accade per le chiavi create prima che l'app potesse visualizzarle nuovamente. La chiave funziona ancora normalmente; devi usare **Rigenera** (sotto la scheda della chiave, nella stessa sezione) solo se hai effettivamente bisogno di vedere di nuovo il testo in chiaro. La rigenerazione invalida immediatamente la vecchia chiave e interrompe ogni integrazione che la utilizza finché non incolli quella nuova: aggiorna le tue integrazioni subito dopo.
:::


::: warning
**Importante:** la tua chiave API è come una password: garantisce l'accesso completo al tuo account. Non condividerla pubblicamente né pubblicarla in luoghi in cui altri possano vederla. Se ritieni che la tua chiave sia stata compromessa, rigenerala immediatamente.
:::


> **Membri del team:** la chiave API appartiene al proprietario dell'account, quindi se hai effettuato l'accesso come membro del team invitato (incluso un Amministratore), la sezione mostrerà una nota invece della chiave. Accedi come proprietario dell'account per visualizzarla, copiarla o rigenerarla; questo vale anche per le chiavi con ambito limitato.

> **Dove trovarla:** **Chiave API** è una sezione a sé stante sotto Impostazioni → Integrazioni, separata dai **Webhook**. Se una guida o un collega ti dice di cercare la chiave sotto "Webhook", guarda invece nella sezione accanto.

---

## URL di base

Tutte le richieste API utilizzano il seguente indirizzo web di base:

```
https://api.youraiconnector.com/v1/
```

---

## Autenticazione

Ogni richiesta deve includere la tua chiave API in modo che la piattaforma sappia che sei tu. Il modo più semplice è aggiungerla alla fine dell'indirizzo web:

```
https://api.youraiconnector.com/v1/contacts?apiKey=YOUR_API_KEY
```

Puoi anche inviare la chiave come intestazione della richiesta invece che nell'URL (scelta consigliata per la produzione, in modo che la chiave non finisca nei log del server):

```
X-API-Key: YOUR_API_KEY
```
```
Authorization: Bearer YOUR_API_KEY
```

Tutte le richieste devono utilizzare una connessione sicura (HTTPS). Le richieste non sicure (HTTP) vengono rifiutate.

> **Cerchi le guide complete per sviluppatori?** Questa pagina è una rapida introduzione che copre le operazioni più comuni. Per guide complete passo dopo passo — ogni risorsa, con esempi in cURL, JavaScript e Python — consulta [Introduzione all'API](../api/getting-started.md) e il [Riferimento API](../api/reference.md).

---

## Operazioni API comuni

### Creare un contatto

**Richiesta:**

```http
POST https://api.youraiconnector.com/v1/contacts?apiKey=YOUR_API_KEY
Content-Type: application/json

{
  "firstName": "Jane",
  "lastName": "Smith",
  "phoneNumber": "+15551234567",
  "email": "jane@example.com"
}
```

**Campi obbligatori:** un `phoneNumber` (con prefisso internazionale) è sempre richiesto per creare un contatto. Un indirizzo email da solo non è sufficiente: una richiesta senza un numero di telefono valido viene rifiutata. L'email è facoltativa.

**Risposta:**

```json
{
  "success": true,
  "data": {
    "message": "Successfully created new contact",
    "contactId": "abc123xyz",
    "listsAdded": []
  }
}
```

Salva `data.contactId`: ti servirà per la chiamata "Aggiungi un contatto a una lista".

::: note
**Nota:** se esiste già un contatto con lo stesso numero di telefono, l'API **non** crea né restituisce quel contatto, ma restituisce `{ "success": false, "error_code": 409 }`. Cerca prima il contatto esistente con `GET https://api.youraiconnector.com/v1/contacts?phoneNumber=...`.
:::


---

### Aggiungi un contatto a una lista

```http
POST https://api.youraiconnector.com/v1/contacts/lists?apiKey=YOUR_API_KEY
Content-Type: application/json

{
  "contactId": "abc123xyz",
  "listId": "YOUR_LIST_ID"
}
```

Trova l'ID di una lista nell'app sotto **Contatti → Liste**, dal menu della riga della lista (**Copia ID lista**).

---

### Aggiorna un contatto

```http
PUT https://api.youraiconnector.com/v1/contacts/YOUR_CONTACT_ID?apiKey=YOUR_API_KEY
Content-Type: application/json

{
  "customFields": { "company": "Acme Inc" }
}
```

Vengono modificati solo i campi inclusi. Questo è anche il modo per caricare in blocco i valori dei campi personalizzati dopo un'importazione: consulta [Campi personalizzati, Profilo lead e Note](../get-started/custom-contact-fields.md#bulk-loading-custom-fields). Dettagli completi nell'[API Contatti](../api/contacts.md).

---

### Invia un messaggio (Canale personalizzato)

```http
POST https://api.youraiconnector.com/v1/send_custom_channel_message?apiKey=YOUR_API_KEY
Content-Type: application/json

{
  "customData": {
    "fromId": "external-contact-id",
    "customChannel": "my-channel",
    "body": "Hello Jane! Your order has been shipped.",
    "campaignId": "optional-campaign-id",
    "firstName": "Jane",
    "lastName": "Smith"
  }
}
```

| Campo | Obbligatorio | Descrizione |
|---|---|---|
| `customData.fromId` | Sì | L'ID del contatto sulla tua piattaforma |
| `customData.customChannel` | Sì | Il nome del tuo canale personalizzato |
| `customData.body` | Sì | Il testo del messaggio da inviare |
| `customData.campaignId` | No | Instrada il messaggio verso una campagna specifica |
| `customData.firstName` | No | Nome del contatto (utilizzato durante la creazione di un nuovo contatto) |
| `customData.lastName` | No | Cognome del contatto |
| `customData.email` | No | Indirizzo email del contatto |

::: note
**Nota:** questo endpoint è per la messaggistica tramite canale personalizzato. Per WhatsApp, SMS, Instagram e Messenger, i messaggi vengono inviati tramite Broadcast, Campagne e Agenti AI.
:::


---

### Ricevi messaggi in entrata (Canale personalizzato)

Accetta messaggi da sistemi esterni come canale personalizzato. È così che integrazioni come GoHighLevel inviano messaggi a <span data-t="appName">Your AI Connector</span>. Consulta [Canali personalizzati](../messaging-channels/custom-channels.md) per tutti i dettagli.

```http
POST https://api.youraiconnector.com/v1/incoming_custom_channel_message?apiKey=YOUR_API_KEY
Content-Type: application/json

{
  "customData": {
    "messageSid": "unique-message-id",
    "fromId": "external-contact-id",
    "toId": "your-user-id",
    "body": "Customer's message here",
    "channel": "custom",
    "status": "received"
  },
  "messageType": "text"
}
```

| Campo | Obbligatorio | Descrizione |
|---|---|---|
| `customData.messageSid` | Sì | Un ID univoco per questo messaggio (previene i duplicati). Puoi anche usare `customData.id`. |
| `customData.fromId` | Sì | L'ID del mittente nel tuo sistema esterno. |
| `customData.toId` | Sì | Il tuo identificativo aziendale. |
| `customData.body` | Sì | Il testo del messaggio. |
| `customData.channel` | No | Un'etichetta per la sorgente (es. `"email"`, `"livechat"`, `"custom"`). |
| `customData.status` | No | Stato del messaggio. Il valore predefinito è `"received"`. |
| `messageType` | No | `"text"` per messaggi di testo, `"reaction"` per reazioni con emoji. |

---

## Panoramica delle operazioni disponibili

| Azione | Metodo | Indirizzo | Descrizione |
|---|---|---|---|
| Crea un contatto | `POST` | `/contacts` | Aggiungi un nuovo contatto al tuo account |
| Ottieni dettagli contatto | `GET` | `/contacts?phoneNumber=X` o `/contacts?email=X` | Cerca un contatto tramite numero di telefono o email |
| Aggiorna un contatto | `PUT` | `/contacts/{contactId}` | Aggiorna qualsiasi campo su un contatto esistente |
| Aggiungi contatto a una lista | `POST` | `/contacts/lists` | Aggiungi un contatto esistente a una lista specifica |
| Invia un messaggio | `POST` | `/send_custom_channel_message` | Invia un messaggio tramite un canale personalizzato |
| Ricevi un messaggio | `POST` | `/incoming_custom_channel_message` | Accetta un messaggio da un sistema esterno |

---

## Limitazione della frequenza (Rate Limiting)

The API enforces rate limits to ensure platform stability. Exceeding your limit returns `429 Too Many Requests` — back off and retry after the time indicated in the response headers. For high-volume use cases (bulk imports), use the built-in [import feature](../get-started/importing-contacts.md) or email [<span data-t="supportEmail">hi@youraiconnector.com</span>](mailto:hi@youraiconnector.com) for guidance.

---

## Best practice

- **Conserva la tua chiave API in modo sicuro** — usa un gestore di password o una configurazione lato server, mai codice lato client che un visitatore del browser potrebbe leggere.
- **Includi sempre il prefisso internazionale** nei numeri di telefono (`+1` per gli USA, `+44` per il Regno Unito, `+31` per i Paesi Bassi).
- **Gestisci gli errori correttamente** — controlla i codici di stato e leggi eventuali messaggi di errore restituiti.
- **Gestisci i duplicati** — un numero di telefono duplicato restituisce `{ "success": false, "error_code": 409 }` invece di un nuovo contatto. Cerca prima il contatto se devi lavorarci.
- **Esegui test con un piccolo set di dati** prima di eseguire operazioni in blocco.

---

## Risposte di errore

```json
{
  "error": {
    "code": "INVALID_PHONE",
    "message": "Phone number must include a valid country code."
  }
}
```

| Status Code | Meaning |
|---|---|
| `200` | Success |
| `201` | Resource created |
| `400` | Bad request — check your parameters |
| `401` | Unauthorized — invalid or missing API key |
| `403` | Forbidden — your plan doesn't include API access, or you lack permission |
| `404` | Resource not found |
| `429` | Rate limit exceeded |
| `500` | Server error — email [<span data-t="supportEmail">hi@youraiconnector.com</span>](mailto:hi@youraiconnector.com) if this persists |

---

## Prossimi passi

- [Webhook](webhooks.md) — ricevi notifiche in tempo reale dall'app (una sezione separata dalla tua chiave API).
- [Connetti assistenti AI (MCP)](connect-ai-clients.md) — usa la stessa chiave API per consentire a Claude di gestire il tuo account.
- [Moduli lead di Facebook](facebook-lead-forms.md) — usa l'API con piattaforme di automazione per acquisire lead.
- [Integrazione GoHighLevel](ghl-integration.md) — un esempio completo di integrazione API bidirezionale.