bindCommerce API Export Documenti XML

Chiamata ed autenticazione

La chiamata viene effettuata all’URL generato da bindCommerce per lo specifico connettore.

L’autenticazione avviene attraverso token assegnato da bindCommerce. Il parametro viene trasmesso nell'header della richiesta.

Esempio script PHP per eseguire la chiamata

<?php

$curl = curl_init();

curl_setopt_array($curl, array(
          CURLOPT_URL => "https://hABCDE.bindcommerce.cloud/integrator-tool/api/export_orders.php?connector=2",
          CURLOPT_SSL_VERIFYHOST => true,
          CURLOPT_RETURNTRANSFER => true,
          CURLOPT_HTTPHEADER => array(
                "cache-control: no-cache",
                "token: 84b670ea63539f5bc0572a260f1f4dfb"
          ),
));

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
echo "cURL Error #:" . $err;
} else {
echo $response;
}

File ordini

In risposta alla richiesta viene fornito un file XML contenente gli ordini.

Esempio file

<?xml version="1.0" encoding="UTF-8"?>
<Documents><Document>
<General> ---- dalla versione 4
         <DocumentType>C</DocumentType>
         <bindCommerceNumber>15918</bindCommerceNumber>
         <Number>89568</Number>
<DocumentNumber></DocumentNumber>
         <Node>eBay superseller</Node>
         <NodeID>55</NodeID>
         <Technology>Marketplace eBay</Technology>
         <Market></Market>
         <Date>2018-03-22 17:34:07</Date>
<LastUpdate>2021-03-22 17:34:07</LastUpdate>
         <StatebindID>1</StatebindID>
         <StateCode>C</StateCode>
         <StateName>Completed</StateName>
</General> ---- dalla versione 4
<Customer>
         <Code>14833</Code>
         <Name>Daniele</Name>
         <Surname>Beccarelli </Surname>
         <Company></Company>
         <Address>Via delle Rosine 70 </Address>
         <Postcode>00121</Postcode>
         <City>Lido di Ostia</City>
         <Province>RM</Province>
         <CountryCode>IT</CountryCode>
         <VatCode></VatCode>
         <FiscalCode></FiscalCode>
         <Phone>32871800000</Phone>
         <MobPhone></MobPhone>
         <Email>Questo indirizzo email è protetto dagli spambots. È necessario abilitare JavaScript per vederlo.;;/Email>
</Customer>
<Delivery>
         <Name>Daniele</Name>
         <Surname>Beccarelli </Surname>
         <Company></Company>
         <Address>Via delle Rosine 70 </Address>
         <Postcode>00121</Postcode>
         <City>Lido di Ostia</City>
         <Province>RM</Province>
         <CountryCode>IT</CountryCode>
         <Phone>32871800000</Phone>
         <MobPhone></MobPhone>
         <Email>Questo indirizzo email è protetto dagli spambots. È necessario abilitare JavaScript per vederlo.;;/Email>
</Delivery>
<Payments>
         <PaymentName>PayPal</PaymentName>
         <PaymentCode>PP</PaymentCode>
         <PaymentTotal>0.00</PaymentTotal>
         <PaymentStatus>Complete</PaymentStatus>
         <PaidTime>2018-03-22 17:34:31</PaidTime>
</Payments>
<Rows>
         <Row>
         <bindID>17027</bindID>
         <Code>3961824</Code>
         <Barcode>8000072058222</Barcode>
         <Description>EURO 3 PLAST Sottovaso medea cm24 verde Giardino Arredo da esterno</Description>
         <Qty>4</Qty>
         <ProductDimensions>
         <Weight>0.05</Weight>
         <WeightUom>Kg</WeightUom>
         <WeightVolume>0</WeightVolume>
         <LwhUom></LwhUom>
         <Length>24</Length>
         <Width>24</Width>
         <Height>4</Height>
         </ProductDimensions>
         <ProductCategories>
         <Category></Category>
         </ProductCategories>
         <Picture>https://webserver.superseller.com/bindcommerce/product/big/17/a5f5_cb73a_130572.jpeg</Picture>
         <Supplier>Rossi S.p.A.</Supplier>
          <SupplierByRepricing>Rossi S.p.A api name</SupplierByRepricing>
         <SupplierByRepricingCost>1.23000</SupplierByRepricingCost>
         <SupplierPrice>0.58</SupplierPrice>
         <MPN>3961824</MPN>
         <PriceVatExcluded>1.12</PriceVatExcluded>
         <Price>1.37000</Price>
         <Discounts>0.00000</Discounts>
         <VatRate>22</VatRate>
         <TotalVatExcluded>4.49</TotalVatExcluded>
         <Total>5.48000</Total>
         <TotalDiscounted>5.48000</TotalDiscounted>
         <Currency>EUR</Currency>
         <Params>
                  <Param>
                  <Name>Param name</Name>
                  <Value>Param value example</Value>
                  </Param>
         </Params>

         </Row>
