Manuali Tecnici Hardware

⌘K
  2. Home
  4. Manuali Tecnici Hardware
  6. Casse Automatiche
  8. VNE

VNE

Manuale Utente

Driver di interfacciamento tra un software gestionale e una cassa automatica VNE Automatic Cash.

**IL DRIVER SI ASPETTA I FILE TIPICI DEL PROTOCOLLO CASHMATIC.

Download Area2VNE

1. A cosa serve

Area2VNE fa da ponte tra due sistemi che non parlerebbero tra loro:

  • da un lato il software gestionale ("master"), che scambia file di testo in una cartella
    condivisa secondo lo standard di interfacciamento Cashmatic;
  • dall'altro la cassa automatica VNE Automatic Cash, che si comanda tramite chiamate di rete
    (API web).

Il gestionale continua a scrivere e leggere gli stessi file di sempre: è il driver Area2VNE che,
dietro le quinte, traduce ogni file in comandi verso la cassa VNE e riporta gli esiti di nuovo nei
file. Non è richiesta alcuna modifica al software gestionale.

   Software gestionale  ──file──►  cartella C:\Cashmatic\  ◄──file──  Area2VNE  ──rete──►  Cassa VNE

2. Requisiti

  • Windows 10 o 11, 64 bit.
  • La cassa VNE Automatic Cash raggiungibile in rete locale dal PC su cui gira il driver.
  • L'indirizzo IP della cassa (impostabile dal menu di configurazione della macchina).
  • Permessi di scrittura sulla cartella di scambio file (di norma C:\Cashmatic\).

Non serve installare altro: l'eseguibile contiene già tutto il necessario.

3. Installazione

  1. Eseguire Area2VNE-Setup-x.y.z.exe (richiede i permessi di amministratore).
  2. Confermare il percorso di installazione (predefinito C:\Program Files\Area2VNE\).
  3. Lasciare selezionata la casella "Avvia Area2VNE automaticamente all'accesso a Windows"
    se si vuole che il driver parta da solo a ogni accensione del PC (consigliato).
  4. Al termine l'installer crea automaticamente:
    • la cartella di scambio C:\Cashmatic\;
    • la cartella dei log C:\ProgramData\Area2VNE\logs\;
    • le scorciatoie nel menu Start.

L'installer può essere rieseguito per aggiornare il driver a una versione successiva: la
configurazione esistente viene mantenuta.

4. Primo avvio e configurazione

