Trasmissione catalogo prodotti

La trasmissione avviene tramite l'invio al sito di e-commerce di un file XML contenente l'elenco dei prodotti con relative descrizioni.

Suggerimento: per verificare i tracciati prodotti, tramite Easyfatt (anche in versione dimostrativa), è possibile esportare gli articoli nel formato XML di seguito descritto. Per farlo è sufficiente accedere al menu Strumenti->E-Commerce->Aggiorna articoli e premere Salva su file.

Struttura del file invio catalogo prodotti XML

Il file XML e' una sequenza di oggetti Product all'interno delle liste Products oppure UpdateProducts e DeletedProducts, descritti nel dettaglio in seguito. L'attributo AppVersion indica la versione del protocollo usato.

Quando l'invio è completo (ovvero vengono trasmessi tutti i prodotti), verrà usata esclusivamente la lista Products e l'attributo Mode dovrà essere valorizzato a full. Trasmissioni complete vengono fatte anche da versioni di Easyfatt che non supportano il protocollo 2, in questo caso l'attributo Mode sarà assente. Esempio:

<?xml version="1.0" encoding="UTF-8"?>
<EasyfattProducts AppVersion="2" Mode="ful">
<Products>
    <Product>
      [...]
    </Product>
    <Product>
      [...]
    </Product>
    [...]
</Products>
</EasyfattProducts>

Quando viene ricevuto un flusso in modalità full, è importante provvedere ad eliminare tutti i prodotti presenti nel database del sito ed assenti nella trasmissione. E' altresì importante che rimanga sempre possibile eseguire un invio COMPLETO dei prodotti senza rischiare di perdere eventuali informazioni aggiuntive inserite nel catalogo prodotti on-line: se su alcuni prodotti sono stata compilate delle informazioni direttamente dal sito e-commerce perche' non disponibili in Easyfatt (ad esempio promozioni, foto delle categorie, garanzia, o altro...), è fondamentale che queste informazioni aggiuntive non vengano perse anche in caso di un invio completo di tutti i prodotti.

Quando l'invio è incrementale (vengono trasmessi solo i nuovi prodotti e quelli modificati o cancellati dall'ultima trasmissione), verranno usate le liste UpdateProducts (per i prodotti da aggiungere o aggiornare) e DeletedProducts (per quelli da eliminare). In questa modalità, l'attributo Mode è impostato su incremental. Esempio:

<?xml version="1.0" encoding="UTF-8"?>
<EasyfattProducts AppVersion="2" Mode="incremental">
<UpdatedProducts>
    <Product>
      [...]
    </Product>
    <Product>
      [...]
    </Product>
    [...]
</UpdatedProducts>
<DeletedProducts>
    <Product>
      [...]
    </Product>
    <Product>
      [...]
    </Product>
    [...]
</DeletedProducts>
</EasyfattProducts>

Esempio

<Product>
<InternalID>16</InternalID>
<Code>0016</Code>
<Description>Armadio Alto funzionalità a giorno</Description>
<Category>Complementi d'arredo</Category>
<Subcategory>Mobile</Subcategory>
<Vat>20</Vat>
<Um>pz</Um>
<NetPrice1>105</NetPrice1>
<NetPrice2>85</NetPrice2>
<GrossPrice1>126</GrossPrice1>
<GrossPrice2>102</GrossPrice2>
<Barcode>AR</Barcode>
<SupplierCode>0054</SupplierCode>
<SupplierName>Il Mio Ufficio</SupplierName>
<SupplierProductCode>52-715-7845</SupplierProductCode>
<SupplierNetPrice>63</SupplierNetPrice>
<SupplierGrossPrice>75.6</SupplierGrossPrice>
<ProducerName>WoodThings</ProducerName>
<WarehouseLocation>Magazzino1</WarehouseLocation>
<Link>http://www.arredamenti.it/catalog?cod=52-715-7845</Link>
<SizeUm>cm</SizeUm>
<NetSizeX>90</NetSizeX>
<NetSizeY>133</NetSizeY>
<NetSizeZ>45</NetSizeZ>
<PackingSizeX>112.5</PackingSizeX>
<PackingSizeY>145</PackingSizeY>
<PackingSizeZ>50.7</PackingSizeZ>
<WeightUm>kg</WeightUm>
<NetWeight>4.5</NetWeight>
<GrossWeight>6</GrossWeight>
<ManageWarehouse>true</ManageWarehouse>
<MinStock>2</MinStock>
<AvailableQty>1</AvailableQty>
<OrderedQty>2</OrderedQty>
<CustomField2>5 Anni</CustomField2>
<CustomField3>Media</CustomField3>
<Notes>Versione di colore: Grigio, Acero, Struttura acero e profili in PVC color Grigio.</Notes>
<ImageFileName>15447.jpg</ImageFileName>
</Product>

