API Ver. 1.1

Le API 1.1 sono ancora attive, ma da considerarsi deprecate e pienamente sostituire dalla versione 1.2.

Le API sono la possibilità di integrare Qapla' sia in lettura che in scrittura con il tuo sistema di ecommerce proprietario o per il quale non è stato ancora implementato un plugin o un connector.

getTrack➔getShipment 1.2
dedicata alla lettura dello stato della spedizione sia in formato JSON che XML

pushTrack➔pushShipment 1.2
che permette l'importazione di una o più spedizioni.

deleteTrack➔deleteShipment 1.2
che permette la cancellazione di una spedizione.

getTracks➔getShipments 1.2
che permette di ottenere la lista delle spedizioni da una certa data.

pushOrder➔pushOrder 1.2
che permette l'importazione di una o più ordini.

getOrders➔getOrders 1.2
che permette di ottenere la lista degli ordini importati da una certa data.

getCredits➔getCredits 1.2
per ottenere i crediti rimanenti sul proprio acount premium.

getCouriers➔getCouriers 1.2
per ottenere la lista dei corrieri supportati.

Per poter utilizzare le API è necessario essere a conoscenza delle API Key assegnate al/ai tuo/i canale/i.

getTrack 1.1➔getShipment 1.2

getTrack permette di leggere lo stato di una spedizione tramite il tracking number.

All'indirizzo https://api.qapla.it/1.1/getTrack/ è sufficiente inviare una richiesta GET contenete i seguenti parametri:

Parametro	Descrizione
apiKey	la API key assegnata al canale che vogliamo interrogare
trackingNumber \| reference	il tracking number interessato \| il riferimento ordine
lang	la lingua (ita o eng), default: ita

Esempio

Il seguente URL

https://api.qapla.it/1.1/getTrack/?apiKey=[API_KEY]&trackingNumber=[Traking_Number]&lang=ita

oppure il seguente

https://api.qapla.it/1.1/getTrack/?apiKey=[API_KEY]&reference=[Order_Reference]&lang=ita

darà come risultato

{
    "getTrack": {
        "error": false,
        "status": "In consegna",
        "statusDate": "31/08/2016 09:17:25",
        "icon": "https://cdn.qapla.it/img/status/4.png",
        "trackingUrl": "https://tracking.qapla.it/5700ac68a8eb963594fdd4b254e173a6",
        "trackingNumber": "2878202252347",
        "reference": "300008236",
        "courier": "SDA",
        "courierInfo": "SDA",
        "courierLogo": "https://cdn.qapla.it/cp/img/corrieri/32/SDA.png",
        "courierTrackingUrl": "http://wwww.sda.it/SITO_SDA-WEB/dispatcher?invoker=home&LEN=&execute2=ActionTracking.doGetTrackingHome&button=Vai&id_ldv=2878202252347",
        "courierStatus": "IN CONSEGNA",
        "courierPlace": "CALTANISSETTA",
        "courierDate": "31-08-2016",
        "tracking": [{
            "status": "In consegna",
            "statusDate": "31/08/2016 00:00:00",
            "icon": "https://cdn.qapla.it/img/status/4.png",
            "courierStatus": "IN CONSEGNA",
            "courierPlace": "CALTANISSETTA",
            "courierDate": "31-08-2016"
        }, {
            "status": "Eccezione",
            "statusDate": "30/08/2016 00:00:00",
            "icon": "https://cdn.qapla.it/img/status/6.png",
            "courierStatus": "DESTIN. ASSENTE-SVINCOLA ONLINE PER NUOVA CONSEGNA",
            "courierPlace": "CALTANISSETTA",
            "courierDate": "30-08-2016"
        }, {
            "status": "In consegna",
            "statusDate": "30/08/2016 00:00:00",
            "icon": "https://cdn.qapla.it/img/status/4.png",
            "courierStatus": "IN CONSEGNA",
            "courierPlace": "CALTANISSETTA",
            "courierDate": "30-08-2016"
        }, {
            "status": "In transito",
            "statusDate": "29/08/2016 00:00:00",
            "icon": "https://cdn.qapla.it/img/status/3.png",
            "courierStatus": "LA SPEDIZIONE E' IN VIAGGIO",
            "courierPlace": "CATANIA",
            "courierDate": "29-08-2016"
        }, {
            "status": "In transito",
            "statusDate": "27/08/2016 00:00:00",
            "icon": "https://cdn.qapla.it/img/status/3.png",
            "courierStatus": "LA SPEDIZIONE E' PARTITA",
            "courierPlace": "ROMA HUB ESPRESSO",
            "courierDate": "27-08-2016"
        }, {
            "status": "In transito",
            "statusDate": "27/08/2016 00:00:00",
            "icon": "https://cdn.qapla.it/img/status/3.png",
            "courierStatus": "IN TRANSITO",
            "courierPlace": "ROMA HUB ESPRESSO",
            "courierDate": "27-08-2016"
        }, {
            "status": "In transito",
            "statusDate": "26/08/2016 00:00:00",
            "icon": "https://cdn.qapla.it/img/status/3.png",
            "courierStatus": "LA SPEDIZIONE E' PARTITA",
            "courierPlace": "NAPOLI 1",
            "courierDate": "26-08-2016"
        }, {
            "status": "Partito",
            "statusDate": "26/08/2016 00:00:00",
            "icon": "https://cdn.qapla.it/img/status/20.png",
            "courierStatus": "LA SPEDIZIONE E' STATA RITIRATA PRESSO IL MITTENTE",
            "courierPlace": "NAPOLI 1",
            "courierDate": "26-08-2016"
        }]
    }
}

