Amministrazione Web API

Le Web API sono il canale con cui Atlantis Evo mette i propri dati a disposizione dell’esterno: l’App Mobile in primo luogo, poi il pannello POS web, i plugin WordPress / WooCommerce, i servizi supplementari di interrogazione e gli assistenti AI (Claude e simili) tramite il server MCP. Questa maschera è il punto in cui il canale si configura e si attiva.

Si trova in Utilità → Amministrazione → Web API.

Come funziona il collegamento

Atlantis Evo non pubblica nulla su internet e non richiede aperture di porte sul router: è il programma stesso che apre una connessione verso il server di appoggio di Atlantis Evo e resta in ascolto delle richieste che arrivano dall’App o dai servizi esterni. Da qui derivano tre conseguenze pratiche, che spiegano la quasi totalità delle segnalazioni di “App che non si collega”:

• il servizio funziona solo mentre Atlantis Evo è aperto sul computer designato. Se quel programma viene chiuso, o il computer viene spento, l’App smette di funzionare per tutti;
• il collegamento viene avviato dalla postazione dell’utente che ha il flag Avvia Web API nella sua scheda in Amministrazione utenti, pochi secondi dopo l’apertura del programma. Se nessun utente ha quel flag, il servizio non parte mai;
• quasi tutte le impostazioni descritte in questa pagina vengono lette solo al momento dell’avvio: una modifica salvata qui diventa operativa soltanto dopo un riavvio del servizio. Le poche eccezioni sono indicate nei rispettivi paragrafi.

All’avvio vengono attivate tutte le configurazioni dell’azienda che hanno il flag Attiva. Il servizio non parte in modalità dimostrativa (“Servizio WEB Api non eseguibile in modalita’ demo.”) né quando la licenza delle Web API risulta scaduta (“WEB Api non disponibili. Licenza scaduta.”).

Creare una configurazione

Si crea un nuovo servizio con il consueto tasto “Aggiungi” (F4 o icona con il “+”) e si compilano i dati:

• Codice: viene assegnato automaticamente dalla procedura. È unico all’interno dell’azienda, quindi ogni azienda gestita ha le proprie configurazioni, indipendenti fra loro;
• Descrizione: testo libero fino a 80 caratteri. Non è solo un’etichetta interna: il collegamento si presenta al server con la dicitura “ragione sociale dell’azienda – descrizione”, quindi conviene usare un nome che faccia capire di quale installazione si tratta;
• Attiva: governa l’attivazione e la disattivazione. Togliere il flag non chiude una connessione già in corso, ma impedisce che venga riaperta al successivo avvio o riavvio del servizio.

La stessa azienda può avere più configurazioni attive, ognuna con il proprio ID installazione e le proprie “Altre impostazioni”. È utile per dare accessi diversi a persone diverse: per esempio una configurazione per il titolare con il server MCP acceso e una per i dipendenti e gli agenti senza. Il numero di utenti previsto dalla licenza vale per l’azienda nel suo complesso: aggiungere configurazioni non moltiplica il limite.

ID installazione e Link APP mobile

L’ID installazione è la chiave che identifica questa installazione e questa azienda: è ciò che l’App usa per sapere a quale Atlantis Evo collegarsi. Va creato con il pulsante Genera posto alla sua destra, che produce un codice di 64 caratteri casuali.

Non conviene scriverlo a mano. Al salvataggio viene comunque controllato e deve rispettare tutte queste condizioni: almeno 24 caratteri, almeno una lettera maiuscola, almeno una minuscola, almeno una cifra, nessuno spazio e nessun simbolo (solo lettere e numeri). Se il controllo non passa il record non viene salvato e compare il messaggio “ID installazione non valido. La lunghezza deve essere almeno 24 caratteri con una maiuscola, una minuscola, una cifra e nessuno spazio”. Il messaggio cita solo gli spazi, ma sono rifiutati anche trattini, punti, trattini bassi e ogni altro simbolo.

Il Link APP mobile è il collegamento pronto all’uso, nella forma https://app.atlantisevo.com/?token=<ID installazione>. Viene ricalcolato da solo quando si genera l’ID e ogni volta che si richiama la configurazione. Il pulsante Copia alla sua destra lo mette negli appunti (“Link copiato negli appunti.”): è sufficiente incollarlo in una email o in un messaggio WhatsApp al dispositivo da configurare. Chi lo apre si ritrova direttamente alla pagina di accesso, senza dover digitare il token. Vedi “Installazione App mobile” per la procedura completa sul dispositivo.

L’ID installazione non è una password: chi conosce il link arriva solo alla pagina di accesso, dove servono comunque nome utente e password.

⚠️ Rigenerare l’ID installazione invalida tutti i dispositivi già configurati. Il vecchio link smette di funzionare e ogni smartphone o tablet va riconfigurato con il nuovo; lo stesso vale per il pannello POS e per gli assistenti AI collegati tramite il server MCP. Si rigenera solo se il token è stato divulgato per errore, mai per abitudine.