</Rows>
<Amounts>
         <TotalWithoutTax>4.49</TotalWithoutTax>
         <VatAmount>0.99</VatAmount>
         <Total>11.97</Total>
         <Currency>EUR</Currency>
         <ShippingCost>6.49</ShippingCost>
         <ShippingCostWithoutTax>6.49</ShippingCostWithoutTax>
         <ShippingTax>0.22</ShippingTax>
         <InternalComment></InternalComment>
         <SellerNote></SellerNote>
         <CouponDiscount>0.00</CouponDiscount>
         <CouponCode></CouponCode>
         <DiscountToCart></DiscountToCart>
</Amounts>
<Commission>
         <PayPalCommission>0.61</PayPalCommission>
         <PayPalTransactionID></PayPalTransactionID>
         <eBayCommission>0.48</eBayCommission>
         <eBayAccount>suo_account</eBayAccount>
         <eBayAdjustmentAmount>0.00</eBayAdjustmentAmount>
         <eBayAmountSaved>13.47</eBayAmountSaved>
</Commission>
<Shipping>
         <Carrier>Altro corriere 3-5 giorni</Carrier>
         <TrackingNumber></TrackingNumber>
         <TransportedWeight>0.2</TransportedWeight>
         <ShippedTime>0000-00-00 00:00:00</ShippedTime>
</Shipping>
</Document></Documents>

Campi del file

CAMPI DI TESTATA DOCUMENTO

Campo	Descrizione
DocumentType	Tipo di documento. Possibili valori: C = Ordine cliente. I = Fattura. N = Nota di credito. R = Ricevuta fiscale.
bindCommerceNumber	Identificativo interno bindCommerce per l’ordine. In condizioni normali si tratta di un contatore numerico. Se viene richiesto di eseguire lo split ordini per fornitore, il formato diventa [id_ordine]-[id_fornitore]. Per richiedere lo split occorre valorizzare a 1 il parametro API_ORDERS_OUT_SPLIT_SUPPLIER nella tabella dei parametri personalizzati.
Number	Numero d’ordine assegnato dal canale di vendita
DocumentNumber	Numero documento (fattura, ricevuta, nota di credito, ecc.)
Node	Nome del nodo bindCommerce dal quale proviene l’ordine (scelto dall’amministratore del contesto). Può contenere il nome del marketplace e dell’account (es. eBay superseller) oppure il nome del sito (ad esempio www.superseller.it)
Technology	Tecnologia alla quale appartiene il nodo. Alcuni valori possibili sono ad esempio: Marketplace eBay, Marketplace Amazon, Marketplace ePrice, Marketplace ManoMano, Marketplace Wish, eCommerce Magento, eCommerce Prestashop, ecc...
Market	Mercato dell’ordine (dato compilato solo per alcuni canali di vendita)
Date	Data ed ora di esecuzione dell’ordine
LastUpdate	Data ed ora di ultimo aggiornamento del documento
StatebindID	Id stato ordine bindCommerce
StateCode	Codice dello stato ordine. Gli stati ordine sono ereditati direttamente dalle piattaforme dalle quali proviene l’ordine.
StateName	Nome dello stato ordine
Customer	Nodo che rimanda tags inerenti le informazioni sul cliente (dati di fatturazione)
Delivery	Nodo che rimanda tags inerenti le informazioni sul destinatario della spedizione
Payments	Nodo che rimanda tags inerenti le informazioni sul Pagamento
Rows	Nodo che rimanda tags inerenti le Righe ordine
Amounts	Nodo che rimanda tags inerenti le informazioni sugli Importi
Commission	Nodo che rimanda tags inerenti le informazioni sulle Commissioni
Shipping	Nodo che rimanda tags inerenti le informazioni sulla Spedizione

INFORMAZIONI DI FATTURAZIONE (CUSTOMER)