In caso di errore:

{
	"getTrack": {
		"error": true,
		"message": "nothing found"
	}
}

pushTrack 1.1➔pushShipment 1.2

pushTrack permette di caricare una o più spedizioni tramite una POST dei dati in formato JSON.

Come per il caricamento manuale o tramite file CSV esistono due formati:

formato "minimo" contenente 3 campi obbligatori
formato "necessario" per attivare i servizi aggiuntivi di comunicazione al cliente come Email transazionali, ecc.
il formato più completo, con sempre i primi 3 campi obbligatori, ma che contiene tutte le informazioni

I campi da valorizzare sono i seguenti:

	Nome	JSON	Obbligatorio
1	Codice Corriere^*	courier	y
2	Tracking Number^*	trackingNumber	y
3	Data spedizione (YYYY-MM-DD)^*	shipDate	y
4	Riferimento	reference	•
5	Data ordine (YYYY-MM-DD)	orderDate
6	Nome e Cognome	name	•
7	Indirizzo	street
8	Località	city
9	CAP	ZIP
10	Provincia	state
11	Nazione	country	•
12	Email	email	•
13	Telefono	telephone
14	Agente¹	agent
15	Importo²	amount
16	POD³	pod
17	Costo spedizone⁴	shipping
19	Valore custom 1⁵	custom1
20	Valore custom 2⁵	custom2
21	Valore custom 2⁵	custom3
22	Nota⁶	note
22	Data consegna (YYYY-MM-DD)⁷	deliveryDate
23	Tag⁸	tag
24	È un tracking number?⁹	isTrackingNumber
25	Righe ordine	rows

Il campo "rows" contiene le righe ordine, facoltative, nel seguente formato:

	Nome	JSON	Obbligatorio
1	Codice prodotto	sku	y
2	Nome	name	y
3	Quantità	qty	y
4	Prezzo	price	y
5	Totale riga	total	y

¹Indirizzo email di un contatto commerciale del cliente
²Eventuale importo della spedizione (da comunicare al cliente. Es: contrassegno)
³Specifica se la spedizione è Pay On Delivery (valore: 1)
⁴Eventuale costo della spedizione
⁵Campi "custom" utilizzabili a piacere (max 255 caratteri)
⁶Una nota relativa alla spedizione (max 255 char)
⁷Data richiesta consegna
⁸Una "tag" per identificare spedizioni appartenenti ad un gruppo.
⁹Se 1 quanto posto nel campo trackingNumber è il tracking number reale della spedizione
^•Campi necessari per attivare i servizi di comunicazione ai clienti aggiuntivi quale Email transazionali, ecc.

