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).
• Timestamps on parcels and orders resources are ISO 8601 and carry a +00:00 suffix (YYYY-MM-DDTHH:MM:SS+00:00). Do not rely on that offset: it is appended without conversion, while the stored value is Europe/Rome local time — so the instant it denotes is off by the Rome offset. Treat these fields as local time, exactly like the tracking ones below. The one exception is orders ingested through the Qapla' import pipeline, which are genuine UTC; the response does not distinguish the two cases.
• Shipment tracking timestamps — statusDate, statusUpdatedAt and history[].date on /v2/shipments — and the timestamps on sandbox resources are returned as YYYY-MM-DD HH:MM:SS without an offset and expressed in Europe/Rome local time, not UTC. The updatedAfter filter is interpreted in that same time zone.
• Date-only fields, such as shipDate and orderDate, use YYYY-MM-DD.

API Key

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

You can find the API Key in the Control Panel under the "Settings" > "Channels" section.

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

Authentication follows the Bearer Token Authentication flow: exchange your API Key for a JWT token, then include it in every request.

To obtain an access token, send a POST request to the authentication endpoint with your API Key:

POST https://api.qapla.it/v2/auth/token

{"apiKey":"API_KEY"}

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

Using the 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. The limit applies per channel and is shared by all the API Keys of that channel, with the following parameters:

Channels with high volumes can be granted a dedicated allowance above the standard one: contact Customer Support. The values assigned to your API Key are always readable in the rate_limit object returned by POST /auth/token.

HTTP Response Status Codes

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

429 Too Many Requests

The response carries the X-RateLimit-Limit, X-RateLimit-Remaining and X-RateLimit-Reset headers. Retry honouring the Retry-After header, with exponential backoff.

Abuse

Repeated abuse of the API (10 or more 429 responses within 5 minutes) results in an automatic 1-hour suspension of the API Key (403 Forbidden). Permanent revocation is managed manually by the system administrator.

Postman Collection

Swagger UI

POSTAuth / Token

POSThttps://api.qapla.it/v2/auth/token

GETSandbox

GEThttps://api.qapla.it/v2/sandbox

GETSandbox / {id}

GEThttps://api.qapla.it/v2/sandbox/{id}

POSTSandbox

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

PUTSandbox / {id}

PUThttps://api.qapla.it/v2/sandbox/{id}

PATCHSandbox / {id}

PATCHhttps://api.qapla.it/v2/sandbox/{id}

DELETESandbox / {id}

DELETEhttps://api.qapla.it/v2/sandbox/{id}

POSTCreate shipments

The response is 201 when every shipment was created, 207 Multi-Status when one or more shipments were rejected (partial or total failure: check items[].errors). Static payload violations (missing required fields, invalid formats) reject the whole request with 422 instead (RFC 7807 with violations).

For volumes above 100 shipments use the asynchronous import POST /shipments/import.

Note
Authentication requires the Bearer Token obtained from the authentication service. Required scope: shipments:write. Shipments are created on the authenticated channel.

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

POSTImport shipments (asynchronous)

Each shipment has the same format as POST /shipments and is processed with the same business rules. Unlike the synchronous endpoint, static validation errors do not block the batch either: an invalid item fails alone with code VALIDATION_ERROR.

The import is safe to retry: if the job is re-executed after an interruption, items already inserted are reported as DUPLICATE_SHIPMENT without double insertions.

Note
Authentication requires the Bearer Token obtained from the authentication service. Required scope: shipments:write. Shipments are created on the authenticated channel.

POSThttps://api.qapla.it/v2/shipments/import

GETSearch shipments

Polling tip
To synchronize tracking updates use the updatedAfter filter: it returns only shipments whose status changed after that moment, avoiding repeated per-shipment requests.

Note
Authentication requires the Bearer Token obtained from the authentication service. Required scope: shipments:read.

GEThttps://api.qapla.it/v2/shipments?updatedAfter={DATETIME}&status={STATUS}&page={PAGE}

GETShipment details

Note
Authentication requires the Bearer Token obtained from the authentication service. Required scope: shipments:read. The shipment must belong to the authenticated channel: a shipment of another channel returns 404, indistinguishable from a non-existing one.

GEThttps://api.qapla.it/v2/shipments/{id}

POSTRequest a stock release

The response is always accepted synchronously (status: "sent"); the real outcome is carried by courierOutcome. GLS and TNT reply synchronously (ok/error); BRT is deferred — the request is transmitted asynchronously and its outcome (pending) becomes visible later through the shipment's tracking events.

Note
Authentication requires the Bearer Token obtained from the authentication service. Required scope: shipments:write. The shipment must belong to the authenticated channel and be currently held in depot.

POSThttps://api.qapla.it/v2/shipments/{id}/stock-release

POSTCompare courier delivery times

The origin is resolved down to the company seat postal code (CAP), deduced server-side from the authenticated company, and can be overridden via the originCap parameter. The data is an anonymous cross-merchant network benchmark (no PII). Metrics are expressed in calendar days: lead = shipped→delivered (primary metric, used for ranking), transit = departed→delivered (carrier-only, history starting ~2026).

Note
Authentication requires the Bearer Token obtained from the authentication service. Required scope: delivery-times:read.

POSThttps://api.qapla.it/v2/couriers/delivery-times

POSTScore courier efficiency

The efficiency index blends three sub-scores with the fixed network weights 40/20/40: scoreSpeed (from the speed median), scoreConsistency (from the gap between p90 and median) and scoreReliability (from the failed/stock/exception rates of the lane). The origin is resolved down to the company seat postal code (CAP), deduced server-side from the authenticated company, and can be overridden via the originCap parameter. The data is an anonymous cross-merchant network benchmark (no PII). Speed metrics are expressed in calendar days (transit when available, otherwise lead).

Note
Authentication requires the Bearer Token obtained from the authentication service. Required scope: efficiency-index:read.

POSThttps://api.qapla.it/v2/couriers/efficiency-index

POSTVerify an address

Two providers sit behind the same contract, selected with the provider parameter. geocode (the default) queries the geocoding service: it covers the whole world and is the only one returning coordinates. gls queries the GLS Italia street registry: Italian addresses only, and only for channels with GLS configured, but in exchange it reports ZTL (restricted traffic zone), difficult area, serving branch and zone, and when the address is not conformant it proposes the addresses it would accept.

An address with no match is not an error: the response is 200 with match.status set to NONE. The check ran, and the answer is that the address does not exist.

NB
Authentication uses the Bearer Token obtained from the authentication service. Required scope: addresses:check.
Every accepted request is metered, whatever the provider and whatever the outcome — including when the address is not found. Requests rejected before the check (403 and 422) are not metered.

POSThttps://api.qapla.it/v2/addresses/check

POSTParcels

Note
Authentication requires the Bearer Token obtained from the authentication service. Required scope: parcels:create.

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

GETParcels

GEThttps://api.qapla.it/v2/parcels?orderReference={REFERENCE}&orderOrigin={ORIGIN}

GETParcels / {hash}

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

PATCHParcels / {hash}

PATCHhttps://api.qapla.it/v2/parcels/{PARCEL-HASH}

DELETEParcels / {hash}

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

DELETEParcels (bulk)

DELETEhttps://api.qapla.it/v2/parcels?orderReference={REFERENCE}&orderOrigin={ORIGIN}