Campo	Descrizione
Code	Codice numerico che identifica il cliente
Name	Nome
Surname	Cognome
Company	Azienda
Address	Via e numero civico
Postcode	Codice di avviamento postale
City	Comune
Province	Provincia
CountryCode	Codice nazione ISO 3166-1 Alpha-2 (es. IT)
VatCode	Partita IVA
FiscalCode	Codice fiscale o identificativo analogo (per clienti esteri)
Phone	Telefono
MobPhone	Telefono mobile
Email	Email. In alcuni casi contiene un indirizzo email non reale (Amazon per esempio assegna un indirizzo di relay provvisorio)
EInvoiceDestCode	Codice destinatario per la fatturazione elettronica (SDI) o indirizzo PEC
Pec	Posta Elettronica Certificata

INFORMAZIONI DI SPEDIZIONE (DELIVERY)

Campo	Descrizione
Name	Nome
Surname	Cognome
Company	Azienda
Address	Via e numero civico
Postcode	Codice di avviamento postale
City	Comune
Province	Provincia
CountryCode	Codice nazione ISO 3166-1 Alpha-2
Phone	Telefono
MobPhone	Telefono mobile
Email	Email. In alcuni casi contiene un indirizzo email non reale (Amazon per esempio assegna un indirizzo di relay provvisorio)

INFORMAZIONI SUL PAGAMENTO (PAYMENTS)

Campo	Descrizione
PaymentName	Nome del metodo di pagamento
PaymentCode	Codice del metodo di pagamento
PaymentTotal	Costo di incasso IVA compresa (ad esempio per i pagamenti in contrassegno è previsto un costo aggiuntivo a carico del cliente)
PaymentStatus	Stato del pagamento
PaidTime	Data ed ora del pagamento
PaymentCOD	Può assumere due valori: YES oppure NO. Indica se il metodo di pagamento è in contrassegno.

RIGHE ORDINI (ROWS)

Ogni riga ordine è contenuta in un tag

Campo	Descrizione
bindID	Identificativo interno bindCommerce per la riga ordine
Code	Codice SKU del prodotto
Barcode	Codice a barre estratto dall’anagrafica prodotto connessa allo SKU venduto
Description of the order line as it appears on the sales channel. For example, for eBay orders the title of the advertisement is returned.	Descrizione della riga ordine come compare sul canale di vendita. Ad esempio per gli ordini eBay viene restituito il titolo dell’inserzione.
Qty	Quantità acquistata (numero)
ProductDimensions	Tag che raggruppa i tag Weight (peso), WeightUom (unità di misura del peso), WeightVolume (peso volumetrico), LwhUom (unità di misura lineare), Length (lunghezza), Width (base), Height (altezza). Queste informazioni, se presenti, vengono estratte dall’anagrafica articoli.
ProductCategories	Category - KeyCat della categoria/e abbinate al prodotto acquistato
Picture	URL immagine prodotto (eventualmente estratta dall’anagrafica articoli)
Supplier	Nome o codice del fornitore (eventualmente estratto dall’anagrafica articoli)
SupplierPrice	Prezzo di costo da riconoscere al fornitore (per indicare il listino da utilizzare occorre inserire la chiave “SupplierPrice” nel campo “Chiave listino Export file”)
PriceVatExcluded	Prezzo unitario IVA esclusa (rif. product_item_price)
Price	Prezzo unitario IVA compresa (rif. product_final_price)
SupplierByRepricing	Nome del fornitore nel caso in cui il prezzo di vendita sia stato imposto tramite l’algoritmo di repricing
SupplierByRepricingCost	Il costo del prodotto relativo al fornitore (SupplierByRepricing) ottenuto tramite l’algoritmo di repricing
Discount	Percentuale di sconto (rif. product_discount_percent)
VatRate	Aliquota IVA (es. 0.22 per indicare il 22%). Vedi nota (***)
TotalVatExcluded	Prezzo totale iva esclusa (rif. product_item_price_total)
Total	Prezzo totale IVA compresa (rif. product_final_price_total)
TotalDiscounted	Prezzo scontato riga ordine IVA compresa (rif. product_final_price_total_discounted)
Currency	Valuta ISO 4217 (es. EUR, CHF, GBP, USD). bindCommerce è in grado di gestire una conversione di valuta affinché tutti gli importi siano espressi in Euro.

RIGHE ORDINI: COMMISSIONI (COMMISSION)

Campo	Descrizione
Commission	eBayCommission ( commissione eBay su riga ordine )

RIGHE ORDINI: CASHFLOW (CASHFLOWROWS)

