New API v2

The new API v2 are being released, featuring new functionalities and a new, more secure authentication method.

Introduction

APIs provide the possibility to integrate Qapla' both for reading and writing with your own ecommerce system or for an e-commerce to which a plugin or connector has not yet been implemented.

Qapla' API is based on REST.
Accepts GET, POST, PUT and DELETE JSON encoded requests.
Returns JSON encoded values.
The reference time zone is CEST, which corresponds to UTC + 2 when daylight saving time is in effect, or UTC + 1 when standard time is in effect.

Latest version available

This is the latest version of the APIs. Not all APIs have been migrated to version 1.3 yet; as new features are added, they will be updated.

APIs that haven't been updated yet still refer to version 1.2

Previous versions

Previous versions of this API are still active, but considered as deprecated.

API 1.2 DEPRECATED
API 1.1 DEPRECATED
API 1.0

Webhook

Qapla' also has a Webhook service which is an integral part of the API.

API Key

In oder to use the APIs, it is necessary to know the Private API Keys assigned to your channel(s), available on the Control Panel in the section:

Settings > Channels > [CHANNEL_NAME] > "Configure" > Channel > Private API Key

This API key must be protected and kept secret.

Endpoint

https://api.qapla.it/[API_VERSION]/[ENDPOINT]

[API_VERSION]	It is the version value of the API.
[ENDPOINT]	It is the endpoint you need to invoke.

Response

The JSON response to a Request uses this standard format

[API_NAME]	The name of the API consumed
[OK/KO]	OK in case of a positive answer, KO In case of an error
[ERROR_MESSAGE]	It is null in case of OK and will contain the error in case of KO

Rate limiting

The system uses the TokenBucket algorithm with the following parameters:

Bucket capacity	120	Maximum of 120 requests
Tokens per second	2	Refilling at a rate of 2 per second

Warning
A multiple request (e.g. pushShipment or pushOrder with 100 shipments or orders) is evaluated as 100 tokens.

HTTP Response Status Codes

Exceeding the limit will lead to the following HTTP response

429 Too Many Requests

and the following response error by any API involved

"error": "Too Many Requests"

Abuse

The abuse of the use will lead to a BAN of the API Key.

Sandbox

There isn't any proper sandbox environment. However you can use the sandbox field in the API methods (where supported) to use the test infrastructure, without having operational effects (like costs, picking requests sent to the carries, etc...)

Test

Once the API Key has been obtained, a connection test can be immediately performed using the API getChannel.

Postman Collection

A Postman Collection is available.

Shipments

The primary key to identify a shipment is:

Channel, represented by API Key
Courier, "courier"
Tracking number, "trackingNumber"

pushShipment

pushShipment allows you to upload one or more shipments through a POST of data in JSON format.

In combination with the Webhook creates an integrated shipping management system.

POSThttps://api.qapla.it/1.3/pushShipment/

REQUEST
RESPONSE

Request

In this example, two shipments are loaded, one in "minimum" and one "complete" format.

{
  "apiKey": "[API_KEY]",
  "pushShipment": [
    {
      "trackingNumber": "123987299",
      "courier": "DHL",
      "shipDate": "2014-08-01"
    },
    {
      "trackingNumber": "1Z0V5V416840696736",
      "courier": "UPS",
      "shipDate": "2014-08-02",
      "reference": "ord. # 1674",
      "orderDate": "2014-07-30",
      "parcels": [{
        "weight": 1.3,
        "length": 10,
        "width": 15,
        "height": 5,
        "boxCode": null,
        "content": null,
        "originCountry": null
      }],
      "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": false,
      "shipping": 8.00,
      "custom1": "valore custom 1",
      "custom2": "valore custom 2",
      "custom3": "valore custom 3",
      "note": "This is a note",
      "language": "it",
      "deliveryDate": "2014-07-31",
      "latestShipDate": "2014-08-03",
      "latestDeliveryDate": "2014-08-05",
      "tag": "customer1",
      "isTrackingNumber": false,
      "origin": "magento",
      "isReturnable": true,
      "platformOrderID": "1234567890",
      "rows": [
        {
          "sku": "BAR-301",
          "name": "Barrette di Crusca d'Avena con Cioccolato (4 pezzi) 120g",
          "qty": 1,
          "weight": 1.5,
          "url": "https://www.iltuosito.it/alimenti/barretta-al-cocco",
          "imageUrl": "https://www.iltuosito.it/img/alimenti/barretta-al-cocco.jpg",
          "price": 6.35,
          "total": 6.35,
          "isReturnable": true,
          "customsCode": null,
          "originCountry": null,
          "netWeight": null,
          "unitOfMeasurement": null,
          "parcelID": null,
          "transparencyCodes": [
            "ABC123",
            "DEF456"
          ],
          "custom1": "valore custom 1",
          "custom2": "valore custom 2",
          "custom3": "valore custom 3",
          "custom4": "valore custom 4",
          "custom5": "valore custom 5"
        },
        {
          "sku": "BEV-001",
          "name": "Bevanda al mango in polvere 9g",
          "qty": 5,
          "weight": 1,
          "url": "https://www.iltuosito.it/alimenti/barretta-al-cocco",
          "imageUrl": "https://www.iltuosito.it/img/alimenti/barretta-al-cocco.jpg",
          "price": 0.38,
          "total": 1.9,
          "isReturnable": true,
          "customsCode": null,
          "originCountry": null,
          "netWeight": null,
          "unitOfMeasurement": null,
          "parcelID": null,
          "custom1": "valore custom 1",
          "custom2": "valore custom 2",
          "custom3": "valore custom 3",
          "custom4": "valore custom 4",
          "custom5": "valore custom 5"
        }
      ]
    }
  ]
}