Campi della sezione <Product>

InternalID	ID interno dell'applicazione.
Code	Codice prodotto (campo obbligatorio).
Barcode	Codice a barre (se diverso dal codice articolo).
Description	Descrizione prodotto in testo semplice.
DescriptionHTML	Descrizione prodotto in formato HTML - Sono supportati i seguenti tag: p, br, a, b, i, u, ul, li, span - Sono supportati gli attributi di colore e allineamento del testo - Sono disponibili 4 classi di stile denominate: ef-titolo1, ef-titolo2, ef-titolo3, ef-titolo4 Per ciascun prodotto viene sempre compilato il tag <Description>, mentre il tag <DescriptionHTML> è opzionale (l'utente può scegliere se compilarlo o meno). Se il sito di e-commerce supporta il testo descrittivo in formato HTML, si dovrà quindi tenere conto di questo fattore.
Category	Categoria.
Subcategory	Sottocategoria.
Vat	Codice IVA.
Um	Unità di misura.
ProducerName	Nome del produttore .
Link	Link a file o pagina web con informazioni relative al prodotto.
CustomField1	Campo libero 1.
CustomField2	Campo libero 2.
CustomField3	Campo libero 3.
Notes	Note.
ImageFileName	Nome dell'immagine associata al prodotto. Questo tag potrebbe essere ripetuto, in presenza di più immagini sullo stesso prodotto (funzione non ancora presente in Easyfatt). L'intero percorso locale della cartella delle immagini è ricavabile dalla proprietà ImageFolder associata all'oggetto EasyfattProducts.
Prezzi:
NetPrice1 ... 9	Prezzo netto listino 1...9 [Valuta].
GrossPrice1 ... 9	Prezzo ivato listino 1...9 [Valuta].
NetEcoFee	Importo netto Iva dell'eco-contributo [Valuta].
GrossEcoFee	Importo ivato dell'eco-contributo [Valuta].
Fornitore:
SupplierCode	Codice del fornitore.
SupplierName	Nome del fornitore.
SupplierProductCode	Codice articolo per il fornitore.
SupplierNetPrice	Prezzo netto d'acquisto [Valuta].
SupplierGrossPrice	Prezzo ivato d'acquisto [Valuta].
Magazzino:
ManageWarehouse	Gestione magazzino abilitata [true\|false].
WarehouseLocation	Ubicazione.
MinStock	Scorta minima [Numerico].
AvailableQty	Quantità disponibile [Numerico].
OrderedQty	Quantità ordinata ed in arrivo [Numerico].
Dimensioni:
SizeUm	Unità di misura delle dimensioni.
NetSizeX	Larghezza prodotto [Numerico].
NetSizeY	Altezza prodotto [Numerico].
NetSizeZ	Profondità prodotto [Numerico].
PackingSizeX	Larghezza imballo [Numerico].
PackingSizeY	Altezza imballo [Numerico].
PackingSizeZ	Profondità imballo [Numerico].
WeightUm	Unità di misura peso [Numerico].
NetWeight	Peso del prodotto [Numerico].
GrossWeight	Peso del prodotto imballato [Numerico].

Nota: nelle liste DeletedProducts, l'oggetto Product conterrà esclusivamente il campo <Code>, necessario per identificare ed eliminare il prodotto dal database.

Taglie e colori

Per i prodotti gestiti con taglie e colori (tipico del settore dell'abbigliamento o delle calzature), all'interno di ciascun <Product> vengono specificate le informazioni sulle singole varianti (<Variant>):

<Product>
[...]
   <Variant>
      <Size>M</Size>
      <Color>Blu</Color>
      <AvailableQty>23</AvailableQty>
   </Variant>
   <Variant>
      <Size>M</Size>
      <Color>Rosso</Color>
      <AvailableQty>14</AvailableQty>
   </Variant>
   <Variant>
      [...]
   </Variant>
[...]
</Product>

Campi della sezione <Variant>:

Size	Taglia.
Color	Colore.
AvailableQty	Quantità disponibile (viene omesso quando quantità=0).

Protocollo trasmissione file catalogo prodotti XML

Il file XML viene trasmesso con un POST HTTP alla URL indicata nella linguetta Impostazioni della funzione di aggiornamento articoli del programma. Se lo script che riceve il file è posizionato in una cartella del webserver ad accesso limitato (ad esempio la cartella "admin" di os-commerce), è possibile specificare, sempre nelle Impostazioni, la Login e la Password di accesso.

Il file viene trasmesso con Content-type "multipart/form-data", come se venisse inviato un parametro "file" da un form HTML.

Di seguito un esempio minimale di script PHP per ricevere il file:

admin/uploadarticoli.php:

<?php
if (move_uploaded_file ($HTTP_POST_FILES['file']['tmp_name'], "articoli.xml")){
echo "OK";
} else {
echo "Error";
}
?>

Se al termine della trasmissione Easyfatt riceve una risposta diversa da "OK", la mostra all'utente come messaggio di errore.

Essendo decisamente più complessa la procedura in ASP VBScript, è stato creato un apposito esempio da scaricare.

Trasmissione immagini

Nel caso in cui il sito di e-commerce, al termine della ricezione dell'elenco prodotti, desideri ricevere anche le relative immagini, gli sarà necessario aggiungere, successivamente all'OK di risposta, i seguenti parametri:

ImageSendURL=URL
- URL può essere un indirizzo HTTP (es.: http://www.miosito.it/uploadImmagini.php )
- oppure URL può essere un indirizzo FTP (es.: ftp://ftp.miosito.it/folder/immagini ); l'autenticazione FTP sarà eseguita con le stesse login/password usate negli altri contesti, tuttavia l'URL può contenere una diversa login/password, che verrà usata in modo prioritario (es.: ftp://login:password@ftp.miosito.it/folder/immagini ) ... in questo caso attenzione al fatto che la login e la password specificate nella URL dovranno essere codificate opportunamente in presenza di caratteri non consentiti, se ad esempio la login è un indirizzo e-mail, il carattere @ andrà codificato con %40 (maggiori informazioni: escape url characters).
ImageSendFinishURL=URL
questo è un parametro opzionale. Se presente, al termine della trasmissione di tutte le immagini, Easyfatt effettuerà una chiamata alla URL specificata. La URL può essere esclusivamente un indirizzo http (es.: http://www.miosito.it/uploadTerminato.php ), la pagina chiamata dovrà restituire la stringa "OK" per confermare l'avvenuta elaborazione, oppure una stringa di errore da mostrare all'utente.

Importante: questi parametri vanno richiesti solo se il protocollo in uso (AppVersion) è uguale o maggiore a 2. Nel caso in cui vengano specificati sul protocollo precedente, Easyfatt gestirà questa stringa come se si trattasse di un errore nella trasmissione del catalogo prodotti.

Esempio di risposta con richiesta di immagini, senza segnalazione di trasmissione terminata:

OK
ImageSendURL=http://www.miosito.it/immagini/upload.asp

Esempio di risposta con richiesta di immagini, con segnalazione di trasmissione terminata:

OK
ImageSendURL=ftp://ftp.miosito.it/immagini
ImageSendFinishURL=http://www.miosito.it/invio_terminato.asp

E' importante che le diverse righe contenenti OK, ImageSendURL e ImageSendFinishURL siano separate da un carattere di INVIO ("new line").

L'invio delle immagini in modalità HTTP avverrà con un post per ciascun file trasmesso in modalità Content-type "multipart/form-data" contenente due parametri: "file" (il file trasmesso) e "fileName" (il nome del file).