Grandoc: Created page with "Category:Modules Category:AtooNet =Modulo psimport= ==Presentazione== '''psimport''' è un modulo per Dolibarr ERP/CRM pubblicato da [https://www.atoo-net.com Atoo-..."

2026-07-10T09:20:53Z

Created page with "Category:Modules Category:AtooNet =Modulo psimport= ==Presentazione== '''psimport''' è un modulo per Dolibarr ERP/CRM pubblicato da [https://www.atoo-net.com Atoo-..."

New page

[[Category:Modules]]
[[Category:AtooNet]]

=Modulo psimport=

==Presentazione==

'''psimport''' è un modulo per Dolibarr ERP/CRM pubblicato da [https://www.atoo-net.com Atoo-Net].

Include strumenti a riga di comando per '''migrare un negozio PrestaShop verso Dolibarr''': categorie, terzi/indirizzi, prodotti (con IVA risolta e immagine di copertina), file scaricabili dei prodotti virtuali, gallerie di immagini e ordini. La migrazione si basa sull'API REST Webservice di PrestaShop, con tabelle di appoggio intermedie (<code>llx_psimport_*</code>) che permettono di controllare e correggere i dati prima dell'importazione definitiva in Dolibarr, e di ripetere un'importazione senza richiamare nuovamente l'API.

Tutti i prodotti vengono importati come '''servizio''' (<code>Product::TYPE_SERVICE</code>), trattandosi di moduli dematerializzati, indipendentemente dal tipo impostato lato PrestaShop.

{| class="wikitable"
|-
!Proprietà!!Valore
|-
|Autore||Philippe Grand — Atoo-Net
|-
|Versione||1.0
|-
|Licenza||GNU GPL v3+
|-
|Dolibarr minimo||v24.0
|-
|PHP minimo||v8.1
|-
|PrestaShop supportato||v1.6 a 9.x (API Webservice)
|}

==Perché usare psimport?==

psimport permette di trasferire tutti i dati di un negozio PrestaShop esistente in Dolibarr, senza connessione diretta al database MySQL di PrestaShop (a eccezione di un passaggio opzionale e una tantum per i file scaricabili). Ogni fase passa attraverso una tabella di appoggio che può essere controllata prima dell'importazione finale.

===Casi d'uso===

====Migrazione completa di un negozio PrestaShop====
Recupero di categorie, terzi/indirizzi, prodotti (con IVA risolta tramite i gruppi di regole fiscali di PrestaShop) e ordini, tramite l'API REST Webservice, senza alcuna installazione aggiuntiva lato PrestaShop oltre all'attivazione del Webservice.

====Controllo prima dell'importazione finale====
Ogni risorsa viene prima recuperata in una tabella di appoggio (<code>llx_psimport_*</code>) dove i dati possono essere controllati e corretti prima dell'importazione effettiva in Dolibarr. Questo evita di richiamare nuovamente l'API di PrestaShop in caso di errore.

====Riesecuzione mirata dopo la correzione degli errori====
Ogni riga della tabella di appoggio ha uno stato (<code>import_status</code>). Le righe in errore possono essere riportate a "da importare" (pulsante "Reimposta errori" o una query SQL) e rielaborate, senza dover reimportare tutto da zero.

====Recupero dei file scaricabili dei moduli====
L'API Webservice di PrestaShop non espone i file allegati ai "prodotti virtuali/scaricabili" (limitazione confermata dal ticket ufficiale GitHub PrestaShop/PrestaShop#27834). Un modulo "bridge" per PrestaShop fornito con psimport aggira questo limite, in sola lettura.

====Galleria completa delle immagini prodotto====
Oltre all'immagine di copertina (recuperata insieme al prodotto), psimport può recuperare anche la galleria completa delle immagini di ogni prodotto tramite il sub-endpoint API <code>products/{id}/images</code>.

==Installazione==

'''Requisiti lato PrestaShop''':

#Attivare il Webservice: '''Parametri avanzati > Webservice > Attiva il webservice di PrestaShop''' → Sì
#Creare una chiave API ("Aggiungi una nuova chiave webservice") con permessi GET su: <code>categories</code>, <code>customers</code>, <code>addresses</code>, <code>countries</code>, <code>products</code>, <code>images</code>, <code>tax_rule_groups</code>, <code>tax_rules</code>, <code>taxes</code>, <code>orders</code>, <code>order_details</code>
#Annotare l'URL del sito e la chiave API generata

'''Requisiti lato Dolibarr''':

#Moduli attivati: Terzi, Prodotti, Servizi, Categorie, Ordini, Fatture
#Attivare il modulo '''psimport''' in '''Home → Configurazione → Moduli/Applicazioni''' (famiglia "Altri")

Attivando il modulo, le tabelle di appoggio <code>llx_psimport_*</code> vengono create automaticamente tramite il meccanismo standard di attivazione dei moduli di Dolibarr — non è necessaria alcuna importazione SQL manuale.

Il modulo psimport '''non ha menu né permessi propri'''. L'unica schermata è la pagina di configurazione (Configurazione > Moduli/Applicazioni > psimport > icona chiave inglese), dove si inseriscono l'URL del negozio PrestaShop e la chiave API del Webservice (costanti <code>PSIMPORT_API_URL</code> e <code>PSIMPORT_API_KEY</code>), utilizzate di default dagli script CLI quando non viene passato alcun parametro da riga di comando. L'intera migrazione viene poi gestita da riga di comando tramite gli script nella cartella <code>scripts/</code>.

==Configurazione==

===Connessione all'API di PrestaShop===

{| class="wikitable"
|-
!Costante!!Descrizione
|-
|<code>PSIMPORT_API_URL</code>||URL di base dell'API Webservice di PrestaShop (es. <code>https://www.yourshop.com/api</code>)
|-
|<code>PSIMPORT_API_KEY</code>||Chiave API del Webservice di PrestaShop
|}

===Risoluzione problemi: HTTP 403 sull'API (hosting dietro Cloudflare)===

Se il test di connessione (o uno script <code>fetch-*</code>/<code>import-*</code>) fallisce con un errore del tipo <code>HTTP 403 Forbidden</code> '''con corpo della risposta vuoto''' e nessun reindirizzamento rilevato, mentre la stessa chiamata funziona nel browser, il blocco probabilmente non proviene da PrestaShop ma da un firewall applicativo a monte (Cloudflare, ModSecurity, ecc.) che rifiuta la richiesta prima che raggiunga il sito.

Caso riscontrato e confermato su un hosting '''Cloudflare (piano gratuito)''': il '''Bot Fight Mode''' gratuito di Cloudflare rileva le chiamate cURL del modulo (nessun browser, nessun JS, User-Agent non standard) come traffico bot e risponde con una "Managed Challenge" — che lato modulo si presenta come un 403 a corpo vuoto.

Per confermarlo: nella dashboard Cloudflare, '''Security > Analytics > Events''', filtrare gli ultimi minuti dopo un test recente. Se la voce bloccata mostra '''Service = "Bot fight mode"''' e '''Action = "Managed Challenge"''', si tratta di questo caso.

Nel piano gratuito, questo Bot Fight Mode '''non può essere aggirato in modo selettivo per percorso URL'''. L'unica opzione è disattivare l'interruttore '''globalmente''': '''Security > Settings > "Bot fight mode"''' → Off durante l'esecuzione degli script di importazione, per poi riattivarlo se necessario.

Su un piano Cloudflare a pagamento (Pro e superiori), Super Bot Fight Mode consente un bypass più mirato tramite una regola di sicurezza "Skip" per <code>/api*</code>.

==Utilizzo==

[[File:psimport_admin.png|center|thumb|800px|Gestione delle importazioni]]

===Ordine di esecuzione===

<pre>
# 1. Categorie
php scripts/fetch-categories.php https://www.yourshop.com/api ABCDEF... 0 0
php scripts/import-categories.php 0

# 2. Clienti + indirizzi
php scripts/fetch-customers.php https://www.yourshop.com/api ABCDEF... 0 0
php scripts/import-customers.php 0

# 3. Prodotti (IVA risolta tramite tax_rules_groups, immagine di copertina scaricata)
php scripts/fetch-products.php https://www.yourshop.com/api ABCDEF... 0 0
php scripts/import-products.php https://www.yourshop.com/api ABCDEF... 0

# 4. File scaricabili dei moduli (richiede il modulo PrestaShop "Psimport Bridge")
php scripts/fetch-product-files.php https://www.yourshop.com/api ABCDEF... 0 0
php scripts/import-product-files.php https://www.yourshop.com/api ABCDEF... 0

# 4b. Galleria completa delle immagini prodotto
php scripts/fetch-product-images.php https://www.yourshop.com/api ABCDEF... 0 0
php scripts/import-product-images.php https://www.yourshop.com/api ABCDEF... 0

# 5. Ordini (configurare $importable_state_ids e $payment_module_map all'inizio dello script prima della prima esecuzione)
php scripts/fetch-orders.php https://www.yourshop.com/api ABCDEF... 0 0
php scripts/import-orders.php 0
</pre>

Parametri comuni:

*<code>limit</code> = 0 per recuperare/importare tutto, o un numero per testare su un campione
*<code>clean_all_before_fetch</code> = 1 per svuotare la tabella di appoggio prima di un nuovo recupero (default 0 = accumula/aggiorna)

===Ripetere un'importazione dopo la correzione degli errori===

Ogni tabella di appoggio ha una colonna <code>import_status</code>:

*<code>0</code> = da importare
*<code>1</code> = importato correttamente (<code>fk_dolibarr</code> contiene l'id dell'oggetto creato in Dolibarr)
*<code>2</code> = in errore (dettagli in <code>import_error</code>)

Per rielaborare solo le righe in errore dopo averle corrette, usare il pulsante "Reimposta errori" nella scheda di gestione importazione, oppure:

<pre>
UPDATE llx_psimport_product SET import_status = 0 WHERE import_status = 2;
</pre>

quindi rieseguire lo script di importazione corrispondente.

===File scaricabili dei moduli===

L'API Webservice di PrestaShop '''non espone''' i file dei "prodotti virtuali/scaricabili" (confermato dal ticket ufficiale GitHub PrestaShop/PrestaShop#27834 e da diversi thread del forum PrestaShop). Questo viene aggirato da un modulo "bridge" per PrestaShop installato una tantum sul negozio.

'''Consigliato: modulo Psimport Bridge''' (un clic, come ogni altra importazione):

#Installare il modulo fornito in <code>bridge/psimportbridge/</code> sul negozio PrestaShop (caricare lo zip dal back office, oppure copiarlo via FTP/SFTP in <code>modules/</code> e installarlo)
#Nessuna configurazione aggiuntiva necessaria: riutilizza la stessa chiave API del Webservice già impostata (<code>PSIMPORT_API_KEY</code>)
#Nella scheda '''Gestione importazione''', usare i pulsanti '''↓ Recupera''' e '''→ Importa''' sulla riga "File prodotto", esattamente come per ogni altra risorsa
#Una volta completata la migrazione, il modulo può essere disinstallato senza rischi (sola lettura, nessuna scrittura su database o disco lato PrestaShop)

Questo modulo consente di scaricare solo i file già referenziati in <code>ps_product_download</code> (protegge da letture di file arbitrarie).

'''Alternativa''' (se il modulo bridge non può essere installato): un'esportazione CSV manuale di <code>ps_product_download</code> da phpMyAdmin/Adminer, insieme a una copia locale della cartella <code>download/</code> di PrestaShop, quindi <code>php scripts/import-product-files.php /path/to/export.csv /path/to/download/</code>.

===Galleria completa delle immagini prodotto===

<code>fetch-product-images.php</code> / <code>import-product-images.php</code> recuperano '''tutte''' le immagini di ogni prodotto PrestaShop (non solo la copertina), tramite il sub-endpoint Webservice <code>products/{id}/images</code>, in una tabella di appoggio dedicata <code>llx_psimport_productimage</code>.

Punti da verificare alla prima esecuzione:

*La posizione di ogni immagine nella galleria Dolibarr deriva dall'ordine restituito dall'API — verificare visivamente l'ordine dopo l'importazione e riordinare manualmente se necessario
*Per evitare di mostrare due volte la stessa immagine (copertina + galleria), i duplicati esatti vengono rilevati e ignorati silenziosamente
*La forma esatta della risposta JSON può variare a seconda della versione di PrestaShop: testare prima con <code>limit=5</code> su un campione

===Controlli dopo ogni fase===

#Verificare il contenuto delle tabelle <code>llx_psimport_*</code> (coerenza dei dati, IVA correttamente risolta)
#Nell'interfaccia Dolibarr, verificare: albero delle categorie, schede terzi (indirizzo, contatto), schede prodotto (prezzo netto/lordo, IVA, immagine, file allegato), ordini (righe, totali, stato)
#Confrontare i conteggi (numero di categorie/clienti/prodotti/ordini) tra PrestaShop, la tabella di appoggio e Dolibarr

==FAQ==

===Ho bisogno dell'accesso diretto al database MySQL di PrestaShop?===
No. L'intera migrazione passa attraverso l'API REST Webservice di PrestaShop, salvo un passaggio opzionale e una tantum (esportazione CSV manuale) se il modulo bridge non può essere installato per i file scaricabili.

===Quali versioni di PrestaShop sono compatibili?===
Da PrestaShop 1.6 a 9.x, tramite l'API Webservice standard. Il modulo bridge (lato PrestaShop) dichiara esso stesso questo intervallo di compatibilità.

===Cosa fare se l'importazione di una risorsa fallisce parzialmente?===
Correggere i dati sottostanti (nella tabella di appoggio o lato PrestaShop), riportare le righe in errore a <code>import_status = 0</code> (pulsante "Reimposta errori" o una query SQL), quindi rieseguire solo lo script di importazione corrispondente.

===Il test di connessione fallisce con un 403 anche se l'URL funziona nel browser===
Vedere la sezione [[#Risoluzione problemi: HTTP 403 sull'API (hosting dietro Cloudflare)|Risoluzione problemi HTTP 403]]: di solito si tratta di un firewall applicativo (Cloudflare Bot Fight Mode) che blocca le chiamate cURL, non di PrestaShop stesso.

===Il modulo Psimport Bridge modifica i dati su PrestaShop?===
No, è di sola lettura: nessuna scrittura su database o disco lato PrestaShop, e consente solo di scaricare file già referenziati in <code>ps_product_download</code>.

==Vedi anche==

*[https://www.atoo-net.com Atoo-Net — Editore del modulo]
*[https://framagit.org/grandoc/psimport Repository del modulo]
*[https://wiki.dolibarr.org/index.php/Module_UltimateMarketPlace_EN Module UltimateMarketPlace]

==Altre lingue==

* [[Module_psimport_FR|Documentation en français du module psimport]]
* [[Module_psimport_EN|English documentation for the psimport module]]
* [[Module_psimport_DE|Deutsche Dokumentation für das Modul psimport]]
* [[Module_psimport_ES|Documentación en español del módulo psimport]]

[[fr:Module_psimport_FR]]
[[en:Module_psimport_EN]]
[[de:Module_psimport_DE]]
[[es:Module_psimport_ES]]

Module psimport IT - Revision history

Grandoc: Created page with "Category:Modules Category:AtooNet =Modulo psimport= ==Presentazione== '''psimport''' è un modulo per Dolibarr ERP/CRM pubblicato da [https://www.atoo-net.com Atoo-..."