L'**API pubblica** di **Aymar Agents** è una superficie REST curata — lead, contatti, conversazioni,
appuntamenti e ticket del tuo account — pensata per integrare il tuo codice, il tuo CRM o la tua
automazione con il tuo account, senza passare dall'interfaccia web. Non è uno specchio di tutto ciò che fa
la Piattaforma: esistono rotte solo per questi 5 risorse, qualunque sia il permesso della tua chiave.

Disponibile sui piani **Pro** ed **Enterprise**. Con il piano Starter, qualsiasi chiamata restituisce
`403 PLAN_NOT_ELIGIBLE` anche se la chiave e il permesso sono corretti — vedi
[Piani e limiti](/it/api/plans-and-limits/).

## 1. Crea la tua chiave

Le chiavi API si creano e si gestiscono da **Profilo → Le mie chiavi API** (o **Impostazioni → Chiavi API**
per una chiave aziendale) — la procedura completa, con screenshot, è nella guida
**[Chiavi API](/it/guides/claves-api/)**. Quando la crei:

- In "Cosa può fare questa chiave", premi **"Personalizza"** e seleziona solo le risorse di cui la tua
  integrazione ha bisogno — vedi l'elenco completo in [Autenticazione](/it/api/authentication/). Una chiave
  senza il permesso di una risorsa riceve `403 PERMISSION_DENIED` sulle sue rotte, anche se il resto della
  chiave funziona.
- La chiave completa viene mostrata **una sola volta**: copiala in un gestore di segreti prima di chiudere
  la finestra.

## 2. Verifica la tua chiave

`GET /me` non richiede nessun permesso proprio — solo una chiave valida di un tenant con piano idoneo —
quindi è il modo più veloce per confermare che tutto sia in ordine:

```bash
curl https://api.aymaragents.com/public/v1/me \
  -H "X-API-Key: aa_TUA_CHIAVE_COMPLETA"
```

```json
{
  "tenantId": "b3f5b6b0-...",
  "keyPrefix": "aa_1b2e1ebd",
  "scopes": ["tenant:leads.read", "tenant:leads.manage"],
  "plan": "pro",
  "rateLimit": { "perMinute": 180, "perDay": 50000 }
}
```

Se `scopes` non include quello che ti aspettavi, controlla la selezione "Personalizza" della tua chiave
(guida delle chiavi API, sezione 7) — la selezione resta fissata alla creazione, non si aggiorna da sola.

## 3. Fai la tua prima chiamata di business

Con una chiave che ha `tenant:leads.read`, elenca i lead più recenti:

```bash
curl "https://api.aymaragents.com/public/v1/leads?dateFrom=2026-01-01" \
  -H "X-API-Key: aa_TUA_CHIAVE_COMPLETA"
```

Ogni risposta di lista usa lo stesso formato di paginazione del resto dell'API — controlla il campo `meta`
della risposta per richiedere la pagina successiva.

## Prima di automatizzare l'invio di messaggi

`POST /public/v1/conversations/{id}/messages` e `POST /public/v1/conversations/start` consegnano il
messaggio al canale reale, ma **non** compaiono all'istante nell'inbox della Piattaforma né nel widget del
visitatore — un operatore umano li vede al successivo aggiornamento/riconnessione della sua schermata, non
in tempo reale. Se la tua integrazione ha bisogno che un operatore reagisca subito, avvisalo anche per
un'altra via (il tuo sistema, un ticket…) oltre a inviare il messaggio. Dettaglio completo nel gruppo
**[Conversazioni](/api/reference/operations/tags/conversaciones/)** della referenza.

## Continua da qui

- **[Autenticazione](/it/api/authentication/)** — l'header `X-API-Key`, il catalogo completo dei permessi.
- **[Piani e limiti](/it/api/plans-and-limits/)** — quale piano ti serve e quante chiamate puoi fare.
- **[Errori](/it/api/errors/)** — l'envelope di errore e il catalogo completo dei codici.
- **[Casi d'uso](/it/api/use-cases/)** — 5 integrazioni reali con esempi di codice brevi.
- **Referenza**, nella barra laterale — una pagina per operazione, generata dalla definizione
  OpenAPI reale.

Domande durante l'integrazione? Scrivi a **soporte@aymaragents.com**.