La comunicazione con il web service obbliga ad utilizzare la API key assegnata al canale nel quale si desidera importare le spedizioni.

L'indirizzo del web service è: https://api.qapla.it/1.1/pushTrack/

Codice di esempio (PHP)

Nel seguente codice di esempio vengono incapsulate due spedizioni, una "minima" e l'altra completa di tutti i dati.

<?php
$data = array(
	"apiKey" => "[API_KEY]",

	"pushTrack" => array(
		array(
			"trackingNumber" => "123987299",
			"courier" => "DHL",
			"shipDate" => "2014-08-01"
			), //minimun required fields example

		array(
			"trackingNumber" => "1Z0V5V416840696736",
			"courier" => "UPS", "shipDate" => "2014-08-02",
			"reference" => "ord. # 1674",
			"orderDate" => "2014-07-30",
			"name" => "Pepito Sbazzeguti",
			"street" => "Via Aieie, 99",
			"city" => "Parnazza",
			"ZIP" => "12345",
			"state" => "MQ",
			"country" => "IT",
			"email" => "name@domain.ext",
			"telephone" => "02342522",
			"agent" => "007@company.ext",
			"amount" => "150,00",
			"pod" => 1,
			"shipping" => "8,00",
			"custom1" => "valore custom 1",
			"custom2" => "valore custom 2",
			"custom3" => "valore custom 3",
			"note" => "This is a note",
			"deliveryDate" => "2014-07-31",
			"tag" => "customer1",
			"isTrackingNumber" => 1,
			"rows": [{
			        "sku": "B00TZMVRR4",
			        "name": "YoyoFactory Protostar Yo-Yo - Blu",
			        "qty": 1,
			        "price": "20.10",
			        "total": "20.10"
			    },
			    {
			        "sku": "OXY4",
			        "name": "OXYGENE Oxy 4",
			        "qty": 1,
			        "price": "79.80",
			        "total": "79.80"
			    }
			]
		)
	)

);

$data_string = json_encode($data);

$ch = curl_init('https://api.qapla.it/1.1/pushTrack/');
curl_setopt($ch, CURLOPT_HEADER, false);
curl_setopt($ch,CURLOPT_POST,1);
curl_setopt($ch, CURLOPT_TIMEOUT, 60);
curl_setopt($ch, CURLOPT_RETURNTRANSFER, 1);
curl_setopt ($ch, CURLOPT_SSL_VERIFYPEER, 0);
curl_setopt ($ch, CURLOPT_SSL_VERIFYHOST, 0);
curl_setopt($ch, CURLOPT_POSTFIELDS, $data_string);

$result = curl_exec($ch);

curl_close($ch);

echo $result;
?>

Ottenendo una stringa in formato JSON di questo tipo:

{
   "apiKey":"[API_KEY]",
   "pushTrack":[
      {
         "trackingNumber":"123987299",
         "courier":"DHL",
         "shipDate":"2014-08-01"
      },
      {
         "trackingNumber":"1Z0V5V416840696736",
         "courier":"UPS",
         "shipDate":"2014-08-02",
         "reference":"ord. # 1674",
         "orderDate":"2014-07-30",
         "name":"Pepito Sbazzeguti",
         "street":"Via Aieie, 99",
         "city":"Parnazza",
         "ZIP":"12345",
         "state":"MZ",
         "country":"IT",
         "email":"name@domain.ext",
         "telephone":"02342522",
         "agent":"agent@company.ext",
         "amount":"150,00",
         "pod":"1",
         "shipping":"8,00",
         "custom1":"valore custom 1",
         "custom2":"valore custom 2",
         "custom3":"valore custom 3",
         "note":"This is a note",
         "deliveryDate":"2014-07-31",
         "tag":"customer1",
         "isTrackingNumber": 1
      }
   ]
}

