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