Parameters

There are 3 types of shipment loading modes.

"minimum" containing 3 mandatory fields^*
"necessary" to activate additional communication services to the customer such as transactional emails, etc.^•
"complete" always with the first 3 mandatory fields, but containing all the information

^*Mandatory parameter

^•Parameter required to activate transactional emails and / or SMS

⚠
The maximum number of shipments that can be sent for individual request is 100.

apiKey(string) The API Key assigned to the channel into which you want to import shipments

pushShipment(array)

It is an array of maximum 100 shipments to load.

trackingNumber^*(string) The tracking number / shipping number / waybill of the courier

courier^*(string) The Qapla' courier code.

Also accepts a courier variant code (e.g. BRT-V1) if configured for the channel. Available variants are listed in the variants field of the getCouriers response.
Note: if a variant code is passed that is not configured for the channel, the shipment is rejected with an explicit KO error.

shipDate^*(string) Shipment date

reference^•(string) Order reference

platformOrderID(string) Optional numeric or alphanumeric ID, used as additional order reference

orderDate(string) Order date

parcels(array)

Possible parcels of the delivery. Each shipment can be defined through an object composed as follows:

weight(float)	Potential weight of the order. Mandatory if the "boxCode" is not sent
length(float)	Potential measurements: length. Mandatory if the "boxCode" is not sent
width(float)	Potential measurements: width. Mandatory if the "boxCode" is not sent
height(float)	Potential measurements: height. Mandatory if the "boxCode" is not sent
boxCode(string)	Potential box code (if used, measurements will be taken from the box with the corresponding code)
originCountry(string)	Potential Country of origin of the package in ISO 3166-1 alpha-2 format (Example: IT)
content(string)	Potential description of the content

name^•(string) Recipient Name

street(string) Recipient address

city(string) Recipient City

ZIP(string) Recipient postal code

state(string) Recipient province

country(string) Recipient country in format ISO 3166-1 alpha-2 (Example: IT)

email^•(string) Recipient email

telephone^•(string) Recipient telephone

agent(string) Email address of a customer business contact

amount(float) Potential amount of the shipment (to be communicated to the customer. Ex: cash on delivery)

pod(boolean) It is true if payment is cash on delivery

shipping(float) Potential cost of shipment

custom1(string) Custom value 1

custom2(string) Custom value 2

custom3(string) Custom value 3

note(string) A note regarding the shipment (max 255 chars)

language(string) Shipment language ( ISO 639-1 , ex: 'fr').
A null or unrecognized value will indicate the shipment as 'it'.

origin(string)

Origin of shipment, permitted values:

    ahlens, aliexpress, allegro, alltricks, amazon, animalis, anthropologie, asos, atlasformen, auchan, bandq, beerwulf, bestsecret,
    bhv, bigcommerce, bild, blackredwhite, blokker, boots, brandalley, bricobravo, bricodepot, bricomarche, bricoprive, bulevip, but, carrefour_es,
    carrefour_fr, casadellibro, castorama, cdiscount, commercelayer, conforama, creavea, cultura, darty, debenhams, decathlon, douglas, ebay, ecwid,
    elcorteingles, elkjop, ellos, empik, eprice, etsy, fanatics, feelunique, fnac, fonq, freepeople, fressnapf, gifi, greenweez_fr, handm, home24, ibs,
    incomedia, lafayette, laredoute, leroyMerlin_it, magento, magento2, maisonDuMonde_es, maisonDuMonde_it, manomano, manomano_de, manomano_es, manomano_fr,
    manomano_gb, manomano_it, matalan, mathon, maty, maykers, mediaMarkt_at, mediaMarkt_de, mediaMarkt_es, mediaMarkt_it, mediaMarkt_nl, miravia_es, modivo_pl,
    mountainwh, natureetdeco, newcart, nocibe, obelink, pandacola, pccomponentes, perfumesclub, phonehouse, pixmania, placedestend, planetahuerto, pourdebon,
    prestashop, printemps, privalia, privalia_es, privalia_it, privsportshop, public, quirumed, redcarepharmacy, rueducommerce, sarenza, shopapotheke, shopify,
    shopware6, showroomprive, slood, spartoo, spartoo_be, spartoo_bg, spartoo_cn, spartoo_com, spartoo_comhr, spartoo_couk, spartoo_cz, spartoo_de, spartoo_dk,
    spartoo_es, spartoo_fi, spartoo_fr, spartoo_gb, spartoo_gr, spartoo_hu, spartoo_it, spartoo_nl, spartoo_pl, spartoo_pt, spartoo_ro, spartoo_se, spartoo_si, spartoo_sk, sprinter_es,
    stadium, storeden¤, superdrug, teamsystemcommerce¤tiendanimal, tradeinn, truffaut, twil, ubaldi, urbanoutfitters, venca, venteunique, vivino, vtex, watchfinder,
    winesitting, woocommerce, wook, worten_es, worten_pt, yoox

