Blog - NewCart.it: carrello negozio elettronico e-commerce

NewCart : Specifiche del webservice per l'esportazione degli ordini

Panoramica
Gli ordini generati in Newcart possono essere esportati successivamente grazie ad appositi webservices. Questo documento definisce il formato dei dati che verranno esportati nonchè il set di parametri di input supportati dal webservice.

Note generali
L'output del webservice produce un documento XML formattato secondo gli standards XML, di seguito una lista di parametri necessari per il suo utilizzo.

Parametro di input	Tipo dato	Obbligatorio	Descrizione
access_token	string	SI	Chiave di accesso alfanumerica La chiave può essere generata nel campo "Api Secret String" dell'amministratore con le cui credenziali si desidera accedere. L'amministratore deve avere il permesso "Uso dei webservices dell'E-Shop" abilitato
locale	string	NO	Codice ISO della lingua (due lettere) (Ad esempio IT,GB,FR...)
currency	string	NO	Codice ISO della valuta (tre lettere) (Ad esempio EUR,USD,JPY...) Consultare l'appendice A per una lista dei valori ammessi
odate_from	datetime	NO	Data minima per gli ordini che si vorranno includere nell'esportazione
odate_to	datetime	NO	Data massima per gli ordini che si vorranno includere nell'esportazione
oshippingdate_from	datetime	NO	Data di spedizione minima degli ordini che si vorranno includere nell'esportazione
oshippingdate_to	datetime	NO	Data di spedizione massima degli ordini che si vorranno includere nell'esportazione
opaymentdate_from	datetime	NO	Data di pagamento minima degli ordini che si vorranno includere nell'esportazione
opaymentdate_to	datetime	NO	Data di pagamento massima degli ordini che si vorranno includere nell'esportazione
oexport_status	integer	NO	Status di esportazione dell'ordine Consultare l'appendice B per una lista dei valori ammessi
opayment_status	integer	NO	Status di pagamento dell'ordine Consultare l'appendice C per una lista dei valori ammessi
oshipping_status	integer	NO	Status della spedizione dell'ordine Consultare l'appendice D per una lista dei valori ammessi
odeleted_include	integer	NO	Status di cancellazione dell'ordine Consultare l'appendice E per una lista dei valori ammessi
no_ord127_convert	string	NO	Se impostato su "yes" i caratteri con i codici da 127 in poi verranno inviati così come sono in output. Di default (o in assenza del parametro o quando è impostato a "no") il sistema convertirà tutti i caratteri speciali con i codici 1 ... 31 e i caratteri "nazionali" con i codici maggiori o uguali a 127 in base ai loro codici nel formato: &#<codice>. Ad esempio Tab(9) verrà visualizzato come &#9
expand_kits_to_parts	integer	NO	Modalità di esportazione dei Kit di prodotti Consultare l'appendice F per una lista dei valori ammessi
oid_marketplace	integer	NO	Scelta del codice d'ordine assegnato dal marketplace invece che dall'E-Shop nel caso di ordini generati dai marketplace Consultare l'appendice G per una lista dei valori ammessi
preserve_export_status	integer	NO	Consente di scegliere se contrassegnare o meno gli ordini esportati come tali. Nel caso non fossero contrassegnati come esportati verrebbero inclusi nella successiva esportazione anche senza utilizzare il parametro oexport_status Consultare l'appendice I per una lista dei valori ammessi
saleschannel	string	NO	Consente di selezionare i soli ordini provenienti da determinati canali di vendita (sito web, marketplace, etc.) Consultare l'appendice L per una lista dei valori ammessi
limit_start	integer	NO	Imposta il primo elemento della paginazione (ad esempio se è 50, in output ci fornirà una lista di ordini parziale partendo dal cinquantesimo elemento)
limit_records	integer	NO	Imposta il numero di elementi che deve avare la lista paginata (il numero di elementi per pagina)
get_order_by_fields	string	NO	Se viene inserito nella url (anche vuoto) attiva l’ordinamento e rende possibile impostarlo diverso da quello di default (l’ordinamento di default e per data: odate)
order_by_field	string	NO	Se è stato inserito il parametro “order_by_fields”, imposta il campo per l’ordinamento degli ordini.
order_by_direction	string	NO	Determina se l’ordinamento delle lista degli ordini è crescente o decrescente (ASC DESC).
decryption_key	string	NO	Chiave per decriptare eventuali dati criptati all'interno degli ordini. La chiave va codificata con la codifica standard per le URL (url encoding) prima di essere inserita nella query string, sostituendo i caratteri non ammissibili nelle query string con le loro codifiche standard (in particolare nelle chiavi RSA va sostituito il ritorno a capo con '%0A', '+' con '%20', '/' con '%2F' e '=' con '%3D')
country_format	string	NO	Imposta il modo in cui vengono valorizzati i campi <country>. Il valore 'extended' fornisce il nome del paese per esteso (ad esempio 'Italy') e questo è anche il comportamento predefinito che si applica anche al caso in cui questo parametro sia omesso, i valori ISO e ISO2 forniscono invece il codice ISO a due lettere (ad esempio 'IT') mentre il valore ISO3 fornisce il codice ISO a tre lettere (ad esempio 'ITA')