Campo	Descrizione
SettlementId	ID Transazione
Currency	Valuta
TransactionType	Tipo transazione
OrderId	ID Ordine
MerchantOrderId	ID Ordine Merchant
AdjustmentId	AdjustmentId
ShipmentId	ID Spedizione
MarketplaceName	Marketplace
ShipmentFeeType	Tipo spese di spedizione
ShipmentFeeAmount	Importo spese di spedizione
OrderFeeType	Tipo commissione ordine
OrderFeeAmount	Importo commissione ordine
FulfillmentId	Fulfillment Id
PostedDate	Posted Date
OrderItemCode	Order Item Code
MerchantOrderItemId	Merchant Order Item Id
MerchantAdjustmentItemId	Merchant Adjustment Item Id
Sku	Sku
QuantityPurchased	Quantità acquistata
PriceType	Tipo prezzo
PriceAmount	Prezzo
ItemRelatedFeeType	Item Related Fee Type
ItemRelatedFeeAmount	Item Related Fee Amount
MiscFeeAmount	Misc Fee Amount
OtherFeeAmount	Other Fee Amount
OtherFeeReasonDescription	Other Fee Reason Description
DirectPaymentType	Direct Payment Type
DirectPaymentAmount	Direct Payment Amount
OtherAmount	Other Amount
Amount	Importo
AmountType	Tipo Importo
AmountDescription	Descrizione importo

IMPORTI (AMOUNTS)

Campo	Descrizione
TotalWithoutTax	Costo merce IVA esclusa IVA esclusa (rif. order_subtotal)
VatAmount	Importo IVA (rif. order_tax)
Total	Totale ordine (rif. order_total)
Currency	Valuta ISO 4217 (es. EUR, CHF, GBP, USD).
ShippingCost	Costo spedizione IVA compresa (rif. order_shipping_total)
InternalComment	Note inserite dal cliente in fase di acquisto (rif. customer_note)
SellerNote	Note inserite dal venditore (rif. seller_note)
CouponDiscount	Sconto coupon (rif. coupon_discount)
CouponCode	Codice coupon
ShippingCostWithoutTax	Ammontare delle spese di spedizione tasse escluse
ShippingTax	Aliquota iva applicata alla spedizione
DiscountToCart	Sconto al carrello (rif. discount_to_cart)

COMMISSIONI (COMMISSION)

Campo	Descrizione
PayPalCommission	Importo commissione PayPal (disponibile solo per ordini eBay)
PayPalTransactionID	ID transazione PayPal
eBayCommission	Importo commissione eBay
eBayAccount	Account eBay
eBayAdjustmentAmount	Rettifica costi ordine eBay
eBayAmountSaved	Importo risparmiato sulla spedizione combinata eBay

INFORMAZIONI SULLA SPEDIZIONE (SHIPPING)

Campo	Descrizione
Carrier	Spedizioniere
TrackingNumber	Codice di tracciabilità
TransportedWeight	Peso trasportato
ShippedTime	Data ed ora di spedizione
ShippingMethod	Metodo di spedizione

Note relative all’aliquota IVA

bindCommerce importa ordini da varie fonti: piattaforme eCommerce e marketplace (quali ad esempio eBay, Amazon, ePrice, Spartoo, Wish), ed ognuna delle fonti trasmette un differente dettaglio relativamente all'applicazione dell'IVA. In generale i marketplace non adattano il prezzo in base al tipo di acquirente (privato / azienda) e la sua provenienza (Italia / Europa / resto del mondo). Se un acquirente acquista ad € 100,00 un determinato bene, la determinazione di quanto valore è da imputare ad imponibile e quanto ad IVA è un'attività che può essere eseguita solo dopo l'acquisto (e un eventuale esenzione IVA si tradurrà di fatto in una vendita a prezzo superiore). Inoltre sia su eBay che su Amazon, la richiesta di eventuale fattura viene effettuata con metodi manuali (messaggi) in concomitanza o subito dopo l'acquisto (su Amazon sempre dopo), quindi non è possibile effettuare aggiustamenti di prezzo prima del pagamento.

Osservando inoltre i dati relativi alle aliquote trasmessi dai marketplace principali, notiamo che: eBay (tutti i mercati) trasmette sempre l'aliquota che è stata impostata al momento della creazione dell'inserzione (anche quando non deve essere applicata), mentre Amazon (tutti i mercati, se non vengono attivate le opzioni business) non trasmette alcuna aliquota IVA (a differenza di eBay che la trasmette potenzialmente sbagliata).

