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>
142 lines
7.3 KiB
Markdown
142 lines
7.3 KiB
Markdown
# API REST
|
||
|
||
> **Stato:** bozza · **Ultima revisione:** 2026-11-10 · **Versione software:** non ancora rilasciata (milestone M12)
|
||
> **Modulo di licenza:** API · **Permessi principali:** flag utente "può usare le API" + permessi della chiave · **Specifica:** SPEC §15
|
||
|
||
Guida per chi deve **collegare un altro programma** a Khaemhat: sito web, e-commerce, strumenti di analisi, script
|
||
interni. Il contratto tecnico completo (tutti i codici di errore, le proposte ancora da confermare, i test) è in
|
||
[docs/API.md](https://gitea.encke-hake.ts.net/BalboSoft/Khaemhat/src/branch/main/docs/API.md). Per gli agenti AI vedi
|
||
[MCP](MCP); per creare chiavi e webhook vedi [API-e-MCP](API-e-MCP).
|
||
|
||
## Cosa serve
|
||
|
||
1. Il modulo **API** attivo (**Amministrazione › Licenze e moduli**, vedi [Licenze-e-moduli](Licenze-e-moduli)).
|
||
2. Un **utente tecnico** dell'azienda con i permessi strettamente necessari e il flag **Può usare le API**.
|
||
3. Una **chiave API** creata da **Amministrazione › Chiavi API, MCP e webhook**: copia la chiave quando viene
|
||
mostrata, perché **non sarà più visibile** (il programma conserva solo un'impronta e il prefisso).
|
||
4. L'indirizzo pubblico di Khaemhat in HTTPS (ad esempio `https://gestionale.example.com`).
|
||
|
||

|
||
*Mockup 088 — elenco delle chiavi con prefisso, utente, permessi, azienda, IP consentiti e scadenza; sotto, i tool MCP esposti e un esempio di configurazione del client (anteprima ridotta).*
|
||
|
||
## Come si chiama l'API
|
||
|
||
Ogni richiesta porta la chiave e, se serve, l'azienda:
|
||
|
||
```bash
|
||
curl -s "https://gestionale.example.com/api/v1/parties?pageSize=20" \
|
||
-H "Authorization: Bearer kh_test_0000000000000000000000" \
|
||
-H "X-Company: DEMO"
|
||
```
|
||
|
||
| Elemento | Valore |
|
||
|---|---|
|
||
| Indirizzo base | `https://<tuo-server>/api/v1/` |
|
||
| Autenticazione | `Authorization: Bearer kh_…` |
|
||
| Azienda | header `X-Company: <codice>`; facoltativo se la chiave è già legata a un'azienda |
|
||
| Formato | JSON, nomi dei campi in `camelCase`, date `aaaa-mm-gg`, importi con il punto decimale |
|
||
| Documentazione interattiva | `https://<tuo-server>/api/docs` |
|
||
| Descrizione macchina | `https://<tuo-server>/api/v1/openapi.json` (OpenAPI 3.1) |
|
||
|
||
La documentazione interattiva e il file OpenAPI mostrano **solo** le risorse dei moduli attivi.
|
||
|
||
## Risorse disponibili
|
||
|
||
| Area | Risorse |
|
||
|---|---|
|
||
| Anagrafiche e articoli | `parties`, `items`, `price-lists` |
|
||
| Vendite | `sale-orders`, `delivery-notes`, `invoices` |
|
||
| Acquisti | `purchase-orders`, `purchase-invoices` |
|
||
| Magazzino | `inventory/balances`, `inventory/entries` |
|
||
| Contabilità (ACCT) | `ledger/accounts`, `ledger/entries` |
|
||
| Scadenzario (FIN) | `open-items`, `payments` |
|
||
| Fatturazione elettronica (EINV) | `e-invoices` |
|
||
| Allegati | `attachments` (download) e caricamento di un file su un documento |
|
||
| CRM | `crm/leads`, `crm/opportunities`, `crm/activities` |
|
||
| Canali e-commerce (CHAN) | `channels/{codice}/orders` |
|
||
| Report | `reports/{codice}` |
|
||
| Amministrazione | `admin/status` (sola lettura, solo account di istanza) |
|
||
|
||
I metodi previsti per ogni risorsa sono nella tabella di
|
||
[docs/API.md](https://gitea.encke-hake.ts.net/BalboSoft/Khaemhat/src/branch/main/docs/API.md#8-risorse-previste).
|
||
|
||
## Elenchi: pagine, ordinamento e filtri
|
||
|
||
```
|
||
GET /api/v1/invoices?page=1&pageSize=50&sort=-date&filter=date ge 2026-10-01
|
||
```
|
||
|
||
- `page` e `pageSize` (predefinito 50) per scorrere; la risposta contiene `items`, `page`, `pageSize`, `totalCount`.
|
||
- `sort`: uno o più campi separati da virgola; il segno `-` ordina dal più grande al più piccolo.
|
||
- `filter`: condizioni sui campi ammessi dalla risorsa (la sintassi esatta sarà fissata in sviluppo ed è descritta
|
||
nella documentazione interattiva).
|
||
|
||
## Modificare senza sovrascrivere il lavoro di altri
|
||
|
||
Quando leggi un record ricevi un'intestazione `ETag`. Per modificarlo o eliminarlo rimandala in `If-Match`: se nel
|
||
frattempo qualcuno ha salvato lo stesso record, Khaemhat risponde **412** e non cambia nulla. Rileggi il record e
|
||
riprova.
|
||
|
||
## Non creare doppioni
|
||
|
||
Per le creazioni (ordini, anagrafiche, pagamenti, caricamento file) aggiungi un'intestazione `Idempotency-Key` con un
|
||
valore univoco (ad esempio il numero dell'ordine web). Se la stessa richiesta parte due volte per un problema di rete,
|
||
Khaemhat crea il record **una sola volta** e restituisce la stessa risposta.
|
||
|
||
## Quando qualcosa va storto
|
||
|
||
Gli errori seguono lo standard RFC 9457: un JSON con titolo, descrizione in italiano, un `code` leggibile dal programma
|
||
e un **`traceId`**. Comunica il `traceId` all'amministratore: è il **Codice errore** con cui ritrova l'evento in
|
||
**Amministrazione › Log** (vedi [Log](Log)).
|
||
|
||
| Stato | Cosa significa | Cosa fare |
|
||
|---|---|---|
|
||
| 400 | dati non validi | correggere i campi indicati in `errors` |
|
||
| 401 | chiave mancante, errata, scaduta o IP non ammesso | verificare la chiave e gli IP consentiti |
|
||
| 403 | permesso mancante o modulo non attivo (`module_not_licensed`) | chiedere all'amministratore |
|
||
| 404 | il record non esiste in quell'azienda | controllare id e `X-Company` |
|
||
| 409 | operazione non possibile nello stato attuale (es. fattura già emessa, periodo bloccato) | cambiare operazione |
|
||
| 412 | il record è stato modificato da altri | rileggere e riprovare |
|
||
| 429 | troppe richieste | attendere i secondi indicati in `Retry-After` |
|
||
| 503 | azienda in manutenzione | riprovare più tardi |
|
||
|
||
## Webhook: farsi avvisare da Khaemhat
|
||
|
||
Invece di interrogare l'API di continuo, puoi farti chiamare quando succede qualcosa (fattura emessa, ordine
|
||
confermato, notifica SDI…):
|
||
|
||
1. In **Amministrazione › Chiavi API, MCP e webhook** crea un webhook con l'indirizzo del tuo servizio e conserva il
|
||
**segreto**.
|
||
2. In **Automazioni** crea una regola con azione **Webhook** sull'evento che ti interessa (vedi
|
||
[Automazioni](Automazioni)).
|
||
3. Il tuo servizio riceve un `POST` JSON firmato con HMAC-SHA256: verifica sempre la firma con il segreto prima di
|
||
fidarti del contenuto.
|
||
4. Rispondi con uno stato `2xx` entro pochi secondi: in caso contrario Khaemhat ritenta più volte a intervalli
|
||
crescenti e, dopo ripetuti errori, disattiva il webhook e avvisa gli amministratori.
|
||
|
||
## Esempio: un ordine dal sito web
|
||
|
||
```bash
|
||
curl -s -X POST "https://gestionale.example.com/api/v1/sale-orders" \
|
||
-H "Authorization: Bearer kh_test_0000000000000000000000" \
|
||
-H "X-Company: DEMO" -H "Content-Type: application/json" \
|
||
-H "Idempotency-Key: web-100231" \
|
||
-d '{ "partyCode": "C000042", "date": "2026-11-10",
|
||
"lines": [ { "itemCode": "ART-0001", "quantity": 2 } ] }'
|
||
```
|
||
|
||
Per i negozi online con molti ordini è più adatto il **connettore generico** dei canali e-commerce
|
||
(`POST /api/v1/channels/{codice}/orders`, vedi [Canali-e-commerce](Canali-e-commerce)).
|
||
|
||
## Buone pratiche di sicurezza
|
||
|
||
- Una chiave per ogni integrazione, con i soli permessi necessari, una **scadenza** e gli **IP consentiti**.
|
||
- Mai inserire la chiave nel codice di una pagina web pubblica: va usata solo lato server.
|
||
- Se una chiave è stata esposta, revocala subito e creane una nuova.
|
||
- Il traffico deve passare in HTTPS dal reverse proxy.
|
||
|
||
## Pagine correlate
|
||
|
||
[API-e-MCP](API-e-MCP) · [MCP](MCP) · [Automazioni](Automazioni) · [Utenti-e-permessi](Utenti-e-permessi) ·
|
||
[Licenze-e-moduli](Licenze-e-moduli) · [Log](Log)
|