API Ver. 1.1

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
dedicata alla lettura dello stato della spedizione sia in formato JSON che XML

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

deleteTrack
che permette la cancellazione di una spedizione.

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

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

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

getCredits
per ottenere i crediti rimanenti sul proprio acount premium.

getCouriers
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

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:

ParametroDescrizione
apiKeyla API key assegnata al canale che vogliamo interrogare
trackingNumber | referenceil tracking number interessato | il riferimento ordine
langla 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

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:

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

I campi da valorizzare sono i seguenti:
NomeJSONObbligatorio
1Codice Corriere*couriery
2Tracking Number*trackingNumbery
3Data spedizione (YYYY-MM-DD)*shipDatey
4Riferimentoreference
5Data ordine (YYYY-MM-DD)orderDate
6Nome e Cognomename
7Indirizzostreet
8Localitàcity
9CAPZIP
10Provinciastate
11Nazionecountry
12Emailemail
13Telefonotelephone
14Agente1agent
15Importo2amount
16POD3pod
17Costo spedizone4shipping
19Valore custom 15custom1
20Valore custom 25custom2
21Valore custom 25custom3
22Nota6note
22Data consegna (YYYY-MM-DD)7deliveryDate
23Tag8tag
24È un tracking number?9isTrackingNumber
25Righe ordinerows

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

NomeJSONObbligatorio
1Codice prodottoskuy
2Nomenamey
3Quantitàqtyy
4Prezzopricey
5Totale rigatotaly
1Indirizzo email di un contatto commerciale del cliente
2Eventuale importo della spedizione (da comunicare al cliente. Es: contrassegno)
3Specifica se la spedizione è Pay On Delivery (valore: 1)
4Eventuale costo della spedizione
5Campi "custom" utilizzabili a piacere (max 255 caratteri)
6Una nota relativa alla spedizione (max 255 char)
7Data richiesta consegna
8Una "tag" per identificare spedizioni appartenenti ad un gruppo.
9Se 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

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:

ParametroDescrizione
apiKeyla API key assegnata al canale che vogliamo interrogare
dateFrom/daysdata 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

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.2

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

I campi da valorizzare sono i seguenti:

NomeJSONObbligatorio
1Riferimento ordineidy
2ID ordineorderID
3Codice corrierecourier
4Stato ordinestatusy
5Data creazionecreatedAty
6Data aggiornamentoupdatedAty
7NomecustomerNamey
8IndirizzocustomerAddressy
9LocalitàcustomerCityy
10ProvinciacustomerStatey
11CAPcustomerZipy
12Nazione*customerCountry
13Indirizzo e-mailcustomerEmail
14TelefonocustomerTelephone
15Importo ordineamount
16Tipo pagamentopaymentTypey
17È contrassgno (true)isPOD
18Note ordinenotes
19Righe ordinerows
20Pesoweight
21Colliparcels
22Lunghezzalength
23Larghezzawidth
24Altezzaheight
*In formato ISO 3166-1 alpha-2 (Esempio: IT)

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

NomeJSONObbligatorio
1Codice prodottoskuy
2Nomenamey
3Quantitàqtyy
4Prezzopricey
5Totale rigatotaly

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:

In caso di errore:

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

getOrders

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:

ParametroDescrizione
apiKeyla API key assegnata al canale che vogliamo interrogare
dateFrom/daysdata 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

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:
ch
cn
de
es
eu
fr
gb
global
gr
hk
it
nl
us

getCredits

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" }}