Modulo UltimateMarketPlace

Presentazione

Il modulo UltimateMarketPlace è un'estensione per Dolibarr ERP/CRM pubblicata da Atoo-Net.

Fornisce tutto il necessario per pubblicare un marketplace online a venditore unico: un modello di sito web pronto all'uso (catalogo prodotti, carrello, processo d'ordine, account clienti, area download), utilizzabile con il modulo Sito web di Dolibarr, per vendere i propri prodotti e servizi direttamente online.

Si tratta di un fork semplificato del modulo Dolibarr «Marketplace» (usato per dolistore.com), dal quale è stato rimosso tutto ciò che è specifico dell'associazione Dolibarr, nonché il circuito multi-venditore / invio e revisione dei moduli da parte di sviluppatori terzi.

Proprietà	Valore
Autore	Philippe Grand — Atoo-Net
Versione	24.0.1
Licenza	GNU GPL v3+
Dolibarr minimo	v24.0
PHP minimo	v8.2

Perché usare UltimateMarketPlace?

UltimateMarketPlace trasforma la vostra installazione di Dolibarr in un negozio online autonomo, senza dipendere da un CMS o da una piattaforma di e-commerce esterna (PrestaShop, WooCommerce…). Catalogo, ordini, fatture e clienti restano nativamente in Dolibarr.

Casi d'uso

Vendita di prodotti fisici o digitali

Pubblicate il vostro catalogo di prodotti o servizi direttamente dalle schede prodotto di Dolibarr: basta collocarli sotto la categoria principale del negozio. I file allegati al prodotto possono essere consegnati al cliente nella sua area download dopo il pagamento.

Abbonamenti e licenze a durata limitata

Con la durata di validità dei prodotti e i livelli di prezzo di Dolibarr («Multiprezzi»), vendete uno stesso prodotto con diverse durate di abbonamento: i link di download scadono automaticamente alla fine del periodo acquistato.

Prezzi preferenziali per i vostri migliori clienti

Gli sconti per categoria associano una categoria di clienti a una categoria di prodotti: il prezzo scontato viene mostrato automaticamente non appena il cliente è connesso, senza codice da inserire.

Operazioni commerciali e codici sconto

Create codici sconto (percentuale o importo fisso), limitati nel tempo o nel numero di utilizzi, ciascuno riservato a un prodotto preciso, per animare le vostre vendite online.

Pagamento online

Collegate il processo d'acquisto ai moduli di pagamento online già configurati in Dolibarr (Stripe, PayPal…), con un classico reindirizzamento alle pagine pubbliche di pagamento oppure integrato in un frame del negozio.

Posizionamento e analisi del traffico

URL semplificati, sitemap.xml, robots.txt e llms.txt generati automaticamente, markup Schema.org, verifica Google Search Console e integrazione di Matomo Analytics per seguire le visite senza dipendere da Google Analytics.

Installazione

Requisiti:

Dolibarr 24.0 o superiore e PHP 8.2 o superiore;
le pagine del negozio contengono codice PHP dinamico: prima di attivare il modulo, aggiungete la riga $dolibarr_website_allow_custom_php = '1'; in htdocs/conf/conf.php (valore 2 se le funzioni di sistema PHP exec, passthru, shell_exec, system, popen e proc_open non sono disattivate in php.ini). Senza questa riga, Dolibarr rifiuta di importare il modello del sito e il negozio resta vuoto;
i moduli Dolibarr Soggetti terzi, Prodotti, Servizi, Categorie, Ordini, Fatture, Banche, Mailing e Sito web sono necessari: vengono attivati automaticamente con il modulo.

Scaricate il modulo da DoliStore o clonate il repository Git in htdocs/custom/ultimatemarketplace
Andate in Home → Impostazioni → Moduli/Applicazioni
Individuate Ultimate Market Place nella famiglia Web sites ed altre applicazioni
Attivate il modulo con il pulsante della colonna Attivo

Attivazione del modulo UltimateMarketPlace

All'attivazione, il modulo esegue automaticamente diverse azioni:

Attivazione della gestione multilingue (MAIN_MULTILANGS), poiché le schede prodotto possono essere tradotte
Creazione di una categoria principale dei prodotti e di una categoria di soggetti terzi «prospect/cliente» se non ne è ancora configurata nessuna
Registrazione del modello PDF di fattura proprio del modulo
Creazione (o riattivazione) di un sito web dedicato nel quale viene importato il modello di sito fornito dal modulo

