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. L'attributo Warehouse è presente solo se l'utente sta gestendo più magazzini ed in tal caso è specificato il magazzino che si sta aggiornando.
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="full" Warehouse="Negozio">
<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>
<Product>
<InternalID>16</InternalID>
<Code>0016</Code>
<Description>Armadio Alto funzionalità a giorno</Description>
<Category>Complementi d'arredo</Category>
<Subcategory>Mobile</Subcategory>
<Vat Perc="21" Class="Imponibile" Description="Aliquota 21%">21</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>
|
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 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. |
|
Subcategory2...9 |
Ulteriori sotto-livelli di categoria (in Easyfatt vanno inseriti nel campo della sottocategoria, specificando i nuovi livelli con ">>", ad esempio: "Auto Italiane >> A gasolio >> Trazione integrale"). |
|
Vat |
Codice IVA. Il codice è accompagnato dalle seguenti proprietà, il cui uso è facoltativo: |
|
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. |
|
CustomField4 |
Campo libero 4. |
|
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]. Usare questi campi quando il sito web mostra prezzi al netto d'Iva. |
|
GrossPrice1 ... 9 |
Prezzo ivato listino 1...9 [Valuta]. Usare questi campi quando il sito web mostra prezzi comprensivi di Iva. |
|
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]. |
| SupplierNotes |
Note del fornitore. |
|
Magazzino: |
|
|
ManageWarehouse |
Gestione magazzino abilitata [true|false]. |
|
WarehouseLocation |
Ubicazione. |
|
OrderWaitDays |
Giorni di riordino [Numerico]. |
|
OrderStep |
Multipli (qtà) di riordino [Numerico]. |
|
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.
Per i prodotti gestiti con taglie e colori (tipico del settore dell'abbigliamento o delle calzature), per ciascun <Product> vengono specificate le informazioni sulle singole varianti (<Variant>) all'interno della sezione <Variants>:
<Product>
[...]
<Variants>
<Variant>
<Size>M</Size>
<Color>Blu</Color>
<Barcode>0042/M/Blu</Barcode>
<AvailableQty>23</AvailableQty>
</Variant>
<Variant>
<Size>M</Size>
<Color>Rosso</Color>
<Barcode>0042/M/Rosso</Barcode>
<AvailableQty>14</AvailableQty>
</Variant>
<Variant>
[...]
</Variant>
</Variants>
[...]
</Product>
Campi della sezione <Variant>:
|
Size |
Taglia. |
|
Color |
Colore. |
|
Barcode |
Codice a barre. |
|
AvailableQty |
Quantità disponibile. |
Quando un prodotto ha codici a barre aggiuntivi, all'interno di ciascun <Product> va creata la sezione <ExtraBarcodes> contenente l'elenco di codici:
<Product>
[...]
<ExtraBarcodes>
<Barcode>90273782</Barcode>
<Barcode PackageQty="12">XY981</Barcode>
<Barcode PackageQty="24">XY982</Barcode>
</ExtraBarcodes>
[...]
</Product>
Campi della sezione <ExtraBarcodes>:
|
Barcode |
Codice a barre aggiuntivo, in formato alfanumerico. Quando il codice a barre è riferito ad una confezione con più pezzi, indicare la quantità tramite la proprietà PackageQty. |
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:
if (move_uploaded_file ($_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.
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:
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).