Windows Printer Service

Il Windows Printer Service è l’applicazione desktop che permette di collegare le stampanti fisiche al sistema SagraFacile. Funziona come ponte tra il cloud (o il server self-hosted) e le stampanti installate su un PC Windows.

Panoramica

L’applicazione permette di:

Gestire multiple stampanti da un unico PC
Supportare sia stampanti termiche ESC/POS che stampanti standard (laser, inkjet)
Ricevere i lavori di stampa in tempo reale tramite connessione WebSocket
Monitorare lo stato e la coda di ogni stampante
Funzionare in background con icona nella barra delle applicazioni

Il Windows Printer Service è gratuito ed è incluso in tutte le versioni di SagraFacile.

Requisiti di Sistema

Sistema operativo: Windows 10 o successivo (64-bit)
Connessione internet: Necessaria per comunicare con il server SagraFacile
Stampanti: Qualsiasi stampante installata e funzionante su Windows

Download e Installazione

Scarica l’applicazione

Dalla pagina Gestione Stampanti nel pannello di amministrazione SagraFacile, clicca su “Scarica App Windows”.

In alternativa, scarica l’ultima versione dalla pagina delle release .

Estrai i file

Il download è un file ZIP. Estrai il contenuto in una cartella a tua scelta, ad esempio:

C:\Program Files\SagraFacilePrinter\
C:\SagraFacilePrinter\

Avvia l’applicazione

Esegui il file SagraFacilePrinter.exe. Al primo avvio, verrà mostrata la finestra di configurazione iniziale.

L’applicazione non richiede installazione. Non eliminare la cartella dopo aver estratto i file.

Aggiornare a una versione più recente

Chiudi prima la versione in esecuzione — tasto destro sull’icona vicino all’orologio, poi Esci — e solo dopo avvia il nuovo SagraFacilePrinter.exe.

Se provi ad avviare l’applicazione mentre un’altra copia è già attiva, compare un avviso e la seconda copia non parte. Non è un errore: due copie sullo stesso PC si contendono le stesse stampanti, registrandosi a turno presso il server, e le comande possono uscire dall’installazione sbagliata.

È la situazione in cui si finisce più spesso scaricando di nuovo il file senza chiudere quello attivo, perché il browser rinomina il secondo download in SagraFacilePrinter (1).exe invece di sovrascrivere il primo.

Configurazione Iniziale

Al primo avvio, l’applicazione mostra una finestra di benvenuto per la configurazione iniziale.

Configura l’URL del server

Cloud

Per la versione Cloud, inserisci:


https://api.sagrafacile.it

Non è l’indirizzo con cui accedi al gestionale. Il gestionale è su app.sagrafacile.it, ma quell’indirizzo non espone il servizio a cui l’app stampante deve collegarsi: se lo inserisci, l’app non riesce a connettersi. L’indirizzo corretto inizia con api.

Non aggiungere /api in fondo: l’app lo mette da sé.

Avvio automatico (opzionale)

Seleziona “Avvia automaticamente all’accensione del PC” se vuoi che l’applicazione parta in automatico quando accendi il computer.

Completa la configurazione

Clicca su “Inizia” per completare la configurazione e accedere alla dashboard principale.

Dashboard Principale

La dashboard mostra una panoramica di tutte le stampanti configurate e il loro stato.

Elementi dell’Interfaccia

Elemento	Descrizione
Server	URL del server configurato
Stato	Stato generale della connessione (Connesso, Parziale, Disconnesso)
Lista Stampanti	Elenco di tutte le stampanti configurate con stato e coda
Log Attività	Registro in tempo reale degli eventi e delle stampe

Indicatori di Stato

Simbolo	Colore	Significato
●	Verde	Connessa e pronta
◔	Arancione	Connessione in corso
○	Grigio	Disconnessa
●	Rosso	Errore
◌	Grigio chiaro	Disabilitata

Aggiungere una Stampante

Crea la stampante nel pannello web

Prima di tutto, devi creare la stampante nel pannello di amministrazione SagraFacile:

Vai a Gestione Stampanti nel pannello admin
Clicca “Aggiungi Nuova Stampante”
Configura nome, tipo documento (ESC/POS o HTML/PDF), e altre impostazioni
Salva la stampante

Genera il codice di associazione