⚠️ Due configurazioni non devono avere lo stesso ID installazione. La maschera non lo impedisce, ma le richieste verrebbero sempre servite dalla prima delle due, con le sue impostazioni.

URL server MCP

Sotto il Link APP mobile compare l’URL server MCP, nella forma https://ws.daobox.net/mcp/<ID installazione>: è l’indirizzo da inserire nel connettore di un assistente AI (in claude.ai: Impostazioni → Connettori → Aggiungi connettore personalizzato). Anche questo si aggiorna da solo con l’ID installazione e ha il suo pulsante Copia.

Se la configurazione ha il flag Server MCP (assistenti AI) acceso la copia conferma “URL del server MCP copiato negli appunti.”; se è spento l’indirizzo viene copiato lo stesso ma compare l’avviso “URL copiato. Attenzione: il server MCP non e’ attivo per questo record (Altre impostazioni).”, perché con quell’indirizzo l’assistente non riuscirebbe a collegarsi. Il flag è descritto più avanti.

Durata in gg login

Indica per quanti giorni resta valido l’accesso eseguito dall’App, o l’autorizzazione data a un assistente AI: entro quel periodo l’utente ritrova l’applicazione già aperta e non deve reinserire le credenziali a ogni utilizzo. Se il campo è vuoto o contiene zero il valore non viene comunicato al server, che applica il proprio valore predefinito di 30 giorni.

Valori bassi (1-7 giorni) sono più sicuri se i dispositivi sono personali ma non protetti; valori alti sono più comodi per gli agenti che usano l’App tutti i giorni.

ID Servizi