^¤storeden and teamsystemcommerce can be used as synonyms

isReturnable(bool) If it is true, it indicates the possibility of returning the entire shipment.

deliveryDate(string) Potential delivery request date

latestShipDate(string) To be shipped by this date in the YYYY-MM-DD format

latestDeliveryDate(string) To be delivered by this date in the YYYY-MM-DD format

tag(string) A "tag" to identify shipments belonging to a group.

isTrackingNumber(bool) It is true when placed in the trackingNumber field it is the real tracking number of the shipment.

rows

It is an array of "order lines".

It is not mandatory, but if populated it has some data that is.

sku^*(string)

Article code

name^*(string)

Article description

qty^*(int)

Quantity

price^*(float)

Price

total(float)

Total price

weight(float)

Potential article weight

url(string)

The specific url of the product

imageUrl(string)

The url of the product image

notes(string)

Product notes

customsCode(string)

Potential code used for customs (HSCode, Taric, etc.)

originCountry(string)

Product's country of origin ISO 3166-1 alpha-2 (Esempio: IT)

netWeight(float)

Potential net weight of the product

unitOfMeasurement(string)

Generale
DHL

Potential unit of measurement

Code	Description
BOX	Boxes
2GM	Centimeters
2M3	Cubic Centimeters
3M3	Cubic Feet
M3	Cubic Meters
DPR	Dozen Pairs
DOZ	Dozen
2NO	Each
PCS	Pieces
GM	Grams
GRS	Gross
KG	Kilograms
L	Liters
M	Meters
3GM	Milligrams
3L	Milliliters
X	No Unit Required
NO	Number
2KG	Ounces
PRS	Pairs
2L	Gallons
3KG	Pounds
CM2	Square Centimeters
2M2	Square Feet
3M2	Square Inches
M2	Square Meters
4M2	Square Yards
3M	Yards
CM	Centimeters
CONE	Cone
CT	Carat
EA	Each
LBS	Pounds
RILL	Rill
ROLL	Roll
SET	Set
TU	Time Unit
YDS	Yard

parcelID(int)

Potential progressive number, identifying the package number in which the product is shipped

transparencyCodes(string[])

Transparency Code array

custom1(string)

value custom 1

custom2(string)

value custom 2

custom3(string)

value custom 3

custom4(string)

value custom 4

custom5(string)

value custom 5

Response Body`200`

Errors

In case of error, each shipping line will be reported:

getShipment

getShipment allows you to read the status of a shipment through the tracking number, the order reference or the ID.

For a total and integrated management of the update cycle of shipments, also evaluate the Webhook.

🛈
Remember the usage limits and also evaluate the Webhook.

GEThttps://api.qapla.it/1.3/getShipment/?apiKey=[API_KEY]&trackingNumber=[TRACKING_NUMBER]

GEThttps://api.qapla.it/1.3/getShipment/?apiKey=[API_KEY]&reference=[ORDER_REFERENCE]

GEThttps://api.qapla.it/1.3/getShipment/?apiKey=[API_KEY]&id=[SHIPMENT_ID]

GEThttps://api.qapla.it/1.3/getShipment/?apiKey=[API_KEY]&custom1=[CUSTOM1]

REQUEST
RESPONSE

Parameters

Parameter

Description

apiKey^*(string)

The API Key assigned to the channel we want to query

Exclusive parameters

trackingNumber(string)

The interested tracking number

reference(string)

The order reference

id(int)

Shipment ID

custom1, custom2, custom3(string)

The fields custom1, custom2, custom3

Optional parameters

lang

The language of the names of the Qapla' status (it, en, es), default: it.

Example:

&lang=en

data

The flag data specifies which and how much data we want to receive, by default it returns minimal data on the progress of the shipment.
It can have the following values:

Parameter	Description
	If no parameter is specified, it will be returned the minimum data
all	Minimum data + all the data to follow
consignee	Minimum data + recipient data
children	Minimum data + data of child shipments, if any
parent	Minimum data + data of the parent shipment, if any
flag	Minimum data + data relating to the report of the shipment, if any
notifications	Minimum data + notification data (email sms, webhook, qaplAPP)
history	Minimum data + shipment tracking history
rows	Minimum data + product rows
parcels	Minimum data + parcels information
deliveryInfo	Minimum data + information on shipping methods (ship by, delivery by)

The parameter can be combined separated by commas, for example

&data=consignee,history

in order to get only these data.

Response Body`200`

