Mon Ami 3000 - Guida integrazione per altri siti e-commerce

Guida integrazione per altri siti e-commerce

Questa integrazione consente di scambiare dati tra Mon Ami 3000 e i propri siti e-commerce (shopify, magento, etc.).

Per i siti realizzati con PrestaShop e WooCommerce sono disponibili anche dei plugin già pronti per i quali è possibile consultare le relative guide.

Per consultare la guida del plugin PrestaShop clicca qui.

Per consultare la guida del plugin WooCommerce clicca qui.

In particolare è possibile inviare gli articoli, le relative immagini e le quantità e ricevere ordini e clienti.

Se lo si desidera è possibile anche sincronizzare Mon Ami 3000 con il proprio e-commerce ad intervalli regolari.

Scambio dati

Lo scambio dati può avvenire in HTTP, in FTP o tramite cartella locale, sempre in formato xml.

Per poter effettuare lo scambio sarà necessario predisporre 3 diversi script che dovranno occuparsi del caricamento sul sito e-commerce di articoli e immagini ricevuti da Mon Ami 3000 e di inviare a Mon Ami 3000 i nuovi ordini acquisiti.

I tracciati dei file xml di articoli e ordini sono riportati al termine della guida. Le immagini sono caricate con un POST classico per l’invio delle immagini da form.

Creare un profilo di sincronizzazione

Accedere alla Configurazione tramite il pulsante Impostazioni presente nella barra dei menù che si trova in alto.

Abilitare l'opzione E-Commerce, premere il pulsante Configura che si trova alla sua destra e, nella schermata che appare, cliccare sul pulsante Aggiungi.
Compilare la descrizione del sito.
Selezionare come tipo di piattaforma Personalizzata.
Abilitare questa opzione per inviare gli articoli al sito e-commerce.
Selezionare il listino di riferimento per gli articoli da inviare; saranno inviati solo gli articoli appartenenti a tale listino. Selezionando Tutti saranno esportati gli articoli associati a qualsiasi listino con tutti i relativi prezzi.
Selezionare il magazzino di riferimento per gli articoli da inviare; saranno inviati solo gli articoli appartenenti a tale magazzino.
La selezione è disponibile solo se si gestiscono più magazzini. Non è necessario creare un magazzino specifico per il sito e-commerce.
Selezionare il tipo di accesso ai dati per l’invio degli articoli fra HTTP, FTP o File e compilare i parametri richiesti in base alla scelta effettuata (*). In questo caso abbiamo scelto HTTP.
Selezionare il tipo di accesso ai dati per l’invio delle immagini fra HTTP, FTP o File e compilare i parametri richiesti in base alla scelta effettuata (*). In questo caso abbiamo scelto FTP.
Abilitare questa opzione per ricevere gli ordini dal sito e-commerce.
Selezionare il tipo di accesso ai dati per la ricezione degli ordini fra HTTP, FTP o File e compilare i parametri richiesti in base alla scelta effettuata (*). In questo caso abbiamo scelto HTTP.
Abilitando questa opzione il sito e-commerce sarà sincronizzato in background ad intervalli regolari.

(*)

HTTP: inserire gli indirizzi http degli script di gestione e compilare “Nome utente” e “Password” per l’autenticazione.

FTP: inserire gli indirizzi FTP degli script di gestione e compilare “Nome utente” e “Password” per l’accesso.

File: inserire i percorsi degli script di gestione (contenuti in una cartella nel pc stesso o condivisa all’interno della rete locale LAN).

Associare gli articoli al sito e-commerce

Perché gli articoli possano essere inviati al sito e-commerce è necessario associarli a esso. Per farlo, accedere all'elenco degli articoli tramite il pulsante Articoli presente nella barra dei menù che si trova in alto.

Selezionare gli articoli da associare al Sito e-commerce.
Premere il pulsante Variazione di gruppo.
Abilitare la variazione relativa al Sito e-commerce.
Dal menu a tendina selezionare il Sito e-commerce.
Selezionare Aggiungi.
Premere Conferma.