La risposta a questa chiamata sarà:

{
   "pushTrack":
    {
       "track":[
          {
             "result":"OK",
             "row":1,
             "url": "https://tracking.qapla.it/885e80583703b2ded2236ec4d263694b"
          },
          {
             "result":"OK",
             "row":2,
             "url": "https://tracking.qapla.it/aeb091cd3d690aa91c183b7b58989b07"
          }
       ],
       "imported":2
    }
}

In caso di errore invece ogni riga di spedizione verrà segnalata:

{
   "pushTrack":
    {
       "track":[
          {
             "result":"KO",
             "row":1,
             "error":"tracking number 1Z0V5V416840696735 already used"
          },
          {
             "result":"KO",
             "row":2,
             "error":"tracking number 1Z0V5V416840696736 already used"
          }
       ],
       "imported":0
    }
}

getTracks 1.1➔getShipments 1.2

getTracks permette di ricevere la lista delle spedizioni importate da Qapla', con un limite massimo di 100 spedizioni a chiamata.

All'indirizzo https://api.qapla.it/1.1/getTracks/ è sufficiente inviare una richiesta GET contenete i seguenti parametri:

Parametro	Descrizione
apiKey	la API key assegnata al canale che vogliamo interrogare
dateFrom/days	data ora dalla quale richiedere gli ordini in formato standard "YYYY-MM-DD HH:MM:SS" / giorni a partire dalla data odierna

Esempio

Il seguente URL

http://api.qapla.it/1.1/getTracks/?apiKey=[API-KEY]&dateFrom=2017-07-13 09:00:00

oppure

http://api.qapla.it/1.1/getTracks/?apiKey=[API-KEY]&days=0

darà come risultato uno schema uguale a quello di getTrack:

{
    "getTracks": {
        "result": "OK",
        "error": false,
        "dateFrom": "2017-07-13",
        "count": 4,
        "tracks": []
    }
}

In caso di errore:

{
    "getOrders": {
        "result": "KO",
        "error": "invalid api key"
    }
}

deleteTrack 1.1➔deleteShipment 1.2

deleteTrack permette di eliminare una spedizione.

All'indirizzo https://api.qapla.it/1.1/deleteTrack/ è sufficiente inviare una richiesta GET contenete i seguenti parametri:

https://api.qapla.it/1.1/deleteTrack/?apiKey=[API_KEY]&trackingNumber=1Z0V5V416840696735

Il risultato sarà:

{"deleteTrack": { "error": false, "result": "OK" }}

pushOrder 1.1➔pushOrder 1.2

pushOrder permette di caricare uno o più ordini tramite una POST dei dati in formato JSON.

I campi da valorizzare sono i seguenti:

	Nome	JSON	Obbligatorio
1	Riferimento ordine	id	y
2	ID ordine	orderID
3	Codice corriere	courier
4	Stato ordine	status	y
5	Data creazione	createdAt	y
6	Data aggiornamento	updatedAt	y
7	Nome	customerName	y
8	Indirizzo	customerAddress	y
9	Località	customerCity	y
10	Provincia	customerState	y
11	CAP	customerZip	y
12	Nazione^*	customerCountry
13	Indirizzo e-mail	customerEmail
14	Telefono	customerTelephone
15	Importo ordine	amount
16	Tipo pagamento	paymentType	y
17	È contrassgno (true)	isPOD
18	Note ordine	notes
19	Righe ordine	rows
20	Peso	weight
21	Colli	parcels
22	Lunghezza	length
23	Larghezza	width
24	Altezza	height

^*In formato ISO 3166-1 alpha-2 (Esempio: IT)

Il campo "rows" contiene le righe ordine, facoltative, nel seguente formato:

	Nome	JSON	Obbligatorio
1	Codice prodotto	sku	y
2	Nome	name	y
3	Quantità	qty	y
4	Prezzo	price	y
5	Totale riga	total	y

La comunicazione con il web service obbliga ad utilizzare la API key assegnata al canale nel quale si desidera importare le spedizioni.

