Webhook Ver. 1.2

Introduction

Webhook is a notification of an event published in a URL of your choice.

Webhooks are useful for integration with third-party services and other external APIs that support them.

Qapla' webhook is part of the API of Qapla'.

API Key

In order to use the APIs it is necessary to be aware of the Private API Keys assigned to your channel(s), which are located on the Control Panel in section "Settings \ [CHANNEL_NAME]"

This API key must be protected and kept secret.

Security

The IP addresses from which it will be possible to receive the POST of the webhook are:

• 34.96.89.1
• 35.195.3.242
• 35.205.84.188
• 35.205.236.254
• 34.78.56.172
• 35.195.153.127
• 35.205.146.223

Shipments webhook

Each change of shipment status communicated by the courier (ex: if the shipment changes from "delivery" to "delivered"), a POST in JSON format is sent to the URL indicated in the channel configuration on the Qapla' control panel.

POSThttps://[YOUR_ENDPOINT]

HTTP POST

In a POST at the endpoint indicated in the channel configuration Qapla' Control Panel, like:

POST / HTTP/1.1
Content-Type: application/json;
Content-Length: 1232
Host: webhook.qapla.it
Connection: Keep-Alive
User-Agent: Mozilla/5.0

it will be sent the following communication: { "apiKey": "[API_KEY]", "trackingNumber": "2253647804", "return": 0, "hasChildren": 0, "isChild": 0, "courier": "DHL", "reference": "2007135", "date": "2019-06-18 20:35:53", "courierStatus": "PL", "place": "LEGHORN/LIVORNO-ITA", "qaplaStatusID": "3", "qaplaStatus": "IN TRANSIT", "statusDetails": [], "custom1": "", "custom2": "", "custom3": "" }

"statusDetails" will be sent if necessary as follows. For example, note the "STOCK" status detail, referring to the "EXCEPTION" status. { "apiKey": "[API_KEY]", "trackingNumber": "2253647804", "return": 0, "hasChildren": 0, "isChild": 0, "courier": "DHL", "reference": "2007135", "date": "2019-06-18 20:35:53", "courierStatus": "PL", "place": "LEGHORN/LIVORNO-ITA", "qaplaStatusID": "6", "qaplaStatus": "EXCEPTION", "statusDetails": [{ "id": 1, "detail": "STOCK" }], "custom1": "", "custom2": "", "custom3": "" }

Description

Following the description of the individual parameters.

Parameter	Description
apiKey(string)	The API Key of the channel from which we are receiving the notification.
trackingNumber(string)	The tracking number of the shipment
return(int)	It is 1 if it is a return shipment
hasChildren(int)	It is 1 if the shipment has "child" shipments
isChild(int)	It is 1 if the shipment is a "child" shipment
courier(string)	The Qapla' courier code
reference(string)	Order's alphanumeric reference
date(string)	The status date, as reported by the courier
courierStatus(string)	The status communicated by the courier
place(string)	The place communicated by the courier
qaplaStatusID(string)	The "translation" of the status of the courier in the Qapla' status
qaplaStatus	Status description
statusDetails	The ID of possible detail
custom1	Possible custom1 value of the shipment
custom2	Possible custom2 value of the shipment
custom3	Possible custom3 value of the shipment

Response

The response from URL called must be:

{"result": "OK"}

Only in case of error will be:

{"result": "KO"}

Retry

The result "KO" or any other type of wrong answer that is not "OK" will force the webhook to retry the transmission 2 more times in the following hours.

Abuse

After 100 failed transmission attempts (i.e. with "KO" response or non-compliant response) the service will be disabled.

Enpoint example

POSThttps://[YOUR_URL]/qaplaWebhook.php

The following example of a "listening" page takes the JSON content and processes it.

<?php
//...I set the content-type as JSON
header('Content-type: application/json; charset=utf-8');

//...API Key that I expect
const API_KEY = '[API_KEY]';

//...I obtain the string sent as a POST
$data = file_get_contents('php://input');

//...If it is empty I get very angry
if(empty($data)):
    exit('{"result": "KO"}');
endif;

//...I turn it in a JSON
$json = json_decode($data);

//...If it's an incorrect JSON, I get even more angry
if(($json === false))
    exit('{"result": "KO"}');
endif;

//...I verify that the API KEY posted matches, security check.
if($json->apiKey !== API_KEY):
    exit('{"result": "KO"}');
endif;

//...I update the potential table
$sql = "UPDATE orders-shipments SET status = ".$json->qaplaStatusID." WHERE id = ".$json->reference;

//...Everything right, I write "result": "OK" in JSON
echo '{"result": "OK"}';
?>

Test

Test your endpoint and send a typical Qapla' transmission.

API Key*
URL*
Tracking Number*
Courier*
Reference*
Courier Status*
Place*
Qapla' Status	[2] INFO RECEIVED[20] DEPARTED[3] IN TRANSIT[50] PROCESSING[4] OUT FOR DELIVERY[5] FAILED ATTEMPT[8] DELAY[6] EXCEPTION[10] PICKUP POINT[95] RETURNED[99] DELIVERED

Shipments return webhook

Each return request from the end customer * will be sent to an endpoint defined on the Qapla 'Control Panel , details of the return shipment.

POSThttps://[YOUR_ENDPOINT]

*This service is only available after enabling, configuring and purchasing the Automatic Returns (Type 3 Returns) service on the Qapla 'Store.

HTTP POST

Below is a detailed example of the POST