Dal menu azioni della stampante (tre puntini), seleziona “Associa App Windows”
Apparirà un codice di 6 cifre valido per alcuni minuti

Aggiungi la stampante nell’app Windows

Nella dashboard del Windows Printer Service, clicca “Aggiungi Stampante”
Inserisci il codice di 6 cifre nel campo apposito
Clicca “Associa con Codice”

Configura la stampante locale

Dopo l’associazione riuscita, configura i dettagli:

Nome: Un nome descrittivo per identificare la stampante
Stampante Windows: Seleziona la stampante fisica dal menu a tendina
Tipo: ESC/POS (termica) o Standard (GDI)
Formato carta: Solo per stampanti Standard (A4, A5, Letter, Legal)
Abilitata: Lascia attivo per iniziare a ricevere stampe

Verifica la connessione

La stampante apparirà nella lista con stato verde (●). Puoi inviare una stampa di test dal pannello web per verificare.

Gestire le Stampanti

Clicca sulla colonna [···] di una stampante per aprire il menu azioni:

Azione	Descrizione
Modifica	Cambia nome, stampante fisica, tipo, o formato carta
Stampa Test	Invia una pagina di prova alla stampante
Stampa Prossimo	Stampa manualmente il prossimo job dalla coda
Abilita/Disabilita	Attiva o disattiva temporaneamente la stampante
Rimuovi	Elimina la stampante dalla configurazione

Modificare una Stampante

Seleziona la stampante e clicca “Modifica” dal menu azioni
Modifica i campi desiderati
Se necessario, clicca “Riassocia” per generare un nuovo collegamento
Clicca “Salva”

Disabilitare Temporaneamente

Se devi mettere in pausa una stampante (manutenzione, sostituzione carta, ecc.):

Apri il menu azioni della stampante
Clicca “Disabilita”

La stampante rimarrà configurata ma non riceverà nuovi lavori di stampa. I job verranno accodati sul server.

Per riattivare, clicca “Abilita” dallo stesso menu.

Rimuovere una Stampante

Rimuovere una stampante la disconnette completamente. Per riutilizzarla dovrai generare un nuovo codice di associazione dal pannello web.

Apri il menu azioni della stampante
Clicca “Rimuovi”
Conferma la rimozione

Icona nella Barra delle Applicazioni

L’applicazione funziona in background e mostra un’icona nella system tray (area di notifica di Windows).

Comportamento

Chiudere la finestra (X) la nasconde nella barra, non chiude l’applicazione
Doppio clic sull’icona riapre la dashboard
Clic destro sull’icona apre il menu rapido

Opzione	Descrizione
Apri Dashboard	Mostra la finestra principale
Stampanti	Lista rapida delle stampanti con stato
Impostazioni	Apre le impostazioni
Cartella Log	Apre la cartella dei file di log
Esci	Chiude completamente l’applicazione

Colore dell’Icona

L’icona cambia colore in base allo stato generale:

Colore	Significato
Verde	Tutte le stampanti connesse
Arancione	Alcune stampanti disconnesse
Rosso	Tutte le stampanti disconnesse o errore
Grigio	Nessuna stampante configurata

Impostazioni

Accedi alle impostazioni cliccando “Impostazioni” nella dashboard o dal menu della system tray.

Opzioni Disponibili

Impostazione	Descrizione
URL Server	Indirizzo del server SagraFacile
Avvio automatico	Avvia l’app all’accensione del PC
Riconnetti	Forza la riconnessione al server

Cambiare il Server

Se devi cambiare il server (es. da test a produzione):

Apri le Impostazioni
Modifica l’URL Server
Clicca “Riconnetti”
Attendi che le stampanti si ricolleghino

Cambiando server, le stampanti esistenti potrebbero non funzionare se non sono state create anche sul nuovo server. Potrebbe essere necessario riassociarle.

Log e Diagnostica

Log Attività

La dashboard mostra un log in tempo reale con:

Connessioni e disconnessioni
Lavori di stampa ricevuti ed eseguiti
Errori e avvisi

File di Log

I log dettagliati vengono salvati in:


%LOCALAPPDATA%\SagraFacilePrinterService\logs\

Equivalente a:


C:\Users\[TuoUtente]\AppData\Local\SagraFacilePrinterService\logs\

Per aprire la cartella:

Dal menu Impostazioni, clicca “Apri Cartella Log”
Oppure dal menu della system tray, seleziona “Cartella Log”