{
  "getShipment": {
    "result": "OK",
    "error": null,
    "version": "1.3.0",
    "lang": "it",
    "count": 1,
    "shipments": [
      {
        "id": 1690120025,
        "hash": "347513728eab0009bfc60cc47acaffd0",
        "url": "https://tracking.qapla.it/347513728eab0009bfc60cc47acaffd0",
        "reference": "RAD000UFPL",
        "trackingNumber": "080010017684806",
        "isDeleted": false,
        "isArchived": false,
        "origin": {
          "code": "magento",
          "name": "Magento",
          "icon": "https://cdn.qapla.it/origin/magento.svg"
        },
        "courier": {
          "code": "BRT",
          "name": "BRT",
          "icon": "https://cdn.qapla.it/courier/BRT.svg",
          "note": null,
          "estimatedDeliveryDate": null,
          "courierEstimatedDeliveryDate": null,
          "trackingURL": "https://brt.it/tracking/fooandnoes"
        },
        "status": {
          "date": "2019-06-14 06:15",
          "dateISO": "2019-06-14 06:15:00",
          "status": "ON_THE_ROAD",
          "place": "RIVALTA (TO) (IT)",
          "qaplaStatus": {
            "id": 3,
            "status": "IN TRANSIT",
            "detailID": 0,
            "detail": null,
            "color": "#1D76D8",
            "icon": "https://cdn.qapla.it/status/3.svg"
          },
          "dateUpd": "2019-06-14 15:53:15",
          "lastCheck": "2019-06-14 22:17:13"
        },
        "shipDate": "2019-06-13",
        "orderDate": "2019-01-31",
        "dateIns": "2019-06-14 15:49:18",
        "consignee": {
          "name": "Luca Cassia",
          "address": "Via Campazzino, 12",
          "city": "Milano",
          "state": "MI",
          "postCode": "20100",
          "country": "IT",
          "email": "adso@defanchisgiocattoli.it",
          "isAmazon": false,
          "phone": "02343522"
        },
        "language": "it",
        "newTrackingNumber": null,
        "oldTrackingNumber": null,
        "hasNewTrackingNumber": false,
        "isTrackingNumber": true,
        "returnTrackingNumber": null,
        "isReturnShipment": false,
        "isCOD": false,
        "amountText": null,
        "amount": null,
        "isDelivered": false,
        "isChild": true,
        "parent": {
          "id": "2010200",
          "reference": "AD000UFPL",
          "rackingNumber": "090010015489",
          "courier": "BRT",
          "url": "https://api.qapla.it/1.3/getShipment/?apiKey=XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX&id=0000000"
        },
        "hasChildren": true,
        "children": [
          {
            "id": "121029109",
            "reference": "303-XX11XX-5621132",
            "trackingNumber": "0844!!!!7689193",
            "courier": "DPD",
            "url": "https://api.qapla.it/1.3/getShipment/?apiKey=XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX&id=000001"
          }
        ],
        "trueTrackingNumber": null,
        "altTrackingNumber": null,
        "custom1": null,
        "custom2": null,
        "custom3": null,
        "deliveryMode": "pickup",
        "hasFlag": true,
        "latestShipDate": "2018-04-03",
        "latestDeliveryDate": "2018-04-05",
        "flag": {
          "description": "Ritardo Courier",
          "note": "telefonato a Pino"
        },
        "notifications": {
          "email": [
            {
              "result": "OK",
              "statusID": 3,
              "status": "IN TRANSIT",
              "date": "2019-06-14 16:00:08",
              "error": false,
              "isOpened": true
            }
          ],
          "sms": [
            {
              "result": "OK",
              "statusID": 20,
              "status": "PARTITO",
              "date": "2019-06-14 18:50:29"
            }
          ],
          "webhook": [
            {
              "statusID": 3,
              "date": "2019-06-14 23:51:06",
              "result": "OK",
              "status": "IN TRANSITO"
            }
          ],
          "qaplAPP": [
            {
              "statusID": 4,
              "result": "OK",
              "date": "2019-06-15 08:00:00",
              "status": "IN COSEGNA"
            },
            {
              "statusID": 3,
              "result": "OK",
              "date": "2019-06-14 19:15:09",
              "status": "IN TRANSITO"
            }
          ]
        },
        "trackingHistory": [
          {
            "date": "2019-06-14 06:15",
            "dateISO": "2019-06-14 06:15:00",
            "status": "IN TRANSIT",
            "place": "RIVALTA (TO) (IT)",
            "qaplaStatus": {
              "id": 3,
              "status": "IN TRANSIT",
              "detailID": 0,
              "detail": null,
              "color": "#1D76D8",
              "icon": "https://cdn.qapla.it/status/3.svg"
            }
          },
          {
            "date": null,
            "dateISO": null,
            "status": "PARCEL HANDED TO DPD",
            "place": null,
            "qaplaStatus": {
              "id": 20,
              "status": "DEPARTED",
              "detailID": 0,
              "detail": null,
              "color": "#8A2BE2",
              "icon": "https://cdn.qapla.it/status/20.svg"
            }
          }
        ]
      }
    ]
  }
}

