Specifiche tecniche e-commerce con Easyfatt:
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. 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>

Esempio


<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>

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.

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:
- Perc (percentuale di tassazione applicata)
- Class (classe: imponibile, non imponibile, intra-ue, extra-ue, esente, escluso, fuori campo, iva non esposta, rev. charge)
- Description: descrizione libera del 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]. 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 fornitoire.

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.

Taglie e colori

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.

 

Codici a barre aggiuntivi e pezzi per confezione

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.

 

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:


  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.

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).