Gitea flags en dash, multiplication sign, minus sign and single angle quotes as confusable characters, which put a warning on most pages; use plain equivalents (docs/SPEC.md stays untouched). STATUS.md now lists the issue numbers per milestone, the items waiting for the owner and the open specification questions tracked by issue #114. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
159 lines
7.3 KiB
Markdown
159 lines
7.3 KiB
Markdown
# 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
|
|
|
|

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