PotaPay β€” Manuale Operativo

Guida completa all'utilizzo dell'app cassa per sagre, feste e pro loco su Windows e Android.

Versione 2.0.0

1. Introduzione

PotaPay Γ¨ un programma di cassa pensato per sagre paesane, feste e attivitΓ  delle pro loco. Permette di gestire il listino articoli, prendere comande, stampare scontrini e tenere traccia degli incassi senza obbligo di connessione internet.

Piattaforme supportate

PiattaformaRequisitiCaso d'uso tipico
Windows Windows 10/11 64 bit Cassa principale, gestione amministrativa, stampa A4/A5/A6 o rotolo termico via stampante di sistema
Android Android 6.0+ (API 23+) Cassa portatile sotto al gazebo, stampa scontrini su stampante termica Bluetooth ESC/POS

Filosofia di base

Schermata iniziale POS
Schermata iniziale del POS β€” griglia articoli e pannello comanda

2. Installazione e primo avvio

Windows Win

  1. Scarica PotaPay-Setup-X.Y.Z.exe da www.potapay.it.
  2. Doppio click sull'installer e segui la procedura guidata.
  3. Al primo avvio compare la schermata di login con il cassiere predefinito Admin Sistema (PIN 0000).
  4. Cambia subito il PIN dell'admin: Settings β†’ Cassieri β†’ modifica.

Android And

  1. Apri il link al download dell'APK dal browser del cellulare (lo trovi su www.potapay.it).
  2. Conferma "Installa app sconosciute" se Android lo richiede (la prima volta).
  3. Avvia l'app: stesso login Admin/0000 come su Windows.
Aggiornamenti successivi Reinstallare l'APK sopra una versione esistente non cancella i dati: catalogo, comande, impostazioni restano intatti. Lo stesso vale per il Setup.exe su Windows.
Schermata di login
Login con PIN cassiere

3. Licenza e modalitΓ  demo

PotaPay parte in modalitΓ  Demo finchΓ© non viene attivata una licenza. La demo permette di provare l'app con alcuni limiti:

Attivare la licenza

  1. Vai su Settings β†’ Licenza.
  2. Copia il Fingerprint PC mostrato (es. 91F6-4CE4-0DFA).
  3. Invialo al rivenditore/amministratore: emetterΓ  un codice licenza dedicato a quel fingerprint + numero postazione.
  4. Incolla il codice nel campo Codice licenza e premi Attiva licenza.
Firma non valida? Il codice licenza Γ¨ collegato al fingerprint specifico del dispositivo e al numero di postazione configurato. Cambiare PC o numero postazione invalida la licenza.

FunzionalitΓ  pro (richiedono licenza attiva)

Pannello licenza in Impostazioni
Pannello Licenza con fingerprint del dispositivo e codice da attivare

4. Login cassieri e ruoli

Ogni operatore della cassa Γ¨ identificato da un PIN numerico di 4 cifre. Esistono due ruoli:

RuoloPermessi
Amministratore Tutto: anagrafica reparti/articoli/cassieri, magazzino, storico, statistiche, impostazioni, reset.
Cassiere Solo POS + accesso in sola lettura a Dashboard incassi, Storico comande e Magazzino. Niente impostazioni, niente modifiche all'anagrafica.

Per creare nuovi cassieri vai su Settings β†’ Cassieri β†’ Nuovo cassiere. Ricorda di assegnare il ruolo giusto in fase di creazione.

Lista cassieri
Anagrafica cassieri con PIN e ruolo

5. OperativitΓ  cassa (POS)

La schermata POS Γ¨ il cuore dell'app. Si compone di:

Aprire una nuova comanda

  1. Premi + Nuova in basso a destra (o tap sul tasto principale del pannello).
  2. Se attivo l'opzione in Settings, comparirΓ  un dialog per inserire il nome cliente (opzionale) e il flag Da asporto.
  3. Conferma per aprire la comanda.

Aggiungere articoli

Note e allergie

Annullare una comanda

Tasto Annulla ordine nel pannello: chiede conferma. La comanda viene marcata come "annullata" nello storico.

Back button Android Premendo il tasto Indietro fisico con righe non confermate nella comanda, l'app chiede conferma prima di uscire β€” niente perdita accidentale.
POS con comanda aperta
POS desktop con comanda aperta β€” griglia articoli a sinistra, pannello comanda a destra