Description

result The result of the operation: OK or KO in case of error

error The error in case of result: KO

version The API version

lang The required language / transferred as parameter (default: it)

count Number of current shipments

shipments

It is an array that can contain more than one shipment

id Shipment ID

hash The hash of the shipment, used for example by the tracking page

url Web address of the tracking page of this shipment

reference Order reference

trackingNumber The tracking number

isDeleted It is true (boolean value) if the shipment is cancelled

isArchived It is true (boolean value) if the shipment is filed

origin The origin of the shipment if loaded (es: magento, prestashop, amazon, ecc)

courier

code	Courier code
name	Name of the courier
icon	Icon's URL of the courier
note	Possible notes from the courier on the shipment
estimatedDeliveryDate	Possible estimated date of expected delivery, the one declared by whoever created the shipment
courierEstimatedDeliveryDate	Possible delivery date announced by the courier (`YYYY-MM-DD`), `null` until the courier publishes one. Same information as `note`, read as a date instead of a sentence
url	Address URL of the courier
trackingURL	Tracking URL address of the courier for this shipment

status

Current status of the shipment

date

Status date, as reported by the courier

dateISO

The ISO version YYYY-MM-DD HH:MM:SS of the date communicated by the courier

status

Status communicated by the courier

place

Location communicated by the courier

qaplaStatus

The "translation" of the status of the courier in the status of Qapla'

id	The ID of the status
status	The description
detailID	ID of the possible detail
detail	Description of the possible detail
color	The color assigned by Qapla' to the status
icon	Status icon

dateUpd

The date in which the shipment status has been updated on Qapla'

lastCheck

The date of the last control of the shipment status

shipDate The shipment date communicated when the shipment is loaded

orderDate The order date communicated when the shipment is loaded

dateIns The upload date of the shipment

consignee

Recipient data

name	Recipient name
address	Recipient address
city	Recipient city
state	Recipient province
country	Recipient country
email	Recipient email
isAmazon	It is true (boolean value) if the recipient email is from Amazon
phone	Recipient telephone number

language The language in which the shipment will "speak" when notifications such as email or SMS are sent

newTrackingNumber Possible new tracking number assigned to shipment

oldTrackingNumber Possible old tracking number in case it has been populated the field newTrackingNumber

hasNewTrackingNumber It is true (boolean value) if the shipment has obtained a new tracking number

isTrackingNumber It is true (boolean value) if the trackingNumber value contains the true tracking number

trueTrackingNumber It contains the potential "true" tracking number

altTrackingNumber It contains an alternative tracking number in case the shipment has changed it for the same courier during the trip

returnTrackingNumber It indicates any return tracking number if different from the outward one

isReturnShipment It is true (boolean value) if the shipment is a return / restitution shipment

isCOD It is true (boolean value) if the shipment is cash on delivery

amountText The textual amount of the shipment

amount The amount as a float number

isDelivered It is true (boolean value) if the shipment is delivered

isChild It is true (boolean value) if the shipment is "daughter" of another shipment, in this case the "parent" field will be populated

parent

The "father" shipment

id	Shipment ID
reference	The order reference of the shipment
trackingNumber	The order tracking number of the shipment
courier	The courier code of the shipment
url	The URL to this same API to call back the "father" shipment

hasChildren It is true (boolean value) if the shipment has "children", in this case the "children" field will be populated

children

It is an array of "child" shipments

id	Shipment ID
reference	The order reference of the shipment
trackingNumber	The order tracking number of the shipment
courier	The courier code of the shipment
url	The URL to this same API to call back the "father" shipment

custom1 The custom1 value as imported

custom2 The custom2 value as imported

custom3 The custom3 value as imported

deliveryMode It can assume the values "home" for a delivery direct to the recipient or "pickup" for a delivery direct to a collection point (Pickup point)

hasFlag It is true (boolean value) if the shipment has been "reported", in this case the "flag" field is populated

flag

Description	The description of the flag
Note	The potential note

notifications

All notifications sent by status for this shipment. Obtainable using the data parameter=notifications and included if data=all

It is an array of sent email

result	It is OK if the email has been successful, otherwise KO
statusID	The Qapla' status for which the email has been sent
status	Description of the sent status
date	Sent date
error	Possible error
isOpened	It is true (boolean value) if the email has been opened / read

sms

It is an array of SMS sent

result	It is OK if the SMS has been successful, otherwise KO
statusID	The Qapla' Status for which SMS has been sent
status	Description of the sent status
date	Sent date

webhook

It is an array of sent webhook

result	It is OK if the email has been successful, otherwise KO
statusID	The Qapla' status for which the webhook has been sent
status	Description of the sent status
date	Sent date

qaplAPP

It is an array of sent notifications to qaplAPP

result	It is OK if the email has been successful, otherwise KO
statusID	The Qapla' status or which notification has been sent to qaplAPP
status	Description of the sent status
date	Notification date

trackingHistory

It is an array of following elements:

date

The date of the status as communicated by the courier

dateISO

