# API HTTP (/it-IT/ontwikkelaars/http)

L'API di Tillor è una REST API. Autenticati con una chiave API e invia gli header giusti a ogni richiesta. Le chiavi API sono **per account** - una chiave vale per tutte le organizzazioni a cui hai accesso.

## Riferimento API e OpenAPI [#api-referentie-en-openapi]

- **[Riferimento API](/api-referentie)** - Ogni endpoint con parametri ed esempi; prova le richieste direttamente nel browser
- **[Specifica OpenAPI](https://tillor.eu/api/openapi.json)** - Documentazione completa dell'API in formato JSON per la generazione di codice o l'importazione in Postman/Insomnia

---

## Chiavi API [#api-sleutels]

### Creare [#aanmaken]

Le chiavi API le crei nell'app Tillor dal menu utente in **Account > Chiavi API** (indicatore **1** = menu, indicatore **2** = Chiavi API nello screenshot). Puoi crearle anche tramite l'API con una sessione effettuata (senza chiave API). Vedi la [specifica OpenAPI](https://tillor.eu/api/openapi.json) sotto il tag `api-keys` per percorsi e schemi di richiesta e risposta.

<DocScreenshot src="/screenshots/http/api-keys-nav.png" alt="Chiavi API nelle impostazioni dell'account" />

La chiave in chiaro viene restituita **una sola volta** alla creazione o alla rigenerazione. Conservala con cura; dopo non potrai più recuperarla.

### Limitare i permessi [#rechten-beperken]

Per impostazione predefinita una chiave può fare tutto ciò che puoi fare tu, in ogni organizzazione di cui sei membro. Nella finestra della chiave attiva **Limita alle autorizzazioni selezionate** e scegli i permessi di cui il collegamento ha bisogno, ad esempio solo la lettura delle fatture. Una chiave limitata ottiene in ogni organizzazione l'intersezione dei suoi permessi e della tua appartenenza lì: una chiave non può mai fare più di te. Una chiamata al di fuori dei permessi scelti riceve `403 Forbidden`, proprio come un utente senza quel permesso. Una modifica dei permessi vale entro un minuto. Tramite l'API: `scopes` (elenco di id di permessi come `invoices:read`, oppure `null` per tutto) alla creazione e all'aggiornamento di una chiave.

### Utilizzo [#gebruik]

Invia la chiave API nell'header `x-api-key`:

```http
x-api-key: tkn_xxx
```

Le chiavi usano il prefisso `tkn_`. Negli endpoint dell'organizzazione l'ID dell'organizzazione è nel percorso (`/orgs/org_abc123/...`); non serve un header a parte.

### Rate limit [#rate-limits]

- **Predefinito:** 5000 richieste ogni 60 secondi per chiave
- In caso di superamento: `429 Too Many Requests` con `Retry-After`
- Ogni risposta con chiave API contiene gli header IETF `RateLimit-*`:

```http
RateLimit-Limit: 5000
RateLimit-Remaining: 4999
RateLimit-Reset: 58
RateLimit-Policy: 5000;w=60
```

`RateLimit-Reset` è il numero di secondi prima che la finestra attuale ricominci. I client browser possono leggere questi header tramite CORS (`Access-Control-Expose-Headers`).

### Sicurezza [#beveiliging]

<Callout type="warn" title="Attenzione">
- **Mai** esporre le chiavi API nel codice lato client o in repository pubblici
- Rigenera periodicamente le chiavi con **Rigenera** nell'app (OpenAPI: `POST /api/api-keys/:id/renew`)
- Elimina le chiavi inutilizzate con `DELETE /api/api-keys/:id`
</Callout>

---

## Base URL e contesto dell'organizzazione [#base-url-en-organisatie-context]

**Base URL:** `https://tillor.eu` (o l'URL del tuo deployment; OpenAPI indica `{APP_URL}/api`)

**Percorsi dell'organizzazione:** aggiungi l'ID dell'organizzazione nel percorso:

```
/api/orgs/:orgId/...
```

**Esempio:**

```
GET https://tillor.eu/api/orgs/org_abc123/customers
```

**Header richiesto per gli endpoint dell'organizzazione:** `x-api-key: tkn_xxx`. L'ID dell'organizzazione è nel percorso.

---

## Esempio: cURL [#voorbeeld-curl]

```bash
curl -X GET "https://tillor.eu/api/orgs/org_abc123/customers" \
  -H "x-api-key: tkn_xxx" \
  -H "Content-Type: application/json"
```

---

## Integrazioni (marketplace) [#integraties-marketplace]

Le integrazioni dell'organizzazione (prima "apps" nell'API) usano una risorsa per tipo sotto `/api/orgs/:orgId/integrations/{integrationType}`. I permessi richiesti sono `organization:integrations:read` e `organization:integrations:write` (sostituisce `organization:apps:*`).

| Method | Percorso | Descrizione |
|--------|------|-------------|
| GET | `/integrations/{integrationType}` | Stato (`installed`, `available`) e `settings` oscurate |
| POST | `/integrations/{integrationType}` | Installare (`settings` facoltative nel body; OAuth può restituire `redirectUrl`) |
| PUT | `/integrations/{integrationType}` | Aggiornare le impostazioni (`settings` nel body) |
| DELETE | `/integrations/{integrationType}` | Disinstallare |

Con `GET` e dopo `PUT`, `settings` contiene solo campi **pubblici** più, per ogni campo segreto, `{ configured: true }`. Password, chiavi API e token OAuth non vengono restituiti. Lascia vuoti i campi segreti con `PUT` per mantenere il valore esistente.

Vedi la [specifica OpenAPI](https://tillor.eu/api/openapi.json) (tag `integrations`) per gli schemi esatti.

---

## Correlati [#gerelateerd]

- [Riferimento API](/api-referentie) - Ogni endpoint, da provare nel browser
- [OpenAPI](https://tillor.eu/api/openapi.json) - Specifica API (JSON)
- [MCP](/ontwikkelaars/mcp) - Collegare Cursor, Claude, ChatGPT o Gemini tramite OAuth
- [Notifiche esterne](/ontwikkelaars/externe-notificaties) - Registra le e-mail inviate dal tuo sistema
- [Webhook](/ontwikkelaars/webhooks) - Ricevi eventi tramite HTTP POST
- [Webhook in ingresso di un'automazione](/ontwikkelaars/automatiseringen#een-automatisering-starten-met-een-webhook) - Avvia un'automazione con una POST, senza chiave API
- [SSE](/ontwikkelaars/sse) - Ricevi eventi in streaming con Server-Sent Events
- [Esempi](/ontwikkelaars/voorbeelden) - Esempi di codice e di payload