2
API e MCP
Alberto Balbo edited this page 2026-11-10 22:28:47 +01:00

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

088 · Amministrazione · chiavi API, MCP e webhook

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

  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 → 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

  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:
{
  "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).

  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.

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