Files
Alby96andClaude Opus 5.5 88de272b3e docs: avoid ambiguous Unicode and record Gitea planning in STATUS
Gitea flags en dash, multiplication sign, minus sign and single angle
quotes as confusable characters, which put a warning on most pages;
use plain equivalents (docs/SPEC.md stays untouched). STATUS.md now
lists the issue numbers per milestone, the items waiting for the owner
and the open specification questions tracked by issue #114.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
2026-11-10 22:44:14 +01:00

159 lines
7.3 KiB
Markdown

# API e MCP
> **Stato:** bozza · **Ultima revisione:** 2026-11-10 · **Versione software:** non ancora rilasciata (milestone M12)
> **Modulo di licenza:** API · **Livello richiesto:** amministratore · **Specifica:** SPEC §5.4, §7.3, §11.12, §12.10, §15
## A cosa serve
Khaemhat si collega ad altri programmi in tre modi, tutti nel modulo **API**:
- **API REST** (`/api/v1`): un sito web che invia lead, un e-commerce che legge giacenze e crea ordini, un gestionale
esterno che legge le fatture;
- **MCP** (`/mcp`): un assistente di intelligenza artificiale che consulta i dati del gestionale (clienti, giacenze,
partite aperte, bilancio di verifica) ed eventualmente crea bozze;
- **webhook** in uscita: Khaemhat avvisa un altro sistema quando succede qualcosa (eventi delle automazioni).
Questa pagina spiega come **gestire chiavi, MCP e webhook** dal pannello. Il riferimento tecnico delle risorse e
degli strumenti è nelle pagine [API](API) e [MCP](MCP).
## Dove si trova
**Amministrazione → Chiavi API e MCP** (titolo: *Chiavi API, MCP e webhook*). In alto a destra un indicatore mostra
se il modulo API è attivo. Senza modulo **API** le API e l'endpoint MCP non sono registrati.
## Schermata
![088 · Amministrazione · chiavi API, MCP e webhook](https://gitea.encke-hake.ts.net/BalboSoft/Khaemhat/raw/branch/main/docs/mockups/thumbs/088-admin-chiavi-api-mcp.png)
*Mockup 088 — elenco delle chiavi (prefisso, nome, utente tecnico, permessi, azienda, IP consentiti, ultimo uso,
scadenza, stato); sotto, gli strumenti MCP esposti con la chiave selezionata e un esempio di configurazione di un
client MCP (anteprima ridotta)*
## Chiavi API
Ogni integrazione usa una **chiave API** propria, nella forma `kh_…`. La chiave:
- è legata a un **utente tecnico** dell'azienda (vedi [Utenti e permessi](Utenti-e-permessi));
- vale per **una sola azienda**;
- ha **permessi propri** (sottoinsieme dei permessi dell'utente tecnico);
- può avere una **scadenza** e un elenco di **IP consentiti**;
- viene salvata solo come impronta (hash SHA-256): nel pannello si vede soltanto il **prefisso** (es. `kh_7f3a…`).
### Elenco
| Colonna | Significato |
|---|---|
| **Chiave** | prefisso visibile della chiave |
| **Nome** | descrizione dell'integrazione (es. *Integrazione e-commerce*, *Assistente AI (MCP, sola lettura)*, *Sito web · form lead*) |
| **Utente tecnico** | utente a cui la chiave appartiene (es. `api-shop`) |
| **Permessi** | codici concessi (es. `items.read`, `inventory.read`, `crm.leads.write`) |
| **Azienda** | azienda su cui opera |
| **IP consentiti** | indirizzi o reti ammessi (es. `10.0.0.0/8`) oppure *qualsiasi* |
| **Ultimo uso** | data e numero di chiamate recenti |
| **Scadenza** | data di scadenza o nessuna |
| **Stato** | *Attiva*, *Scaduta*, *Revocata* |
### Creare una chiave
1. Se non esiste, crea l'**utente tecnico** dell'integrazione (livello *Tecnico*, flag **Può usare le API**).
2. Premi **Nuova chiave**.
3. Indica **nome**, **utente tecnico**, **azienda**, **permessi** (solo quelli necessari), **scadenza** e **IP
consentiti**.
4. Conferma. La chiave completa viene mostrata **una sola volta**: copiala subito nel sistema che la userà. Khaemhat
conserva solo l'impronta e non potrà mostrarla di nuovo.
La chiave si usa nell'intestazione di ogni richiesta:
```
Authorization: Bearer kh_…
X-Company: DEMO
```
### Revocare o sostituire una chiave
- **Revoca**: la chiave smette subito di funzionare; resta in elenco come *Revocata* per lo storico.
- Per sostituire una chiave (ad esempio a una scadenza o se è stata esposta) crea una nuova chiave, aggiorna il
sistema esterno e poi revoca la vecchia.
### Buone pratiche
- Una chiave per integrazione: se una viene compromessa la revochi senza fermare le altre.
- Permessi minimi: una chiave per un assistente AI di sola consultazione non deve avere permessi di scrittura.
- IP consentiti quando il sistema esterno ha un indirizzo fisso.
- Scadenza sulle chiavi date a terzi.
- Le chiamate sono soggette a **rate limiting per chiave** (vedi [Impostazioni](Impostazioni) → Sicurezza) e
registrate nella sezione *API / MCP* del [Log](Log).
## MCP
MCP (*Model Context Protocol*) permette a un assistente AI di usare i dati di Khaemhat tramite **strumenti**
(tool). L'endpoint è `/mcp` (Streamable HTTP, JSON-RPC 2.0) e si autentica con una chiave API come le API REST.
### Abilitare un assistente
1. Crea una chiave per l'assistente (es. *Assistente AI (MCP, sola lettura)*) con i soli permessi di lettura
necessari.
2. Seleziona la chiave: il riquadro **MCP · tool esposti con la chiave selezionata** elenca gli strumenti che
l'assistente potrà usare con quei permessi.
3. Copia l'esempio dal riquadro **Configurazione client MCP** nel programma dell'assistente, sostituendo indirizzo
e chiave:
```json
{
"mcpServers": {
"khaemhat": {
"type": "http",
"url": "https://gestionale.example.com/mcp",
"headers": { "Authorization": "Bearer kh_…" }
}
}
}
```
### Strumenti
- **In lettura**: `search_parties`, `get_party`, `search_items`, `get_item_stock`, `get_document`, `list_documents`,
`get_open_items`, `sales_summary`, `get_account_balance`, `trial_balance`, `vat_settlement_preview`,
`crm_pipeline_summary`, `get_log_errors` (solo amministratori).
- **In scrittura, opzionali per chiave**: `create_sale_order` (crea un ordine cliente in bozza), `create_party`,
`create_crm_activity`. Sono disponibili solo se la chiave ha i permessi corrispondenti.
Gli strumenti dei moduli non licenziati non compaiono. Il dettaglio di ogni strumento è nella pagina [MCP](MCP).
## Webhook
I **webhook** sono notifiche HTTP che Khaemhat invia a un indirizzo esterno quando scatta un evento, come azione
di una regola di [Automazioni](Automazioni) (es. documento emesso, lead creato, ticket aperto).
1. Premi **Webhook** nella barra della pagina.
2. Indica l'**indirizzo di destinazione** e gli eventi o le regole che lo usano.
3. Khaemhat genera un **segreto** con cui **firma** ogni invio (firma **HMAC**): il sistema che riceve verifica la
firma per essere sicuro che il messaggio venga da Khaemhat e non sia stato alterato.
4. Se la destinazione non risponde, l'invio viene **ritentato** automaticamente; gli esiti sono nel [Log](Log).
Formato del messaggio, intestazioni della firma e politica di retry sono descritti nella pagina [API](API) (da
definire in sviluppo).
## Riferimenti rapidi
| Voce | Valore |
|---|---|
| Base delle API REST | `/api/v1/{modulo}/{risorsa}`, JSON `camelCase` |
| Documentazione OpenAPI | `/api/v1/openapi.json` (OpenAPI 3.1) e pagina `/api/docs` |
| Errori | formato RFC 9457 con `trace_id` (vedi [Log](Log)) |
| Idempotenza | intestazione `Idempotency-Key` |
| Concorrenza | `ETag` / `If-Match` |
| MCP | `/mcp`, Streamable HTTP, JSON-RPC 2.0 |
## Domande frequenti
- **Ho perso la chiave.** Non è recuperabile: creane una nuova e revoca la vecchia.
- **La chiamata risponde 503.** L'azienda è in modalità manutenzione (vedi [Istanza e database](Istanza-e-database)).
- **La chiamata risponde "permesso negato" per un modulo.** Il modulo non è licenziato (`module_not_licensed`) o la
chiave non ha il permesso.
## Pagine correlate
[API](API) · [MCP](MCP) · [Utenti e permessi](Utenti-e-permessi) · [Automazioni](Automazioni) ·
[Canali e-commerce](Canali-e-commerce) · [Log](Log) · [Licenze e moduli](Licenze-e-moduli)