Through our API it is possible to integrate Qapla’ with your proprietary eCommerce both in writing and reading mode or with an eCommerce that doesn’t have a plugin or a connector implemented.

To use our API you need your API Key assigned to your channel/channels in:
Settings > [Channel Name] > 1. Channel > Private API Key

API Ver. 1.1

getTrack
read the status of a shipment in Qapla’ and obtain a response both in Json and XML format

pushTrack
insert one or more shipments in Qapla’

deleteTrack
delete a shipment

getCouriers
get the couriers list, with name and internal Qapla’ ID

pushOrder
insert one or more orders in Qapla’

getOrders
permit to obtain a list of oders in Qpala’ database in a given date range

To use Qapla’ API you need your channel API Key, every channel has it’s own Private API Key.

 


getTrack 1.1

getTrack permits to read the status of a shipment using tracking number or your order reference.
On https://api.qapla.it/1.1/getTrack/ you can send a GET request with the below parameters:

Parameter Description
auth you channel API
trackingNumber | reference tracking number | your reference numbers
lang Language (ita o eng), default: ita

Example

URL with Tracking number

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

or URL with reference number

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

results

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

if there is and error the output will be:

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

 


pushTrack

With pushTrack you can add one or more shipments with a JSON format.
There are two methods of set of datas that you can submit:

  1. “minimum” format containing 3 mandatory fields
  2. format “required” to enable additional customer communication services such as transactional Emails, etc.
  3. the most complete format, always with the first 3 mandatory fields, but containing all the information

The fields to be valued are the following:

Name JSON mandatory
1 Courier Code* courier y
2 Tracking Number* trackingNumber y
3 Shipping date (YYYY-MM-DD)* shipDate y
4 Order Reference reference
5 Order date (YYYY-MM-DD) orderDate
6 Name and Surname name
7 Street street
8 City city
9 ZIP/Postal code ZIP
10 State/Province state
11 Country country
12 Email email
13 Telephone telephone
14 agent1 agent
15 Order amount2 amount
16 Pay on Delivery3 pod
17 Shipping Cost4 shipping
19 Custom value 15 custom1
20 Custom value 25 custom2
21 Custom value 35 custom3
22 Note6 note
22 Delivery date (YYYY-MM-DD)7 deliveryDate
23 Tag8 tag

1Mail address of commercial contact
2Amount of order, used in end user comunications. i.e for Pay on delivery orders
3If the order is a Pay on delivery use the value 1
4Shipping cost
5Custom fields used (max 255 chars)
6A note and further information on the shipping (max 255 chars)
7Delivery date estimation
8one “TAG” that permit to filter and aggregate shipping in the control panel
Mandatory field to enable transactional email and SMS to end users. Without this values Qapa’ can’t sent this kind of communications

Communication with the web service obliges you to use the API key assigned to the channel in which you want to import the shipments.

Web Service URL is: https://api.qapla.it/1.1/pushTrack/

Example code (PHP)

The following sample code encapsulates two shipments, one “minimum” and the other complete with all the data.

<?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"
		)
	)

);

$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;
?>

Obtaining a JSON string of this type:

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

The answer to this call is:

{  
   "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 case of error, each shipping line will be reported:

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

deleteTrack

deleteTrack allows you to delete a shipment.
In https://api.qapla.it/1.1/deleteTrack/ , just submit a GET request containing the following parameters:

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

The result will be:

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

 


getCouriers

getCouriers allows you to request the list of couriers for both total and single country / region.
At https://api.qapla.it/getCouriers/ , just submit a GET request containing the following parameters:

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

The result will be:

{  
   "getCouriers":{  
      "error":false,
      "courier":[  
         {  
            "code":"BRT",
            "name":"BRT",
            "country":"it"
         },
         {  
            "code":"GLS-ITA",
            "name":"GLS Italia",
            "country":"it"
         },
         {  
            "code":"PTI",
            "name":"Poste Italiane",
            "country":"it"
         },
         {  
            "code":"SDA",
            "name":"SDA",
            "country":"it"
         },
         {  
            "code":"TNT-ITA",
            "name":"TNT Italia",
            "country":"it"
         }
      ]
   }
}

The values for “country” fields:

ch
de
es
eu
fr
gb
global
it
nl
us


pushOrder

pushOrder allows you to load one or more orders through a POST of JSON-formatted data.
The fields to be valued are:

Name JSON Mandatory
1 Order Reference id y
2 Order ID orderID
3 Courier code courier
4 Order Status status y
5 Order date createdAt y
6 Update date updatedAt y
7 Customer Name/Surname customerName y
8 Customer Address customerAddress y
9 City customerCity y
10 State/Province customerState y
11 ZIP/Postal code customerZip y
12 Country* customerCountry
13 Customer e-mail customerEmail
14 Customer telephone customerTelephone
15 Order amount amount
16 Payment paymentType y
17 Pay on delivery (true) isPOD
18 Note notes
19 Orders rows rows
20 Weight weight
21 Number of parcels parcels
22 Legth length
23 Width width
24 Height height

*In ISO 3166-1 alpha-2 Format (example: IT)The “rows” field contains the order lines, optional, in the following format:

Name JSON Mandatory
1 Product code sku y
2 Name/Description name y
3 Quantity qty y
4 Prezzo price y
5 Totale riga total y

The communication with the WebServices forces to use the API Key assigned to your channel where orders will be imported.

The WebService address URL is: https://api.qapla.it/1.1/pushOrder/

Example code (PHP)

The following sample code encapsulates two orders:

$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;

The answer to this call is:

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

Where “action” considers the following values:

  • ins: inserted order
  • upd: order updated
  • none: no action undertaken

In case of error:

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


getOrders

getOrders permits to receive a list of orders imported from Qapla’, maximum limit of 100 orders each call.
The following URL is enough to send the GET request which includes the following parameters: https://api.qapla.it/1.1/getOrders/

Parameter Description
auth the API key assigned to the channel you want to query
dateFrom/days date and time from which request orders in standard format “YYYY-MM-DD HH:MM:SS” / days from today’s date

Example

The following URL

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

or

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

the result will be the same as the pushOrder result:

{
    "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 case of error:

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