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
- 35.195.158.219
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:
"statusDetails" will be sent if necessary as follows. For example, note the "STOCK" status detail, referring to the "EXCEPTION" status.
Enable the receipt of products and packages.
Enabling the
webhook 1.3 from
Qapla' Control Panel allows you to receive information related to products and packages.
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(bool) |
It is 1 if it is a return shipment |
| hasChildren(bool) |
It is 1 if the shipment has "child" shipments |
| isChild(bool) |
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 |
Description of additional parameters if version 1.3 is enabled:
| Parameter |
Description |
| rows(array) |
| Parameter |
Description |
| id(string) |
Article internal id representation |
| sku(string) |
Article code |
| name(string) |
Article description |
| price(string) |
Price |
| total(string) |
Total price |
| weight(string) |
Potential article weight |
| qty(string) |
Quantity |
| url(string) |
The specific url of the product |
| imageUrl(string) |
The url of the product image |
| isReturnable(boolean) |
If it is true, it indicates the possibility of returning the single item |
| customsCode(string) |
Potential code used for customs (HSCode, Taric, etc.) |
| notes(string) |
Potential product notes |
| netWeight(string) |
Potential net weight of the product |
| originCountry(string) |
Product's country of origin ISO 3166-1 alpha-2 (Esempio: IT) |
| unitOfMeasurement(string) |
Potential unit of measurement |
| parcelID(string) |
Potential progressive number, identifying the package number in which the product is shipped |
|
| parcels(array) |
| Parameter |
Description |
| boxCode(string) |
Potential box code (if used, the measurements will be taken from the box with the corresponding code) |
| weight(float) |
Potential weight of the shipment |
| length(float) |
Potential measures: length |
| height(float) |
Potential measures: height |
| width(float) |
Potential measures: width |
| originCountry(string) |
Country of origin of the Parcel ISO 3166-1 alpha-2 (Example: IT) |
| content(string) |
Potential description of parcels content |
|
| consignee(object|null) |
| Parameter |
Description |
| name (string) |
The full name of the consignee |
| address (string) |
The address of the consignee |
| city (string) |
The city of the consignee |
| state (string) |
The state or province of the consignee |
| postCode (string) |
The postal code of the consignee |
| country (string) |
The country of the consignee |
| email (string|null) |
Optional email address of the consignee |
| phone (string|null) |
Optional phone number of the consignee |
|
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.
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
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:
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.
Qapla' Status
It is the interpretation of the status of the shipment with values that Qapla' assigns to each possible state of the courier.
| id | detailID | Name | Description |
|---|
Couriers
List of Qapla's couriers' codes, in alphabetical order.
