Wiresphere Docs

Tutto ciò che serve per lavorare con Wiresphere — organizzato per destinatari: utenti finali (sistema di gestione), DevOps & architetti (piattaforma, operatività, concetti) e sviluppatori (SDK, CLI, API).

Accesso & login

Ecco come accedere al sistema di gestione:

• Apra l'URL di amministrazione nel browser (ad es. https://suo-dominio.it/admin/login)
• Inserisca nome utente e password ricevuti nell'e-mail di benvenuto — rispettando maiuscole e minuscole
• Con l'icona a forma di occhio può rendere visibile la password; «Salva login» memorizza il Suo accesso
• Password dimenticata? Tramite «Reimposta password» sotto il pulsante di login riceve un link di reset

Dashboard

La dashboard offre una panoramica delle prestazioni della Sua azienda e aiuta a monitorare gli indicatori più importanti. La maggior parte dei widget può essere impostata tramite menu a tendina su intervalli settimanali, mensili o annuali.

Panoramica dei processi

La panoramica dei processi mostra tutte le transazioni e il loro stato. I processi possono essere filtrati (ordinamento, tipo, canale, periodo), analizzati e gestiti.

• Tabella: numero di transazione, cliente, data, importo (netto), stato del pagamento, canale, numero di tipo e tipo (offerta, fattura, ordine)
• Stato del pagamento: Pagato (verde) · In attesa di pagamento (giallo) · In sospeso (arancione) · Scaduto/insoluto (rosso)
• Azioni: «+ Aggiunga transazione», «Esporta selezione» e «Applica filtri»

Dettagli del processo

Un clic su un processo nella panoramica apre la vista di dettaglio con tutte le informazioni sul suo svolgimento.

• Dettagli cliente & pagamento: nome, numero cliente, e-mail; stato della fattura e metodo di pagamento (ad es. NFC Payment)
• Indirizzi: indirizzo di fatturazione e di consegna modificabili tramite l'icona di modifica
• Tabella articoli: codice articolo, descrizione, quantità, prezzo unitario, IVA, peso totale, prezzo totale
• Riepilogo prezzi: subtotale, sconto, spese di spedizione, IVA, totale complessivo
• Azioni: aggiungere articoli, stornare la selezione, stampare il QR code, eliminare il processo, salvare

Gestire i prodotti

La panoramica prodotti (menu «Gestione merci» → «Panoramica prodotti») elenca tutti i prodotti con codice articolo, prezzo netto, giacenza e stato.

Creare & modificare un prodotto

I nuovi prodotti si creano tramite «+ Aggiunga prodotto» (nome articolo, codice articolo, categoria, prezzo, giacenza → Salva). I prodotti esistenti si modificano tramite l'icona a matita nella riga della tabella.

Prezzi scaglionati

Nella scheda «Prezzi scaglionati» della vista di dettaglio del prodotto definisce per ogni scaglione quantità minima e prezzo; con «+ aggiunga» inserisce ulteriori scaglioni.

Add-On-Sellings

Le vendite aggiuntive (accessori, upgrade, garanzie) possono essere associate direttamente a un prodotto principale e vengono proposte automaticamente al momento dell'ordine — questo aumenta il valore del carrello e favorisce il cross-selling.

Esportare / importare prodotti

Esportare: tutti i dati prodotto (nome, codice articolo, prezzi, giacenza, categorie) come file XLS o CSV — per analisi, elaborazione esterna o documentazione.

Importare: dati prodotto aggiornati o nuovi in formato XLS/CSV. Il sistema riconosce i prodotti esistenti dal codice articolo e aggiorna le informazioni modificate; i nuovi prodotti vengono aggiunti senza sovrascrivere quelli esistenti.

Categorie

In «Categorie» suddivide i Suoi prodotti in gruppi — questo semplifica la gestione e la reperibilità nell'assortimento.

• Nome: significativo e univoco
• Slug: versione URL-friendly del nome (minuscolo, senza caratteri speciali o spazi) — importante per link e SEO
• Proprietà filtro & navigazione: vengono aggiunte automaticamente dal sistema dopo il salvataggio
• Salvare / eliminare: per sicurezza, le eliminazioni richiedono un'ulteriore conferma

