Ricezione ordini

La ricezione viene effettuata ricevendo dal sito un file XML con l'elenco dei documenti (tipicamente conferme d'ordine).

Suggerimento: per effettuare delle verifiche sui tracciati, tramite Easyfatt (anche in versione dimostrativa), è possibile esportare documenti nel formato XML di seguito descritto. Per farlo è sufficiente accedere alla sezione DOCUMENTI, selezionare i documenti desiderati e premere il pulsante Strumenti > Trasferisci documenti (formato Easyfatt-Xml).

Struttura del file

<?xml version="1.0" encoding="UTF-8"?>
<EasyfattDocuments AppVersion="2" Creator="Danea Soft" CreatorUrl="www.danea.it">
<Company>
      [...]
</Company>
<Documents>
    <Document>
      [...]
      <Row>
        [...]
      </Row>
      <Row>
        [...]
      </Row>
      [...]
      <Payment>
        [...]
      </Payment>
      <Payment>
        [...]
      </Payment>
      [...]
    </Document>
    <Document>
      [...]
      <Row>
        [...]
      </Row>
      <Row>
        [...]
      </Row>
      [...]
      <Payment>
        [...]
      </Payment>
      <Payment>
        [...]
      </Payment>
      [...]
    </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, oltre ai campi della testata, degli altri sottoelementi:
- elementi Row, che rappresentano le singole righe del documento;
- elementi Payment, che rappresentano i singoli pagamenti del documento (opzionali e di norma non usati nelle operazioni di e-commerce).

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>
      <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>20</VatCode>
      </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>20</VatCode>
      </Row>
      <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>
    </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 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.). Se omesso, l'importazione userà la numerazione scelta nelle relative impostazioni.
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.
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.
CustomerTel	Numero di telefono.
CustomerCellPhone	Numero di cellulare.
CustomerFax	Numero di fax.
CustomerEmail	Indirizzo e-mail.
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.
ShipmentTerms	Porto (franco, assegnato...).
TransportedWeight	Peso trasportato.
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).
CostAmount	Importo spese aggiuntive [Valuta].
Total	Totale documento (usato solo per mostrarlo nell'elenco di importazione, il totale effettivo viene ricalcolato al termine dell'importazione) [Valuta].
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].
WithholdingTaxPerc	Percentuale ritenuta d'acconto applicata [Numerico].
WithholdingTaxPerc2	Seconda percentuale della ritenuta d'acconto (es.: 20% del 50%) [Numerico].
PriceList	Numero (1..N) del listino usato [Numerico].
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.
Campi nelle righe del documento (da collocare all'interno degli 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).
WithholdingTax	Ritenuta d'acconto applicata [true\|false].
Stock	Movimentazione magazzino [true\|false].
CommissionPerc	Percentuale provvigione agente [Numerico].
Campi nei pagamenti del documento (da collocare all'interno degli 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 o e-mail:
  - 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:

admin/ordini.php:

<?php
$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:

admin/ordini.asp:

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