Esporta Diagnostica

Per inviare informazioni di debug al supporto:

Apri le Impostazioni
Clicca “Esporta Diagnostica”
Scegli dove salvare il file
Il file conterrà: configurazione, stato stampanti, informazioni sistema

Problemi Comuni

La stampante rimane “Disconnessa”

Verifica l’URL del server nelle impostazioni. Sul Cloud deve iniziare con api.sagrafacile.it, non con app.sagrafacile.it: quest’ultimo è il gestionale e non accetta la connessione dell’app stampante. Non deve inoltre terminare con /api.
Controlla la connessione internet del PC
Verifica che la stampante sia abilitata nel pannello web
Verifica che non sia rimasta aperta una vecchia installazione dell’app su questo o su un altro PC configurata con le stesse stampanti: due applicazioni che condividono la stessa configurazione si rubano la connessione a vicenda
Prova a cliccare “Riconnetti” nelle impostazioni

La stampa non esce

Verifica che la stampante Windows sia corretta (modifica la configurazione)
Controlla che la stampante sia accesa e pronta
Verifica la coda di stampa di Windows per errori
Prova una stampa di test dal menu azioni

Caratteri speciali non stampati correttamente

Per le stampanti ESC/POS, i caratteri speciali dipendono dalla codepage configurata:

Nel pannello web, vai a Gestione Stampanti
Dal menu azioni della stampante, seleziona “Trova Codepage”
Segui la procedura guidata per trovare la codepage corretta

L’applicazione non si avvia

Verifica i requisiti di sistema (Windows 10+ 64-bit)
Controlla l’antivirus che potrebbe bloccare l’esecuzione
Prova a eseguire come amministratore (clic destro → Esegui come amministratore)
Controlla i log per messaggi di errore

Connessione instabile

Se la connessione si interrompe frequentemente:

Verifica la stabilità della rete internet
Controlla firewall e proxy che potrebbero bloccare WebSocket
Per self-hosted: verifica che il server sia raggiungibile dalla rete del PC

Migrazione da Versioni Precedenti

Se hai utilizzato una versione precedente del Windows Printer Service (con profili singoli), l’applicazione rileverà automaticamente i vecchi profili e offrirà di importarli.

Prima di iniziare, chiudi la vecchia applicazione. Fai clic destro sulla sua icona nell’area di notifica (vicino all’orologio) e scegli Esci, poi apri Gestione attività e verifica che non resti in esecuzione alcun processo SagraFacilePrinter.

Se resta aperta, le due applicazioni si contendono le stesse stampanti: si registrano a turno sul server e le comande possono finire sull’installazione sbagliata, con la stampante che risulta connessa da entrambe le parti. È il problema più comune di questa migrazione.

Chiudi la versione precedente

Esci dalla vecchia applicazione come descritto sopra e verifica in Gestione attività che non sia più in esecuzione.

Rilevamento automatico

All’avvio, se vengono trovati profili legacy, apparirà la finestra di migrazione.

Seleziona i profili

Seleziona quali profili importare dalla lista. Ogni profilo diventerà una stampante nella nuova configurazione.

Completa la migrazione

Clicca “Importa e Continua”. I vecchi profili verranno convertiti nel nuovo formato multi-stampante.

I vecchi file di configurazione non vengono eliminati: la cartella profiles\ viene rinominata in profiles_migrated_AAAAMMGG_hhmmss\. Puoi rimuoverla manualmente da %LOCALAPPDATA%\SagraFacilePrinterService\ dopo aver verificato che tutto funzioni.

Vengono invece rimossi i collegamenti di avvio automatico della versione precedente, così al riavvio del PC parte solo la nuova applicazione. La rimozione ha effetto dal riavvio successivo: è un motivo in più per chiudere la vecchia applicazione adesso.

Percorsi dei File

File/Cartella	Percorso
Configurazione	`%LOCALAPPDATA%\SagraFacilePrinterService\settings.json`
Log	`%LOCALAPPDATA%\SagraFacilePrinterService\logs\`
Profili legacy	`%LOCALAPPDATA%\SagraFacilePrinterService\profiles\`

Pagine Correlate

Configurazione Stampa - Gestisci stampanti, scontrini e comande
Architettura di Stampa - Panoramica del sistema di stampa
Lavori di Stampa - Monitoraggio coda di stampa