Tutti i parametri sopra elencati sono CASE SENSITIVE e possono essere inviati allo script usando sia la modalità POST sia la modalità GET.
I valori che esprimono una data devono essere rappresentati nella forma che segue : (2011-05-24T18:50:00)

Gestione errori
Il webservice supporta un set di codici di errore univoci.
Di seguito un tipico esempio di errore :

<errors>
<error code="1390">You must login in order to access this page</error>
</errors>

Consultare l'appendice H per una lista di posibili codici di errore.

Esempio completo di output xml

<?xml version="1.0" encoding="UTF-8" ?>
<orders>
    <order locale_code="225" currency_code="1">
        <order_id>1883727306</order_id>
        <order_internal_id>3416</order_id>
        <order_date>2011-05-24T18:50:00</order_date>
        <order_channel>eBay</order_channel>
        <order_payment>
            <status>1</status>
            <name>PayPal</name>
            <code>paypal</code>
            <date>2023-09-18</date>
            <plan>
                <id>13</id>
                <name>PayPal account o Carta di credito, debito, prepagata.</name>
            </plan>
            <source_of_funds>
            <code>paypal</code>
            <name>Paypal account</name>
            </source_of_funds>
        </order_payment>
        <order_shipping_status>1</order_shipping_status>
        <order_shipping_date>2011-05-25T18:50:00</order_shipping_date>
        <order_deleted_status>1</order_deleted_status>
        <package_weight>22.44</package_weight>
        <order_courier>DHL 2</order_courier>
        <order_tracking_number>QWERTY</order_tracking_number>
        <order_tracking_url>http://dhl.com/?52552rr3w</order_tracking_url>
        <order_shipping_notes>Test note</order_shipping_notes>
        <order_shipping_type>
            <shipping_type>Standard</shipping_type>
            <shipping_area>Europe</shipping_area>
            <onsite_pickup>no</onsite_pickup>
        </order_shipping_type>
        <order_note>Admin's note about user</order_note>
        <order_extra_info>Extra info for user</order_extra_info>
        <order_agreement>yes</order_agreement>
        <order_billing_info>
           <customer_id>22</customer_id>
           <ebay_customer_id>1234567</ebay_customer_id>
           <price_list>Listino al Pubblico</price_list>
           <price_list_id>1</price_list_id>
           <first_name>Mario</first_name>
           <middle_name />
           <last_name>Rossi</last_name>
           <ssn>MRARSS72A01H620Y</ssn>
           <vat_number />
           <address>Viale dei Giardini</address>
           <street_number>44</street_number>
           <city>Napoli</city>
           <zip>81100</zip>
           <state>NA</state>
           <country>Italy</country>
           <country_code2>IT</country_code2>
           <country_code3>ITA</country_code3>
           <phone>081 666666666</phone>
           <mobile>12341234</mobile>
           <email>my@email.com</email>
           <electronic_invoice_destination_code/>
           <electronic_invoice_destination_PEC>my@pec.it</electronic_invoice_destination_PEC>
        </order_billing_info>
        <order_shipping_info>
           <first_name>Mario</first_name>
           <middle_name />
           <last_name>Rossi</last_name>
           <ssn />
           <address>Viale dei Giardini</address>
           <street_number>44</street_number>
           <city>Napoli</city>
           <zip>81100</zip>
           <state>NA</state>
           <country>Italy</country>
           <country_code2>IT</country_code2>
           <country_code3>ITA</country_code3>
           <phone>081 666666666</phone>
           <email>my@email.com</email>
        </order_shipping_info>
        <order_salesman>Ugo Amantini</order_salesman>
        <order_custom_fields>
           <field>
             <name>Nome sul citofono</name>
             <value>Rossi</value>
           </field>
           <field>
             <name>testo per il biglietto di accompagnamento</name>
             <value>Con i miei auguri di Buon Compleanno! Claudia</value>
           </field>
        </order_custom_fields>
        <basket>
           <product>
              <code>398f83h</code>
              <ean>1234567890123</code>
              <upc>087162143127</code>
              <isbn>978-3-16-148410-0</code>
              <asin>B00F0L0B58</code>
              <name>T68i</name>
              <brand>Sony Ericsson</brand>
              <url>https://www.eshop.com/productpage/</url>
              <features/>
              <gross_amount>110.00</gross_amount>
              <qty>1</qty>
              <units>pezzi</units>
              <estimated_shipping_date>2011-05-25T18:50:00</estimated_shipping_date>
              <total_net_amount>100</total_net_amount>
              <total_net_amount_vat>10</total_net_amount_vat>
              <suppliers>
                <supplier>
                  <id>1</id>
                  <name>MegaSupplies Inc.</name>
                  <code>ABC34D9i</code>
                </supplier>
                <supplier>
                  <id>3</id>
                  <name>Wharehouse s.r.l.</name>
                  <code>gbthk29</code>
                </supplier>
              <suppliers>
           </product>
           <product>
              <code>sdkdsf7</code>
              <name>Nintendo DS<name;/>
              <brand>Nintendo</brand>
              <features/>
              <gross_amount>480.00</gross_amount>
              <qty>2</qty>
              <units>pezzi</units>
              <estimated_shipping_date>2011-05-25T18:50:00</estimated_shipping_date>
              <total_net_amount>400</total_net_amount>
              <total_net_amount_vat>20</total_net_amount_vat>
           </product>
           <qty_total>3</qty_total>
           <units_total>pezzi</units_total>
           <discount_surcharge>
               <rule>
                   <name>Sconto 5% Fuori Tutto</name>
                   <sign>-</sign>
                   <amount>
                       <total_gross_amount>29.50</total_gross_amount>
                       <vat_subtotal>
                           <net_amount_vat>10</net_amount_vat>
                           <net_amount>5.00</net_amount> </vat_subtotal>
                       <vat_subtotal>
                          <net_amount_vat>20</net_amount_vat>
                           <net_amount>20.00</net_amount> </vat_subtotal>
                   </amount>
               </rule>
               <rule>
                   <name>2% contributo spese Paypal</name>
                   <sign>+</sign>
                   <amount>
                       <total_gross_amount>8.20</total_gross_amount>
                       <vat_subtotal>
                           <net_amount_vat>10</net_amount_vat>
                           <net_amount>2</net_amount> </vat_subtotal>
                       <vat_subtotal>
                          <net_amount_vat>20</net_amount_vat>
                           <net_amount>5</net_amount> </vat_subtotal>
                   </amount>
               </rule>
           </discount_surcharge>
           <shipping_cost>
               <gross_amount>12</gross_amount>
               <net_amount>10</net_amount>
               <net_amount_vat>20</net_amount_vat>
           </shipping_cost>
           <shipping_handling_fee>
               <gross_amount>0.60</gross_amount>
               <net_amount>0.50</net_amount>
               <net_amount_vat>20</net_amount_vat>
           </shipping_handling_fee>
           <cash_on_delivery>
               <gross_amount>0</gross_amount>
               <net_amount>0</net_amount>
               <net_amount_vat>0</net_amount_vat>
           </cash_on_delivery>
           <net_total>495,33</net_total>
           <vat_total>99.06</vat_total>
           <grandtotal>602.60</grandtotal>
           <user_credit available_amount="100.00" used_amount="50.00" />
           <total_charge>552.60</total_charge>
           <gifts>
               <name>Business Inkjet 2600</name>
           </gifts>
           <order_estimated_shipping_date>2011-05-26T00:00:00</order_estimated_shipping_date>
        </basket>
        <custom_statuses>
           <status>
              <id>1</id>
              <title>Controllo magazzino</title>
              <assignment_date>2023-06-01T03:00:00</assignment_date>
              <administrator>
                 <id>1</id>
                 <title>Mario Rossi</title>
              </administrator>
              <note>lieve graffio su imballo esterno</note>
           </status>
           <status>
              <id>3</id>
              <title>Packed</title>
              <assignment_date>2023-06-01T10:00:00</assignment_date>
              <administrator>
                 <id>1</id>
                 <title>Eugenio Grimaldi</title>
              </administrator>
              <note/>
           </status>
        </custom_statuses>
    </order>
    <order>
    ......
    </order>
    <order>
    ......
    </order>
