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
Guida
Installazione
Interfaccia
Anagrafiche
Documenti
Contabilità e fisco
- Contabilità
- Chiusura e bilancio
- IVA
- Cespiti
- Intrastat
- Dichiarazioni d'intento
- Scadenzario
- Fatturazione elettronica
- Fiscalità italiana
CRM e servizi
Amministrazione
- Istanza e database
- Licenze e moduli
- Utenti e permessi
- Attività programmate
- Log
- Impostazioni
- Stato sistema
- Chiavi API e MCP
- Import/Export
- Dati di base e di esempio
Riferimento
Sviluppo
Khaemhat · ERP + CRM per PMI italiane · Repository · Issue · Roadmap · Sorgente della wiki: docs/wiki/ (le modifiche si fanno lì, non dall'editor del wiki)