Specifiche tecniche e-commerce con Easyfatt:
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 Utilità > 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>
      [...]
      <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.). 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. 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.

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