L'indirizzo del web service è: https://api.qapla.it/1.1/pushOrder/

Codice di esempio (PHP)

Nel seguente codice di esempio vengono incapsulati due ordini.

$json ='{
    "apiKey": "[API_KEY]",
    "pushOrder": [{
            "id": "2000994",
            "orderID" : "812012",
            "courier": "BRT",
            "status": "processing",
            "createdAt": "2017-06-16 11:18:00",
            "updatedAt": "2017-06-16 16:09:20",
            "customerName": "Luca Cassia",
            "customerAddress": "Via Aieiez, 99",
            "customerCity": "Vedano Olona",
            "customerState": "VA",
            "customerZip": "21040",
            "customerCountry": "IT",
            "customerEmail": "adso@ngi.it",
            "customerTelephone": "340342522",
            "amount": "EUR 99.90",
            "paymentType": "ccash",
            "isPOD": true,
            "notes": "This is a note",
            "weight": "1.5",
            "parcels": "2",
            "length": "30",
            "width": "20",
            "height": "10",
            "rows": [{
                    "sku": "B00TZMVRR4",
                    "name": "YoyoFactory Protostar Yo-Yo - Blu",
                    "qty": 1,
                    "price": "20.10",
                    "total": "20.10"
                },
                {
                    "sku": "OXY4",
                    "name": "OXYGENE Oxy 4",
                    "qty": 1,
                    "price": "79.80",
                    "total": "79.80"
                }
            ]
        },
        {
            "id": "2000992995",
            "status": "processing",
            "createdAt": "2016-09-23 12:22:00",
            "updatedAt": "2016-09-23 14:15:20",
            "customerName": "Roberto Fumarola",
            "customerAddress": "Via Icelord, 22",
            "customerCity": "Crispiano",
            "customerState": "TA",
            "customerZip": "74012",
            "customerCountry": "IT",
            "customerEmail": "icelord@ngi.it",
            "customerTelephone": "340112233",
            "amount": "EUR 110.05",
            "paymentType": "creditcard"
        }
        ]
}';


$ch = curl_init('https://api.qapla.it/1.1/pushOrder/');
curl_setopt($ch, CURLOPT_HEADER, false);
curl_setopt($ch,CURLOPT_POST,1);
curl_setopt($ch, CURLOPT_TIMEOUT, 60);
curl_setopt($ch, CURLOPT_RETURNTRANSFER, 1);
curl_setopt ($ch, CURLOPT_SSL_VERIFYPEER, 0);
curl_setopt ($ch, CURLOPT_SSL_VERIFYHOST, 0);
curl_setopt($ch, CURLOPT_POSTFIELDS, $json);

$result = curl_exec($ch);

curl_close($ch);

echo $result;

La risposta a questa chiamata sarà:

{
    "pushOrder": {
        "result": "OK",
        "error": "",
        "count": 2,
        "orders": [{
            "row": 1,
            "action": "ins",
            "id": "2000992994"
        }, {
            "row": 2,
            "action": "upd",
            "id": "2000992995"
        }],
        "imported": 0,
        "updated": 0
    }
}

Dove "action" prevede i seguenti valori:

ins: ordine inserito
upd: ordine aggiornato
none: nessuna azione intrapresa

In caso di errore:

{
    "pushOrder": {
        "result": "KO",
        "error": "invalid api key"
    }
}

getOrders 1.1➔getOrders 1.2

getOrders permette di ricevere la lista degli ordini importati da Qapla', con un limite massimo di 100 ordini a chiamata.

All'indirizzo https://api.qapla.it/1.1/getOrders/ è sufficiente inviare una richiesta GET contenete i seguenti parametri:

Parametro	Descrizione
apiKey	la API key assegnata al canale che vogliamo interrogare
dateFrom/days	data ora dalla quale richiedere gli ordini in formato standard "YYYY-MM-DD HH:MM:SS" / giorni a partire dalla data odierna

Esempio

Il seguente URL

http://api.qapla.it/1.1/getOrders/?apiKey=[API-KEY]&dateFrom=2017-07-13 09:00:00

