NewCart : Specifiche del webservice per l’esportazione degli ordini
Category:Newcart,ProgrammiPanoramica.
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 |
| login | string | SI | Login Amministratore (con abilitati i diritti all’uso dei webservices) |
| password | string | SI | Password Amministratore |
| 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 gli ordini che si vorranno includere nell’esportazione |
| oshippingdate_to | datetime | NO | Data di spedizione massima gli 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 |
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 pageerror>
errors>
Consultare l’appendice F per una lista di posibili codici di errore.
Esempio completo di output xml
| <?xml version=”1.0″ encoding=”ISO-8859-1″ ?> <orders> <order locale_code=”225″ currency_code=”1″> <order_id>1883727306</order_id> <order_date>2011-05-24T18:50:00</order_date> <order_channel>eBay</order_channel> <order_payment_status>1</order_payment_status> <order_payment_type>Paypal</order_payment_type> <order_shipping_status>1</order_shipping_status> <order_shipping_date>2011-05-25T18:50:00</order_shipping_date> <package_weight>22.44</package_weight> <order_courier>DHL 2</order_courier> <order_tracking_number>QWERTY</order_tracking_number> <order_tracking_url>https://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> </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> <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> <city>Napoli</city> <zip>81100</zip> <state>NA</state> <country>Italy</country> <phone>081 666666666</phone> <mobile>12341234</mobile> <email>my@email.com</email> </order_billing_info> <order_shipping_info> <first_name>Mario</first_name> <middle_name /> <last_name>Rossi</last_name> <ssn /> <address>Viale dei Giardini</address> <city>Napoli</city> <zip>81100</zip> <state>NA</state> <country>Italy</country> <phone>081 666666666</phone> <email>my@email.com</email> </order_shipping_info> <basket> <product> <code>398f83h</code> <name>T68i</name> <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> </product> <product> <code>sdkdsf7</code> <name>Nintendo DS</name> <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> </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
Lista di 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
Lista di 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
Lista di 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
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 |
Appendice F
Lista di 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 |
Esempi :
Lista di possibili codici di errore
Esempio di richiesta degli ordini mai esportati prima, nella lingua e valuta di default :
https://www.mydomain.com/ws/orders_export.php?login=xxxx&password=xxx
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 :
https://www.mydomain.com/ws/orders_export.php?login=xxxx&password=xxx&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.
https://www.mydomain.com/ws/orders_export.php?login=xxxx&password=xxx&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