The ISO version YYYY-MM-DD HH:MM:SS of the date communicated by the courier

status

Status communicated by the courier

place

The place

qaplaStatus

The "translation" of the status of the courier in the status of Qapla'

id	Status ID
status	The description
detailID	ID of the possible detail
detail	Description of the possible detail
color	The color assigned by Qapla' to the status
icon	Status icon

parcels

The parcels present in the shipment. Obtainable using the parameter data=parcels and included if data=all.

weight(float)	Potential weight of the order. Mandatory if the "boxCode" is not sent
length(float)	Potential measurements: length. Mandatory if the "boxCode" is not sent
width(float)	Potential measurements: width. Mandatory if the "boxCode" is not sent
height(float)	Potential measurements: height. Mandatory if the "boxCode" is not sent
boxCode(string)	Potential box code (if used, measurements will be taken from the box with the corresponding code)
originCountry(string)	Potential Country of origin of the package in ISO 3166-1 alpha-2 format (Example: IT)
content(string)	Potential description of the content

rows

The rows of the products present in the shipment. Obtainable using the parameter data=rows and included if data=all.

sku^*(string)

Article code

name^*(string)

Article description

qty^*(int)

Quantity

price^*(float)

Price

total(float)

Total price

weight(float)

Potential article weight

url(string)

The specific url of the product

imageUrl(string)

The url of the product image

notes(string)

Product notes

customsCode(string)

Potential code used for customs (HSCode, Taric, etc.)

originCountry(string)

Product's country of origin ISO 3166-1 alpha-2 (Esempio: IT)

netWeight(float)

Potential net weight of the product

unitOfMeasurement(string)

Generale
DHL

Potential unit of measurement

Code	Description
BOX	Boxes
2GM	Centimeters
2M3	Cubic Centimeters
3M3	Cubic Feet
M3	Cubic Meters
DPR	Dozen Pairs
DOZ	Dozen
2NO	Each
PCS	Pieces
GM	Grams
GRS	Gross
KG	Kilograms
L	Liters
M	Meters
3GM	Milligrams
3L	Milliliters
X	No Unit Required
NO	Number
2KG	Ounces
PRS	Pairs
2L	Gallons
3KG	Pounds
CM2	Square Centimeters
2M2	Square Feet
3M2	Square Inches
M2	Square Meters
4M2	Square Yards
3M	Yards
CM	Centimeters
CONE	Cone
CT	Carat
EA	Each
LBS	Pounds
RILL	Rill
ROLL	Roll
SET	Set
TU	Time Unit
YDS	Yard

parcelID(int)

Potential progressive number, identifying the package number in which the product is shipped

custom1(string)

value custom 1

custom2(string)

value custom 2

custom3(string)

value custom 3

custom4(string)

value custom 4

custom5(string)

value custom 5

Errors

In case of error the "result" field will contain "KO" and the "error" field the description of the error.

{
"getShipment": {
    "result": "KO",
    "error": "[ERROR_MESSAGE]"
}
}

getShipments

getShipments allows you to receive the list of shipments imported from Qapla' by input date, shipping date, order date.

GEThttps://api.qapla.it/1.2/getShipments/?apiKey=[API_KEY]&[DATE]

REQUEST
RESPONSE

Parameters

Parameter	Description
apiKey	the API Key assigned to the channel we want to query
[DATE]^*
shipDate	shipment date in format ISO 8601 "YYYY-MM-DD"
orderDate	order date in format ISO 8601 "YYYY-MM-DD"
dateIns	upload date in format ISO 8601 "YYYY-MM-DD"

^*If no parameter is set, it will be used by default dateIns and current date.

Response Body`200`

{"getShipments":{"result":"OK","error":null,"version":"1.2.8","search":"shipDate=2019-06-20","count":2,"shipments":[{"id":1000000000001,"getShipment":"https://api.qapla.it/1.2/getShipment/?apiKey=[API_KEY]&id=000000000002","reference":"0101000101002","trackingNumber":"XX000001","isDeleted":false,"isArchived":false,"origin":"spartoo_it","courier":"GLS-ITA","statusID":2,"statusDetailID":0,"shipDate":"2019-06-20","orderDate":"2019-06-19","dateIns":"2019-06-20 11:21:10","language":"it","custom1":null,"custom2":null,"custom3":null,"isCOD": true,"deliveredDate": null},{"id":2000000000002,"getShipment":"https://api.qapla.it/1.2/getShipment/?apiKey=[API_KEY]&id=000000000002","reference":"0101000101001","trackingNumber":"XX000002","isDeleted":false,"isArchived":false,"origin":"spartoo_it","courier":"BRT","statusID":3,"statusDetailID":0,"shipDate":"2019-06-20","orderDate":"2019-06-19","dateIns":"2019-06-20 11:21:10","language":"it","custom1":null,"custom2":null,"custom3":null,"isCOD": false,"deliveredDate": "2019-06-27 10:19:23"}]}}

Description

result(string)

The result of the operation: OK or KO in case of error

error(string)

The error in case of result: KO

version(string)

The API version

