Introduction

The Qapla' v2 API provides an advanced platform for both reading and writing integration with proprietary e-commerce systems or those that do not have a specific plugin or connector available.

The architecture is based on a RESTful style that ensures intuitive resource management and compliance with international standards, simplifying integration and process automation.

• The API is structured according to REST principles (RESTful API).
• It supports GET, POST, PUT, DELETE, and PATCH requests, using the JSON format for both sending and receiving data.
• Responses include HTTP status codes to indicate the result of the request (HTTP Status Codes).
• The reference time zone for all dates and timestamps in the API is UTC.
• Dates are provided in the ISO 8601 format (YYYY-MM-DDTHH:MM:SSZ). Example: 2025-04-24T05:17:19Z

API Key

To use the APIs, you must have a private API Key, which is assigned to the enabled channels.

The API Key must be kept confidential and secure.
Each channel has one or more private API Keys, which define the permissions and accessible endpoints.

Authentication

Channel authentication is performed through the Qapla' SSO service following the Bearer Token Authentication flow.

To obtain an access token, you need to send a POST request to the dedicated endpoint with the channel's API Key:

POST https://sso.qapla.it/auth/channel

{"apiKey":"API_KEY"}

curl -X POST https://sso.qapla.it/auth/channel \
                -H "Content-Type: application/json" \
                -d '{"apiKey": "API_KEY"}'

Access token

curl -X GET https://api.qapla.it/v2/endpoint \
         -H "Authorization: Bearer ACCESS_TOKEN" \
         -H "Content-Type: application/json"

Errors

Each code indicates the type of error encountered while processing the request, providing a clear and standard-compliant indication of any authentication, validation, or incorrect endpoint usage issues.

HTTP Status Codes

Body

Header

Usage Limits

The request management system uses a Token Bucket algorithm to limit the number of API calls within a specified time interval, with the following parameters:

A multi-request (e.g., 100 shipments or orders) is counted as 100 tokens.

HTTP Response Status Codes

If the usage limit is exceeded, the response will be:

429 Too Many Requests

Abuse

Abuse of the API may lead to temporary or permanent suspension of the associated API Key.

Postman Collection

POSTParcel

The order or shipment (label) created will "inherit" the parcels previously uploaded.

Note
Authentication is done through the Bearer Token obtained with the authentication service.

POSThttps://api.qapla.it/v2/parcel

GETParcel

GEThttps://api.qapla.it/v2/parcel/{PARCEL-HASH}

DELETEParcel

DELETEhttps://api.qapla.it/v2/parcel/{PARCEL-HASH}

GETParcels

GEThttps://api.qapla.it/v2/parcels/{REFERENCE}-{ORIGIN}

DELETEParcels

DELETEhttps://api.qapla.it/v2/parcels/{REFERENCE}-{ORIGIN}