Fatte queste premesse, sono possibili 2 approcci alternativi:

trasmettere i dati sicuramente corretti (chi è l'acquirente, cosa ha acquistato e quanto ha pagato) e l’aliquota proveniente dal marketplace (che potrebbe non essere corretta) e poi lasciare che sia l’ERP a ricalcolare le aliquote corrette da applicare e gli eventuali codici di esenzione.
utilizzare una funzione Premium di bindCommerce che è in grado di ricalcolare le aliquote da applicare alle vendite, per i costi di spedizione e per la merce, in funzione di un parametro “gruppo aliquota iva” (attributo di prodotto da importare precedentemente) e della destinazione della merce

STATI DEGLI ORDINI

I valori che bindCommerce trasmette nel campo StateName rappresentano gli stati ordine utilizzati dalla piattaforma dalla quale proviene l’ordine. Il campo StateCode è utilizzato solo in alcune piattaforme ed il campo StateName può essere considerato univoco nell’ambito di una determinata tecnologia. Segue una presentazione dei possibili stati ordine per le piattaforme più comuni.

STATI DEGLI ORDINI PER IL MARKETPLACE EBAY

StateName	Note
Active	Acquisto non ancora completato / confermato
Cancelled	Annullato
CancelPending	In fase di annullamento
Completed	Acquisto completato
Refunded	Totalmente rimborsato
Shipped	Spedito

STATI DEGLI ORDINI PER IL MARKETPLACE WISH

StateName	Note
APPROVED	Acquisto confermato (pagato a Wish)
REFUNDED	Rimborsato
SHIPPED	Spedito

STATI DEGLI ORDINI PER IL MARKETPLACE AMAZON

StateName	Note
Pending	Acquisto non ancora completato / confermato
Cancelled	Annullato
Unshipped	Confermato (pagato ad Amazon) ma non ancora spedito
Shipped	Spedito

STATI DEGLI ORDINI PER IL MARKETPLACE EPRICE

StateName	Note
RECEIVED	Ricevuto da ePrice
SHIPPED	Spedito
SHIPPING	In spedizione
WAITING_ACCEPTANCE	In attesa di accettazione da parte del venditore

STATI DEGLI ORDINI PER IL MARKETPLACE ALLEGRO

StateName	Note
BOUGHT	acquisto senza modulo di pagamento compilato
FILLED_IN	modulo di pagamento compilato ma il pagamento non è stato ancora completato, quindi i dati potrebbero ancora cambiare
READY_FOR_PROCESSING	pagamento completato. L'acquisto è pronto per l'elaborazione.
CANCELLED	acquisto annullato dall'acquirente.

STATI DEGLI ORDINI PER IL MARKETPLACE CDISCOUNT

StateName	Note
CancelledByCustomer
WaitingForSellerAcceptation
AcceptedBySeller
PaymentInProgress
WaitingForShipmentAcceptation
Shipped
RefusedBySeller
AutomaticCancellation	es: nessuna risposta dal venditore
PaymentRefused

StateName	Note
ShipmentRefusedBySeller
Waiting for Fianet validation “A valider Fianet” (None)
Validated Fianet
RefusedNoShipment
AvailableOnStore
NonPickedUpByCustomer
PickedUp
Filled

STATI DEGLI ORDINI PER LA PIATTAFORMA ECOMMERCE PRMAGENTO

si noti che questi stati possono essere modificati dal gestore del sito

StateName	Note
canceled
closed
complete
completed
failed
holded
on-hold
paid
paypal_canceled_reversal
paypal_reversed
pending
processing
refunded

STATI DEGLI ORDINI PER LA PIATTAFORMA ECOMMERCE PRESTASHOP

note that these states can be changed by the site operator

StateName	Note
Awaiting bank wire payment
Awaiting Cash On Delivery validation
Awaiting check payment
Awaiting for PayPal payment
Canceled
Delivered
On backorder (paid)
Payment accepted
Payment error
Processing in progress
Refunded
Shipped

Gestione annullamento ordini

L’informazione relativa all’annullamento totale di un ordine può essere dedotta dal cambio di stati dello stesso.
Riguardo al caso di "alcune righe ordine annullate", bindCommerce trasmetterà un aggiornamento dell’ordine stesso ponendo a 0 (zero) la quantità per le righe ordine annullate.

0 su 5 - 0 valutazioni

Grazie per aver valutato questo contenuto.

Servizio online self service

Servizio chiavi in mano

Export documenti XML