CRM: contatti & organizzazioni

Il modulo CRM gestisce centralmente referenti (persone) e organizzazioni — raggiungibile tramite la scheda «CRM» nella navigazione principale.

• Creare un contatto: «+ Aggiunga contatto» → scegliere persona o organizzazione → inserire i dati → associare facoltativamente la persona a organizzazioni → salvare
• Modificare: icona a matita accanto alla voce — lì anche aggiunta ed eliminazione (attenzione: l'eliminazione è definitiva)
• Cercare & filtrare: tramite la barra di ricerca per nome, indirizzi e-mail e altri criteri

Esportare / importare contatti

Esportare: tutti i contatti come file XLS o CSV — per ulteriori elaborazioni, archiviazione o analisi.

Importare: dati di contatto aggiornati o nuovi in formato XLS/CSV. Le modifiche vengono riconosciute automaticamente e le voci esistenti aggiornate — senza record duplicati. Ideale per la manutenzione periodica dei dati e il consolidamento da fonti diverse.

Attivare / disattivare gli account

In CRM → Persone → Modifica persona si trova l'interruttore «L'account è disattivato» — utile in caso di cambio di reparto, assenza o uscita dall'azienda.

Se l'interruttore è attivo, la persona non può più effettuare l'accesso; se viene disattivato, riacquista l'accesso regolare. Confermi le modifiche con «Salva». La disattivazione non elimina alcun dato — l'account può essere riattivato in qualsiasi momento.

Impostazioni

Tramite l'icona a ingranaggio in alto a destra raggiunge le configurazioni centrali — organizzate a sinistra in Shop (metodi di pagamento, plugin, valute), Utenti (ruoli e permessi), Aliquote fiscali e Unità.

Che cos'è Wiresphere?

Wiresphere è una runtime modulare per il software enterprise. Le applicazioni non vengono costruite una volta e poi mantenute, ma composte a runtime da moduli intercambiabili. L'ecosistema è formato da quattro componenti: la Runtime carica, isola e orchestra i moduli. Il Module SDK definisce come vengono costruiti i moduli — contract-first, type-safe, versionati. L'Enterprise SDK lo estende con Private Functions senza obbligo di pubblicazione, oltre a SSO, policy e integrazione audit. Il Marketplace si occupa di discovery, licenze e aggiornamenti automatici dei moduli certificati.

Il core è open source e funziona nel cloud UE o sulla propria infrastruttura. Non ci sono licenze né partecipazione al GMV — si paga solo l'infrastruttura.

Concetti fondamentali

Modulo

L'unità di base di Wiresphere. Un modulo incapsula una capacità funzionale (ad es. checkout, integrazione con il magazzino, configuratore) in uno scope isolato con un contract tipizzato in modo esplicito. Ciò che non è nel contract, per gli altri moduli non esiste.

Scope

Lo spazio di isolamento di un modulo. Gli scope limitano l'accesso e l'impatto degli errori: un modulo non può accedere allo stato altrui e un errore resta confinato nel proprio scope. Gli scope sono volutamente piccoli — abbastanza piccoli perché anche un coding agent con contesto limitato possa comprenderli per intero.

Contract

L'interfaccia tipizzata e versionata semanticamente di un modulo. I contract vengono applicati dal Service Broker: riceve le richieste dei moduli via HTTP e le valida prima dell'elaborazione — le chiamate incompatibili vengono rifiutate, non scoperte in produzione.

Composizione

Lo stato di un'applicazione: quali moduli sono attivi, in quale versione e come sono collegati. Le composizioni si modificano a runtime — caricare, sostituire, disattivare moduli — senza redeploy.

Glossario

Opzioni di deployment

• Wiresphere Cloud (UE): infrastruttura preconfigurata e a scalabilità automatica. Deploy in 1 clic su Wiresphere Cloud — si parte gratuitamente.
• Self-hosting: la runtime open source funziona sulla propria infrastruttura — on-premise o nel cloud di Sua scelta. Funzionalità complete, piena sovranità dei dati.
• Ibrido: runtime on-premise, collegamento al Marketplace per moduli e update tramite canali controllati.

Indipendentemente dal deployment, codice sorgente e dati restano nelle Sue mani — la piattaforma è exit-ready by design.

Composizione live

I moduli vengono inseriti, sostituiti o disattivati nell'applicazione in esecuzione — senza downtime e senza finestre di manutenzione. Prima di ogni modifica la runtime verifica la compatibilità dei contract della composizione di destinazione; le modifiche incompatibili vengono rifiutate prima di avere effetto.

Svolgimento di una modifica

• La nuova versione del modulo viene caricata e inizializzata nello scope
• La runtime collega i contract e reindirizza le chiamate in modo atomico alla nuova versione
• La versione precedente viene scaricata; in caso di errori interviene il rollback automatico per singolo modulo

Scope isolati

Ogni modulo viene eseguito in uno scope dedicato con confini definiti. Questo limita il blast radius degli errori, previene accoppiamenti nascosti e rende i moduli sviluppabili, testabili e manutenibili in modo indipendente — anche da coding agent, il cui contesto non basterebbe mai per un monolite.

Update & rollback

I moduli ricevono gli update dal Marketplace tramite canali versionati. Prima dell'installazione la runtime verifica la compatibilità semantica rispetto alla composizione attiva. Ogni update è reversibile per singolo modulo — un update difettoso non richiede il restore dell'applicazione.

Frontend

I frontend sono disaccoppiati dai moduli e consumano gli stessi contract — web, app, backoffice B2B o hardware kiosk senza contesto browser. Lo stack frontend è liberamente selezionabile; un cambio non richiede alcuna migrazione del backend.

Channels & Checkout Handler

Wiresphere lavora per Channels: canali autonomi attraverso cui vengono piazzati ordini e commesse. I Channels disponibili sono E-Commerce, Kiosk, Cassa, Live Chat e AI Chat. Tutti i Channels alimentano gli stessi moduli — la logica degli ordini esiste una sola volta.

Ruoli & permessi

Ogni Channel è soggetto a un proprio modello di ruoli e permessi. I diritti vengono assegnati per canale — un agente di chat, un cassiere e un assistente AI operano con permessi diversi, senza autorizzazioni globali.

Checkout Handler

Checkout Handler flessibili determinano come funziona il flusso d'ordine nel rispettivo Channel. Lo stesso ordine può così seguire un percorso completamente diverso a seconda del canale:

Console di amministrazione

La console di amministrazione è la centrale operativa di un'applicazione Wiresphere. Mostra la composizione attiva — tutti i moduli, le versioni, i canali di update e i collegamenti tra contract — e registra ogni modifica.

• Panoramica della composizione: quali moduli sono in esecuzione, in quale versione, da quando e da quale fonte
• Registro delle modifiche: chi ha inserito, aggiornato o ripristinato quale modulo e quando
• Ambienti: composizioni separate per produzione, staging e sviluppo

Gestire i moduli

• Installare: scegliere il modulo dal Marketplace, confermare la licenza, selezionare la composizione di destinazione — la verifica di compatibilità è automatica
• Aggiornare: definire il canale di update per modulo (stable/beta); gli update fluiscono automaticamente o dopo approvazione manuale
• Ripristinare: ogni versione di modulo può essere riportata singolarmente allo stato precedente
• Disattivare: i moduli possono essere rimossi dalla composizione senza disinstallarli

Utenti & permessi

L'accesso alla console di amministrazione è basato sui ruoli. Ruoli tipici: Owner (tutto, fatturazione inclusa), Operator (modificare la composizione, approvare gli update), Auditor (accesso in sola lettura a composizione e registri). Le modifiche alle composizioni di produzione possono richiedere un'approvazione a quattro occhi.

Operatività & monitoraggio

• Stato per scope: health, carico ed errori vengono rilevati per singolo modulo — le anomalie sono direttamente riconducibili alla loro origine
• Audit & compliance: stato della composizione e cronologia delle modifiche esportabili in qualsiasi momento (rilevante per le evidenze NIS2)
• Controllo del deployment: regione UE oppure on-premise; i dati non lasciano la giurisdizione scelta

Quickstart

Avviare la runtime locale, generare lo skeleton di un modulo, comporre — senza registrazione:

# Avviare la runtime locale
npx wiresphere dev

# Generare lo skeleton del modulo (TypeScript, contract-first)
npx wiresphere create module my-checkout

# Comporre il modulo nell'applicazione in esecuzione — nessun rebuild
npx wiresphere compose add ./my-checkout

La dev runtime è disponibile di default su localhost:4200 e mostra la composizione attiva, inclusi tutti i moduli caricati e le versioni dei loro contract.

Module SDK

I moduli vengono costruiti in TypeScript sull'SDK. Il contract è il cuore — definisce ciò che il modulo offre e consuma:

import { defineModule } from "@wiresphere/sdk";
import { CartContract, PaymentContract } from "./contracts";

export default defineModule({
  name: "checkout",
  version: "1.4.2",
  contracts: { cart: CartContract, payment: PaymentContract },
  scope: { isolation: "strict" },
  setup({ runtime, config }) {
    runtime.expose("checkout.session", createSession(config));
  },
});

API Runtime

Contract & versionamento

I contract sono versionati semanticamente. La runtime accetta automaticamente gli update minor e patch (retrocompatibili); gli update major richiedono una modifica esplicita della composizione. Le incompatibilità vengono intercettate al Service Broker (validazione di ogni richiesta HTTP rispetto al contract versionato) e al momento della composizione — mai soltanto in produzione.

CLI

API REST

Oltre a SDK e CLI, Wiresphere mette a disposizione un'API REST multi-tenant. Il riferimento completo degli endpoint con tutti gli schemi di request/response è disponibile come pagina dedicata:

Apri il riferimento API completo 

Autenticazione

L'API utilizza l'autenticazione basata su token (Bearer JWT). I token si richiedono tramite POST /api/v1/auth/token-auth con username e password e sono validi 24 ore. Un token scaduto o non valido genera 409 Conflict.

Authorization: Bearer <il-suo-token>

Concetto di tenant

L'API è multi-tenant: quasi ogni richiesta deve identificare il contesto dello shop tramite l'header tenant-id — senza di esso le richieste vengono rifiutate. Eccezione: l'autenticazione come utente admin (in quel caso l'header non deve essere inviato).

