API e integrazioni

Questa pagina spiega come collegare Lema ad altri sistemi.

Cosa è disponibile oggi

Esigenza Come
Mostrare contenuti su un sito o un'app (news, pagine, FAQ) Web e App: i contenuti si leggono in JSON con la libreria @arcaweb/lema-web, senza credenziali segrete
Portare dati in Lema (contatti, prodotti, scadenze) Importazione dati da CSV, XLS, XLSX
Movimenti bancari Import degli estratti camt.053 / camt.054 nella riconciliazione bancaria
Portare dati fuori da Lema Ogni elenco ha Esporta CSV e Stampa lista; i documenti si scaricano in PDF; il backup scarica tutti i dati dell'azienda
Moduli sul tuo sito I formulari si possono incorporare in una pagina web
Calendari e contatti Biglietti da visita in vCard; gli eventi del portale si aggiungono al calendario
Far lavorare un agente AI esterno (Claude, ChatGPT, un agente tuo) sui dati dell'azienda Agenti AI esterni (MCP): consulta i dati e organizza i siti di Web e App

API REST

L'applicazione Lema usa un'API REST su https://lema.arcaweb.ch/api. È l'API dell'app stessa: ogni richiesta è autenticata come un utente, con i suoi permessi e i moduli attivi della sua azienda.

Per le applicazioni esterne non esistono ancora credenziali dedicate (chiavi API o account di servizio): l'accesso richiede email, password e il codice di verifica inviato via email, quindi non è adatto a un'integrazione automatica che gira da sola. L'unica eccezione sono gli agenti AI esterni, che leggono i dati con una credenziale propria.

💡 Hai bisogno di collegare un tuo gestionale, un e-commerce o un'app a Lema? Contattaci: valutiamo insieme la soluzione e ti avvisiamo quando le credenziali per app esterne saranno disponibili.

Regole che valgono per ogni chiamata

  • Una sola azienda per volta: la richiesta vede solo i dati dell'azienda corrente dell'utente
  • Permessi: un utente senza permesso riceve 403 PERMISSION_DENIED; un modulo non attivo dà 403 FEATURE_DISABLED
  • Documenti emessi immutabili: fatture e note di credito confermate non si modificano (403 IMMUTABLE_DOCUMENT)
  • Modifiche concorrenti: ogni aggiornamento porta il campo version; se nel frattempo un altro utente ha salvato, la risposta è 409 e bisogna ricaricare il dato
  • Limiti di frequenza: login e richieste ripetute sono limitati per indirizzo IP (429)

Agenti AI esterni (MCP)

Un agente AI esterno (Claude Code, Claude Desktop, ChatGPT o un agente tuo) può lavorare sui dati della tua azienda con il Model Context Protocol (MCP): usa gli stessi strumenti di consultazione dell'assistente AI (ricerche, statistiche su fatture e pagamenti, agenda, scadenze, magazzino, analisi del fatturato e della liquidità…), con il modello AI che scegli tu.

Cosa può fare:

  • leggere i dati consentiti dai suoi permessi;
  • in Web e App, se ha i permessi: creare un sito (Amministrazione), creare sezioni, importare contenuti da un file JSON di import e ordinare sezioni e contenuti (Scrittura). I contenuti importati restano bozze: li pubblichi tu in Lema. Prima di importare l'agente fa una prova e ti mostra cosa creerebbe.

Non pubblica, non elimina e non modifica altri dati (contatti, documenti…): per queste operazioni ti dice cosa fare in Lema.

Collegare un agente

  1. Apri Impostazioni → Accessi, sezione Agenti esterni (MCP), e clicca Aggiungi agente (serve essere amministratore)
  2. Dai un nome all'agente, scegli la validità della credenziale (30, 90 o 365 giorni) e i permessi: l'agente vede solo i dati consentiti. Per consultare basta Lettura; per lavorare sui siti dai a Web e App il livello Scrittura
  3. Copia l'indirizzo del server MCP e la credenziale: la credenziale si vede una volta sola
  4. Inseriscili nell'agente. Per Claude Code la finestra mostra il comando pronto da copiare:
claude mcp add --transport http lema https://lema.arcaweb.ch/api/mcp --header "Authorization: Bearer lema_mcp_..."

Ogni agente è un utente dell'azienda: occupa un posto utente dell'abbonamento e compare nell'elenco utenti con l'etichetta Agente MCP.

Gestire gli agenti

Vuoi… Come
Cambiare cosa vede Permessi sull'agente (o Modifica nell'elenco utenti): vale dalla richiesta successiva
Sostituire una credenziale persa o in scadenza Nuova credenziale: quella vecchia smette subito di funzionare
Bloccare l'accesso Revoca. L'agente resta e occupa il posto
Liberare il posto Disattiva o Rimuovi l'agente dall'elenco utenti

💡 Tratta la credenziale come una password: chi la possiede legge i dati consentiti all'agente. I risultati vengono letti dal fornitore AI che usi con l'agente.