# 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)