search(string)

The parameter ascribed as search

count(int)

Number of current shipments

shipments(array)

It is an array that can contain more than one shipment

id(int)	Numeric ID of the shipment
getShipment(string)	The url to the getShipment API for this shipment
reference(string)	The order reference
trackingNumber(string)	The tracking number
isDeleted(bool)	It is true (boolean value) if the shipment is cancelled
isArchived(bool)	It is true (boolean value) if the shipment is filed
origin(string)	Shipment origin platform
courier(string)	The courier code of the shipment
statusID(int)	The Qapla' status of the shipment
statusDetailID(int)	Possible Qapla' status of detail
shipDate(string)	Shipment date
orderDate(string)	Order date
dateIns(string)	Upload date to Qapla''
language(string)	Shipment language
custom1(string)	The custom1 value
custom2(string)	The custom2 value
custom3(string)	The custom3 value
isCOD(boolean)	It is true if payment is cash on delivery
deliveredDate(string)	Delivered date

Errors

getCompanyShipment

getCompanyShipment allows you to read the status of a shipment in any of a company's channels through the tracking number, the order reference or the ID.

For a total and integrated management of the update cycle of shipments, also evaluate the Webhook.

🛈
Remember the usage limits and also evaluate the Webhook.

GEThttps://api.qapla.it/1.3/getCompanyShipment/?apiKey=[API_KEY]&trackingNumber=[TRACKING_NUMBER]

GEThttps://api.qapla.it/1.3/getCompanyShipment/?apiKey=[API_KEY]&reference=[ORDER_REFERENCE]

GEThttps://api.qapla.it/1.3/getCompanyShipment/?apiKey=[API_KEY]&id=[SHIPMENT_ID]

GEThttps://api.qapla.it/1.3/getCompanyShipment/?apiKey=[API_KEY]&custom1=[CUSTOM1]

REQUEST
RESPONSE

Parameters

Parameter

Description

apiKey^*(string)

The API Key of any of the company's channels

Exclusive parameters

trackingNumber(string)

The interested tracking number

reference(string)

The order reference

id(int)

Shipment ID

custom1, custom2, custom3(string)

The fields custom1, custom2, custom3

Optional parameters

lang

The language of the names of the Qapla' status (it, en, es), default: it.

Example:

&lang=en

data

The flag data specifies which and how much data we want to receive, by default it returns minimal data on the progress of the shipment.
It can have the following values:

Parameter	Description
	If no parameter is specified, it will be returned the minimum data
all	Minimum data + all the data to follow
consignee	Minimum data + recipient data
children	Minimum data + data of child shipments, if any
parent	Minimum data + data of the parent shipment, if any
flag	Minimum data + data relating to the report of the shipment, if any
notifications	Minimum data + notification data (email sms, webhook, qaplAPP)
history	Minimum data + shipment tracking history
rows	Minimum data + product rows
parcels	Minimum data + parcels information

The parameter can be combined separated by commas, for example

&data=consignee,history

in order to get only these data.

Response Body`200`