Al primo avvio è necessario indicare al driver dove si trova la cassa VNE.

  1. Avviare Area2VNE (dal menu Start o dall'icona).
  2. Premere il pulsante Impostazioni....
  3. Compilare almeno i campi della sezione VNE:
Campo Descrizione Valore tipico
URL macchina VNE Indirizzo del servizio web della cassa https://192.168.1.100/selfcashapi/
opName Nome operatore associato alle operazioni cassa1
Timeout (s) Secondi di attesa massima per una risposta 5
Ignora errori SSL Da tenere attivo: le casse usano certificati interni attivo
Cartella scambio file Dove gestionale e driver si scambiano i file C:\Cashmatic\
Polling (ms) Frequenza di interrogazione dello stato pagamento 250
Check connessione (s) Ogni quanti secondi verificare la cassa 10
Tentativi prima di allarme Quante verifiche fallite prima di segnalare la cassa offline 3
tipo_annullamento default Come gestire l'annullamento di un pagamento 2 - Restituisci denaro
Pagamenti rimborsabili Se i pagamenti potranno essere rimborsati attivo
Default credit_card (POS) Se i pagamenti vanno gestiti su POS anziché contanti non attivo
  1. Premere Salva.
  2. Premere Ferma e poi Avvia driver perché le nuove impostazioni abbiano effetto
    (oppure riavviare l'applicazione).

Nell'indirizzo URL sostituire 192.168.1.100 con l'IP reale della cassa. La parte
/selfcashapi/ finale va lasciata invariata.

5. La finestra principale

La finestra mostra, dall'alto verso il basso:

  • Stato connessione — testo colorato che indica se la cassa risponde
    (vedi capitolo 9).
  • Cartella — il percorso della cartella di scambio in uso.
  • Pulsanti:
    • Avvia driver — mette il driver in ascolto della cartella.
    • Ferma — sospende il driver.
    • Apri cartella — apre in Esplora risorse la cartella di scambio.
    • Impostazioni... — apre la finestra di configurazione.
    • Test... — apre gli strumenti di prova (vedi capitolo 8).
    • Pulisci log — svuota il riquadro del log a video.
  • Riquadro del log — registro in tempo reale delle operazioni.

Il driver si avvia da solo all'apertura del programma. Normalmente non serve premere alcun
pulsante: basta lasciare la finestra aperta (anche ridotta a icona).

6. Come funziona

6.1 Pagamento di uno scontrino

  1. Il gestionale crea il file subtotale.txt con l'importo da incassare.
  2. Area2VNE rileva il file e avvia il pagamento sulla cassa VNE.
  3. Mentre il cliente inserisce denaro, il driver aggiorna il file saldato.txt con l'importo
    versato fino a quel momento.
  4. A pagamento concluso il driver crea:
    • pagato.txt con il totale versato;
    • erogato.txt con l'eventuale resto erogato dalla cassa;
    • nonerogato.txt se la cassa non è riuscita a erogare tutto il resto dovuto.
  5. Il file subtotale.txt viene cancellato dal driver, a indicare che la transazione è chiusa.

6.2 Annullamento

Se il gestionale crea il file annulla.txt, il driver annulla la transazione in corso. In base
all'impostazione tipo_annullamento:

  • Restituisci denaro: l'importo già inserito dal cliente viene riconsegnato.
  • Accetta pagamento parziale: l'importo inserito viene trattenuto e registrato.

6.3 Prelievo

Se subtotale.txt contiene un importo preceduto dal segno meno, il driver non incassa ma
ordina alla cassa di erogare quella cifra (prelievo operatore). L'esito finisce in
erogato.txt (e in nonerogato.txt per l'eventuale parte non erogata).

7. Formato dei file

Tutti gli importi sono espressi in centesimi, come numero di 9 cifre con eventuali zeri
iniziali. Esempi: 000000590 = 5,90 € — 000012000 = 120,00 €.

File in ingresso (creati dal gestionale)

File Contenuto Significato
subtotale.txt 000000590 Avvia un incasso di 5,90 €
subtotale.txt -000000500 Avvia un prelievo (erogazione) di 5,00 €
annulla.txt vuoto Annulla la transazione in corso

File in uscita (creati da Area2VNE)

File Contenuto Significato
saldato.txt importo a 9 cifre Importo parziale versato (aggiornato durante l'incasso)
pagato.txt importo a 9 cifre Importo totale versato a transazione conclusa
erogato.txt importo a 9 cifre Importo erogato dalla cassa (resto o prelievo)
nonerogato.txt importo a 9 cifre Importo che la cassa non è riuscita a erogare
connected vuoto Il driver è in esecuzione
disconnected vuoto Il driver è fermo o chiuso

Importante: i file in uscita (saldato, pagato, erogato, nonerogato) non vengono
cancellati dal driver. È compito del software gestionale leggerli e poi rimuoverli, così da
essere pronto per la transazione successiva.

8. Funzione Test

Il pulsante Test... apre una finestra che permette di provare il driver senza usare il
software gestionale. Utile in fase di installazione o per diagnosi.

Pulsante Cosa fa
Test connessione (tipo=20) Interroga subito la cassa e mostra se risponde
Scrivi subtotale.txt (pagamento) Simula una richiesta di incasso dell'importo indicato
Scrivi subtotale.txt (prelievo) Simula una richiesta di erogazione dell'importo indicato
Scrivi annulla.txt Simula la richiesta di annullamento

Inserire l'importo in euro nell'apposito campo e premere il pulsante desiderato. Gli esiti
compaiono sia nella finestra di test sia nel log principale.

9. Stato della connessione

Il testo in alto nella finestra indica se la cassa VNE è raggiungibile:

Colore Testo Significato
Grigio "Verifica connessione VNE…" Controllo in corso (primi secondi dopo l'avvio)
Verde "VNE raggiungibile — ultimo contatto HH:mm:ss" La cassa risponde correttamente
Rosso "VNE non risponde…" La cassa non risponde da più tentativi consecutivi

Un singolo controllo fallito non fa scattare subito l'allarme rosso: serve un numero di
fallimenti consecutivi pari al valore Tentativi prima di allarme (predefinito 3). Questo evita
falsi allarmi per disturbi di rete momentanei.

File connected / disconnected

Nella cartella di scambio è sempre presente uno di questi due file:

  • connected quando il driver è in esecuzione;
  • disconnected quando il driver è fermo o è stato chiuso.

Indicano lo stato del driver, non lo stato istantaneo della rete: a driver avviato resta
connected anche durante un eventuale disturbo di rete temporaneo.

10. File di log

Oltre al riquadro a video (che si azzera alla chiusura del programma), Area2VNE scrive un registro
permanente su disco:

C:\ProgramData\Area2VNE\logs\app-AAAA-MM-GG.log
  • Un file per ogni giornata.
  • I file più vecchi di 30 giorni vengono eliminati automaticamente.
  • In caso di problemi, questo è il primo file da consultare o da inviare all'assistenza.

Il percorso esatto è riportato anche nella prima riga del log a video all'avvio.

11. Avvio automatico

Se durante l'installazione è stata lasciata attiva la relativa casella, Area2VNE si avvia da solo
a ogni accesso a Windows.

Per attivarlo o disattivarlo in seguito:

  1. Premere Win + R, digitare shell:startup e premere Invio.
  2. Si apre la cartella di esecuzione automatica:
    • per attivare l'avvio automatico, copiarvi un collegamento ad Area2VNE.exe;
    • per disattivarlo, eliminare il collegamento Area2VNE presente.

12. Risoluzione dei problemi

Sintomo Possibili cause e soluzioni
Stato sempre rosso "VNE non risponde" Verificare che la cassa sia accesa e in rete; controllare l'IP nell'URL delle Impostazioni; provare un ping al PC della cassa; usare Test → Test connessione per leggere l'errore nel log.
All'avvio compare "cartella non scrivibile" L'utente Windows non ha permessi di scrittura sulla cartella di scambio. Concedere i permessi sulla cartella indicata, oppure indicarne un'altra dalle Impostazioni.
Il pagamento non parte quando il gestionale crea subtotale.txt Controllare che il driver sia avviato (stato non "Driver fermo"); verificare che il contenuto del file sia un numero di 9 cifre; consultare il log.
Resta pagato.txt / erogato.txt dal pagamento precedente È normale: i file in uscita li cancella il gestionale, non il driver. Se il gestionale non li rimuove, verificare la sua configurazione.
Errori SSL nel log Tenere attiva l'opzione "Ignora errori SSL" nelle Impostazioni.
La finestra dà errore aprendo le Impostazioni dopo un aggiornamento Chiudere e riaprire l'applicazione.
Modifica alle Impostazioni senza effetto Dopo il salvataggio premere Ferma e Avvia driver, o riavviare l'applicazione.

Per ogni segnalazione all'assistenza allegare sempre il file di log della giornata
(C:\ProgramData\Area2VNE\logs\).

13. Disinstallazione

Disinstallare Area2VNE da Impostazioni di Windows → App, oppure dalla scorciatoia
"Disinstalla Area2VNE" nel menu Start.

La disinstallazione mantiene:

  • la configurazione (appsettings.json);
  • i file di log;
  • la cartella C:\Cashmatic\ e il suo contenuto.

Vengono rimossi solo l'eseguibile e i file di stato connected / disconnected.

14. Contatti

Per assistenza tecnica rivolgersi a Vulcano Team.

Allegare sempre alla richiesta:

  • una descrizione del problema e l'orario in cui si è verificato;
  • il file di log della giornata interessata.

Come possiamo aiutarti?