oppure

http://api.qapla.it/1.1/getOrders/?apiKey=[API-KEY]&days=0

darà come risultato uno schema uguale a quello di pushOrder:

{
    "getOrders": {
        "result": "OK",
        "error": "",
        "dateFrom": "2017-07-13",
        "count": 2,
        "orders": [{
            "source": "magento",
            "importedAt": "2017-07-13 16:00:13",
            "reference": "100001408",
            "courier": "",
            "status": "processing",
            "createdAt": "2017-07-08 00:00:00",
            "updatedAt": "2017-07-08 00:00:00",
            "customerName": "Yolanda Rios",
            "customerAddress": "via G. Bonaventura 2",
            "customerCity": "Cerveteri",
            "customerState": "RM",
            "customerZip": "00052",
            "customerCountry": "IT",
            "customerEmail": "testQapla-1@qaplatest.it",
            "customerTelephone": "340342522",
            "amount": "EUR 29.",
            "paymentType": "gene_braintree_paypal",
            "isPOD": false,
            "notes": "",
            "weight": "1",
            "parcels": "1",
            "length": "0",
            "width": "0",
            "height": "0",
            "rows": []
        }, {
            "source": "woocommerce",
            "importedAt": "2017-07-13 16:00:13",
            "reference": "1033815D",
            "courier": "",
            "status": "processing",
            "createdAt": "2017-07-08 00:00:00",
            "updatedAt": "2017-07-08 00:00:00",
            "customerName": "Lucio Settimio Severo",
            "customerAddress": "Via Gualtiero Serafino,20",
            "customerCity": "Roma",
            "customerState": "RM",
            "customerZip": "00136",
            "customerCountry": "IT",
            "customerEmail": "testQapla--7@qaplatest.it",
            "customerTelephone": "340342522",
            "amount": "€ 5.50",
            "paymentType": "Amazon",
            "isPOD": false,
            "notes": "",
            "weight": "1",
            "parcels": "1",
            "length": "0",
            "width": "0",
            "height": "0",
            "rows": [{
                "sku": "CIACAR.Panbau_300_neu",
                "name": "Protobread 300g",
                "qty": 6.0000,
                "price": "7.7300",
                "total": "46.3600"
            }, {
                "sku": "ciaocarb_protopiadina",
                "name": "Protopiadina 2 x 50g",
                "qty": 4.0000,
                "price": "3.6700",
                "total": "14.6900"
            }]
        }]
    }
}

In caso di errore:

{
    "getOrders": {
        "result": "KO",
        "error": "invalid api key"
    }
}

getCouriers 1.1➔getCouriers 1.2

getCouriers permette di richiedere l'elenco dei corrieri sia totale, sia per singola nazione /ragione.

All'indirizzo https://api.qapla.it/1.1/getCouriers/ è sufficiente inviare una richiesta GET contenete i seguenti parametri:

https://api.qapla.it/1.1/getCouriers/?apiKey=[API_KEY]&country=it,global

Il risultato sarà:

{
	"getCouriers": {
		"result": "OK",
		"error": null,
		"count": 58,
		"courier": [{
			"code": "ARAMEX",
			"name": "Aramex",
			"country": "global"
		}, {
			"code": "ARCO",
			"name": "Arco Spedizioni",
			"country": "it"
		}, {
			"code": "ARTONI",
			"name": "Artoni",
			"country": "it"
		},
        ...
    ]
	}
}

I valori per il campo "country" sono i seguenti:

getCredits 1.1➔getCredits 1.2

getCredits permette di ottenere l'ammontare dei crediti rimanenti sul prorpio account premium.

All'indirizzo https://api.qapla.it/1.1/getCredits/ è sufficiente inviare una richiesta GET contenete i seguenti parametri:

https://api.qapla.it/1.1/getCredits/?apiKey=[API_KEY]

Il risultato sarà:

{"getCredits": { "result": "OK", "credits": 100, "date": "2017-02-14 11:07:17" }}