{
  "getCompanyShipment": {
    "result": "OK",
    "error": null,
    "version": "1.3.0",
    "lang": "it",
    "count": 1,
    "shipments": [
      {
        "id": 1690120025,
        "hash": "347513728eab0009bfc60cc47acaffd0",
        "url": "https://tracking.qapla.it/347513728eab0009bfc60cc47acaffd0",
        "reference": "RAD000UFPL",
        "trackingNumber": "080010017684806",
        "isDeleted": false,
        "isArchived": false,
        "origin": {
          "code": "magento",
          "name": "Magento",
          "icon": "https://cdn.qapla.it/origin/magento.svg"
        },
        "courier": {
          "code": "BRT",
          "name": "BRT",
          "icon": "https://cdn.qapla.it/courier/BRT.svg",
          "note": null,
          "estimatedDeliveryDate": null,
          "courierEstimatedDeliveryDate": null,
          "trackingURL": "https://brt.it/tracking/fooandnoes"
        },
        "status": {
          "date": "2019-06-14 06:15",
          "dateISO": "2019-06-14 06:15:00",
          "status": "ON_THE_ROAD",
          "place": "RIVALTA (TO) (IT)",
          "qaplaStatus": {
            "id": 3,
            "status": "IN TRANSIT",
            "detailID": 0,
            "detail": null,
            "color": "#1D76D8",
            "icon": "https://cdn.qapla.it/status/3.svg"
          },
          "dateUpd": "2019-06-14 15:53:15",
          "lastCheck": "2019-06-14 22:17:13"
        },
        "shipDate": "2019-06-13",
        "orderDate": "2019-01-31",
        "dateIns": "2019-06-14 15:49:18",
        "consignee": {
          "name": "Luca Cassia",
          "address": "Via Campazzino, 12",
          "city": "Milano",
          "state": "MI",
          "postCode": "20100",
          "country": "IT",
          "email": "adso@defanchisgiocattoli.it",
          "isAmazon": false,
          "phone": "02343522"
        },
        "language": "it",
        "newTrackingNumber": null,
        "oldTrackingNumber": null,
        "hasNewTrackingNumber": false,
        "isTrackingNumber": true,
        "returnTrackingNumber": null,
        "isReturnShipment": false,
        "isCOD": false,
        "amountText": null,
        "amount": null,
        "isDelivered": false,
        "isChild": true,
        "parent": {
          "id": "2010200",
          "reference": "AD000UFPL",
          "rackingNumber": "090010015489",
          "courier": "BRT",
          "url": "https://api.qapla.it/1.3/getCompanyShipment/?apiKey=XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX&id=0000000"
        },
        "hasChildren": true,
        "children": [
          {
            "id": "121029109",
            "reference": "303-XX11XX-5621132",
            "trackingNumber": "0844!!!!7689193",
            "courier": "DPD",
            "url": "https://api.qapla.it/1.3/getCompanyShipment/?apiKey=XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX&id=000001"
          }
        ],
        "trueTrackingNumber": null,
        "altTrackingNumber": null,
        "custom1": null,
        "custom2": null,
        "custom3": null,
        "deliveryMode": "pickup",
        "hasFlag": true,
        "flag": {
          "description": "Ritardo Courier",
          "note": "telefonato a Pino"
        },
        "notifications": {
          "email": [
            {
              "result": "OK",
              "statusID": 3,
              "status": "IN TRANSIT",
              "date": "2019-06-14 16:00:08",
              "error": false,
              "isOpened": true
            }
          ],
          "sms": [
            {
              "result": "OK",
              "statusID": 20,
              "status": "PARTITO",
              "date": "2019-06-14 18:50:29"
            }
          ],
          "webhook": [
            {
              "statusID": 3,
              "date": "2019-06-14 23:51:06",
              "result": "OK",
              "status": "IN TRANSITO"
            }
          ],
          "qaplAPP": [
            {
              "statusID": 4,
              "result": "OK",
              "date": "2019-06-15 08:00:00",
              "status": "IN COSEGNA"
            },
            {
              "statusID": 3,
              "result": "OK",
              "date": "2019-06-14 19:15:09",
              "status": "IN TRANSITO"
            }
          ]
        },
        "trackingHistory": [
          {
            "date": "2019-06-14 06:15",
            "dateISO": "2019-06-14 06:15:00",
            "status": "IN TRANSIT",
            "place": "RIVALTA (TO) (IT)",
            "qaplaStatus": {
              "id": 3,
              "status": "IN TRANSIT",
              "detailID": 0,
              "detail": null,
              "color": "#1D76D8",
              "icon": "https://cdn.qapla.it/status/3.svg"
            }
          },
          {
            "date": null,
            "dateISO": null,
            "status": "PARCEL HANDED TO DPD",
            "place": null,
            "qaplaStatus": {
              "id": 20,
              "status": "DEPARTED",
              "detailID": 0,
              "detail": null,
              "color": "#8A2BE2",
              "icon": "https://cdn.qapla.it/status/20.svg"
            }
          }
        ]
      }
    ]
  }
}

Description

result The result of the operation: OK or KO in case of error

error The error in case of result: KO

version The API version

lang The required language / transferred as parameter (default: it)

count Number of current shipments

shipments

It is an array that can contain more than one shipment

id Shipment ID

hash The hash of the shipment, used for example by the tracking page

url Web address of the tracking page of this shipment

reference Order reference

trackingNumber The tracking number

isDeleted It is true (boolean value) if the shipment is cancelled

isArchived It is true (boolean value) if the shipment is filed

origin The origin of the shipment if loaded (es: magento, prestashop, amazon, ecc)

courier

code	Courier code
name	Name of the courier
icon	Icon's URL of the courier
note	Possible notes from the courier on the shipment
estimatedDeliveryDate	Possible estimated date of expected delivery, the one declared by whoever created the shipment
courierEstimatedDeliveryDate	Possible delivery date announced by the courier (`YYYY-MM-DD`), `null` until the courier publishes one. Same information as `note`, read as a date instead of a sentence
url	Address URL of the courier
trackingURL	Tracking URL address of the courier for this shipment

status

Current status of the shipment

date

Status date, as reported by the courier

dateISO

The ISO version YYYY-MM-DD HH:MM:SS of the date communicated by the courier

status

Status communicated by the courier

place

Location communicated by the courier

qaplaStatus

The "translation" of the status of the courier in the status of Qapla'

id	The ID of the status
status	The description
detailID	ID of the possible detail
detail	Description of the possible detail
color	The color assigned by Qapla' to the status
icon	Status icon

dateUpd

The date in which the shipment status has been updated on Qapla'

lastCheck

The date of the last control of the shipment status

shipDate The shipment date communicated when the shipment is loaded

orderDate The order date communicated when the shipment is loaded

dateIns The upload date of the shipment

consignee

Recipient data

name	Recipient name
address	Recipient address
city	Recipient city
state	Recipient province
country	Recipient country
email	Recipient email
isAmazon	It is true (boolean value) if the recipient email is from Amazon
phone	Recipient telephone number