6. Pagamento e chiusura comanda

Quando la comanda Γ¨ completa, premi Conferma. Si apre il dialog di pagamento.

ModalitΓ  di pagamento

ModalitΓ Quando usarla
ContantiPagamento in contanti. Inserisci la cifra ricevuta β€” l'app calcola il resto.
CartaPagamento elettronico con POS esterno (Sumup, Nexi, ecc.).
MistoParte in carta + parte in contanti. Inserisci l'importo carta, il resto va in contanti.
OmaggioTotale a 0 €: non registra incasso ma traccia comunque l'erogazione (utile per statistiche).

Conferma il pagamento per chiudere la comanda. Vengono automaticamente:

Dialog pagamento con calcolo resto
Dialog pagamento contanti con calcolo automatico del resto

7. Stampa scontrini

PotaPay supporta tre tipi di scontrino, attivabili indipendentemente da Settings β†’ Stampa:

TipoCosa contieneA chi serve
Scontrino cliente Lista completa con prezzi, totale, modalitΓ  pagamento, eventuale resto. Cliente che paga al banco.
Per reparto Una "fetta" separata per ogni destinazione di stampa (es. Cucina, Bar). QuantitΓ  grandi, niente prezzi. Personale di servizio per preparare gli ordini.
Cameriere Riepilogo unico raggruppato per reparto, senza prezzi. Cameriere/runner che serve ai tavoli.

Formati di stampa Win

Stampante predefinita

Da Settings β†’ Stampa puoi scegliere una stampante predefinita installata sul sistema. Se attivi "stampa diretta", il PDF viene inviato senza mostrare il dialog di Windows, perfetto per uso a tutto schermo.

Parametri di stampa
Configurazione tipi di scontrino, formato carta e stampante predefinita

8. Stampante termica Bluetooth And

Su Android le stampanti del sistema operativo non sono utilizzabili dalla cassa. Al loro posto si usa una stampante termica Bluetooth ESC/POS, formato 80mm o 58mm.

Modelli compatibili

Qualsiasi stampante termica Bluetooth classic con supporto ESC/POS standard. Esempi testati: Munbyn, Xprinter, Goojprt. Range di prezzo tipico 40–100 €.

Setup in 4 passi

  1. Accendi la stampante e abilita la modalitΓ  Bluetooth.
  2. Da Android β†’ Impostazioni β†’ Bluetooth β†’ cerca dispositivi β†’ Pair (PIN tipico 0000 o 1234).
  3. Apri PotaPay β†’ Settings β†’ Stampante termica Bluetooth β†’ Rilegge β†’ seleziona la stampante dalla lista.
  4. Premi Test: deve uscire uno scontrino di prova con caratteri di vari stili.

Larghezza rotolo

Imposta 80mm o 58mm in base al rotolo che usi. Le 58mm sono piΓΉ compatte ma con meno spazio per i nomi articolo.

Sequenza di stampa A pagamento confermato la cassa apre una sola connessione Bluetooth ed emette in sequenza: scontrino cliente, copie per reparto (Cucina, Bar, ecc.), copia cameriere. Tra ogni copia c'Γ¨ un taglio automatico per separarle facilmente.

9. Importa comanda da QR

I clienti possono pre-ordinare tramite un sito o app esterno (es. portale potapay.it) e presentarsi al banco con un QR code. La cassa lo legge e importa direttamente le righe nella comanda corrente.