È il token dei servizi supplementari: le chiamate con cui un sistema esterno può chiedere ad Atlantis Evo, per esempio, il prezzo di un articolo o il PDF di un documento. Il valore costituisce la parte variabile dell’indirizzo che il sistema esterno deve richiamare (https://ws.daobox.net:4433/service/<ID Servizi>/…), quindi va comunicato a chi realizza l’integrazione.

Anche qui si usa il pulsante Genera (produce 24 caratteri) e valgono le stesse regole di validazione dell’ID installazione; il messaggio di errore in caso di valore non conforme è “ID servizi non valido. La lunghezza deve essere almeno 24 caratteri con una maiuscola, una minuscola, una cifra e nessuno spazio”. Se il campo resta vuoto i servizi supplementari non vengono pubblicati e le relative chiamate non trovano risposta.

Chi conosce l’ID Servizi raggiunge l’indirizzo dei servizi senza nome utente e password, ma da solo ottiene soltanto la risposta del servizio di prova: il prezzo degli articoli e il PDF dei documenti richiedono anche il Token Servizi WordPress / WooCommerce. L’ID Servizi non dà accesso né ai dati dell’App né al server MCP.

Chi può accedere: utenti e agenti

Le credenziali abilitate non si impostano in questa maschera: vengono raccolte automaticamente all’avvio del servizio da due archivi.

• Tutti gli utenti di Atlantis Evo che hanno una password impostata. Sull’App entrano con le stesse credenziali che usano sul programma e con accesso completo ai dati;
• Tutti gli agenti che hanno compilato sia Nome utente sia Password nel riquadro “Dati accesso API / APP” della loro anagrafica. L’agente vede i propri clienti, cioè quelli a lui collegati in anagrafica. Il nome utente dell’agente deve essere univoco: in caso contrario l’anagrafica agente non si salva e segnala “Nome utente per API / APP già utilizzato”.

Il numero di utenti e di agenti effettivamente utilizzabili è stabilito dalla licenza. Anche in questo caso l’elenco viene costruito all’avvio: un utente creato, o una password modificata, entra in funzione solo dopo un riavvio del servizio.

Gli assistenti AI collegati al server MCP accettano soltanto gli utenti di Atlantis Evo, non gli agenti, e non occupano posti nel limite utenti della licenza.

Livello complessità password richiesta

Questa impostazione, nel riquadro Altre impostazioni, decide quali fra le credenziali appena descritte vengono davvero pubblicate. Le password che non soddisfano il requisito non vengono comunicate al server e quindi non permettono l’accesso all’App né agli assistenti AI.

Basso (non consigliato)	nessun requisito reale: basta una password di almeno 2 caratteri
Medio (8 car. maiuscole e min. + numeri)	almeno 8 caratteri, con almeno una lettera minuscola, una maiuscola e una cifra
Alto (10 caratteri con simboli)	almeno 10 caratteri, con almeno una lettera minuscola, una maiuscola, una cifra e un simbolo

⚠️ L’esclusione è silenziosa. Chi ha una password troppo debole non riceve un avviso in Atlantis Evo: semplicemente non riesce più ad accedere all’App, che risponde come se le credenziali fossero sbagliate. Dopo aver alzato il livello è necessario far aggiornare le password agli interessati e riavviare il servizio, altrimenti si passa il pomeriggio a cercare un guasto che non c’è.

Token Servizi WordPress / WooCommerce

È la chiave da incollare nella configurazione del plugin WordPress / WooCommerce per abilitare il dialogo fra il sito e Atlantis Evo. Si crea con il pulsante Genera alla sua destra, che produce 32 caratteri.

Il token viaggia dentro ogni richiesta del plugin: se non coincide con quello memorizzato qui la risposta è “Token errato” e il sito non riceve dati. A differenza dei due precedenti, questo token non viene controllato al salvataggio: se lo si scrive a mano, un errore di battitura non viene segnalato dalla maschera ma si manifesta solo come sito che non risponde.

Il token viene riletto a ogni richiesta: dopo averlo cambiato non serve riavviare il servizio, ma va aggiornato subito anche nel plugin.

App Pro

Il flag App Pro abilita le funzioni evolute dell’App, in primo luogo la creazione dei documenti dal dispositivo. Con App Pro attivo il numero di agenti abilitati è quello previsto dalla licenza.

Richiede il relativo modulo nella licenza. Se il modulo non c’è il flag è bloccato, appare spento anche su una configurazione in cui era stato acceso in passato, e passandoci sopra con il mouse compare “Modulo App Pro non compreso nella licenza”; al salvataggio viene registrato spento.

Il flag viene letto dall’App al momento dell’accesso: non serve riavviare il servizio, basta che l’utente esca e rientri nell’App.

Pannello Pos

Il flag Pannello Pos abilita il pannello di vendita POS web per chi accede con questa configurazione. Si comporta come App Pro: richiede il modulo POS nella licenza, altrimenti è bloccato con l’avviso “Modulo POS non compreso nella licenza” e viene salvato spento; non richiede il riavvio del servizio.

Server MCP (assistenti AI)

Il flag Server MCP (assistenti AI) permette a un assistente AI (claude.ai, Claude Desktop, Claude Code e gli altri programmi compatibili con il protocollo MCP) di leggere i dati del gestionale: anagrafiche, articoli, prezzi, documenti, scadenze, mastrini e tabelle di base. L’accesso è in sola lettura: l’assistente non può creare, modificare o cancellare nulla.

Il collegamento si fa con l’URL server MCP descritto sopra. La prima volta l’assistente apre una pagina di accesso in cui si inseriscono nome utente e password di un utente di Atlantis Evo (non di un agente), con una password che rispetti il livello di complessità della configurazione. L’assistente legge poi con la visibilità completa dell’azienda, come l’utente che lo ha autorizzato, fino alla scadenza indicata in Durata in gg login.

Il flag vale per la singola configurazione: per limitare gli assistenti AI a poche persone conviene creare una configurazione apposita, con il flag acceso e il livello password Alto, lasciandolo spento su quella usata da tutti per l’App.

⚠️ Per accendere il server MCP serve il riavvio del servizio, per spegnerlo no. Spegnendo il flag e salvando, le richieste degli assistenti già collegati vengono rifiutate subito; accendendolo, invece, il server diventa raggiungibile solo dopo Avvia / Riavvia. Con il flag spento la pagina di accesso avvisa “Il server MCP non è attivo per questa installazione”.

Avviare, fermare e riavviare il servizio

Oltre all’avvio automatico all’apertura del programma, nello stesso ramo di menu è disponibile la maschera di stato del servizio: mostra se il collegamento è attivo e mette a disposizione i pulsanti Avvia / Riavvia e Ferma. È lo strumento da usare dopo ogni modifica fatta qui, dopo aver creato un utente o cambiato una password, e ogni volta che l’App risulta irraggiungibile.

Se il collegamento cade per un problema di rete viene ritentato automaticamente, con attese progressivamente più lunghe; non è quindi necessario intervenire per una disconnessione momentanea.

Promemoria

• L’App, il pannello POS e gli assistenti AI funzionano solo mentre Atlantis Evo è aperto sulla postazione dell’utente con il flag “Avvia Web API”. Su quella postazione conviene evitare spegnimenti e sospensioni.
• Dopo una modifica in questa maschera serve un riavvio del servizio. Fanno eccezione solo il Token WordPress, i flag App Pro e Pannello Pos e lo spegnimento del server MCP.
• Non rigenerare l’ID installazione se non è strettamente necessario: tutti i dispositivi e gli assistenti AI già configurati vanno rifatti.
• Ogni configurazione deve avere un ID installazione diverso.
• Gli ID vanno creati con il pulsante “Genera”. Digitarli a mano espone all’errore di salvataggio o, per il token WordPress, a un guasto che la maschera non segnala.
• Alzando il livello di complessità password si escludono senza avviso gli utenti e gli agenti che non lo rispettano.
• Tutti gli utenti di Atlantis Evo con una password entrano nell’App con accesso completo: chi non deve accedere da mobile va gestito di conseguenza.
• Chi autorizza un assistente AI gli presta la propria visibilità completa sui dati, in sola lettura: il server MCP va acceso solo sulle configurazioni che servono.
• “Durata in gg login” vuoto significa 30 giorni, non “nessuna scadenza”.
• I flag App Pro e Pannello Pos senza il relativo modulo a licenza non producono alcun effetto e vengono salvati spenti.