1. Numeratori Documenti

Gestisce i progressivi numerici e le serie dei documenti emessi dal terminale:

• FT: Fattura Accompagnatoria (es. Serie A, Numero 101).
• BC: Bolla di Consegna / Documento di Trasporto DDT (es. Serie A, Numero 205).
• RC: Ricevuta Fiscale di vendita.
• LC: Lista di Carico dell'automezzo.
• AC: Numeratore progressivo per le registrazioni di Acconto.

2. Impostazioni Azienda

Contiene tutti i dati anagrafici e fiscali della società mittente: Ragione Sociale, Indirizzo, Città, CAP, Partita IVA, Codice Fiscale, Telefono, Email aziendale e codice IBAN per i bonifici. Se l'opzione Stampa Dati Azienda è attiva, tali dati verranno stampati nell'intestazione dei documenti fiscali.

3. Impostazioni Operatore

Configura l'identificativo dell'autista/venditore associato al dispositivo:

• Nome Operatore: Nome stampato sui documenti e trasferito nei record file.
• Targa Veicolo: Targa dell'automezzo utilizzata per DDT e liste di carico.
• Causale Lista di Carico: Causale di trasporto standard (es. "Tentata Vendita").
• Aspetto dei Beni: Descrizione esteriore standard (default: "CASSE A VISTA").
• Numero Postazione & Numero Magazzino: Identificativi numerici del furgone/deposito viaggiante per il gestionale.

4. Configurazione Rete & Stampante

Regola i canali di sincronizzazione dati e l'hardware di stampa:

• Tipo Sincronizzazione: Scelta tra File (tramite Samba SMB o FTP) e Magaworld (via Web Services REST API).
• Parametri Samba (SMB): Indirizzo IP del server locale, nome dominio di rete, utente, password, cartella di download e cartella di upload.
• Parametri FTP: Dominio/IP FTP, porta (default 21 o 2121), credenziali e cartelle di scambio.
• Impostazioni Stampante: Scelta del dispositivo Bluetooth associato (indirizzo MAC), selezione del marchio (BIXOLON o ESC/POS compatibile generico).
• Configurazione E-Mail (SMTP): Server SMTP, porta, credenziali, crittografia TLS/STARTTLS per l'invio automatico delle fatture in PDF via mail al cliente dopo la stampa.

5. Opzioni Avanzate Operative

• Abilita modifica prezzo: Consente all'operatore di variare manualmente il prezzo di riga rispetto al listino durante la vendita.
• Nascondi prezzi: Nasconde gli importi a display per evitare che il cliente veda margini o prezzi durante la digitazione.
• Visualizza giacenza lotti: Mostra la disponibilità residua di ciascun lotto nella maschera di vendita.
• Layout di stampa: Selezione tra rotolo largo 112mm (4 pollici, ideale per DDT dettagliati) e 80mm (3 pollici).
• Stampa prezzi in Lista Carico: Permette di valorizzare economicamente la merce caricata sul veicolo.
• Abilita timestamp nei file di export: Aggiunge un suffisso temporale (_timestamp) ai file esportati per evitare sovrascritture sul server gestionale.
• Richiedi acconto su documento: Richiede automaticamente se registrare un incasso contestualmente alla chiusura del documento.

6. Amministratore (Area Protetta)

Sezione protetta da password per impostare policy aziendali rigide:

• Blocco delle modifiche sui documenti dopo la loro emissione.
• Blocco della modifica o eliminazione delle liste di carico già stampate.
• Controllo obbligatorio dell'import giornaliero (impedisce di emettere documenti se al mattino non sono stati aggiornati gli archivi).
• Filtro Codice Agente (limita la visibilità dei soli clienti assegnati allo specifico operatore).

Ricerca Cliente Multifiltro

La schermata di ricerca clienti consente di localizzare all'istante l'anagrafica desiderata:

• Digitando nel campo di ricerca è possibile filtrare in tempo reale per Ragione Sociale, Codice Cliente o Partita IVA / Codice Fiscale.
• Per ciascun cliente vengono mostrati: indirizzo completo, recapito telefonico, modalità di pagamento abituale, numero di listino associato e il saldo contabile attuale.

Gestione Destinazioni Diverse (Sedi di Consegna)

Per i clienti con più punti vendita o cantieri (gestiti tramite anag_cli_sedi.csv), l'applicazione permette di selezionare la sede di consegna specifica. La sede scelta verrà stampata sul documento fiscale e riportata nel record di testata del file esportato verso l'ERP aziendale.

Estratto Conto Multiselezione & Scadenzario

Attraverso la maschera dell'estratto conto:

1. Vengono elencate tutte le fatture aperte e le rate insolute importate dal gestionale (tramite il file estratto_conto.csv).
2. L'operatore può visualizzare numero documento, data, tipo rata, data scadenza e importo residuo.
3. È possibile selezionare una o più partite aperte tramite caselle di spunta: il sistema sommerà istantaneamente il dovuto e permetterà di trasferire il totale direttamente nella maschera di incasso.

Flusso Operativo di Carico

1. Creazione Nuova Lista: L'autista accede al modulo Lista Carico e preme il pulsante + per generare una nuova lista (associata al progressivo numeratore LC).
2. Aggiunta Articoli: Gli articoli possono essere aggiunti tramite digitazione rapida del codice, selezione da elenco anagrafico o lettura del codice a barre con lo scanner integrato.
3. Attribuzione Lotti: Se l'articolo prevede la tracciabilità per lotto, il sistema richiede obbligatoriamente l'indicazione del codice lotto prelevato dal magazzino centrale e la relativa quantità.
4. Chiusura e Stampa: Una volta completato il carico, la lista viene confermata e stampata sul rotolo termico Bluetooth per il riscontro in magazzino.

Stampa Valorizzata con Listino Prezzi

Se è attiva l'opzione Stampa prezzi in Lista Carico, l'operatore prima della stampa può scegliere quale listino prezzi applicare (o utilizzare il prezzo base standard). La stampa produrrà un documento dettagliato con:

• Quantità caricate e Unità di Misura per ogni articolo;
• Prezzo unitario e totale riga merce;
• Totale Complessivo Valore Carico a bordo del mezzo.

Come Funziona la Verifica

Il modulo Verifica Carico (VerificaCaricoActivity) garantisce la corrispondenza al 100% tra quanto registrato a sistema nella Lista di Carico e la merce fisicamente presente a bordo dell'autocarro:

• L'operatore seleziona la Lista di Carico della giornata.
• Inizia a sparare con il lettore barcode o la fotocamera i colli caricati a bordo.
• Il software confronta in tempo reale le quantità rilevate con quelle previste in lista carico e aggiorna visivamente lo stato degli articoli con un codice colore chiaro:

Al termine, l'operatore può premere Stampa Riepilogo per generare un verbale di avvenuta verifica carico su stampante da 80mm o 112mm.

Tipologie di Documento Fiscali

Procedura Passo-Passo per l'Emissione

1. Scelta Cliente e Dati Testata: L'operatore seleziona il cliente, la tipologia documento (FT/BC/RC), la serie (es. standard o sezionale), la modalità di pagamento e l'eventuale sede secondaria di consegna.
2. Carrello Articoli: Inserimento merce tramite scansione codice a barre o ricerca alfabetica. Per ogni riga il programma ricava il prezzo dal listino cliente o dai prezzi speciali assegnati (tabella prezzi personalizzati).
3. Selezione Lotti e Scadenza: Se il prodotto è deperibile/gestito a lotti, si apre automaticamente la finestra di ripartizione quantitativa per lotto con le relative scadenze.
4. Sconti e Resi Merce: Possibilità di inserire sconti percentuali di riga o quantità negative per la gestione dei resi merce dal cliente.
5. Firma Grafica Cliente: Si apre la finestra di firma su schermo (CaptureSignature): il cliente appone la firma con il dito o pennino, salvata come immagine bitmap collegata al documento.
6. Incasso Contestuale (Opzionale): Se il cliente paga all'atto della consegna, l'operatore registra l'acconto o il saldo immediato.
7. Stampa e Generazione PDF: Viene stampato il documento cartaceo sulla stampante Bluetooth. Se configurato, viene generato il PDF ufficiale salvato in locale e inviato in copia email al cliente.

Funzionalità del Modulo Revisione

La schermata Revisione Documenti riepiloga tutti i documenti emessi durante il turno:

• Stato Documento: Un indicatore visivo mostra se il documento è ancora locale (non trasferito) o già esportato verso il server centrale (trasferito = true).
• Dettaglio Documento: Toccando un documento è possibile visualizzare l'elenco delle righe articolo, quantità, prezzi, totale imponibile, castelletto IVA e modalità di pagamento.
• Ristampa Singolo Documento: Invia una copia conforme alla stampante termica (utile in caso di fine carta o copie aggiuntive richieste dal cliente).
• Stampa Riepilogo Giornaliero: Tramite il pulsante Stampa Totale, viene stampato un resoconto cumulativo con il totale delle vendite suddiviso per aliquote IVA e totali incassati.
• Modifica o Annullamento: Permette di stornare o modificare un documento emesso per errore, a condizione che non sia già stato trasferito al gestionale e che l'amministratore non abbia impostato il blocco modifiche.

Registrazione Incasso

Il modulo Incassi consente all'operatore di riscuotere denaro sul campo in modo puntuale o cumulativo:

• Incasso da Estratto Conto: Selezionando una o più fatture aperte del cliente, l'importo da incassare viene precompilato automaticamente a saldo della partita contabile.
• Incasso Libero / Acconto Generico: Possibilità di inserire un versamento spontaneo del cliente come acconto non legato a un documento specifico.
• Modalità di Pagamento: Selezione tra Contanti, Assegno bancario, POS / Carta o Bonifico.
• Stampa Ricevuta: Al termine della registrazione viene emessa una ricevuta cartacea firmata da rilasciare al cliente per quietanza.

Conteggio Fisico e Differenze

Il modulo Inventario permette di verificare l'esatta concordanza tra la merce rimasta fisicamente sul mezzo e i movimenti teorici (Carico iniziale - Venduto - Resi):

1. L'operatore inserisce la quantità reale contata per ogni articolo (manualmente o mediante barcode).
2. Il sistema confronta la quantità rilevata con la giacenza contabile calcolata dal programma.
3. Vengono evidenziate le differenze in positivo (eccedenze) o in negativo (ammacchi/rotture).
4. È possibile stampare il prospetto di quadratura inventario da consegnare al responsabile di magazzino al rientro in sede.

Pianificazione e Tragitto

Il modulo Giro struttura la giornata lavorativa dell'autista secondo una sequenza ottimizzata di tappe:

• L'elenco dei clienti da visitare può essere predisposto dall'ufficio logistico e scaricato sul terminale.
• Accanto a ogni cliente viene visualizzato lo stato: Da visitare, Completato con vendita, Chiuso senza vendita.
• Grazie al modulo GPS (GPSTracker), con un tocco sul cliente l'autista può aprire direttamente Google Maps o Waze per avviare la navigazione stradale guidata verso la destinazione.

Pulsanti della Maschera Archivi

Hardware di Stampa Supportato

TVStart integra driver nativi per le più diffuse stampanti portatili da cintura per tentata vendita:

• Protocollo BIXOLON Nativo: Supporta la serie Bixolon SPP-R200, SPP-R300, SPP-R310, SPP-R410 con librerie BXL native ad alte prestazioni grafiche.
• Protocollo ESC/POS Standard: Sequenze di escape universali per qualsiasi stampante termica Bluetooth industriale (Zebra, Epson, Custom, Rongta, ecc.).
• Formato Carta 112mm (4 pollici): Consigliato per le aziende che necessitano di stampare documenti di trasporto (DDT) o fatture ricche di dettagli, con castelletto IVA ben spaziato e riepiloghi articolati.
• Formato Carta 80mm (3 pollici): Ideale per ricevute fiscali rapide, scontrini di tentata vendita, liste di carico e ricevute di incasso.
• Logo Grafico Aziendale: Inserendo il file logo.png nella cartella tv_Start/images/, l'applicazione stamperà l'intestazione grafica societaria in testa a ciascun documento.

TVStart è stato progettato per integrarsi agevolmente con qualsiasi ERP di mercato mediante lo scambio di file CSV strutturati con tracciati record fissi. Lo scambio dati può avvenire attraverso due canali standard:

1. Cartella Condivisa di Rete (Samba / SMB): Ideale per reti locali aziendali. Il terminale si connette in Wi-Fi alla cartella condivisa del server aziendale (es. smb://192.168.1.100/ScambioDati/) con credenziali di dominio.
2. Server FTP / FTPS: Ideale per agenti fuori sede che sincronizzano i dati da remoto tramite connessione dati 4G/5G con un server FTP aziendale.
3. Web Services REST Cloud MagaWorld: Integrazione avanzata tramite API JSON e chiamate HTTP/HTTPS gestite dalla libreria mwlib.

Regole Generali dei File CSV

1. anag_cli.csv (Anagrafica Clienti)

Contiene l'anagrafica completa dei clienti. Sono supportate righe da 14, 15 o 16 colonne:

codice;ragione_sociale;indirizzo;cap;localita;provincia;cod_pag;codice_fiscale;piva;telefono;email;listino;saldo;iban;gdo;codice_agente
CLI001;Ristorante Il Moro Srl;Via Garibaldi 10;00100;Roma;RM;01;01234567890;01234567890;069876543;amministrazione@ilmoro.it;1;150.00;IT60X0542811101000000123456;0;AG01

2. anag_cli_sedi.csv (Destinazioni Diverse di Consegna)

Utilizzato quando un cliente possiede più punti vendita, cantieri o magazzini di consegna:

3. anag_art.csv (Anagrafica Articoli)

Catalogo dei prodotti caricati a bordo o vendibili:

codice;descrizione;um;iva;gest_lotto;prz
ART100;Parmigiano Reggiano 24M 1KG;KG;4;1;18.50
ART200;Olio Extra Vergine Oliva 1LT;BT;4;0;8.90

4. anag_alias.csv (Codici a Barre Alternativi)

Collega molteplici codici a barre (EAN13, EAN128, Code128) allo stesso codice articolo primario:

5. anag_lot.csv (Giacenze Lotti e Scadenze)

Permette di caricare a bordo del veicolo i singoli lotti con le rispettive giacenze disponibili:

6. pagam.csv (Modalità di Pagamento)

7. anag_listini.csv (Listini Prezzi Multipli)

8. anag_prz.csv & storico_prezzi_cliente.csv (Prezzi Personalizzati & Storico)

anag_prz.csv: codice_art;codice_cli;prz;[sconto] per definire accordi di prezzo specifici cliente/articolo.

storico_prezzi_cliente.csv: codice_cliente;codice_articolo;data_documento;prezzo;[sconto] per mostrare all'operatore l'ultimo prezzo e sconto applicati a quel cliente nei viaggi precedenti.

9. estratto_conto.csv (Scadenzario & Partite Aperte)

Fornisce l'elenco delle fatture ancora insolute per consentire all'autista di riscuotere sul campo:

1. export_testata.csv (Testata Documenti Fiscali)

Contiene la testata di ogni Fattura (FT), Bolla DDT (BC) o Ricevuta (RC) emessa. Gestisce in modo nativo il castelletto IVA multi-aliquota fino a 4 aliquote distinte:

2. export_articoli.csv (Righe Articoli del Documento)

Contiene il dettaglio di ogni riga venduta nei documenti di vendita:

3. export_lotti.csv (Dettaglio Scarico Lotti)

Traccia in modo inequivocabile i lotti e le scadenze consegnati per ogni riga venduta:

4. export_incassi.csv (Registrazione Incassi)

Esporta tutte le riscossioni eseguite dall'operatore durante il turno:

5. export_clienti.csv (Nuovi Clienti Censiti sul Palmare)

Contiene i clienti creati ex-novo dall'operatore sul campo per l'acquisizione nel database anagrafico centrale dell'azienda, inclusi i campi per la Fatturazione Elettronica:

Flusso Giornaliero Raccomandato (Best Practice)

1. Ore 06:00 - Generazione Dati da Gestionale: L'ERP aziendale esporta nella cartella Download i file anagrafici aggiornati: anag_cli.csv, anag_art.csv, anag_alias.csv, anag_lot.csv, anag_listini.csv, anag_prz.csv, pagam.csv ed estratto_conto.csv.
2. Ore 06:30 - Sincronizzazione Mattutina Palmare: L'autista accende il terminale sotto rete Wi-Fi aziendale, apre Archivi e preme Import Totale. In circa 10-20 secondi l'intero database locale SQLite viene sincronizzato.
3. Ore 07:00 - Carico & Partenza: L'autista compila o verifica la Lista di Carico, esegue la Verifica Carico con barcode scanner e parte per il giro consegne.
4. Attività sul Campo (Offline): Emissione fatture, DDT, lotti, firme grafiche, incassi e ricevute in mobilità senza dipendere dalla copertura internet.
5. Ore 18:00 - Rientro Serale & Acquisizione ERP: Al rientro in sede, l'autista apre Archivi e tocca Export Totale. I file export_testata.csv, export_articoli.csv, export_lotti.csv ed export_incassi.csv vengono depositati nella cartella Upload del server. L'ERP aziendale legge i file, genera le fatture elettroniche XML per l'Agenzia delle Entrate e registra gli incassi di cassa.

Esempio Completo di Record per Documento di Vendita

Esempio di fattura emessa per il cliente CLI001 con vendita di 2 colli di Parmigiano Reggiano con lotto tracciato:

1. export_testata.csv

id;numeratore;cliente;tot_documento;trasferito;data_fattura;serie;sigla;cod_pag;magazzino;nome_operatore;imponibile_1;aliquotaIVA_1;totIVA_1;imponibile_2;aliquotaIVA_2;totIVA_2;imponibile_3;aliquotaIVA_3;totIVA_3;imponibile_4;aliquotaIVA_4;totIVA_4;firma;codice_sede;data_modifica;ora_modifica;nota
1;1;CLI001;38.48;false;27-08-2026;A;FT;01;1;Mario Rossi;37.00;4.0;1.48;;;;;;;;;;firma_1_FT.png;SEDE01;;;Merce consegnata integra al piano terra

2. export_articoli.csv

id;id_testata;descrizione;codice;qta;um;prz;importo;iva;sconto;numero_documento;sigla
1;1;Parmigiano Reggiano 24M 1KG;ART100;2.0;KG;18.50;37.00;4;0;1;FT

3. export_lotti.csv

id;lotto;id_articolo_emissione_doc;qta;codice_lotto;id_testata;numero_documento;sigla
1;LOTTO_PR_2026;1;2.0;L26-085;1;1;FT