POST / HTTP/1.1
Content-Type: application/json;
Content-Length: 1232
Host: webhook.qapla.it
Connection: Keep-Alive
User-Agent: Mozilla/5.0

{ "webhookReturnShipments": { "id": "123456789098765432", "apiKey": "[API_KEY]", "version": 1.0, "count": 1, "returnShipments": [ { "date": "2022-01-01", "reference": "123456fgh", "RMA": "s3d3d", "parcels": 1, "weight": 1, "trackingNumber": "ZZ12356897654", "courier": { "code": "CRONO-REVERSE", "name": "Crono reverse", "icon": "https://cdn.qapla.it/courier/CRONO-REVERSE.svg" }, "sender": { "name": "Pepito Sbazzeguti", "address": "Via Don Camillo Martire,90", "city": "Brescello", "state": "RE", "postCode": "42041", "country": "IT", "email": "pepito@sbazzeguti.it", "telephone": "3473432522" }, "consignee": { "name": "The merchant SRL", "address": "Via enterprise,10", "city": "Milano", "state": "MI", "postCode": "20100", "country": "IT" }, "rows": [ { "sku": "A-1233", "name": "Whisky in the Jar", "qty": 1, "total": "12.00", "reason": "Jar empty" } ] } ] } }

Description

Below is the description of the individual parameters.

Parameter	Description
apiKey(string)	The API Key of the channel from which we are receiving the notification.
returnShipments(object[])	Parameter Description date(string) Return creation date reference(string) Order reference RMA(string) Return Merchandise Authorization Code parcels(integer) Parcels weight(float) Weight trackingNumber(string) The tracking number of the return shipment courier(object) Parameter Description code(string) Code name(string) Name icon(string) Link to icon sender(object) He is the sender of the shipment if different from the contract holder. Parameter Description name(string) Sender's name address(string) Sender's address city(string) City of the sender state(string) Province postCode(string) Post Code country(string) Country in ISO 3166-1 alpha-2 format (Example: IT) email(string) Sender's email telephone(string) Sender's phone consignee(object) It is the recipient of the Return shipment. Parameter Description name(string) Name / Company name address(string) Address city(string) City state(string) Province postCode(string) Postal code country(string) Country in ISO 3166-1 alpha-2 format (Example: IT) rows(array of objects) List of items in return Parameter Description sku(string) SKU name(string) Item name qty(string) Quantity total(string) Total item cost reason(string) Reason for returning the item

Response

The response of the URL named should be :

{"result": "OK"}

While only in case of error will it be:

{"result": "KO"}

Retry

The result "KO" or any other type of incorrect response other than "OK" will force the webhook to retry the transmission 2 more times in the following hours.

Abuse

After 100 failed transmission attempts (ie with "KO" or non-compliant response) the service will be deactivated.

Orders webhook

Webhook can be configured to be sent when the shipment is created (label printing) or sent (sending confirmation to the courier), in the appropriate section on Control Panel of Qapla'.

POSThttps://[YOUR_ENDPOINT]

HTTP POST

In a POST at the endpoint indicated in the channel configuration on Qapla' Control Panel, like:

POST / HTTP/1.1
Content-Type: application/json;
Content-Length: 1232
Host: webhook.qapla.it
Connection: Keep-Alive
User-Agent: Mozilla/5.0

it will be sent the following communication: { "apiKey": "01306b82789acd2d9317e12f2s70c4z0e0f4669c21e4c88df2c8a919e0a0d", "orders": [{ "reference": "51704", "orderDate": "2018-02-21 14:04:19", "shipDate": "2018-02-22 12:54:15", "courier": "GLS-ITA", "trackingNumber": "XX580104809", "return": null, "returnTrackingNumber": null, "weight": 1, "parcels": 1, "length": 0, "width": 0, "height": 0, "amount": "€ 28.74", "isPOD": false, "customerName": "Pepito Sbazzeguti", "customerAddress": "Via Don Camillo Martire,90", "customerCity": "Brescello", "customerState": "RE", "customerZip": "42041", "customerCountry": "IT", "customerTelephone": "3473432522", "customerEmail": "pepito@sbazzeguti.it", "notes": "" }] }

Description

apiKey(string)

The API Key of the channel from which we are receiving the notification.

orders(array)

It is an array of orders. reference(string) Order reference orderDate Order date shipDate Order creation date courier The Qapla' courier code trackingNumber The tracking number of the shipment return(bool) It is true if the shipment has a return returnTrackingNumber(string) Possible tracking number of return shipment weight(float) Weight parcels(int) Packages length(float) Length width(float) Width height(float) Height amount(string) Shipment cost isPOD(bool) It is true if the shipment is cash on delivery customerName(string) Recipient name customerAddress(string) Recipient address customerCity(string) Recipient City customerState(string) Recipient province customerZip(string) Recipient postal code customerCountry(string) Recipient country customerTelephone(string) Recipient telephone customerEmail(string) Recipient email notes(string) Any order notes

Test

Test your endpoint and send a typical Qapla' transmission.

API Key*
URL*
Reference*
Order date
Ship date
Tracking Number
Courier
Weight
Parcels
Length
Width
Height
Amount
Is POD
Customer Name
Customer Address
Customer City
Customer State
Customer Zip
Customer Country
Customer Telephone
Customer Email
Notes

Qapla' Status

It is the interpretation of the status of the shipment with values that Qapla' assigns to each possible state of the courier.

Couriers

List of Qapla's couriers' codes, in alphabetical order.