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>
7.3 KiB
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 e 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
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);
- 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
- Se non esiste, crea l'utente tecnico dell'integrazione (livello Tecnico, flag Può usare le API).
- Premi Nuova chiave.
- Indica nome, utente tecnico, azienda, permessi (solo quelli necessari), scadenza e IP consentiti.
- 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 › Sicurezza) e registrate nella sezione API / MCP del 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
- Crea una chiave per l'assistente (es. Assistente AI (MCP, sola lettura)) con i soli permessi di lettura necessari.
- Seleziona la chiave: il riquadro MCP · tool esposti con la chiave selezionata elenca gli strumenti che l'assistente potrà usare con quei permessi.
- Copia l'esempio dal riquadro Configurazione client MCP nel programma dell'assistente, sostituendo indirizzo e chiave:
{
"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.
Webhook
I webhook sono notifiche HTTP che Khaemhat invia a un indirizzo esterno quando scatta un evento, come azione di una regola di Automazioni (es. documento emesso, lead creato, ticket aperto).
- Premi Webhook nella barra della pagina.
- Indica l'indirizzo di destinazione e gli eventi o le regole che lo usano.
- 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.
- Se la destinazione non risponde, l'invio viene ritentato automaticamente; gli esiti sono nel Log.
Formato del messaggio, intestazioni della firma e politica di retry sono descritti nella pagina 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) |
| 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).
- 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 · MCP · Utenti e permessi · Automazioni · Canali e-commerce · Log · Licenze e moduli