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 |
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>. |
expand_kits_to_parts | integer | NO |
Modalità di esportazione dei Kit di prodotti |
oid_marketplace | integer | NO |
Scelta del codice d'ordine assegnato dal marketplace invece che dall'E-Shop nel caso di ordini generati dai marketplace |
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 |
saleschannel | string | NO |
Consente di selezionare i soli ordini provenienti da determinati canali di vendita (sito web, marketplace, etc.) |
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>. |
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>Supplier s.r.l.</name> <code>ABC34D9i</code> <email>supplier@fantasysuppliers.org</email> <address>Via dei Platani, 19</address> <postal_code>12345</postal_code> <city>Torino</city> <phone>+39.000123456</phone> <fax>+39.0001234567</fax> <url>https://www.fantasysuppliers-supplier.org</url> <vat_number>01234567890</vat_number> <codice_destinatario_SDI>1234567</codice_destinatario_SDI> </supplier> <supplier> <id>2</id> <name>MegaSupplies Inc.</name> <code>DEF34D0i</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 |
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¤cy=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¤cy=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
Ordini realtime sui nostri E-Shop |