Aggiornamento: dopo la sostituzione dei file, disattivate e riattivate il modulo (le vostre impostazioni vengono conservate). Per allineare le pagine del sito alla nuova versione, usate poi il pulsante Reimposta il template del sito (vedere Modalità manutenzione).

Il modulo non dichiara alcun permesso proprio: le pagine di amministrazione sono riservate agli amministratori di Dolibarr, e le pagine del negozio usano una propria sessione cliente.

Dominio e host virtuale

Il negozio deve essere servito dal suo dominio (ad esempio https://shop.example.com), tramite un host virtuale del server web (Apache, Nginx…). L'indirizzo di anteprima di Dolibarr, …/public/website/index.php?website=…, serve solo per i test: senza dominio, il negozio non funziona completamente.

Il carrello e i download chiamano /_service_page_ajax.php e /_service_download.php alla radice del dominio. Senza host virtuale, queste chiamate finiscono in un errore 404 e il carrello non si aggiorna più.
In anteprima, Dolibarr stampa un commento HTML prima della pagina. Se output_buffering è disattivato in PHP, la sessione dell'acquirente non si avvia («sessione scaduta» all'accesso).
Il sitemap.xml e il robots.txt sono costruiti a partire dall'host virtuale definito sul sito: se è vuoto, non vengono generati, e i link di disiscrizione delle e-mailing puntano a Dolibarr invece che al negozio.

Configurazione:

Creare un host virtuale la cui radice (DocumentRoot) sia la directory del sito: <documents>/website/<ref> (<documents>/<entità>/website/<ref> per un'entità diversa dalla prima). <documents> è la directory dei documenti di Dolibarr, e <ref> il riferimento del sito creato all'attivazione (ultimatemarketplace per impostazione predefinita, vedere il parametro «Sito web da utilizzare per il marketplace»).
PHP deve esservi attivo. L'utente del server web deve poter leggere i file di Dolibarr (htdocs) e scrivere in <documents>/website e <documents>/medias; se si utilizza open_basedir, deve includere queste directory. Consentire i link simbolici nella directory del sito: la sua cartella medias è un link a <documents>/medias.
Attivare HTTPS su questo dominio: i gateway di pagamento lo richiedono.
In Dolibarr, menu Siti web, aprire le proprietà del sito web e inserire il dominio completo, https:// compreso, nel campo Host virtuale o nome di dominio.

Esempio per Apache, da adattare (percorsi di un pacchetto Debian o Ubuntu):

<VirtualHost *:443>
    ServerName shop.example.com
    DocumentRoot "/var/lib/dolibarr/documents/website/ultimatemarketplace"

    <Directory "/var/lib/dolibarr/documents/website/ultimatemarketplace">
        AllowOverride FileInfo Options
        Options -Indexes -MultiViews +FollowSymLinks -ExecCGI
        Require all granted
    </Directory>
    <Directory "/var/lib/dolibarr/documents/medias">
        Options -Indexes -MultiViews -FollowSymLinks -ExecCGI
        Require all granted
    </Directory>

    SSLEngine on
    SSLCertificateFile    /etc/letsencrypt/live/shop.example.com/fullchain.pem
    SSLCertificateKeyFile /etc/letsencrypt/live/shop.example.com/privkey.pem
</VirtualHost>

Configurazione

Il modulo si configura in Home → Impostazioni → Moduli/Applicazioni → Ultimate Market Place, suddiviso in diverse schede: Impostazioni, Configurazione dei pagamenti, Codici sconto, Sconti per categoria, Sicurezza, Configurazione del server API (mostrata solo se il modulo API REST è attivo), Matomo Analytics, Carosello, Guida utente e About.

Prima di aprire il sito al pubblico, percorrete le schede in quest'ordine: Impostazioni (sezioni Varie, Prodotti, Soggetti terzi, Sito web e Modelli e-mail), Configurazione dei pagamenti, Sicurezza, poi disattivate la modalità manutenzione.

Impostazioni

Scheda Impostazioni della configurazione del modulo

Varie

Parametro	Costante	Descrizione
Nome del marketplace	`ULTIMATEMARKETPLACE_NAME`	Nome del negozio: titolo della homepage, titolo del `llms.txt`, nome del mittente sulla fattura PDF
Descrizione del marketplace / Parole chiave del marketplace	`ULTIMATEMARKETPLACE_DESCRIPTION` / `_KEYWORDS`	Meta-descrizione e parole chiave della homepage, traducibili per lingua
Email del marketplace	`ULTIMATEMARKETPLACE_EMAIL`	Email di contatto pubblica mostrata sul sito
Modalità manutenzione	`ULTIMATEMARKETPLACE_MAINTENANCE_MODE`	Chiude il negozio al pubblico e blocca le vendite
Blocca le nuove registrazioni	`ULTIMATEMARKETPLACE_BLOCK_REGISTRATION`	Chiude la creazione di nuovi account cliente
Indirizzi IP autorizzati a bypassare la modalità manutenzione e il blocco delle registrazioni	`ULTIMATEMARKETPLACE_MAINTENANCE_MODE_ALLOWED_IPS`	Lista bianca di indirizzi IP (per esempio quello dell'ufficio)
Durata cache della barra laterale	`ULTIMATEMARKETPLACE_SIDEBAR_CACHE_ENABLED` / `_SIDEBAR_CACHE_DURATION`	Cache della barra laterale in minuti (5 per impostazione predefinita), con un pulsante per svuotare la cache del sito

Prodotti

Parametro	Costante	Descrizione
Categoria principale dei prodotti da vendere sul marketplace	`ULTIMATEMARKETPLACE_ROOT_CATEGORY_ID`	I prodotti/servizi di questa categoria e delle sue sottocategorie formano il catalogo (obbligatorio)
Categoria messa in evidenza nel blocco centrale della homepage	`ULTIMATEMARKETPLACE_ROOT_CATEGORY_ID_BIS`	Facoltativa, altrimenti la categoria principale
Categoria per il widget "Versione"	`ULTIMATEMARKETPLACE_VERSIONS_CATEGORY_ID`	Prodotti con numeri di versione (software scaricabile)
Categoria per il widget "Promozioni"	`ULTIMATEMARKETPLACE_SPECIAL_CATEGORY_ID`	Prodotti mostrati con un badge di promozione
Prezzo minimo del prodotto	`ULTIMATEMARKETPLACE_MIN_PRODUCT_PRICE`	I prodotti a pagamento più economici sono esclusi dal catalogo
Età massima (in giorni) affinché un prodotto sia visibile nella sezione "Nuovi prodotti"	`ULTIMATEMARKETPLACE_DELAY_FOR_NEW`	30 giorni per impostazione predefinita
Categoria per forzare lo stato "Nuovo prodotto"	`ULTIMATEMARKETPLACE_NEW_CATEGORY_ID` / `_NEW_CATEGORY_MAX_AGE`	Forza il badge «Nuovo»; un'attività pianificata giornaliera ne rimuove i prodotti dopo il termine indicato
Attiva la durata di validità del prodotto	`ULTIMATEMARKETPLACE_ENABLE_PRODUCT_VALIDITY_DURATION`	Date di inizio e fine validità sulle righe d'ordine, che governano la scadenza dei download; durate per livello di prezzo se i «Multiprezzi» sono attivi

Soggetti terzi

Parametro	Costante	Descrizione
Categoria per tutti i prospect o clienti creati dal sito del marketplace	`ULTIMATEMARKETPLACE_PROSPECTCUSTOMER_ID`	Categoria assegnata a ogni soggetto terzo creato dal modulo di registrazione
Abilita indirizzi multipli	`ULTIMATEMARKETPLACE_ENABLE_MULTI_ADDRESS`	Sezione «I miei indirizzi» dell'account cliente (indirizzi di fatturazione e di spedizione)
Converti il prospect in cliente al primo pagamento	`ULTIMATEMARKETPLACE_CONVERT_PROSPECT_TO_CUSTOMER_ON_FIRST_PAYMENT`	Il prospect diventa cliente non appena la sua prima fattura è pagata

Sito web

Parametro	Costante	Descrizione
URL del logo del marketplace	`ULTIMATEMARKETPLACE_URL_FOR_LOGO`	Logo dell'intestazione del sito; altrimenti quello dell'azienda, poi un logo fornito con il modulo
URL dell'immagine di benvenuto / Nascondi l'immagine di benvenuto	`ULTIMATEMARKETPLACE_WELCOME_IMAGE_URL` / `_WELCOME_IMAGE_HIDE`	Banner della homepage
Colore principale del tema / Colore secondario del tema	`ULTIMATEMARKETPLACE_THEME_COLOR` / `_SECONDARY_COLOR`	Colori del tema (`#a45931` e `#333333` per impostazione predefinita)
Attiva URL semplificati	`ULTIMATEMARKETPLACE_FRIENDLY_URLS`	URL del tipo `/it/123-nome-del-prodotto.html`
Token di verifica Google Search Console	`ULTIMATEMARKETPLACE_GOOGLE_SITE_VERIFICATION`	Meta tag di verifica
Descrizione per llms.txt	`ULTIMATEMARKETPLACE_LLMS_DESCRIPTION`	Frase di presentazione del sito nel `llms.txt`
Utente con i permessi per eseguire operazioni sul sito web	`ULTIMATEMARKETPLACE_USER_MANAGE_WEBSITE`	Utente tecnico usato dal negozio (creazione di soggetti terzi, di ordini…)
Sito web da utilizzare per il marketplace	`ULTIMATEMARKETPLACE_WEBSITE_ID`	Sito web Dolibarr gestito dal modulo, definito all'attivazione
Elimina sempre l'ordine provvisorio alla disconnessione	`ULTIMATEMARKETPLACE_DELETE_ORDER_ON_LOGOUT`	Svuota il carrello in corso alla disconnessione del cliente
Mostra un banner di consenso ai cookie	`ULTIMATEMARKETPLACE_ENABLE_COOKIE_BANNER`	Banner di consenso sul sito

Importante: se cambiate il sito web associato (ULTIMATEMARKETPLACE_WEBSITE_ID), gli utenti, i soggetti terzi e gli ordini già creati restano collegati al vecchio sito e non vengono migrati automaticamente.

Modelli e-mail

Tre elenchi a discesa permettono di scegliere, tra i modelli di email di Dolibarr (Impostazioni → Email → Modelli), quello dell'email di benvenuto inviata alla creazione dell'account (ULTIMATEMARKETPLACE_WELCOME_EMAIL_TEMPLATE), quello dell'email «Password dimenticata» (ULTIMATEMARKETPLACE_FORGOT_PASSWORD_EMAIL_TEMPLATE) e quello della conferma d'ordine dell'acquirente (ULTIMATEMARKETPLACE_BUYER_ORDER_CONFIRMATION_TEMPLATE).

Configurazione dei pagamenti

Scheda Configurazione dei pagamenti

Parametro	Costante	Descrizione
Bloccare le vendite sul marketplace	`ULTIMATEMARKETPLACE_BLOCK_SALES`	Il catalogo resta consultabile ma gli ordini sono disattivati; forzato finché la modalità manutenzione è attiva
Chiudere automaticamente gli ordini dopo un pagamento riuscito	`ULTIMATEMARKETPLACE_CLOSE_ORDER_AFTER_PAYMENT`	Chiude l'ordine Dolibarr una volta confermato il pagamento
Selezionare il metodo di pagamento da utilizzare	`ULTIMATEMARKETPLACE_MAIN_PAYMENT_METHOD`	Modulo di pagamento online di Dolibarr usato alla convalida dell'ordine
Includere le pagine di pagamento fornite da Dolibarr all'interno di un frame del negozio marketplace (utenti avanzati)	`ULTIMATEMARKETPLACE_PAYMENT_IN_FRAME`	Pagamento mostrato in un frame sotto il dominio del negozio

Sono possibili due modalità di integrazione del pagamento:

Pagina separata (predefinita): nessuna configurazione particolare, il cliente viene reindirizzato alle pagine di pagamento pubbliche del vostro Dolibarr. Svantaggio: il dominio del back-office è visibile al cliente.
Frame (utenti avanzati, Stripe e Stancer): la pagina di pagamento viene richiamata tramite un URL del negozio stesso. È necessaria una regola di reverse proxy sul server web del negozio; un esempio di configurazione viene mostrato nella pagina una volta attivata l'opzione.

Codici sconto

Scheda Codici sconto

Ogni codice sconto è collegato a un prodotto preciso e prevede un tipo di sconto (percentuale o importo fisso), un valore, date di validità e numero massimo di utilizzi facoltativi, oltre a un indicatore attivo/inattivo. L'acquirente inserisce il codice nel carrello: viene accettato solo se è attivo, entro le sue date di validità, sotto il suo limite di utilizzo e se il prodotto interessato è nel carrello. Il contatore degli utilizzi viene incrementato solo alla convalida dell'ordine.

Sconti per categoria

Scheda Sconti per categoria

Uno sconto per categoria associa una categoria di clienti a una categoria di prodotti con una percentuale di sconto. Per un cliente connesso appartenente a questa categoria, il prezzo scontato viene mostrato direttamente sulla scheda prodotto e nel carrello, senza codice da inserire. Se si applicano più regole, prevale la percentuale più alta.

Sicurezza

Scheda Sicurezza

Parametro	Costante	Descrizione
Provider captcha	`ULTIMATEMARKETPLACE_CAPTCHA_PROVIDER`	Nessuno, Google reCAPTCHA o Cloudflare Turnstile, con le relative chiavi del sito e chiavi segrete
Attivare questa protezione	`ULTIMATEMARKETPLACE_LOGIN_PROTECTION_ENABLED`	Limitazione dei tentativi di accesso al negozio
Numero di errori prima del blocco / Durata prima dello sblocco (minuti)	`ULTIMATEMARKETPLACE_LOGIN_MAX_ATTEMPTS` / `_LOGIN_BLOCK_DURATION`	5 errori e 15 minuti per impostazione predefinita
Indirizzi IP autorizzati a bypassare questa protezione	`ULTIMATEMARKETPLACE_LOGIN_BYPASS_IPS`	Lista bianca (test automatizzati, rete di fiducia)

Il captcha e la protezione dell'accesso sono disattivati per impostazione predefinita: configurateli prima di aprire la registrazione al pubblico.

Configurazione del server API

Questa scheda compare solo se il modulo API REST di Dolibarr è attivo. Contiene la Chiave API pubblica (ULTIMATEMARKETPLACE_PUBLIC_API_KEY, con un pulsante per generarla), passata come parametro apikey ai due endpoint pubblici in sola lettura aggiunti dal modulo: /api/index.php/ultimatemarketplace/categories e /api/index.php/ultimatemarketplace/products.

Matomo Analytics

Scheda Matomo Analytics

Costante	Descrizione
`ULTIMATEMARKETPLACE_ENABLE_MATOMO`	Attiva Matomo sul sito: il codice di tracciamento viene inserito in ogni pagina
`ULTIMATEMARKETPLACE_MATOMO_SITE_KEY`	Identificativo del sito Matomo
`ULTIMATEMARKETPLACE_MATOMO_SERVER_URL`	URL completo del server Matomo
`ULTIMATEMARKETPLACE_MATOMO_AUTH_TOKEN`	Token di autenticazione facoltativo, necessario per mostrare le statistiche Matomo in Dolibarr

Carosello

Scheda Carosello

Impostazioni del carosello della homepage: tipo di transizione (nessuna, dissolvenza, scorrimento), velocità in millisecondi, pausa al passaggio del mouse e ripetizione in loop. Ogni diapositiva ha un'immagine, un link facoltativo e un titolo; l'ordine si modifica con il trascinamento e le immagini si scelgono o si caricano tramite un selettore di immagini.

Guida utente

Scheda Guida utente

La scheda Guida utente mostra, nella lingua dell'utente, una guida completa alla configurazione e all'utilizzo del modulo, in solo testo: le schermate si trovano in questa pagina.

Utilizzo

Negozio online

Homepage del negozio

Il sito generato dal modulo riprende il logo e i colori definiti nella configurazione e propone:

un catalogo organizzato per categorie, con i badge «Nuovo» e «Promozioni» e un carosello nella homepage;
una scheda prodotto con il prezzo (sconto per categoria già applicato) e, per i prodotti con livelli di prezzo, la scelta della durata;
un carrello, conservato in sessione fino alla convalida, con l'inserimento di un codice sconto;
un processo d'ordine collegato al modulo di pagamento online scelto;
un'area cliente: dati personali, «I miei indirizzi», storico degli ordini e area download.

Scheda prodotto del negozio

La convalida del carrello crea un ordine standard di Dolibarr; il pagamento genera una fattura standard di Dolibarr.

File consegnati al cliente

La scheda File negozio della scheda prodotto indica, per ogni file allegato, se è mostrato sulla scheda prodotto pubblica. Un file spuntato come «File principale» o «Visibile dal cliente» può essere scaricato dal cliente una volta pagato l'ordine; viene mostrato un avviso se nessun file del prodotto lo è. Se la durata di validità dei prodotti è attiva, il link di download scade alla fine del periodo acquistato; altrimenti non scade mai.

Menu UltimateMarketPlace

Statistiche del marketplace

Il menu principale Mercato dà accesso a:

Statistiche: statistiche delle fatture, statistiche dei clienti, statistiche dei prodotti, elenco delle vendite e, se Matomo è configurato, statistiche Matomo;
Prodotti senza tag: prodotti del catalogo senza parole chiave, per controllare la qualità del catalogo;
Carrelli e Fatture: elenchi standard degli ordini e delle fatture di Dolibarr, filtrati su quelli provenienti dal negozio.

Modalità manutenzione e reimpostazione del modello

La modalità manutenzione chiude il sito al pubblico (tranne per gli indirizzi IP autorizzati) e blocca le vendite. Finché è attiva, la scheda Impostazioni propone due pulsanti:

Genera sitemap.xml: rigenera immediatamente sitemap.xml;
Reimposta il template del sito: reimporta il modello di sito del modulo nel sito esistente, sovrascrivendo le modifiche fatte a mano nell'editor delle pagine. Da usare dopo un aggiornamento del modulo.

Ricordate di disattivare la modalità manutenzione una volta terminate le verifiche: non si disattiva da sola.

Posizionamento

robots.txt, sitemap.xml e llms.txt vengono rigenerati automaticamente all'attivazione, all'apertura della scheda Impostazioni e dopo una reimpostazione del modello. Una volta attivati gli URL semplificati, i vecchi URL restano validi durante la transizione.

Novità della versione 24.0.1

Documentazione: la guida utente e questa pagina spiegano come servire il negozio sul proprio dominio, tramite un host virtuale la cui radice è la directory del sito (vedi Dominio e host virtuale). Il codice del modulo è invariato.

Novità della versione 24.0.0

Compatibilità

Dolibarr 24 e PHP 8.2 minimo: il modulo richiede ora Dolibarr 24.0.0 e PHP 8.2; è testato fino a PHP 8.5. Il controllo degli aggiornamenti legge versionmodules/ultimatemarketplace/v24/ultimatemarketplace.txt.
Numerazione allineata a Dolibarr: dopo la 1.0.8, il modulo passa direttamente alla 24.0.0, come gli altri moduli Atoo-Net.

Traduzioni

Il blocco carrello del negozio mostrava chiavi grezze (quantity, total, shipping, FreeShipping): ora carica le traduzioni del modulo. Reimpostate il template del sito per beneficiarne.
Aggiunte le etichette mancanti delle pagine del negozio (riferimenti, IVA, articoli, aggiunta e rimozione di indirizzi, controlli del modulo di registrazione…) e dei messaggi di amministrazione, nelle cinque lingue.
Traduzione in francese, tedesco, spagnolo e italiano delle etichette che esistevano solo in inglese.

Documentazione e distribuzione

Guida utente: sezione dei requisiti e della compatibilità; la guida inglese diventa GUIDE_UTILISATEUR-EN.md.
Pagina wiki riscritta a partire dalle schermate attuali, con schermate nelle cinque lingue.
Script di costruzione del pacchetto DoliStore e integrazione continua (installazione delle dipendenze e controllo della sintassi con PHP 8.4 e 8.5).

Versioni precedenti

Il dettaglio delle versioni dalla 1.0.0 alla 1.0.8 (codici sconto, sconti per categoria, carosello, protezione dell'accesso, URL semplificati, llms.txt, guida utente…) si trova nel file ChangeLog.md fornito con il modulo.

FAQ

Module UltimateMarketPlace IT