tenant-id: mio-shop-id

Paginazione, filtri & ordinamento

Tutti gli endpoint di elenco supportano parametri query uniformi:

# Filtro semplice (ricerca di sottostringhe)
f=fieldName::value

# Più valori (in OR)
f=fieldName::val1~~val2

# Escludere (prefisso --)
f=fieldName::--valoreEscluso

# Filtro per periodo (ISO 8601)
f=min_createdAt::2024-01-01T00:00:00.000Z

# Ordinamento
o=createdAt::DESC,name::ASC

Gruppi di endpoint

Guida: comporre uno shop

Uno shop headless nasce da quattro moduli di catalogo — senza sviluppo proprio:

• checkout — carrello, pagamento, fulfillment
• lager-interface — giacenze e disponibilità dalla gestione merci
• subscription-management — opzionale per abbonamenti e pagamenti ricorrenti
• Frontend a Sua scelta — web, app o kiosk, collegato tramite gli stessi contract

I requisiti specifici (ad es. la logica di prezzo) si aggiungono come modulo dedicato — il resto della composizione resta intatto.

Guida: pubblicare un modulo

• Sviluppare: costruire il modulo sull'SDK e validarlo in locale con wiresphere dev e wiresphere test
• Inviare: wiresphere publish — verifica dei tipi, review di compatibilità e qualità nel processo di certificazione
• Distribuire: licenze e auto-update sono gestiti dal Marketplace — con un revenue share equo

Dettagli sul programma partner e sulla certificazione: Sviluppatori → Pubblicare un modulo.