Procedura

  1. Apri una nuova comanda.
  2. Premi Importa da QR.
  3. Scannerizza il QR (su Windows tramite scanner USB; su Android con la fotocamera del telefono).
  4. In alternativa puoi incollare il contenuto del QR manualmente.
  5. La cassa risolve gli articoli (per codice, poi per nome se non c'Γ¨ match) e ne mostra l'anteprima.
  6. Conferma per aggiungere tutte le righe alla comanda.

Per articoli non trovati nel catalogo locale viene creato automaticamente un "articolo ospite" in un reparto dedicato, così la comanda risulta sempre completa.

Dialog importa da QR
Importazione comanda da QR β€” preview righe e stato match catalogo

10. Anagrafiche

L'area Amministrazione (icona Amministrazione nel POS, solo per ruolo admin) contiene tutte le anagrafiche dell'app.

Reparti

Sono le categorie principali del menu (es. Primi, Secondi, Bar, Bibite). Ogni reparto ha:

Reparti di stampa

Le destinazioni fisiche di stampa, separate dai reparti dell'anagrafica. Permettono di accorpare piΓΉ reparti in un'unica stampa.

Esempio: Reparti Primi, Secondi, Contorni tutti puntati alla destinazione "Cucina". Al confirm di una comanda esce una sola stampa "Cucina" con tutti gli articoli di quei tre reparti aggregati, invece di tre stampe separate.

Articoli

Singoli prodotti vendibili. Per ogni articolo:

Allergeni

I 14 allergeni dello standard EU 1169/2011 sono pre-caricati. Puoi aggiungerne di custom (es. "Pomodoro") per intolleranze specifiche. Sugli scontrini stampati gli allergeni associati a un articolo vengono evidenziati in rosso se il cliente ha dichiarato allergie.

Anagrafica articoli
Lista articoli con codice, nome, prezzo e reparto di appartenenza
Editor articolo
Editor dettaglio articolo: prezzo, immagine, allergeni e composizione magazzino

11. Magazzino

La gestione magazzino Γ¨ opzionale ma utile per non finire le scorte durante una serata di sagra.

Prodotti base

Sono le materie prime/ingredienti consumati dagli articoli venduti. Esempio: Pane, Salamelle, Birra in fusto. Ogni prodotto ha:

Composizione articoli

Per ogni articolo del menu definisci quanti prodotti base consuma. Esempio: Panino con salamella consuma 1 Pane + 1 Salamella. A ogni vendita confermata, la giacenza di entrambi diminuisce automaticamente di 1.

Carico rapido

Per aggiungere giacenze (rifornimento, inventario iniziale): Magazzino β†’ Carico rapido. Inserisci quantitΓ  per ogni prodotto.

Rettifica giacenza

Per impostare una giacenza assoluta (post-inventario): apri il prodotto β†’ modifica giacenza manualmente. Viene tracciato un movimento di rettifica.

Avvisi sottoscorta

Durante l'apertura di una comanda, se uno degli articoli scelti porta un prodotto base sotto la soglia minima, compare un badge giallo accanto al nome. Niente popup invadenti, solo un'indicazione visiva.

Movimenti

Lista cronologica di tutte le variazioni di giacenza (carico, scarico da vendita, rettifica, svuotamento). Filtrabile per prodotto e periodo.

Lista giacenze magazzino
Magazzino β€” tab giacenze con quantitΓ  correnti e soglie minime
Movimenti magazzino
Magazzino β€” tab movimenti con storico cronologico di carichi, scarichi e rettifiche

12. Storico comande

Tutte le comande chiuse o annullate sono accessibili da Amministrazione β†’ Storico.

Filtri

Dettaglio comanda

Tap su una riga apre il dettaglio: righe articoli, allergie, totale, modalitΓ  di pagamento, eventuale resto, timestamp di apertura/chiusura.

Ristampa

Bottone Ristampa: rigenera lo scontrino cliente (utile se la stampa originale si Γ¨ rovinata o l'utente l'ha persa).

Storico comande
Storico comande con filtri per data e stato

13. Statistiche e dashboard

Dashboard incassi

Schermata a tile con i numeri principali del periodo:

Filtri rapidi: Oggi / Ultimi 7 giorni / Ultimi 30 giorni / range custom.

Statistiche dettagliate

Tabella di vendite riga per riga (una riga per ogni quantitΓ  venduta) con filtri:

Esporta Excel

Premi Esporta Excel per scaricare un file .xlsx con tutte le righe filtrate + totali in coda. Utile per rendicontazione e contabilitΓ  post-evento.

Dashboard incassi
Dashboard incassi con tile per contanti, carta, omaggi e scontrino medio
Statistiche
Statistiche dettagliate con filtri reparto/articolo/periodo ed esportazione Excel

14. Import / Export configurazione PRO

Disponibile solo con licenza attiva. Permette di sincronizzare il catalogo tra piΓΉ postazioni o di importarlo da un portale esterno.

Esporta configurazione

Settings β†’ Database β†’ Esporta configurazione β†’ genera un file .json con reparti, articoli e cassieri. Puoi mandarlo per email a un'altra cassa.

Importa configurazione

Settings β†’ Database β†’ Importa configurazione β†’ seleziona il file .json. L'app riconosce automaticamente due formati:

L'import Γ¨ idempotente: puoi rieseguirlo all'infinito senza creare duplicati. I match avvengono per:

Solo Android: l'import file Γ¨ disabilitato su Android (dispositivo di vendita, non di amministrazione). Per portare anagrafica nuova su un telefono usa la modalitΓ  Client o Online.

15. ModalitΓ  di rete (multi-cassa)

Quando hai piΓΉ postazioni di cassa devi decidere come fanno a vedere lo stesso catalogo e a non duplicare gli scontrini.

ModalitΓ  Standalone (default)

La cassa lavora da sola. Nessuna comunicazione con altre casse. Catalogo e comande sono completamente locali. Buona per una sagra con una sola cassa.

ModalitΓ  Server Win

Questa cassa fa da hub LAN per le altre. Espone le anagrafiche e riceve le comande dei client. Solo su Windows (richiede di mettere in ascolto una porta TCP, non possibile su Android).

ModalitΓ  Client

La cassa si connette a un'altra cassa configurata come Server (vedi sopra). Catalogo letto dal server, comande chiuse pushate al server.

ModalitΓ  Online PRO

Vedi sezione dedicata sotto.

Selettore modalitΓ  di rete
Selettore modalitΓ  di rete β€” Standalone / Server / Client / Online

16. ModalitΓ  Online e API PotaPay PRO

La modalitΓ  Online connette la cassa al backend cloud potapay.it. Disponibile solo con licenza attiva.

Cosa fa

Configurazione

  1. Settings β†’ Rete β†’ seleziona Online (visibile solo con licenza)
  2. Compare il pannello blu "ModalitΓ  Online β€” sincronizzazione anagrafica cloud":

URL base (modalitΓ  sviluppatore)

Il base URL Γ¨ hardcoded a https://api.potapay.it per la produzione. Per ambienti di test/dev puΓ² essere cambiato:

  1. Settings β†’ scorri fino a Sincronizzazione API PotaPay
  2. Tocca 7 volte il titolo della sezione (countdown nei tap finali)
  3. Compare il campo "URL base (modalitΓ  sviluppatore)"
  4. Esempi: https://api-test.potapay.it (test cloud) o http://10.0.2.2:5127 (dev locale da emulatore Android)
HTTP locale su Android Il file network_security_config.xml consente cleartext HTTP solo verso loopback (10.0.2.2, 127.0.0.1) e LAN privata (192.168.x.x). HTTPS verso api.potapay.it funziona sempre.

Stato coda transazioni

Sezione Sincronizzazione API PotaPay mostra in tempo reale quante transazioni sono in attesa di invio:

Pannello modalitΓ  Online
ModalitΓ  Online β€” toggle auto-sync, dropdown intervallo periodico, bottone sincronizza ora

17. Impostazioni generali

SezioneCosa configura
FestivalNome della sagra mostrato in cima all'app e in testa allo scontrino.
TemaSchema colori dell'interfaccia (arancione, blu, verde, viola, marrone). Tema chiaro o scuro.
POSNumero postazione (1, 2, 3...), chiedi nome cliente all'apertura comanda, raggruppa righe per reparto, mostra immagini/allergeni nella griglia.
StampaTipi di scontrino attivi (cliente / reparto / cameriere), formato carta, stampante predefinita, stampa diretta.
LicenzaStato attivazione, fingerprint dispositivo, attiva/disattiva.
ReteModalitΓ  di rete (vedi Β§15–16).
DatabaseImport/export configurazione (vedi Β§14).
InformazioniVersione app installata, path del database, copia versione negli appunti con long-press.
Stampante BT AndSetup stampante termica Bluetooth (vedi Β§8).
Aggiornamenti WinCheck automatico GitHub Releases, controllo manuale (vedi Β§18).

18. Aggiornamenti dell'app Win

Su Windows l'app puΓ² controllare automaticamente la disponibilitΓ  di nuove versioni.

Controllo automatico

Settings β†’ Aggiornamenti β†’ attiva Controlla aggiornamenti all'avvio. Al massimo una chiamata GitHub ogni 6 ore (rate limit cache).

Controllo manuale

Bottone Controlla ora nella stessa sezione. Mostra immediatamente l'esito:

Download e installazione

  1. Il dialog mostra la versione corrente, quella disponibile, le note di rilascio
  2. Premi Scarica: barra progresso fino a completamento
  3. Premi Installa ora β†’ PotaPay si chiude, parte l'installer Inno Setup
  4. Procedi con la procedura guidata β†’ il database SQLite non viene toccato
Su Android l'auto-update via GitHub Releases non Γ¨ supportato (limiti di policy). Aggiornamenti tramite sideload manuale del nuovo APK.

19. Reset archivi e backup

Settings β†’ Danger Zone. Tre livelli di reset, ognuno con conferma esplicita (richiede di digitare una frase di conferma).

LivelloCancellaMantiene
1 β€” Reset comande Comande e righe (storico transazioni). Movimenti magazzino correlati. Coda outbox sync. Cassieri, articoli, reparti, allergeni, licenza, impostazioni.
2 β€” Reset catalogo Tutto del livello 1 + articoli e reparti. Cassieri, licenza, impostazioni.
3 β€” Reset completo Tutto. Anche cassieri, allergeni custom, prodotti base. Ricrea automaticamente l'admin di default (Admin/Sistema, PIN 0000).
Operazione irreversibile I reset NON sono annullabili. Esporta sempre la configurazione (Settings β†’ Database β†’ Esporta) prima di un reset di livello 2 o 3.

Backup del database

Il file SQLite si trova in:

Copialo periodicamente per avere un backup completo.

21. Promozioni bundle

Le promozioni bundle permettono di applicare automaticamente uno sconto o un omaggio quando la comanda contiene una combinazione specifica di articoli. La valutazione avviene in tempo reale durante la costruzione dell'ordine, senza alcuna azione da parte del cassiere.

Dove si configurano Le promozioni possono essere create e gestite direttamente dalla cassa (Amministrazione β†’ Promozioni) oppure dal portale web app.potapay.it β†’ Promozioni. In modalitΓ  online, le promozioni create sul portale vengono scaricate automaticamente dalla cassa durante la sincronizzazione dell'anagrafica.

Come funziona

Ogni bundle Γ¨ composto da due elementi:

Tipi di benefit

TipoEffettoEsempio
GratisL'articolo benefit viene aggiunto alla comanda a prezzo zero1 bibita omaggio se acquisti 2 pizze
PercentualeSconto % sul prezzo dell'articolo benefit20% di sconto sulle patatine se acquisti un burger
FissoSconto in € sull'articolo benefit€ 1,00 di sconto sull'acqua se acquisti un primo

Preview in tempo reale

Mentre il cassiere aggiunge articoli alla comanda, il pannello ordine mostra automaticamente i bundle applicabili con una nota verde. Non Γ¨ necessario fare nulla: al momento del pagamento lo sconto Γ¨ giΓ  calcolato nel totale.

Bundle ripetibili

Se la promozione Γ¨ configurata come ripetibile, il benefit si moltiplica in proporzione agli articoli trigger presenti. Esempio: trigger 1 pizza + 1 bibita, comanda con 3 pizze + 3 bibite β†’ il benefit viene applicato 3 volte.

Parametri configurabili

ParametroDescrizione
Data inizio / finePeriodo di validitΓ  della promozione
PrioritΓ Ordine di valutazione quando piΓΉ promozioni sono attive contemporaneamente
CumulabileSe attivo, il bundle puΓ² combinarsi con altre promozioni sulla stessa comanda
AttivaToggle per abilitare/disabilitare la promozione senza eliminarla

22. Buoni sconto

I buoni sconto sono voucher con codice univoco che vengono generati automaticamente dalla cassa al raggiungimento di una soglia di spesa e riscattati nelle comande successive. Il sistema Γ¨ sincronizzato con il portale per supportare ambienti multi-cassa.

Generazione automatica

Quando una comanda viene pagata e il totale supera la soglia configurata, la cassa:

  1. Genera un codice univoco nel formato PP-XXXXXX (prefisso configurabile)
  2. Stampa uno scontrino separato con il codice buono e la data di scadenza
  3. Sincronizza il buono con il portale entro 5 minuti
Configurazione dal portale La regola di generazione buoni si crea in app.potapay.it β†’ Promozioni β†’ tipo Buono sconto. Si imposta soglia, valore del buono, validitΓ  in giorni e prefisso del codice.

Riscatto in cassa

Per applicare un buono durante il pagamento:

  1. Apri il dialog di pagamento premendo Incassa
  2. Inserisci il codice del buono nel campo apposito
  3. Premi Verifica β€” la cassa controlla validitΓ , stato e scadenza
  4. Se valido, l'importo del buono viene detratto dal totale da pagare

Validazione del codice

EsitoDescrizione
ValidoIl buono Γ¨ attivo e non scaduto. Lo sconto viene applicato.
Non trovatoIl codice non esiste nΓ© localmente nΓ© sul portale.
ScadutoLa data di scadenza del buono Γ¨ giΓ  passata.
GiΓ  usatoIl buono risulta giΓ  riscattato (stato: usato).
Errore reteIl codice non Γ¨ in locale e non Γ¨ raggiungibile il portale.

Uso parziale

Se il valore del buono supera il totale della comanda, il buono copre l'intero importo senza richiedere un metodo di pagamento aggiuntivo. Se invece il totale supera il valore del buono, il cassiere paga la differenza in contanti o carta. Il valore residuo viene tracciato e il buono rimane attivo fino all'utilizzo completo.

Sincronizzazione multi-cassa

I buoni sono sincronizzati con il portale ogni 5 minuti. Se un buono viene emesso da una cassa e riscattato da un'altra, la seconda cassa verifica la validitΓ  direttamente sul portale prima di accettarlo.

Visualizzazione buoni (schermata admin)

Accedi da Amministrazione β†’ Buoni sconto per vedere la lista di tutti i buoni emessi con codice, data emissione, scadenza, valore residuo e stato.

StatoDescrizione
AttivoBuono valido e riscattabile
UsatoBuono interamente riscattato
ScadutoData di scadenza superata
AnnullatoBuono disabilitato manualmente dal portale

20. Risoluzione problemi

ProblemaCausa probabileCosa fare
"Firma non valida" all'attivazione licenza Il codice Γ¨ stato emesso con un fingerprint o numero postazione diverso dal corrente. Verifica che fingerprint e postazione mostrati corrispondano a quelli usati per generare il codice.
Stampante BT non risponde dopo pair Bluetooth Android non concedeva permessi runtime al primo tentativo, oppure la stampante si Γ¨ messa in standby. Spegni/accendi la stampante. Verifica permessi in Impostazioni β†’ Bluetooth β†’ PotaPay. Premi Test nella sezione stampante BT dell'app.
ModalitΓ  Online: errore HTTP 404 Base URL non corretto. Verifica nella sezione sviluppatore che il base URL sia https://api.potapay.it (senza /api alla fine).
Import JSON dΓ  errore di parse File non riconosciuto: nΓ© SagraMenu nΓ© formato potapay esteso. Verifica il contenuto del file. L'export potapay deve contenere almeno una sezione tra reparti/articoli.
Comande pre-esistenti scomparse dopo update L'APK Γ¨ stato installato firmato con keystore diversa rispetto alla precedente. Da 1.5.0 in poi tutti gli APK usano la stessa keystore stabile. Per ripristinare: copia il file .sqlite dal dispositivo precedente nel percorso del nuovo.
"INSTALL_FAILED_UPDATE_INCOMPATIBLE" su Android L'APK che stai installando Γ¨ firmato con una chiave diversa rispetto a quello giΓ  installato. Fai uninstall dell'app, poi reinstalla (attenzione: i dati locali verranno persi). Verifica che tutti gli APK provengano dalla stessa CI.
FOREIGN KEY constraint failed durante reset Bug noto, fixato in 1.4.0+x: i movimenti magazzino e la coda outbox non venivano puliti prima delle comande. Aggiorna l'app all'ultima versione.
QR import non funziona Il formato del QR non Γ¨ riconosciuto. L'app accetta sia il formato legacy (chiavi corte: items, c, n, p, q) sia il formato potapay.it (chiavi estese: righe, codice, nome, prezzo, qty).

Supporto

Per problemi non elencati qui visita www.potapay.it o manda email a info@potapay.it.

Β© 2026 PotaPay β€” Manuale Operativo App v2.0.0

Per assistenza: info@potapay.it