</orders>

Appendice A
Lista di valute supportate dal sistema

Valuta	Codice ISO
Afghani	AFN
Algerian Dinar	DZD
Argentine Peso	ARS
Armenian Dram	AMD
Aruban Guilder	AWG
Australian Dollar	AUD
Azerbaijanian Manat	AZN
Bahamian Dollar	BSD
Bahraini Dinar	BHD
Baht	THB
Balboa	PAB
Barbados Dollar	BBD
Belarussian Ruble	BYR
Belize Dollar	BZD
Bermudian Dollar (customarily kn	BMD
Bolivar Fuerte	VEF
Boliviano	BOB
Brazilian Real	BRL
Brunei Dollar	BND
Bulgarian Lev	BGN
Burundi Franc	BIF
Canadian Dollar	CAD
Cape Verde Escudo	CVE
Cayman Islands Dollar	KYD
CFA Franc BCEAO	XOF
CFA Franc BEAC	XAF
CFP Franc	XPF
Chilean Peso	CLP
Colombian Peso	COP
Comoro Franc	KMF
Convertible Marks	BAM
Cordoba Oro	NIO
Costa Rican Colon	CRC
Croatian Kuna	HRK
Cuban Peso	CUP
Cyprus Pound	CYP
Czech Koruna	CZK
Dalasi	GMD
Danish Krone	DKK
Denar	MKD
Djibouti Franc	DJF
Dobra	Std
Dominican Peso	DOP
Dong	VND
East Caribbean Dollar	XCD
Egyptian Pound	EGP
El Salvador Colon	SVC
Ethiopian Birr	ETB
Euro	EUR
Falkland Islands Pound	FKP
Fiji Dollar	FJD
Forint	HUF
Franc Congolais	CDF
Ghana Cedi	GHS
Gibraltar Pound	GIP
Gourde	HTG
Guarani	PYG
Guinea Franc	GNF
Guinea-Bissau Peso	GWP
Guyana Dollar	GYD
Hong Kong Dollar	HKD
Hryvnia	UAH
Iceland Krona	ISK
Indian Rupee	INR
Iranian Rial	IRR
Iraqi Dinar	IQD
Jamaican Dollar	JMD
Jordanian Dinar	JOD
Kenyan Shilling	KES
Kina	PGK
Kip	LAK
Kroon	EEK
Kuwaiti Dinar	KWD
Kwacha	ZMK
Kwacha	MWK
Kwanza	AOA
Kyat	MMK
Lari	GEL
Latvian Lats	LVL
Lebanese Pound	LBP
Lek	ALL
Lempira	HNL
Leone	SLL
Liberian Dollar	LRD
Libyan Dinar	LYD
Lilangeni	SZL
Lithuanian Litas	LTL
Loti	LSL
Malagasy Ariary	MGA
Malaysian Ringgit	MYR
Maltese Lira	MTL
Manat	TMM
Mauritius Rupee	MUR
Metical	MZN
Mexican Peso	MXN
Mexican Unidad de Inversion (UDI	MXV
Moldovan Leu	MDL
Moroccan Dirham	MAD
Mvdol	BOV
Naira	NGN
Nakfa	ERN
Namibia Dollar	NAD
Nepalese Rupee	NPR
Netherlands Antillian Guilder	ANG
New Israeli Sheqel	ILS
New Leu	RON
New Taiwan Dollar	TWD
New Turkish Lira	trY
New Zealand Dollar	NZD
Ngultrum	BTN
North Korean Won	KPW
Norwegian Krone	NOK
Nuevo Sol	PEN
Ouguiya	MRO
Pa'anga	TOP
Pakistan Rupee	PKR
Pataca	MOP
Peso Uruguayo	UYU
Philippine Peso	PHP
Pound Sterling	GBP
Pula	BWP
Qatari Rial	QAR
Quetzal	GTQ
Rand	ZAR
Rial Omani	OMR
Riel	KHR
Rufiyaa	MVR
Rupiah	IDR
Russian Ruble	RUB
Rwanda Franc	RWF
Saint Helena Pound	SHP
Saudi Riyal	SAR
SDR	XDR
Serbian Dinar	RSD
Seychelles Rupee	SCR
Singapore Dollar	SGD
Slovak Koruna	SKK
Solomon Islands Dollar	SBD
Som	KGS
Somali Shilling	SOS
Somoni	TJS
Sri Lanka Rupee	LKR
Sudanese Pound	SDG
Surinam Dollar	SRD
Swedish Krona	SEK
Swiss Franc	CHF
Syrian Pound	SYP
Taka	BDT
Tala	WST
Tanzanian Shilling	TZS
Tenge	KZT
trinidad and Tobago Dollar	Ttd
Tugrik	MNT
Tunisian Dinar	TND
UAE Dirham	AED
Uganda Shilling	UGX
Unidad de Valor Real	COU
Unidades de fomento	CLF
Uruguay Peso en Unidades Indexad	UYI
US Dollar	USD
Uzbekistan Sum	UZS
Vatu	VUV
WIR Euro	CHE
WIR Franc	CHW
Won	KRW
Yemeni Rial	YER
Yen	JPY
Yuan Renminbi	CNY
Zimbabwe Dollar	ZWD
Zloty	PLN

Appendice B
oexport_status: lista degli status di esportazione supportati dal sistema
Questo campo riguarda i dati provenienti dal al campo export_status nella tabella degli ordini.

Codice	Tipo ordine	Descrizione
Vuoto o mancante	Nuovi ordini
0	Nuovi ordini
1	Tutti
2	Nuovi e modificati
3	Modificati

Appendice C
opayment_status: lista degli status di pagamento supportati dal sistema

Codice	Tipo ordine	Descrizione
Vuoto o mancante	Tutti
0	Tutti
1	Pagati	valore disponibile con lo stesso significato anche nell'output per il nodo xml <order_payment><status>
2	Non pagati	valore disponibile con lo stesso significato anche nell'output per il nodo xml <order_payment><status>

Appendice D
oshipping_status: lista degli status di spedizione supportati dal sistema

Codice	Tipo ordine	Descrizione
Vuoto o mancante	Tutti
0	Non spediti	il corrispondente valore nel nodo xml <order_shipping_status> dell'output è 2
1	Spediti	valore disponibile con lo stesso significato anche nell'output per il nodo xml <order_shipping_status>

Appendice E
odeleted_include: gestione dell'inclusione degli ordini in base allo status di cancellazione

Codice	Tipo ordine	Descrizione
Vuoto o mancante	Non cancellati
0	Non cancellati
1	Cancellati
2	Tutti gli ordini inclusi i cancellati

Appendice F
expand_kits_to_parts: modalità di esportazione dei Kit di prodotti

Codice	Modalità	Descrizione
Vuoto o mancante	Singoli prodotti	Nel nodo xml saranno elencati i singoli prodotti che compongono i Kit di prodotti eventualmente ordinati
0	Kit prodotti	Nel nodo xml <basket> saranno elencati i Kit di prodotti eventualmente ordinati
1	Singoli prodotti	Nel nodo xml <basket> saranno elencati i singoli prodotti che compongono i Kit di prodotti eventualmente ordinati

Appendice G
oid_marketplace: scelta del codice d'ordine per gli ordini da Marketplace

Codice	ID Ordine	Descrizione
Vuoto o mancante	E-Shop	Il nodo <order_id> contiene sempre il codice d'ordine assegnato dall'E-Shop
0	E-Shop	Il nodo <order_id> contiene sempre il codice d'ordine assegnato dall'E-Shop
1	Marketplace	Il nodo <order_id> contiene il codice d'ordine assegnato dal marketplace se l'ordine è stato generato da un markeplace, altrimenti contiene il quello assegnato dall'E-Shop

Appendice H
Lista dei possibili codici di errore

Codice	Script	Descrizione
1390	orders_export.php	E' necessario il login per accedere alla pagina
1391	orders_export.php	Il linguaggio richiesto non è supportato
1392	orders_export.php	La valuta richiesta non è supportata

Appendice I
preserve_export_status: gestione della marcatura degli ordini esportati come tali

Codice	Descrizione
Vuoto o mancante	Gli ordini esportati vengono contrassegnati come tali
0	Gli ordini esportati vengono contrassegnati come tali
1	Gli ordini esportati NON vengono contrassegnati come tali

Appendice L
saleschannel: filtro ordini per canale di provenienza

Codice	Descrizione
Vuoto o mancante o "all"	Non viene applicato nessun filtro per canale di provenienza
lista separata da virgole di valori	Vengono esportati solo gli ordini provenienti dai canali indicati dai valori. I valori ammessi sono "e-shop" (sito web) "ebay" (eBay) "amazon" (Amazon) e "manomano" (Manomano) ad esempio saleschannel=ebay,e-shop limiterà l'esportazione ai soli ordini provenienti da eBay e dal sito web

Appendice M
get_order_by_fields: parametro per l’attivazione degli ordinamenti

Codice	Descrizione
Mancante o “no” o “0”	Non può essere impostato nessun ordinamento diverso da quello predefinito
Vuoto o “yes” o “1”	Si può scegliere un campo per ordinare la lista degli ordini (tale campo è espresso dal parametro ‘order_by_fields’ )

Appendice N
order_by_field: parametro per l’ordinamento della lista ordini

Campo	Descrizione
oid	id ordine interno
ufirst	nome del cliente
ulast	cognome del cliente
ubusiness	azienda
uaddress	indirizzo cliente
ucity	comune cliente
uzip	CAP cliente
ustate	provincia/stato cliente
ucountry	nazione cliente
uphone	telefono cliente
ufax	fax cliente
uemail	email cliente
dufirst	nome (nei dati di spedizione)
dulast	cognome (nei dati di spedizione)
dubusiness	azienda (nei dati di spedizione)
duaddress	indirizzo di spoedizione
ducity	comune di spedizione
duzip	CAP di spedizione
dustate	provincia di spedizione
ducountry	nazione di spedizione
duphone	telefono (nei dati di spedizione)
dufax	fax (nei dati di spedizione)
duemail	email (nei dati di spedizione)
odate	data dell’ordine
payed	stato del pagamento
pmethod	metodo di pagamento
total	totale netto
iva	totale iva
grandtotal	totale lordo
packageweight	peso
marketplace_transaction_id	id transazione marketplace esterni (ebay, amazon ecc.)

Esempi :

Esempio di richiesta degli ordini mai esportati prima, nella lingua e valuta di default:

http://www.mydomain.com/ws/orders_export.php?login=xxxx&password=xxxx

Esempio di richiesta degli ordini riguardanti uno specifico range di date, mai esportati prima, pagati ma non spediti e non cancellati, in lingua Italiana e aventi per valuta l'Euro:

http://www.mydomain.com/ws/orders_export.php?login=xxxx&password=xxxx&locale=IT&currency=EUR&odate_from=2011-05-25T00:00:00&odate_to=2011-05-31T00:00:00&oshippingdate_from=2011-05-25T00:00:00&oshippingdate_to=2011-05-31T00:00:00&oexport_status=0&opayment_status=1&oshipping_status=0&odeleted_include=0

Esempio di richiesta degli ordini non rientranti in uno specifico range, il cui status è cambiato dall'ultima esportazione, pagati, spediti in un determinato range di data, non cancellati, in lingua Italiana e valuta Euro:

http://www.mydomain.com/ws/orders_export.php?login=xxxx&password=xxxx&locale=IT&currency=EUR&oshippingdate_from=2011-05-25T00:00:00&oshippingdate_to=2011-05-31T00:00:00&oexport_status=3&opayment_status=1&oshipping_status=1&odeleted_include=0

Esempio di richiesta con paginazione e ordinamento:

http://www.mydomain.com/ws/orders_export.php?login=____&password=_____&preserve_export_status=1&get_order_by_fields=&order_by_field=userid&order_by_direction=asc&limit_start=0&limit_records=10

titolo

Personalizza

Cookie funzionali

Cookie per assistenza

Cookie pubblicitari e di tracciamento