Specifiche tecniche e-commerce con Easyfatt: ricezione ordini

Risorse utili

Struttura del file

<?xml version="1.0" encoding="UTF-8"?>
<EasyfattDocuments AppVersion="2" Creator="Danea Soft" CreatorUrl="www.danea.it">  
  <Company>
    [...]
  </Company>
  <Documents>
    <Document>
      [...]
      <Rows>
        <Row>
          [...]
        </Row>
        <Row>
          [...]
        </Row>      
      </Rows>
      <Payments>
        <Payment>  
          [...]
        </Payment>
        <Payment>
          [...]
        </Payment>
    </Payments>
  </Document>
  <Document>
    [...]
      <Rows>
        <Row> 
          [...]
        </Row> 
        <Row> 
          [...]
        </Row>   
      </Rows>
      <Payments>
        <Payment>    
          [...]
        </Payment>
        <Payment>
          [...]
        </Payment> 
      </Payments>
    </Document>
  </Documents>
</EasyfattDocuments>

Annotazioni sugli elementi

EasyfattDocuments

L'attributo AppVersion è opzionale, va usato nell'integrazione e-commerce e rappresenta la versione del protocollo usato.
L'attributo Creator è opzionale e riporta informazioni sul software o sul servizio che ha originato il file (nome della software house e/o del programma). L'attributo CreatorUrl, anch'esso ozionale, contiene un eventuale indirizzo web di approfondimento.

EasyfattDocuments.Company

Questo elemento è opzionale e non rilevante per le operazioni di e-commerce.
Contiene i dati identificativi del mittente del file (nome azienda, indirizzo, partita iva, email, etc), da non confondersi con gli intestatari indicati nei successivi documenti.

EasyfattDocuments.Documents

