> ## Documentation Index
> Fetch the complete documentation index at: https://knowledge.flowella.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Introduzione all'API

> Autenticazione, URL di base, codici di errore, paginazione, limiti di velocità e chiavi di idempotenza per l'API REST Flowella v1: tutto ciò che vi serve prima della prima chiamata.

L'API REST di Flowella consente di inviare messaggi WhatsApp, gestire i contatti e gli opt-out, i modelli di elenco e di invio massivo e le analisi - in modo programmatico. Questa pagina illustra tutto ciò che è necessario sapere prima di chiamare un endpoint.

Il riferimento completo all'endpoint si trova nella barra laterale **riferimento dell'API** (generato automaticamente dalle specifiche [OpenAPI](/api-reference/openapi.json)).

## URL di base

```
https://app.flowella.io
```

Tutti gli endpoint v1 sono sotto `/api/v1`.

## Autenticazione

Ogni richiesta necessita di una chiave API nell'intestazione `Authorization`:

```http theme={null}
Authorization: Bearer flo_xxxxxxxxxxxxxxxxxxxxxxxx
```

Le chiavi sono a livello di organizzazione: agiscono su una singola organizzazione Flowella ed ereditano i permessi di un amministratore in quella organizzazione.

<Warning>
  Trattate le chiavi come le password. Non eseguite mai il commit nel controllo sorgente, non incollatele in chat o nei documenti condivisi e ruotatele quando i compagni di squadra lasciano l'organizzazione. Vedere [Impostazioni → Chiavi API](/it/settings/api-keys) per le fasi di rotazione.
</Warning>

### Creare una chiave

Per gestire le chiavi API è necessario il ruolo **Owner** o **Admin**.

1. Andare a **Impostazioni → Chiavi API** nell'app Flowella.
2. Fare clic su **Crea chiave** e assegnarle un nome memorabile.
3. Copiare la chiave una sola volta: viene visualizzata solo al momento della creazione.

Trattate le chiavi come le password: non impegnatele mai nel controllo sorgente, non incollatele mai in chat e ruotatele quando i compagni di squadra lasciano l'organizzazione.

### Verifica di una chiave

Per confermare la validità di una chiave, si può utilizzare l'endpoint ping:

<CodeGroup>
  ```bash cURL theme={null}
  curl https://app.flowella.io/api/v1/ping \
    -H "Authorization: Bearer flo_xxxxxxxxxxxxxxxxxxxxxxxx"
  ```

  ```js Node.js theme={null}
  await fetch("https://app.flowella.io/api/v1/ping", {
    headers: { Authorization: `Bearer ${process.env.FLOWELLA_API_KEY}` },
  });
  ```

  ```python Python theme={null}
  import os, requests

  requests.get(
      "https://app.flowella.io/api/v1/ping",
      headers={"Authorization": f"Bearer {os.environ['FLOWELLA_API_KEY']}"},
  )
  ```
</CodeGroup>

Un `200 OK` con `{ "ok": true, "organizationId": "…" }` significa che l'utente è autenticato.

## Errori

Tutti gli errori vengono restituiti in una busta coerente:

```json theme={null}
{
  "error": {
    "code": "UNAUTHORIZED",
    "message": "Invalid API key"
  }
}
```

| Stato HTTP | Quando lo vedrete                                                                   |
| ---------- | ----------------------------------------------------------------------------------- |
| `400`      | Convalida fallita, corpo malformato o rifiuto upstream Meta                         |
| `401`      | Chiave API mancante o non valida                                                    |
| `402`      | Pagamento richiesto - l'abbonamento non copre l'azione                              |
| `403`      | Vietato - ad esempio, l'invio a un contatto che ha rinunciato o Meta non è connesso |
| `404`      | Il canale o la risorsa richiesti non esistono                                       |
| `429`      | Velocità limitata - rallentare                                                      |

Il campo `error.code` è stabile e sicuro da attivare programmaticamente. Il campo `error.message` è leggibile dall'uomo e può cambiare.

## Limiti di velocità

Le chiavi API hanno un limite di velocità per organizzazione. Se si supera il limite, si riceve un `429` con il codice `RATE_LIMITED` e il messaggio `Too many requests`. Ritirarsi e riprovare con un ritardo esponenziale.

Se si eseguono grandi invii in massa, preferire **`POST /api/v1/templates/send`** con il parametro `throttlePerHour` - Flowella applica il throttle lato server, quindi non è necessario ritmare le richieste da soli.

## Paginazione

Gli endpoint elenco (`/conversations`, `/contacts`, `/templates`) utilizzano la **paginazione a cursore**:

* Passare `limit` (1-100, valore predefinito 25) e un `cursor` opzionale.
* La risposta contiene `items` e, se ci sono più risultati, `nextCursor`.
* Passare `nextCursor` come parametro `cursor` per recuperare la pagina successiva.
* Quando manca `nextCursor`, si è giunti alla fine.

```bash theme={null}
curl "https://app.flowella.io/api/v1/conversations?limit=50" \
  -H "Authorization: Bearer flo_xxxxxxxxxxxxxxxxxxxxxxxx"
```

## Data e ora

Tutti i timestamp sono stringhe ISO 8601 in UTC (ad esempio `2025-01-15T14:30:00.000Z`). Quando l'API accetta date, sia la sola data (`2025-01-15`) che l'intero ISO 8601 sono forzati dal lato server.

## Numeri di telefono

Passare i numeri di telefono nella forma **E.164** (`+15551234567`), ove possibile. Flowella normalizzerà le varianti più comuni lato server, ma E.164 è più sicuro.

## Canali

Molti endpoint accettano un `whatsappChannelId`. Se la vostra organizzazione ha un solo canale e lo omettete, Flowella utilizzerà il vostro canale predefinito. Se avete più canali, passate esplicitamente l'ID per evitare di inviare dal mittente sbagliato.

Per lo schema URL completo e il cambio di canale, vedere [Multi-channel](/it/essentials/multi-channel).

## OpenAPI spec

Le specifiche leggibili in macchina si trovano in:

```
/api-reference/openapi.json
```

Inseritelo in Postman, Insomnia o nel vostro generatore di codice preferito.

<Tip>
  State costruendo un'integrazione? Abbinate questa pagina a [Webhooks](/it/api-reference/webhooks) per reagire agli eventi invece di eseguire il polling dello stato.
</Tip>