Inviare e ricevere i dati

Accedere alla gestione dei Siti e-commerce tramite il pulsante Avanzate presente nella barra dei menù che si trova in alto.

Inviare articoli e immagini

Selezionare il sito e-commerce (è possibile selezionare più siti) al quale inviare gli articoli e le immagini.
Selezionare l’operazione da eseguire (la prima volta eseguire un Invio completo).
1. Invio aggiornamenti articoli Mon Ami 3000 esegue l'invio dei soli dati inseriti e/o modificati dall'ultimo invio.
2. Invio completo articoli Mon Ami 3000 esegue l'invio completo dei dati impostati nel profilo

Saranno chiamati in sequenza gli script invio_articoli.php e invio_immagini.php che dovranno restituire OK in caso di operazione eseguita con successo, Error in caso contrario.

Ricevere gli ordini

Selezionare il sito e-commerce (è possibile selezionare più siti) dal quale ricevere gli ordini.
Premere Ricezione ordini.

Eventuali ordini già acquisiti non saranno reimportati.

Esempi di script in php

invio_articoli.php

<?php
	$file = UPLOAD_DIR . "articoli.xml";
	if(move_uploaded_file ($_FILES['file']['tmp_name'], $file)){
		$xml = simplexml_load_file($file); // $xml conterrà il file XML degli articoli
		[Codice per caricare l’articolo nel database del sito e-commerce]
		echo 'OK';
	} else {
		echo "Error";
	}
?>

invio_immagini.php

<?php
	$imgName = basename($_FILES['file']['name']);
	$file = UPLOAD_DIR . "immagini\\" . $imgName;
	if(move_uploaded_file ($_FILES['file']['tmp_name'], $file)){
		[Codice per collegare l’immagine al relativo articolo sul sito e-commerce]
		echo "OK";
	} else {
		echo "Error";
	}
?>