Contiene i sottoelementi Document, ciascuno corrispondente ad un singolo documento (ordine, fattura, ddt, rapporto d'intervento, ...).

EasyfattDocuments.Documents.Document

Ciascun Document contiene i dati di testata del documento

EasyfattDocuments.Documents.Document.Rows

Contiene i sottoelementi Row, ciascuno corrispondente ad una riga del documento.

EasyfattDocuments.Documents.Document.Rows.Row

Ciascun Row contiene i dati di una riga del documento.

EasyfattDocuments.Documents.Document.Payments

Contiene i sottoelementi Payment, ciascuno corrispondente ad una scadenza di pagamento del documento.

EasyfattDocuments.Documents.Document.Payments.Payment

Ciascun Payment rappresenta i singoli pagamenti del documento.

Esempio

<?xml version="1.0" encoding="UTF-8"?>
<EasyfattDocuments AppVersion="2" Creator="Danea Soft" CreatorUrl="www.danea.it">
  <Company>
    <Name>Arredufficio Srl</Name>
    <Address>Via Crissolo, 12</Address>
    <Postcode>10138</Postcode>
    <City>Torino</City>
    <Province>TO</Province>
    <Country>Italia</Country>
    <FiscalCode>01303760282</FiscalCode>
    <VatCode>01303760282</VatCode>
    <Tel>011-2568745</Tel>
    <Fax>011-2548793</Fax>
    <Email>arredufficiosrl@arredufficio.it</Email>
    <HomePage>www.arredufficiosrl.it</HomePage>
  </Company>
  <Documents>
    <Document>
      <DocumentType>C</DocumentType>
      <CustomerCode>0018</CustomerCode>
      <CustomerName>Ceramiche Italiane</CustomerName>
      <CustomerAddress>Via Flaminia, 963</CustomerAddress>
      <CustomerPostcode>06061</CustomerPostcode>
      <CustomerCity>Castiglione Del Lago</CustomerCity>
      <CustomerProvince>PG</CustomerProvince>
      <CustomerCountry>Italia</CustomerCountry>
      <CustomerVatCode>03322350178</CustomerVatCode>
      <CustomerTel>075-26589</CustomerTel>
      <CustomerEmail>italianceramiche@ceramiche.it</CustomerEmail>
      <Date>2010-03-23</Date>
      <Number>2</Number>
      <Total>239.4</Total>
      <PaymentName>Bonifico bancario</PaymentName>
      <PaymentBank>Banca Antoniana Popolare Veneta ag. Torino 5 - abi 5040 cab 42970 c/c 16243/x</PaymentBank>
      <InternalComment>Nessun Acconto</InternalComment>
      <CustomField2>08/04/2010</CustomField2>
      <SalesAgent>Arturo Lupini</SalesAgent>
      <Rows>
        <Row>
          <Code>0043</Code>
          <Description>Appendiabiti su ruote. In robusto metallo verniciato dotato di griglia portascarpe in filo metallico.</Description>
          <Qty>1</Qty>
          <Um>pz</Um>
          <Price>162</Price>
          <Discounts>5%</Discounts>
          <VatCode Perc="20" Class="Imponibile" Description="Aliquota 20%">20</VatCode>
          <Notes>vedi preventivo</Notes>
        </Row>
        <Row>
          <Code>0039</Code>
          <Description>Cestini Gettacarta - Pareti in acciaio laminato nero o acciaio</Description>
          <Qty>3</Qty>
          <Um>pz</Um>
          <Price>16</Price>
          <Discounts>5%</Discounts>
          <VatCode Perc="20" Class="Imponibile" Description="Aliquota 20%">20</VatCode>
          <Notes></Notes>
        </Row>
      </Rows>
      <Payments>
        <Payment>
         <Advance>false</Advance>
         <Date>2010-01-31</Date>
         <Amount>100</Amount>
         <Paid>true</Paid>
        </Payment>
        <Payment>
          <Advance>false</Advance>
          <Date>2010-02-28</Date>
          <Amount>139.4</Amount>
          <Paid>false</Paid>
        </Payment>
      </Payments>
    </Document>
  </Documents>
</EasyfattDocuments>

Campi dell'elemento <Document>

DocumentType	è il codice corrispondente al tipo di documento; se questo tag viene omesso, il documento sarà considerato un ordine cliente. Elenco dei tipi ammessi: A: Avviso di parcella B: Vendita al banco C: Ordine cliente (tipo predefinito) D: Documento di trasporto E: Ordine fornitore F: Fattura accompagnatoria G: Rapporto d'intervento I: Fattura J: Fattura d'acconto L: Fattura pro-forma M: Autofattura N: Nota d'accredito O: Nota d'addebito P: Parcella Q: Preventivo R: Ricevuta fiscale S: Preventivo fornitore H: Arrivi merce fornitore
Date	Data del documento [Data]
Number	Numero documento [Numerico]
Numbering	Numerazione documento ( /a, /b, etc.).
Seguono i campi del'intestatario del documento. Va notato che i campi "Customer" (ovvero ... "Cliente") conterranno invece i dati del fornitore per i documenti di fornitura (ordine cliente, arrivo merce, etc.):
CustomerCode	Codice anagrafica; serve per associare l'ordine all'eventuale cliente già inserito in anagrafica. Durante l'importazione, i presenza di <CustomerCode> e in assenza altri codici <Customer...>, i relativi campi anagrafica del documento saranno riempiti con i dati dell'anagrafica corrispondente a <CustomerCode> e già codificata nell'archivio.
CustomerWebLogin	Login web del cliente (usato nell'integrazione e-commerce); nella fase di identificazione dell'anagrafica, questo campo viene preso in considerazione solo in mancanza di CustomerCode.
CustomerName	Cognome e nome o denominazione sociale.
CustomerAddress	Indirizzo.
CustomerPostcode	CAP.
CustomerCity	Città.
CustomerProvince	Provincia (2 caratteri).
CustomerCountry	Nazione.
CustomerFiscalCode	Codice fiscale.
CustomerVatCode	Partita Iva.
CustomerEInvoiceDestCode	Codice destinatario o PEC per l'invio della fattura elettronica.
CustomerTel	Numero di telefono.
CustomerCellPhone	Numero di cellulare.
CustomerFax	Numero di fax.
CustomerEmail	Indirizzo e-mail.
CustomerPec	Indirizzo PEC.
CustomerReference	Persona di riferimento.
I campi "Delivery", si riferiscono all'indirizzo di consegna o spedizione e vanno specificati se tale indirizzo differisce da quello nei precedenti campi "Customer":
DeliveryName	Nome e cognome o denominazione.
DeliveryAddress	Indirizzo.
DeliveryPostcode	CAP.
DeliveryCity	Città.
DeliveryProvince	Provincia (2 caratteri).
DeliveryCountry	Nazione.
Informazioni sul trasporto:
Carrier	Denominazione vettore.
TransportReason	Causale trasporto.
GoodsAppearance	Aspetto delle merci.
NumOfPieces	Numero colli.
TransportDateTime	Data e ora del trasporto.
ShipmentTerms	Porto (franco, assegnato...).
TransportedWeight	Peso trasportato.
TrackingNumber	Numero di tracciatura spedizione.
Note e commenti:
InternalComment	Commento (nell'e-commerce, usare questo campo per indicare note libere dell'acquirente durante la fase dell'ordine).
CustomField1	Campo note 1.
CustomField2	Campo note 2.
CustomField3	Campo note 3.
CustomField4	Campo note 4.
FootNotes	Note a fine pagina.
Altri campi della testata del documento:
CostDescription	Descrizione spese aggiuntive (ad esempio per spese di trasporto).
CostVatCode	Codice IVA spese aggiuntive (deve essere già presente nella tabella "Categorie Iva" dell'applicazione). 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
CostAmount	Importo spese aggiuntive [Valuta].
TotalWithoutTax	Totale documento al netto dell'imposta IVA [Valuta]. Ignorato in fase di importazione.
VatAmount	Totale Iva calcolata [Valuta]. Ignorato in importazione.
Total	Totale documento [Valuta]. Ignorato in importazione.
PaymentAdvanceAmount	Importo acconto già versato (va usato solo nei documenti che non prevedono l'indicazione dei singoli Payment).
PricesIncludeVat	Se "true" i campi CostAmount e Row.Price vengono considerati importi ivati, altrimenti netti [true\|false].
TotalSubjectToWithholdingTax	Importo totale soggetto a ritenuta d'acconto [Numerico].
WithholdingTaxPerc	Percentuale ritenuta d'acconto applicata [Numerico].
WithholdingTaxPerc2	Seconda percentuale della ritenuta d'acconto (es.: 20% del 50%) [Numerico].
WithholdingTaxAmount	Totale ritenuta d'acconto calcolata nel documento [Valuta]. Ignorato in importazione.
WithholdingTaxAmountB	Totale altre ritenute (es.: Enasarco) [Valuta]. Ignorato in importazione.
WithholdingTaxNameB	Descrizione altre ritenute (es.: "Ritenuta ENASARCO").
ContribDescription	Descrizione contributi previdenziali.
ContribPerc	Percentuale contributi previdenziali.
ContribSubjectToWithholdingTax	Contributi previdenziali soggetti a ritenuta d'acconto [true\|false].
ContribAmount	Ammontare contributi previdenziali. Ignorato in importazione.
ContribVatCode	Aliquota Iva contributi previdenziali. Ignorato in importazione.
DelayedVat	Iva ad esigibilità differita [true\|false].
DelayedVatDesc	Causale Iva ad esigibilità differita.
DelayedVatDueWithinOneYear	Iva ad esigibilità differita comunque dovuta dopo un anno [true\|false].
Warehouse	Denominazione del magazzino usato.
PriceList	Denominazione del listino usato.
PaymentName	Nome pagamento (deve essere già presente nella tabella "Tipi pagamento" di Easyfatt).
PaymentBank	Banca pagamento.
SalesAgent	Nome dell'agente venditore (deve corrispondere ad un nominativo già presente nella tabella degli agenti).
ExpectedConclusionDate	Data prevista conclusione ordine [Data].
DocReference	Causale del documento.
Righe documento e scadenze di pagamento:
Rows	Contiene una sequenza di elementi Row.
Payments	Contiene una sequenza di elementi Payment.
Campi nelle righe del documento (elementi <Row>):
Code	Codice prodotto.
SupplierCode	Codice prodotto del fornitore.
Description	Descrizione prodotto o nota.
Qty	Quantità prodotti [Numerico].
Um	Unità di misura della quantità.
Size	Taglia (usato nel settore dell'abbigliamento).
Color	Colore (usato nel settore dell'abbigliamento).
Lot	Lotto.
ExpiryDate	Data scadenza lotto [Data].
Serial	Codice seriale
Price	Prezzo unitario [Valuta].
Discounts	Sconti (es: "20+5.5%").
EcoFee	Importo dell'eco-contributo unitario associato all'articolo.
VatCode	Codice IVA (deve essere già presente nella tabella "Categorie Iva" dell'applicazione). 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
Total	Importo complessivo della riga [Valuta]. Ignorato in importazione.
WithholdingTax	Ritenuta d'acconto applicata [true\|false].
Stock	Movimentazione magazzino [true\|false].
Notes	Note della riga.
CommissionPerc	Percentuale provvigione agente [Numerico].
Campi nei pagamenti del documento (elementi <Payment>):
Advance	Se "true", segnala che il pagamento è riferito ad un acconto [true\|false].
Date	Data [Data].
Amount	Importo [Valuta].
Paid	Se "true", significa che il pagamento è stato eseguito [true\|false].

Campi dell'elemento <Company>

Name	Nome del mittente (l'azienda che ha originato il file).
Address	Indirizzo.
Postcode	CAP.
City	Città.
Province	Provincia (2 caratteri).
Country	Nazione.
FiscalCode	Codice fiscale.
VatCode	Partita Iva.
Tel	Numero di telefono.
Fax	Numero di fax.
Email	Indirizzo e-mail.
HomePage	Indirizzo sito web.

La gestione dell'anagrafica nell'importazione del documento

Quando Easyfatt importa un documento deve verificare se il nominativo Customer è già presente in archivio o se è un nuovo soggetto; nel primo caso, deve inoltre verificare se i dati anagrafici (indirizzo, telefono...) presenti in archivio sono allineati con quelli dell'ordine scaricato. Questa operazione viene svolta secondo il seguente schema:

se nel documento il campo CustomerCode o CustomerWebLogin è compilato (nota: il campo CustomerWebLogin viene preso in considerazione solo se il campo CustomerCode NON è compilato), allora verifica se esiste già in archivio un nominativo con stesso CustomerCode/CustomerWebLogin:
- se esiste, viene associato al nominativo trovato;
- se esiste, ma indirizzo o altre informazioni del nominativo non corrispondono con quelle presenti in archivio, propone all'operatore di aggiornarle;
- se non esiste, allora verifica se esiste già in archivio un nominativo con stesso Cod. fiscale, Partita Iva, e-mail o PEC:
  - se uno di questi dati coincide, l'ordine viene associato al nominativo trovato;
  - se uno di questi dati coincide, ma indirizzo o altre informazioni del nominativo non corrispondono con quelle presenti in archivio, viene proposto all'operatore di aggiornare queste informazioni;
  - se nessuno di questi dati coincide, viene creato automaticamente un nuovo nominativo (anche nei precedenti due casi è data possibilità all'utente di forzare la creazione di un nuovo nominativo).
se né CustomerCode né CustomerWebLogin sono compilati, allora verifica se esiste già in archivio un nominativo con stesso Cod. fiscale, Partita Iva o e-mail:
- se esiste, viene associato al nominativo trovato;
- se non esiste viene creato automaticamente un nuovo nominativo.

Nota: nella procedura di importazione di un file Easyfatt-Xml viene data la possibilità di ignorare completamente la presenza del CustomerCode. Tale possibilità può essere utile quando il trasferimento dei documenti avviene tra soggetti diversi, che preferiscono adottare ognuno un proprio e distinto codice per ciascuna anagrafica.

Modalità di ricezione file ordini XML

Il file XML viene ricevuto con un GET HTTP alla URL indicata nella linguetta Impostazioni della funzione di scaricamento ordini 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.

Vengono, se necessario, accodati alla URL specificata nelle impostazioni i seguenti parametri per limitare il numero di ordini da scaricare:

appver: versione dell'applicazione (es: "2")
firstdate: data minima degli ordini da scaricare, in formato ISO (es: "2009-01-01") [Opzionale]
lastdate: data massima degli ordini da scaricare, in formato ISO (es: "2009-12-31") [Opzionale]
firstnum: primo nr. ordine da scaricare (es: "1") [Opzionale]
lastnum: ultimo nr. ordine da scaricare (es: "45") [Opzionale]

Esempio di URL richiamata:
http://www.mioserver.it/admin/ordini.php?appver=2&firstdate=2009-01-01&lastdate=2009-12-31&firstnum=1&lastnum=45

Di seguito un esempio minimale di script PHP che invia un file XML precedentemente salvato nel server:


$filestring = file_get_contents("ordini.xml");
echo $filestring;

Di seguito un esempio minimale di script ASP VBScript che invia un file XML precedentemente salvato nel server:


Set fs = CreateObject("Scripting.FileSystemObject")
Set textstream = fs.OpenTextFile("ordini.xml", 1)
response.write textstream.ReadAll
textstream.Close