Guida Utente — PuntoVerdi Carte Prepagate
Sistema di gestione carte prepagate per catena di punti vendita
Indice
- Introduzione
- Primo Accesso
- Dashboard — Panoramica
- Gestione Clienti
- Gestione Carte
- Operazioni: Ricariche e Pagamenti
- Il Flusso QR
- Portale Clienti
- Punti Vendita
- Gestione Utenti
- Estratti Conto
- Ricariche Batch
- Bonus Promozionale
- Esportazioni
- Guida Rapida
1. Introduzione
Cos'è PuntoVerdi Prepagate?
PuntoVerdi Prepagate è un sistema per la gestione di carte prepagate utilizzabili all'interno di una catena di punti vendita. Ogni carta è associata a un cliente e può essere:
- Ricarica — il cliente versa denaro sulla carta
- Pagamento — il cliente paga gli acquisti usando il saldo della carta
- Bonus — su ogni ricarica viene applicato automaticamente un bonus promozionale del 20%
Chi può usare il sistema
| Ruolo | Cosa può fare |
|---|---|
| Amministratore | Accesso completo: gestione clienti, carte, PV, utenti, dashboard, esportazioni |
| Operatore PV | Ricariche, pagamenti, gestione clienti e carte del proprio PV |
| Cliente | Accesso al portale clienti per visualizzare saldo, movimenti, cambiare PIN e bloccare la carta |
Requisiti tecnici
- Browser web moderno (Chrome, Firefox, Edge, Safari)
- Connessione Internet
- Per il QR cliente: smartphone con fotocamera
2. Primo Accesso
Indirizzo del sistema
Apri il browser e vai all'indirizzo del server (es. http://185.193.67.99:1953)
Credenziali di accesso
Amministratore
| Campo | Valore |
|---|---|
| Username | admin |
| Password | admin123 |
Operatori PV
| Operatore | Password | Punto Vendita |
|---|---|---|
op_milano |
op123 |
PuntoVerdi Milano |
op_roma |
op123 |
PuntoVerdi Roma |
op_napoli |
op123 |
PuntoVerdi Napoli |
op_torino |
op123 |
PuntoVerdi Torino |
op_bari |
op123 |
PuntoVerdi Bari |
Schermata di Login
La pagina di login presenta: - Area Clienti — link in alto per i clienti (verde) - Form di accesso — username e password per operatori/admin - Pulsante Accedi — avvia la procedura di login - Guida applicazione — link in basso per consultare questa guida
Dopo il login, si viene reindirizzati alla Dashboard principale.
3. Dashboard — Panoramica
La Dashboard è la schermata principale che si apre dopo il login. Mostra un riepilogo operativo dell'intero sistema.
KPI (Indicatori Chiave)
Nella parte superiore sono visibili 5 indicatori numerici:
| Indicatore | Cosa mostra |
|---|---|
| Clienti | Numero totale di clienti / Quanti sono attivi |
| Carte | Carte totali emesse / Carte attive |
| Saldo Totale | Somma di tutti i saldi delle carte attive |
| In Scadenza | Carte che scadranno nei prossimi 30 giorni |
| Settimana | Totale ricariche degli ultimi 7 giorni / Conteggio transazioni |
Grafico Andamento Transazioni
Mostra un grafico a linee con l'andamento giornaliero di: - Ricariche (linea verde) - Pagamenti (linea rossa) - Bonus (linea arancione)
Puoi selezionare il periodo: - 7 giorni — dettaglio fine - 30 giorni — visione mensile - 90 giorni — trend trimestrale
Grafico Ripartizione Transazioni (Oggi)
Grafico a ciambella che mostra la suddivisione delle transazioni odierne tra ricariche, bonus e pagamenti.
Grafico Ripartizione Carte
Grafico a ciambella che confronta le carte attive contro quelle inattive/bloccate.
Punto Vendita Top
Mostra il punto vendita con più transazioni nella giornata corrente.
Transazioni Recenti
Tabella con le ultime transazioni registrate nel sistema, ordinata per data decrescente. Ogni riga mostra: - Data e ora - Tipo (ricarica, bonus, pagamento) con badge colorato - Numero carta - Importo (verde per entrate, rosso per uscite) - Saldo dopo l'operazione - Punto vendita
Pulsante Aggiorna
In alto a destra, permette di ricaricare manualmente i dati della dashboard.
4. Gestione Clienti
Elenco Clienti
La pagina Clienti mostra tutti i clienti registrati con una tabella riepilogativa:
| Colonna | Descrizione |
|---|---|
| ID | Numero identificativo |
| Nome | Nome e cognome |
| Indirizzo email | |
| Telefono | Numero di telefono |
| Codice Fiscale | CF |
| Stato | Attivo / Inattivo (badge) |
| Carte | Numero di carte possedute |
| Azioni | Pulsanti modifica/elimina |
Filtri e Ricerca
- Casella di ricerca — cerca clienti per nome, email o telefono
- Filtro stato — mostra tutti, solo attivi o solo inattivi
Creare un Nuovo Cliente
- Clicca "+ Nuovo Cliente"
- Compila i campi:
- Nome (obbligatorio)
- Email (obbligatorio, deve essere univoca)
- Telefono (opzionale)
- Codice Fiscale (opzionale)
- Note (opzionale)
- Clicca "Salva"
Modificare un Cliente
Clicca sul pulsante modifica (icona matita) nella riga del cliente. Si apre un modale con i dati precompilati. Modifica e salva.
Eliminare un Cliente
Clicca sul pulsante elimina (icona cestino). Attenzione: l'eliminazione è permanente e rimuove anche tutte le carte associate.
5. Gestione Carte
Elenco Carte
La pagina Carte mostra tutte le carte emesse. Ogni carta ha:
| Colonna | Descrizione |
|---|---|
| N. Carta | Numero completo (formato PC + 16 cifre) |
| Cliente | Nome del proprietario |
| Punto Vendita | PV di emissione |
| Saldo | Disponibilità economica |
| Stato | Attiva / Bloccata / Inattiva / Scaduta |
| PIN | ✅ Impostato / ❌ Non impostato |
| Scadenza | Data di scadenza |
| Azioni | Blocca/Sblocca, modifica |
Filtri Avanzati
Puoi filtrare le carte per: - Stato — Attive, Bloccate, Inattive, Scadute - Punto Vendita — seleziona un PV specifico - Cliente — seleziona un cliente specifico - Ricerca testo — cerca per numero carta o nome cliente
Creare una Nuova Carta
- Clicca "+ Nuova Carta"
- Seleziona il Cliente dal menu a tendina
- Seleziona il Punto Vendita di emissione
- Il numero carta viene generato automaticamente
- Imposta eventuale PIN iniziale (opzionale)
- Inserisci note (opzionale)
- Clicca "Crea"
Il sistema assegna automaticamente: - Data di attivazione = oggi - Data di scadenza = oggi + 365 giorni - Stato = Attiva
Bloccare una Carta
- Trova la carta nell'elenco
- Clicca sul pulsante "Blocca" (rosso) nella riga corrispondente
- Inserisci opzionalmente un motivo del blocco
- Clicca "Conferma"
La carta bloccata: - Non può essere utilizzata per pagamenti - Non può essere ricaricata - Può essere sbloccata solo da un amministratore o operatore
Sbloccare una Carta
- Filtra per stato "Bloccate"
- Clicca sul pulsante "Sblocca" (verde)
Impostare/Cambiare il PIN
- Apri i dettagli della carta
- Nella sezione PIN:
- Se non è mai stato impostato: "Imposta PIN"
- Se già presente: "Cambia PIN"
Il PIN è gestito dal cliente tramite il portale clienti, ma l'operatore può impostarlo al momento dell'emissione.
6. Operazioni: Ricariche e Pagamenti
Eseguire una Ricarica
- Vai alla pagina "Operazioni"
- Nella sezione "Ricarica Carta":
- Seleziona la Carta dal menu a tendina
- Inserisci l'Importo in euro
- Seleziona il Punto Vendita
- Inserisci l'Operatore
- Inserisci un Riferimento (es. numero scontrino)
- Inserisci una Nota (opzionale)
- Verifica il Bonus promozionale visualizzato (20%)
- Clicca "Effettua Ricarica"
Risultato: la carta viene accreditata dell'importo + bonus del 20%.
Esempi: | Ricarica | Bonus 20% | Totale accreditato | |----------|-----------|-------------------| | € 10,00 | € 2,00 | € 12,00 | | € 25,00 | € 5,00 | € 30,00 | | € 50,00 | € 10,00 | € 60,00 | | € 100,00 | € 20,00 | € 120,00 | | € 500,00 | € 100,00 (cap) | € 600,00 |
Eseguire un Pagamento
- Nella pagina "Operazioni", sezione "Pagamento":
- Seleziona la Carta
- Inserisci l'Importo da addebitare
- Seleziona il Punto Vendita
- Inserisci l'Operatore
- Inserisci un Riferimento (es. scontrino)
- Inserisci una Nota (opzionale)
- Il sistema controlla che il PIN della carta sia corretto (se richiesto)
- Clicca "Effettua Pagamento"
Attenzione: Il saldo della carta deve essere sufficiente a coprire l'importo del pagamento.
Operazione con QR
Vedi sezione dedicata: Il Flusso QR
7. Il Flusso QR
Il flusso QR permette al cliente di autorizzare ricariche e pagamenti direttamente dal proprio smartphone, senza che l'operatore PV debba conoscere il PIN.
Come funziona
┌─────────┐ ┌─────────┐
│ OPERATORE │ │ CLIENTE │
│ PV │ │ (Cell) │
└─────┬─────┘ └────┬────┘
│ │
│ 1. Apre schermata QR │
│ (carta sul banco) │
│ │
│ 2. Inserisce importo │
│ Clicca "Paga/Ricarica" │
│ │
▼ │
┌──────────┐ │
│ init-pay │ ─── WebSocket ───────→ │ Mostra modale
│ o │ │ con importo
│init-recharge │
└──────────┘ │
│
3. Cliente │
- Vede importo
- Se pagamento: inserisce PIN
- Clicca "Conferma"
│
4. POST /qr/confirm
o /qr/confirm-recharge
│
▼
┌──────────┐
│ Saldo │
│aggiornato│
└──────────┘
Passo 1: Preparazione
Il cliente apre la pagina QR della propria carta. Può farlo in due modi: - Scansionando il QR code stampato sulla carta o sulla ricevuta - Accedendo al Portale Clienti e andando sulla dashboard
La schermata mostra: - Nome del cliente e numero carta - Saldo disponibile in tempo reale - Badge di connessione WebSocket (verde = connesso) - Messaggio: "In attesa di richieste..."
Passo 2: L'operatore avvia la richiesta
Dal terminale del PV, l'operatore: 1. Seleziona la carta (tramite QR scan o ricerca manuale) 2. Sceglie "Paga" o "Ricarica" 3. Inserisce l'importo 4. Clicca "Invia Richiesta"
Passo 3: Il cliente autorizza
Sullo smartphone del cliente appare automaticamente un modale:
Se è un Pagamento: - Titolo: "Pagamento" - Importo evidenziato - Campo per inserire il PIN della carta - Pulsanti: "Rifiuta" / "Paga"
Se è una Ricarica: - Titolo: "Ricarica" - Importo evidenziato - Nessun PIN richiesto - Pulsanti: "Rifiuta" / "Ricarica"
Il cliente: 1. Verifica l'importo 2. Se pagamento: digita il PIN (4-8 cifre) 3. Clicca "Conferma" (o "Rifiuta" per annullare)
Passo 4: Conferma
Dopo la conferma: - Il saldo viene aggiornato istantaneamente - Il cliente vede un messaggio di conferma per 4 secondi - La schermata torna in attesa di nuove richieste - L'operatore vede l'operazione completata
Tecnologia usata
La comunicazione in tempo reale avviene tramite WebSocket: - Connessione diretta tra smartphone e server - Notifica immediata all'arrivo di una richiesta - Se la connessione cade, il telefono passa automaticamente al polling (controllo ogni 2 secondi) e si riconnette dopo 5 secondi
Notifiche Push
Il cliente può attivare le notifiche push cliccando sul pulsante "Attiva notifiche" nella schermata QR: - Richiede l'autorizzazione del browser - Il sistema può inviare notifiche anche a schermo spento - Al click sulla notifica, si apre il portale clienti
8. Portale Clienti
Il portale clienti è accessibile da:
- Link "Accedi all'Area Clienti" nella pagina di login
- Indirizzo diretto: /ui/customer/login
Login Cliente
Il cliente può accedere in due modi:
Modalità 1 — ID Carta (rapido): 1. Inserisce l'ID carta (numero breve, 1-2 cifre, quello del QR code) 2. Il sistema recupera automaticamente il numero completo 3. Inserisce il PIN
Modalità 2 — Numero Carta completo: 1. Inserisce il numero carta completo (formato PC...) 2. Inserisce il PIN
Dashboard Cliente
Dopo il login, il cliente vede:
- Saldo disponibile in grande
- Numero carta e nome cliente
- Stato carta (Attiva/Bloccata) con badge
- Stato PIN (impostato/non impostato)
- Pulsanti:
- Movimenti — storico transazioni
- PIN — cambia PIN
- Blocca — blocca la carta (solo se attiva)
- Ultimi movimenti — tabella con data, tipo, importo
- Link "Vedi tutti" per lo storico completo
Storico Transazioni
Elenco completo dei movimenti della carta con: - Data - Tipo (ricarica, bonus, pagamento) - Importo - Saldo dopo l'operazione - Punto vendita
Cambio PIN
Il cliente può: 1. Impostare il PIN se non è mai stato impostato 2. Cambiare il PIN se già presente (richiede vecchio PIN)
Regole: - Il PIN deve essere di 4-8 cifre - Il PIN è memorizzato in modo sicuro (bcrypt hash) - Il PIN non viene mai mostrato in chiaro
Blocco Carta (Self-Service)
Il cliente può bloccare autonomamente la propria carta: 1. Clicca "Blocca" nella dashboard 2. Conferma la scelta 3. La carta passa a stato "bloccata" 4. Non può più essere utilizzata 5. Per sbloccarla, deve recarsi al punto vendita
Logout
Il cliente può disconnettersi cliccando su "Esci" nella barra superiore.
9. Punti Vendita
Elenco Punti Vendita
La pagina "Punti Vendita" mostra tutti i PV della catena:
| Colonna | Descrizione |
|---|---|
| Codice | Codice breve del PV |
| Nome | Nome del punto vendita |
| Indirizzo | Indirizzo completo |
| Città | Località |
| Telefono | Numero di contatto |
| Stato | Attivo / Inattivo |
| Azioni | Modifica |
Filtri
- Ricerca per nome, codice o città
- Filtro stato (attivi/inattivi)
Creare un Nuovo PV
- Clicca "+ Nuovo Punto Vendita"
- Compila:
- Nome (obbligatorio)
- Codice (obbligatorio, univoco)
- Indirizzo, Città, Telefono (opzionali)
- Clicca "Salva"
Disattivare un PV
Clicca sul pulsante toggle stato. Un PV inattivo non può emettere nuove carte.
10. Gestione Utenti
Elenco Utenti
La pagina "Utenti" mostra tutti gli operatori e amministratori del sistema:
| Colonna | Descrizione |
|---|---|
| Username | Nome utente per il login |
| Indirizzo email | |
| Ruolo | Admin / Operatore |
| Stato | Attivo / Inattivo |
| Punto Vendita | PV associato (solo operatori) |
| Ultimo Accesso | Data ultimo login |
| Azioni | Modifica, reset password |
Filtri
- Ricerca per username o email
- Filtro ruolo (amministratori / operatori)
- Filtro stato (attivi / inattivi)
Creare un Nuovo Utente
- Clicca "+ Nuovo Utente"
- Compila:
- Username (obbligatorio, univoco)
- Email (obbligatorio, univoco)
- Password (obbligatorio)
- Ruolo (Admin / Operatore)
- Punto Vendita (solo se operatore)
- Clicca "Salva"
Operatori e PV
Ogni operatore può essere associato a un Punto Vendita specifico. Questo permette di tracciare quali operazioni sono state eseguite da chi e in quale PV.
11. Estratti Conto
Generare un Estratto Conto
- Vai alla pagina "Estratti Conto"
- Seleziona la Carta
- Scegli il periodo:
- Dal — data inizio
- Al — data fine (se vuoto, fino a oggi)
- Clicca "Visualizza Estratto"
Risultato
L'estratto conto mostra: - Intestazione: dati del cliente e della carta - Riepilogo: saldo iniziale, totale accrediti, totale addebiti, saldo finale - Tabella movimenti: data, tipo, importo, saldo progressivo, descrizione
Download
Puoi scaricare l'estratto conto in due formati: - PDF — documento formattato, ideale per la stampa - CSV — file dati, ideale per Excel o altri programmi
12. Ricariche Batch
La funzione Ricariche Batch permette di caricare più ricariche contemporaneamente.
Da JSON
Invia una lista di ricariche in formato JSON:
[
{"card_number": "PC399082196643998", "amount": 50.0, "store": "PuntoVerdi Milano", "operator": "admin"},
{"card_number": "PC399082196643999", "amount": 25.0, "store": "PuntoVerdi Roma", "operator": "admin"}
]
Da CSV
Carica un file CSV con colonne:
card_number,amount,store,operator,reference
PC399082196643998,50.00,PuntoVerdi Milano,admin,SCONTRINO123
PC399082196643999,25.00,PuntoVerdi Roma,admin,SCONTRINO124
Risultato Batch
Il sistema processa ogni riga e restituisce: - Successi: numero di ricariche completate - Errori: elenco delle righe con errore e motivo
13. Bonus Promozionale
Come funziona
Su ogni ricarica viene applicato automaticamente un bonus del 20%.
Esempio: Se il cliente ricarica € 50,00: - Accredito: € 50,00 - Bonus 20%: € 10,00 - Totale: € 60,00
Cap Massimo
Il bonus ha un cap massimo di € 100,00 per singola ricarica. - Ricarica € 500,00 → Bonus € 100,00 (cap) → Totale € 600,00 - Ricarica € 600,00 → Bonus € 100,00 (cap) → Totale € 700,00
Registrazione in Contabilità
Il bonus viene registrato come una transazione separata di tipo "bonus", chiaramente distinguibile dalla ricarica base.
14. Esportazioni
Export Transazioni
Scarica tutte le transazioni in formato CSV per l'elaborazione esterna.
Export Estratto Conto
Oltre alla visualizzazione a schermo, ogni estratto conto può essere scaricato come: - PDF — con intestazione, riepilogo, tabella movimenti - CSV — dati puri per analisi
15. Guida Rapida
Per l'Operatore PV — operazioni giornaliere
1. Accedi con le tue credenziali
2. Crea un nuovo cliente (solo prima volta)
3. Crea la carta per il cliente (solo prima volta)
4. Per ricaricare: Operazioni → Ricarica → seleziona carta → importo → conferma
5. Per pagamento: Operazioni → Pagamento → seleziona carta → importo → conferma
Oppure usa il flusso QR per far autorizzare il cliente dal telefono
Per l'Amministratore — attività periodiche
- Dashboard: monitoraggio KPI giornaliero
- Estratti conto: fine mese per ogni carta
- Batch: ricariche massive all'inizio del mese
- Utenti: gestione accessi operatori
- Punti Vendita: attivazione/disattivazione PV
Per il Cliente — primo utilizzo
1. Vai su /ui/customer/login
2. Inserisci ID carta (numero breve dal QR) e PIN
3. Visualizza saldo e movimenti
4. (Opzionale) Cambia il PIN
5. Per pagare: mostra il QR all'operatore al momento del pagamento
Credenziali di Test
| Ruolo | Username | Password |
|---|---|---|
| Amministratore | admin |
admin123 |
| Operatore Milano | op_milano |
op123 |
| Operatore Roma | op_roma |
op123 |
| Cliente Demo 1 | Carta ID: 1, PIN: 5678 |
— |
| Cliente Demo 2 | Carta ID: 2, PIN: 1234 |
— |
Codici Colore
Badge Stato
| Stato | Colore |
|---|---|
| Attivo | Verde scuro su fondo verde chiaro |
| Bloccato | Rosso su fondo rosa |
| Inattivo | Grigio |
| Scaduto | Arancione |
Tag Transazione
| Tipo | Colore |
|---|---|
| Ricarica | Verde |
| Bonus | Arancione |
| Pagamento | Rosso |
| Rimborso | Blu |
Documentazione generata il 28/06/2026 — PuntoVerdi Carte Prepagate v3.0.0