Grandoc at 13:36, 28 July 2026

2026-07-28T13:36:12Z

@@ Line 1: / Line 1: @@
 =Sommario=
 [[Category:Moduli aggiuntivi]]
 {{TemplateDocDev}}
 {{TemplateDocUtil}}
@@ Line 226: / Line 225: @@
 ''[[#Sommario|⬆ Torna al sommario]]''

Grandoc: Created page with "=Sommario= Category:Moduli aggiuntivi Category:Ultimateinvoice {{TemplateDocDev}} {{TemplateDocUtil}} =Informazioni= {{TemplateModuleInfo |modulename=UltimateInvoice |..."

2026-07-28T13:22:54Z

Created page with "=Sommario= Category:Moduli aggiuntivi Category:Ultimateinvoice {{TemplateDocDev}} {{TemplateDocUtil}} =Informazioni= {{TemplateModuleInfo |modulename=UltimateInvoice |..."

New page

=Sommario=
[[Category:Moduli aggiuntivi]]
[[Category:Ultimateinvoice]]
{{TemplateDocDev}}
{{TemplateDocUtil}}
=Informazioni=
{{TemplateModuleInfo
|modulename=UltimateInvoice
|editor=[[File:Logo atoonet.jpg|link=https://www.atoo-net.com]]
|webbuy={{LinkToPluginDownloadDoliStore|keyword=ultimateinvoice}}
|status=stable
|prerequisites=Modulo ''Fatture'' attivato - PHP 7.4 minimo
|minversion=23.0.x - 24.0.x
|note=
''[[#Sommario|⬆ Torna al sommario]]''
}}

=Funzionalità=
UltimateInvoice sostituisce il modello PDF nativo di Dolibarr per le '''fatture''' con un modello completamente personalizzabile, chiamato '''<code>ultimate_invoice</code>'''. Vero coltellino svizzero della fattura PDF, consente di definire la propria identità grafica (logo, colori, margini, sfondo di pagina, larghezza delle colonne), di scegliere con precisione ciò che viene stampato sul documento, di allegare le proprie condizioni generali di vendita o altri PDF, di aggiungere codici a barre e codici QR e di '''firmare digitalmente''' il file generato.

'''UltimateInvoice è la versione alleggerita del modulo [[Module_Ultimatepdf_EN|UltimatePDF]]''': copre unicamente le fatture. Per preventivi, ordini, contratti, spedizioni, note spese, interventi, progetti, prodotti/distinte base o documenti fornitore è necessaria la versione completa UltimatePDF.

===Due livelli di configurazione===

Il modulo si basa su due nozioni da non confondere :

*Il '''Design''' (scheda ''Models'') definisce '''l'aspetto''' del documento : colori, margini, logo, alias azienda, sfondo di pagina, larghezza delle colonne. Più Design possono coesistere, uno solo è attivo per impostazione predefinita (costante <code>ULTIMATE_DESIGN</code>), e un selettore in alto a destra nell'applicazione permette di cambiarlo all'istante.
*Le pagine '''Opzioni''' e '''Fatture''' decidono '''cosa viene visualizzato''' sul documento : colonne visibili, blocchi indirizzo, diciture di legge, firme stampate ecc. Non intervengono sull'aspetto grafico.

===Personalizzazione grafica (Design)===

*'''Sfondo di pagina''' : immagine di sfondo o PDF di sfondo (carta intestata già impaginata), con trasparenza e posizionamento X/Y.
*'''Intestazione''' : altezza e larghezza del logo, secondo logo (partner, certificazione), larghezza del blocco mittente con anteprima trascina e rilascia e preimpostazione '''busta con finestra secondo la norma postale francese'''.
*'''Alias azienda''' : consente di stampare sul documento una ragione sociale, un indirizzo, un capitale sociale o una partita IVA diversi da quelli dell'entità giuridica reale — utile per un marchio commerciale o una filiale.
*'''Margini e colonne''' : margini del PDF e larghezza di ciascuna colonna della tabella delle righe (riferimento, immagine, data, tipo, progetto, IVA, prezzo unitario, quantità, unità, sconto), ognuna ridimensionabile con il mouse su un'anteprima grafica.
*'''Piè di pagina''' : dimensione del carattere, altezza riservata al testo libero, colori del testo e dello sfondo.
*'''Carattere''' : scelta del font del documento (DejaVuSans per set di caratteri estesi o cirillici).

Ogni blocco del modulo dispone del proprio pulsante '''Salva''' : si conferma blocco per blocco senza perdere quanto inserito negli altri.

===Contenuto della fattura===

*Colonne delle righe : numerazione, foto prodotto, prezzo unitario netto, sconto, prezzo unitario dopo sconto, quantità, peso e peso totale, unità.
*Blocchi indirizzo : dati del destinatario, del cliente e del commerciale di riferimento, identificativi professionali (codice fiscale, REA...), partita IVA intracomunitaria, impilamento verticale dei blocchi contatto.
*Impaginazione : intestazione non ripetuta su ogni pagina, segno di piegatura, testo accanto alla data, formato carta.
*Specifico fatture : spedizioni collegate, condizioni di pagamento, fattura di stato avanzamento lavori, link di pagamento online, esposizione del cliente, importo in lettere, riga del totale lordo, generazione senza colonna IVA.
*Firme '''stampate''' : firma del responsabile sul documento e firma del commerciale di riferimento nella nota. Sono '''immagini''' aggiunte al PDF, da non confondere con la firma crittografica descritta più avanti.

===Unione di PDF e condizioni generali di vendita===

*'''Condizioni generali di vendita''' : un file PDF con le condizioni generali viene caricato dalla pagina ''Opzioni'' e accodato alla fattura, con possibilità di preselezione predefinita.
*'''File aggiuntivi''' : dopo aver attivato l'opzione corrispondente nella pagina ''Fatture'', uno o più PDF qualsiasi possono essere uniti al documento direttamente dalla scheda della fattura.

===Firma elettronica delle fatture (PAdES)===

UltimateInvoice può apporre una '''firma digitale''' al PDF nel momento in cui viene generato. La firma garantisce al destinatario l'autenticità (il documento proviene realmente da voi) e l'integrità (non è stato modificato da allora). Adobe Acrobat Reader la mostra nel pannello ''Firme'', e in basso a destra sull'ultima pagina viene disegnato un '''riquadro di firma visibile'''.

{| class="wikitable"
! Aspetto !! Dettaglio
|-
| Cosa fa la funzionalità || Firma crittografica PKCS#7 separata, equivalente a '''PAdES-B-B''', integrata nativamente nel PDF, con riquadro visibile e cliccabile
|-
| Cosa non fa || Nessuna marca temporale qualificata (RFC 3161), nessun LTV/archiviazione a lungo termine, '''nessun valore probatorio qualificato eIDAS'''
|-
| Cosa non sostituisce || Né la fatturazione elettronica (FatturaPA, Factur-X / PDF/A-3), né una firma qualificata rilasciata da un prestatore di servizi fiduciari
|}

Formati di certificato accettati : '''<code>.pem</code>, <code>.crt</code>, <code>.p12</code>, <code>.pfx</code>'''. Il file deve contenere '''il certificato e la chiave privata'''. Viene archiviato nella cartella ''documents'' di Dolibarr, fuori dalla cartella web del modulo : non è quindi scaricabile da un browser.

'''Limite importante''' : l'unione di file aggiuntivi riscrive il PDF dopo la generazione e invaliderebbe la firma. Su una fattura in cui vengono uniti dei file, la firma viene quindi '''automaticamente ignorata''' (un avviso viene scritto nel registro di Dolibarr) anziché prodotta non valida. L'aggiunta delle condizioni generali di vendita, invece, resta compatibile.

===Codici a barre, codici QR e fattura QR svizzera===

*'''Codici a barre''' dei prodotti (EAN13 con cifra di controllo, CODE128, CODE39) e dei soggetti terzi, in alto o in basso nella pagina.
*'''Codici QR''' dell'azienda (MyCompany), del soggetto terzo o della fattura.
*'''Codice QR di pagamento SEPA''' (norma EPC069-12) e '''fattura QR svizzera''' (Swiss QR-bill), compresa la polizza di versamento completa su una pagina dedicata. Attenzione : entrambe le impostazioni appartengono al '''core di Dolibarr''' (''Home - Impostazioni - PDF - scheda Specific parameters'', sezione ''Fatture'') e non al modulo, che si limita a rispettarle durante la generazione.

Per la polizza di versamento svizzera completa la modalità di pagamento deve essere il '''bonifico bancario''', sulla fattura deve essere indicato un conto bancario, l'indirizzo della vostra azienda deve essere completo e l'IBAN valido (i QR-IBAN non sono ancora gestiti). Il riquadro della firma elettronica viene disegnato volutamente sull'ultima pagina della fattura, '''prima''' dell'aggiunta della polizza, il cui layout è normativo.

===Compatibilità con il modulo Milestone===

UltimateInvoice riconosce le righe milestone del modulo [[Module_Milestone_EN|Milestone]] (<code>product_type = 9</code>) : non vengono trattate come normali righe prodotto nel calcolo del peso di riga e del prezzo unitario dopo sconto, e conservano la propria formattazione nel PDF.

===Guida d'uso integrata===

Una guida completa, in francese e in inglese, è consultabile direttamente dalla configurazione del modulo, scheda '''User guide'''. Viene aggiornata a ogni versione e descrive in dettaglio ogni opzione.

''[[#Sommario|⬆ Torna al sommario]]''

==Prerequisiti==
'''Dolibarr :''' Versioni supportate :

*'''23.x'''
*'''24.x'''

'''PHP :''' versione 7.4 minima. La polizza di versamento svizzera completa su pagina dedicata richiede PHP 8.1 o superiore.

'''Moduli Dolibarr :''' il modulo '''Fatture''' deve essere attivato.

=⚙️ Procedura di installazione=

===⚙️ Installazione manuale===

#'''Scaricare''' il file archivio del modulo (.zip).
#'''Collocare''' il file nella directory principale di Dolibarr.
#'''Decomprimere''' il file zip con il comando :

<code>unzip module_ultimateinvoice-X.0.0.zip</code>

#'''Verificare''' che la posizione corretta del modulo sia :

<code>htdocs/custom/ultimateinvoice</code>

#'''Il modulo è ora disponibile''' e può essere attivato da Dolibarr.

''[[#Sommario|⬆ Torna al sommario]]''
=Configurazione=
Per utilizzare questo modulo occorre innanzitutto attivarlo. A tale scopo, dopo essersi collegati con un account amministratore,
andare alla pagina "'''Home - Impostazioni - Moduli/Applicazioni'''".
Il modulo compare nella scheda "'''Atoo-Net'''", fare clic su "Abilita".
Alla fine della riga del modulo compare un'icona ; facendo clic su di essa si accede alle pagine di configurazione specifiche del modulo.

Tutte le pagine di amministrazione del modulo sono protette dal permesso <code>ultimateinvoice -> config</code> : solo gli utenti che ne dispongono (di norma gli amministratori) possono accedervi. Gli altri utenti vedono semplicemente il modello <code>ultimate_invoice</code> comparire nell'elenco a discesa "Modello" della scheda fattura.

La configurazione si compone di cinque schede : '''Models''' (modelli), '''Opzioni''', '''Fatture''', '''User guide''' (guida d'uso) e '''About'''.

==Scheda Models (Design)==

Qui si costruisce l'aspetto grafico comune a tutti i vostri documenti.

[[File:slide_01_invoice.png|800px]]

- L'elenco mostra tutti i Design esistenti : etichetta, descrizione, tipo di bordo, colori, stato e contrassegno "Predefinito" per quello attualmente in uso.

- Fare clic su '''Aggiungi un design''' per crearne uno nuovo, oppure sulla matita per modificare un design esistente.

[[File:slide_02_invoice.png|800px]]

- Compilare blocco per blocco : informazioni sul modello e carattere, sfondo di pagina, intestazione e loghi, alias azienda, blocco centrale, margini e larghezza delle colonne, piè di pagina. '''Ogni blocco dispone del proprio pulsante Salva.'''

- Un Design disattivato non compare più negli elenchi di selezione. Il "Modello principale" e il Design predefinito non possono essere eliminati, per non compromettere mai la generazione dei documenti.

'''Importante''' : dopo aver modificato un Design, se il documento generato non sembra cambiato, verificare che sia proprio quel Design a portare il contrassegno "Predefinito".

==Scheda Opzioni (impostazioni globali)==

Queste impostazioni si applicano a tutti i documenti, indipendentemente dal Design scelto : loghi, blocchi indirizzo e identificativi professionali, sfondo di pagina, contenuto delle righe, condizioni generali di vendita, coordinate bancarie, certificato di firma, formato carta.

[[File:slide_03_invoice.png|800px]]

La maggior parte delle impostazioni sono interruttori on/off applicati immediatamente ; il formato carta e gli identificativi professionali si confermano con un apposito pulsante '''Salva'''.

===Caricamento delle condizioni generali di vendita===

Nell'apposito blocco selezionare il file PDF con le condizioni generali di vendita e inviarlo. Comparirà poi in un elenco a discesa accanto al pulsante '''Genera''' della scheda fattura e potrà essere preselezionato per impostazione predefinita.

===Messa in servizio della firma elettronica===

Nel blocco '''Certificato di firma''', in fondo alla pagina Opzioni :

#'''Caricare''' il file del certificato (<code>.pem</code>, <code>.crt</code>, <code>.p12</code> o <code>.pfx</code>) contenente il certificato e la chiave privata.
#'''Indicare il motivo''' della firma (testo libero visibile nelle proprietà di firma del PDF, ad esempio "Fattura certificata conforme").
#'''Indicare la password''' della chiave privata se protetta, quindi salvare.
#'''Attivare''' l'interruttore "Firma elettronicamente il PDF della fattura".
#'''Generare una fattura''' e aprirla in Acrobat Reader : il pannello ''Firme'' deve mostrare la firma e il riquadro visibile compare in basso a destra sull'ultima pagina.

Viene considerato un solo certificato alla volta : eliminare il precedente prima di caricarne uno nuovo.

Per le '''prove''' è sufficiente un certificato autofirmato :

<code>openssl req -x509 -nodes -days 365 -newkey rsa:2048 -keyout signature.key -out signature.crt</code>

<code>cat signature.crt signature.key > signature.pem</code>

Acrobat mostrerà allora la firma come "presente ma non attendibile" : è normale, poiché l'autorità non è riconosciuta. In produzione utilizzare un certificato rilasciato da un'autorità di certificazione.

'''Da sapere prima della messa in produzione''' : la password della chiave privata è memorizzata in chiaro nella tabella delle costanti di Dolibarr, in assenza di un archivio di segreti nativo. Limitare di conseguenza l'accesso al database e ai backup e applicare permessi file rigorosi sulla cartella in cui è archiviato il certificato.

==Scheda Fatture==

Questa pagina raccoglie le impostazioni relative al contenuto della fattura : indirizzi, codici a barre e codici QR, progetto collegato, intestazione e impaginazione, colonne delle righe, firme stampate, unione di PDF e impostazioni specifiche delle fatture (spedizioni collegate, fattura di stato avanzamento lavori, link di pagamento online, esposizione del cliente, importo in lettere...).

[[File:slide_04_invoice.png|800px]]

==Scheda User guide (guida d'uso)==

Mostra la guida completa del modulo nella lingua dell'interfaccia (francese o inglese). È la documentazione di riferimento, più dettagliata di questa pagina.

[[File:slide_05_invoice.png|800px]]

''[[#Sommario|⬆ Torna al sommario]]''

=Utilizzo=

- Aprire la scheda della '''fattura''', quindi, nel blocco '''Documenti''' in fondo alla scheda, scegliere il modello '''<code>ultimate_invoice</code>''' nell'elenco a discesa "Modello" e fare clic su '''Genera'''.

- Il PDF compare nell'elenco dei file allegati : può essere scaricato, visualizzato in anteprima o inviato per e-mail.

- '''Cambiare Design rapidamente''' : utilizzare l'apposito selettore nel menu in alto a destra dell'applicazione, senza tornare alla configurazione completa.

- '''Aggiungere le condizioni generali di vendita''' : selezionare il file nell'elenco a discesa accanto al pulsante Genera.

- '''Unire un PDF aggiuntivo''' : dopo aver attivato l'opzione nella pagina ''Fatture'', selezionare il o i file da unire dalla scheda della fattura. Su queste fatture la firma elettronica viene automaticamente ignorata.

==Risoluzione dei problemi==

{| class="wikitable"
! Sintomo !! Causa probabile
|-
| Il modello <code>ultimate_invoice</code> non compare nell'elenco || Il modulo UltimateInvoice o il modulo ''Fatture'' non è attivato
|-
| Il documento non riflette le modifiche di un Design || Quel Design non è quello che porta il contrassegno "Predefinito"
|-
| Nessuna firma né riquadro visibile sul PDF || Nessun certificato caricato, oppure estensione non riconosciuta
|-
| Registro : ''skipped: additional files merging is active'' || In questa fattura vengono uniti file aggiuntivi, le due funzioni si escludono a vicenda
|-
| Acrobat segnala "firma non valida" || Certificato autofirmato : normale in fase di prova, in produzione utilizzare un certificato di un'autorità riconosciuta
|-
| Registro : ''Error getting private key'' || Password della chiave privata mancante o errata, oppure file privo della chiave privata
|-
| La polizza di versamento svizzera non compare || Consultare i messaggi <code>SwissQr*</code> nel registro di Dolibarr : modalità di pagamento diversa dal bonifico, indirizzo o IBAN non conformi, QR-IBAN non gestito
|}

Il registro di Dolibarr ('''Home - Impostazioni - Altro - Registri''') tiene traccia di ogni generazione e di ogni tentativo di firma.

''[[#Sommario|⬆ Torna al sommario]]''

Module UltimateInvoice IT - Revision history

Grandoc at 13:36, 28 July 2026

Grandoc: Created page with "=Sommario= Category:Moduli aggiuntivi Category:Ultimateinvoice {{TemplateDocDev}} {{TemplateDocUtil}} =Informazioni= {{TemplateModuleInfo |modulename=UltimateInvoice |..."