ricezione_ordini.php

 <?php
 Header('Content-type: text/xml'
 [echo del XML ordini creato secondo la struttura riportata più avanti]
 ?>

File XML articoli

Il file XML contiene una serie di elementi Articolo strutturati come riportato di seguito.

L’attributo Type assume il valore full nel caso di invio completo e update nel caso di aggiornamento. Se lo script invio articoli.php riceve il flusso di articoli con il Type impostato a full dovrà occuparsi anche dell’eliminazione dal sito e-commerce degli articoli a esso non inviati.

La sezione Varianti è compilata solo nel caso l’articolo possieda varianti (nel caso in esempio taglie e colori).

<?xml version="1.0" encoding="UTF-8"?>
<MonAmi3000 Version="1.0" URL="https://www.monami3000.it" Type="update">
	<Articoli>
		<Articolo>
			<Codice>BRN.01</Codice>
			<Descrizione>Borsa notebook</Descrizione>
			<DescrizioneSintetica>Borsa notebook con tracolla</DescrizioneSintetica>
			<SchedaTecnica>Borsa notebook in tessuto con tracolla e tasca</SchedaTecnica>
			<Categoria>Accessori notebook</Categoria>
			<CodiceIVA>I22</CodiceIVA>
			<AliquotaIVA>22</AliquotaIVA>
			<DescrizioneIVA>Imponibile 22%</DescrizioneIVA>
			<UnitaMisura>PZ</UnitaMisura>
			<CampoPersonalizzato1></CampoPersonalizzato1>
			<CampoPersonalizzato2></CampoPersonalizzato2>						
			<CampoPersonalizzato3></CampoPersonalizzato3>						
			<CampoPersonalizzato4></CampoPersonalizzato4>
			<CodiceArticoloProduttore>BRS M1</CodiceArticoloProduttore>												
			<CodiceEAN>9900000001230</CodiceEAN>
			<NomeImmagine>borsanera.jpg</NomeImmagine>
			<Larghezza>0</Larghezza>
			<Altezza>0</Altezza>
			<Profondita>0</Profondita>
			<PesoNetto>0</PesoNetto>
			<PesoLordo>0</PesoLordo>
			<UnitaMisuraPeso>KG</UnitaMisuraPeso>
			<Listini>
				<Listino>
					<Descrizione>Listino small web</Descrizione>
					<PrezzoLordo>15</PrezzoLordo>
					<Sconto1>10</Sconto1>
					<Sconto2>0</Sconto2>
					<Sconto3>0</Sconto3>
					<Sconto4>0</Sconto4>
					<Sconto5>0</Sconto5>
					<Prezzo>13.5</Prezzo>
					<DescrizionePromo>Sconto 10%</DescrizionePromo>
					<PrezzoIVAInclusa>false</PrezzoIVAInclusa>
					<QtaMinima>1</QtaMinima>
					<QtaMultipla>false</QtaMultipla>
				</Listino>
				[...altri listini...]
			</Listini>
			<QtaDisponibile>0</QtaDisponibile>
			<QtaInArrivo>0</QtaInArrivo>
			<Varianti>
				<Variante>
					<Codice>BRN.01-S.BK</Codice>
					<Taglia>Piccola</Taglia>
					<Colore>Nero</Colore>
					<Descrizione>Borsa notebook Piccola Nero</Descrizione>
					<DescrizioneSintetica>Borsa notebook nera con tracolla</DescrizioneSintetica>
					<SchedaTecnica>Borsa in tessuto nero con tracolla e tasca</SchedaTecnica>
					<CampoPersonalizzato1></CampoPersonalizzato1>
					<CampoPersonalizzato2></CampoPersonalizzato2>
					<CampoPersonalizzato3></CampoPersonalizzato3>
					<CampoPersonalizzato4></CampoPersonalizzato4>
					<CodiceArticoloProduttore>BRS M1-BS</CodiceArticoloProduttore>
					<CodiceEAN>9990000000612</CodiceEAN>
					<NomeImmagine>borsa-piccola-nera.jpg</NomeImmagine>
					<Larghezza>0</Larghezza>
					<Altezza>0</Altezza>
					<Profondita>0</Profondita>
					<PesoNetto>0</PesoNetto>
					<PesoLordo>0</PesoLordo>
					<UnitaMisuraPeso>KG</UnitaMisuraPeso>
					<Listini>
						<Listino>
							<Descrizione>Listino small web</Descrizione>
							<PrezzoLordo>10</PrezzoLordo>
							<Sconto1>10</Sconto1>
							<Sconto2>0</Sconto2>
							<Sconto3>0</Sconto3>
							<Sconto4>0</Sconto4>
							<Sconto5>0</Sconto5>
							<Prezzo>9</Prezzo>
							<DescrizionePromo>Sconto 10%</DescrizionePromo>
							<PrezzoIVAInclusa>false</PrezzoIVAInclusa>
							<QtaMinima>1</QtaMinima>
							<QtaMultipla>false</QtaMultipla>
						</Listino>
						[...altri listini...]
					</Listini>
					<QtaDisponibile>10</QtaDisponibile>
					<QtaInArrivo>0</QtaInArrivo>
				</Variante>
				[...altre varianti...]
			</Varianti>
		</Articolo>
		[...altri articoli...]
	</Articoli>
</MonAmi3000>

File XML ordini

<?xml version="1.0" encoding="UTF-8"?>
<MonAmi3000 Version="1.0" URL="https://www.monami3000.it">
	<Documenti>
		<Documento>
			<Tipo>Ordini e-commerce</Tipo>
			<Numero>000015</Numero>
			<Data>15/12/2019</Data>
			<Riferimento>Ordine e-commerce: ABC1234</Riferimento>
			<Controparte>
				<Denominazione>Cliente DEMO</Denominazione>
				<Indirizzo>via demo, 1</Indirizzo>
				<CAP>40126</CAP>
				<Citta>Bologna</Citta>
				<Provincia>BO</Provincia>
				<Paese>Italia</Paese>
				<Codice>demo@demo.it</Codice>
				<PartitaIVA>IT12345678901</PartitaIVA>
				<CodiceFiscale>12345678901</CodiceFiscale>
				<RecapitoFE>ABCDEFG</RecapitoFE>
				<EMail>
				<a href="mailto:demo@demo.it%3c/EMail">demo@demo.it</EMail</a>>
				<EMailPEC>
				<a href="mailto:demo@pec.it%3c/EMail">demo@pec.it</EMail</a>PEC>
				<Referente>Mario Rossi</Fax>
				<Telefono>999 1234567</Telefono>
				<Cellulare>888 1234567</Cellulare>
				<Fax>999 1234568</Fax>
			</Controparte>
			<Destinazione>IDEM</Destinazione>
			<Valuta>EUR</Valuta>
			<Pagamento>Rimessa diretta</Pagamento>
			<Magazzino>Magazzino principale</Magazzino>
			<Listino>Listino generale</Listino>
			<PrezziIVAInclusa>true</PrezziIVAInclusa>
			<Agente>Agente 1</Agente>
			<Righe>
				<Riga>
					<Tipo>Articolo</Tipo>
					<CodiceArticolo>NB.002-CWB</CodiceArticolo>
					<DescrizioneRiga>Sony VAIO - Serie CW - Mod. B</DescrizioneRiga>
					<Quantita>2</Quantita>
					<UnitaMisura>PZ</UnitaMisura>
					<Prezzo>960</Prezzo>
					<Sconto1>10</Sconto1>
					<Sconto2>0</Sconto2>
					<Sconto3>0</Sconto3>
					<Sconto4>0</Sconto4>
					<Sconto5>0</Sconto5>
					<CodiceIVA>I22</CodiceIVA>
					<Conto>400605</Conto>
				</Riga>
				[&hellip;altre righe&hellip;]
			</Righe>
			<Trasporto>
				<Mezzo>Cedente</Mezzo>
			</Trasporto>
			<SpeseTrasporto>
				<Importo>12.1</Importo>
				<CodiceIVA>I22</CodiceIVA>
			</SpeseTrasporto>
			<ScontoAggiuntivo>
				<Importo>226</Importo>
				<CodiceIVA>I22</CodiceIVA>
			</ScontoAggiuntivo>
			<Note>Spedizione: PaccoCelere 3</Note>
			<TS>20130117105714</TS>
		</Documento>
		[&hellip;altri documenti&hellip;]
	</Documenti>
</MonAmi3000>

Alcuni campi particolari del file XML ordini

Sezione Documento

Tipo	Dovrà corrispondere alla descrizione del tipo di documento di Mon Ami 3000 sul quale importare gli ordini
Numero	È il numero che il documento assumerà in Mon Ami 3000. Il numero sarà utilizzato per evitare che l’ordine venga importato più volte per errore.
Destinazione	Dovrà essere una stringa unica con eventuali ritorni a capo.

Per questa sezione sono obbligatori i campi: Tipo, Data e Numero

Sezione Controparte

Codice	È buona norma compilare il campo Codice con l’identificativo web del cliente; ad esempio, se il cliente si registra con l’indirizzo e-mail consigliamo di compilare il campo con tale indirizzo.
CodiceFiscale PartitaIVADenominazione	Nel caso in cui il campo Codice non sia stato compilato, questi tre campi saranno utilizzati anche per capire se il cliente è già presente nell’anagrafica di Mon Ami 3000; in caso affermativo non sarà creato un nuovo cliente ma, se gli altri dati della controparte sono differenti, sarà creata una variante dell’anagrafica del cliente. I campi vengono verificati nell’ordine: CodiceFiscale, PartitaIVA, Denominazione; se il primo è vuoto si passa al successivo fino a trovarne uno compilato. Se si compila il Codice Fiscale e la Partita IVA è vuota il cliente sarà impostato automaticamente come privato.
Cognome e Nome	Se si tratta di un privato i campi Cognome e Nome devono essere utilizzati in alternativa alla Denominazione.

Per questa sezione sono obbligatori i campi: Denominazione (o Cognome e Nome nel caso di privati)

Guide pratiche