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

7.3 KiB
Raw Blame History

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. Per gli agenti AI vedi MCP; per creare chiavi e webhook vedi API-e-MCP.

Cosa serve

  1. Il modulo API attivo (Amministrazione › Licenze e moduli, vedi 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 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:

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.

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

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

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

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 · MCP · Automazioni · Utenti-e-permessi · Licenze-e-moduli · Log