Files
Khaemhat/docs/wiki/API.md
T
Alby96andClaude Opus 5.5 e746d99dab docs: add specification, design docs, mockups, wiki and deploy files
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>
2026-11-10 22:26:58 +01:00

142 lines
7.3 KiB
Markdown
Raw Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
# 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`).
![088 · 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 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)