Files
Khaemhat/docs/wiki/API-e-MCP.md
T
Alby96andClaude Opus 5.5 e746d99dab docs: add specification, design docs, mockups, wiki and deploy files
Prepare everything needed before development starts on Khaemhat, the
ERP + CRM for Italian SMEs:

- docs/SPEC.md: the original project specification, unchanged, plus
  CLAUDE.md with operational rules and amendments (Gitea instead of
  GitHub/GHCR, Docker image as the only deliverable).
- ADR 0001-0011 for the baseline decisions.
- Mockups: 22 high-resolution screens, the full gallery, 88 thumbnails
  cropped from it, mockup.css and an index.
- Technical docs (architecture, data model, modules, API, MCP, deploy,
  security, development process, status with open spec questions).
- Full draft wiki in docs/wiki (already published to the Gitea wiki).
- Icons in assets/ and deploy files for Docker Compose and Unraid,
  pointing to the Gitea package registry.

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

159 lines
7.3 KiB
Markdown
Raw Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
# 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)