IT
RESTful JSON API v2 · rel. 1.2.84
rel. 1.2.84

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.

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.

API Key

Authentication

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

Bearer Token Authentication

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

The request must contain the following JSON in the body:

{"apiKey":"API_KEY"}
apiKey (string) The Qapla' channel API Key.
Access token cURL request:
curl -X POST https://api.qapla.it/v2/auth/token \
                -H "Content-Type: application/json" \
                -d '{"apiKey": "API_KEY"}'
Response Body 200

            
Description
token (string) The JWT token to include as Bearer in the Authorization header of all subsequent requests.
scopes (array) List of permissions granted to the current API Key (e.g. parcels:create, sandbox:read).
token_type (string) Indicates the type of token (always Bearer).
expires_in (int) Token duration in seconds (86400 = 24 hours).
rate_limit (object) Token Bucket parameters configured for this API Key.
refill_rate (int) Tokens added to the bucket per minute.
bucket_size (int) Maximum bucket capacity (maximum burst requests).
cache (bool) Indicates whether the response was served from cache (true) or freshly generated (false).
Errors
400 Bad Request: the request body is missing or is not valid JSON.
401 Unauthorized: the API Key is invalid or the channel is inactive.
422 Unprocessable Content: the apiKey field is missing, empty or not a string.
429 Too Many Requests: rate limit exceeded.
Using the token
The token must be included in the Authorization header of all requests, preceded by Bearer:
curl -X GET https://api.qapla.it/v2/endpoint \
         -H "Authorization: Bearer ACCESS_TOKEN" \
         -H "Content-Type: application/json"

Errors

All errors returned by the Qapla' API are represented using standard HTTP status codes.

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
400 Bad Request: The request is invalid or required parameters are missing from the request body.
401 Unauthorized: The API Key is invalid or does not have the necessary permissions to access the requested endpoint.
403 Forbidden: Access denied. The API Key does not have the necessary permissions or the user is not authorized.
404 Not Found: The specified endpoint does not exist or the requested resource was not found.
405 Method Not Allowed: The HTTP method used (GET, POST, PUT, DELETE) is not supported for this endpoint.
406 Not Acceptable: The server is unable to generate a response in the requested format or language.
409 Conflict: The request cannot be completed due to a conflict with the current state of the resource.
423 Locked: The requested resource is locked and cannot be modified or accessed.
429 Too Many Requests: The maximum number of requests has been exceeded. Please wait before trying again.
500 Internal Server Error: An internal server error occurred while processing the request.
503 Service Unavailable: The service is currently unavailable. Please try again later.
Body
JSON error body.

    
status The type of error.
code The internal error code.
message The error description.
Header
X-Error-Message The descriptive error text.

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:

Bucket capacity 300 Maximum number of requests absorbed in a burst, before throttling starts.
Tokens per minute 150 The bucket refills at a rate of 150 tokens per minute.
Token cost 1 Every request consumes one token, regardless of how many elements the body carries.

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.

Versioning

Besides the API generation (v2 in the path), some endpoints have a contract version of their own: when an endpoint changes the names or shape of its fields a new version comes out, and the previous one keeps being served. Endpoints with more than one version say so on their page; today they are the orders (Orders, versions 2.0 and 1.1) and the parcels (Parcels, versions 2.0 and 1.0).

Choosing the version

The version is requested with the X-Endpoint-Version request header:

X-Endpoint-Version: 2.0

Without the header, the channel's pinned version for that endpoint applies: on the channel's first call to an endpoint with more than one version, the channel is pinned to the version current at that moment, and keeps receiving it from then on. This way an existing integration does not break when a new version comes out: to move to the new one, you ask for it.

Response header

The response carries in X-Endpoint-Version the version actually served: that is how you know which contract you are reading, even without sending the header.

Postman Collection

Postman A Postman Collection is available.

Swagger UI

Swagger UI An interactive Swagger UI is available to explore and test the API endpoints.

Authentication

The authentication service lets you obtain a JWT token from your API Key. The token is valid for 24 hours and must be included as Bearer in the Authorization header of every request.

POSTAuth / Token

Exchanges an API Key for a JWT token valid for 24 hours. The token can be cached and reused until expiry.
POSThttps://api.qapla.it/v2/auth/token
Body

            

*Required parameter

apiKey*(string) The channel's private API Key. Available in the Control Panel under "Settings" > "Channels" > "Configure".

This endpoint does not require authentication (no Authorization header).

Body 200

            
token(string) The JWT token to include as Bearer in the Authorization: Bearer {token} header of every subsequent request.
scopes(array) List of permissions granted to the API Key. Each scope corresponds to a specific action on a resource.
parcels:create, parcels:read, parcels:update, parcels:delete, sandbox:read, sandbox:write, orders:read, orders:write, labels:read, labels:write, jobs:read, shipments:create, shipments:read
token_type(string) Token type (always Bearer).
expires_in(int) Token duration in seconds. Fixed value: 86400 (24 hours).
rate_limit(object) Token Bucket parameters for this API Key.
refill_rate(int) Tokens added to the bucket per minute.
bucket_size(int) Maximum bucket capacity.
cache(bool) true if the response was served from Redis cache (existing token), false if freshly generated.
Response Headers
X-Auth-Cache(string) HIT if the token was served from cache, MISS if freshly generated.
Errors
400 Bad Request: the request body is missing or is not valid JSON.
401 Unauthorized: the API Key is invalid or the channel is inactive.
422 Unprocessable Content: the apiKey field is missing, empty or not a string.
429 Too Many Requests: rate limit exceeded.

Shipments

The Shipments APIs cover the whole shipment lifecycle: synchronous bulk creation (up to 100 per request), asynchronous mass import (up to 5000, with a background job), paginated search with combinable filters, and full detail with tracking history and notifications. They also include stock release (svincolo giacenza), which asks the courier to act on a shipment held in depot: re-deliver it, re-deliver it to a new address, or return it to the sender. A shipment can also be flagged with a reason (lost, damaged, delayed…), as «Segnala questa spedizione» does in the panel.

A shipment is uniquely identified by its numeric id, returned at creation time, and always belongs to the authenticated channel.

Required scopes: shipments:read for search and detail, shipments:write for creation, import, deletion, flagging and stock release.

POSTCreate shipments

Creates up to 100 shipments in a single synchronous request. Each shipment is validated and created individually: the outcome is reported per item in the items array of the response, in the same order as the request.

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
Body
The request body must be a JSON containing the following parameters:

            

*Required parameter

shipments*(array) Shipments to create (minimum 1, maximum 100). Each shipment contains the following fields:
trackingNumber*(string) Tracking number assigned by the courier (max 50 characters).
courier*(string) Courier of the shipment. The value is looked up in this order, and the first match wins: 1) the transcoding set on the channel for a courier; 2) the Qapla' courier code (e.g. UPS, BRT, BRT-V1); 3) the courier name. No match: INVALID_COURIER.
Contract variants: when the merchant has several contracts with the same courier, each one is a variant with its own code (e.g. BRT-V1, a child of BRT), and the shipment is assigned to a contract by sending the variant code. A variant is accepted only if it is configured on the channel, otherwise the item is rejected with COURIER_NOT_CONFIGURED; the base courier has no such constraint.
Transcoding: for each courier (or variant) configured on the channel a single merchant-defined value can be set, e.g. the merchant's own customer code with the courier; sending it in courier, Qapla' resolves it to the courier or variant it is mapped to.
shipDate*(string) Ship date, YYYY-MM-DD format.
orderReference(string) Merchant order reference.
orderDate(string) Order date, YYYY-MM-DD format.
platformOrderId(string) Order id on the source platform.
origin(string) Source platform of the order (e.g. magento, shopify, amazon). When provided it must exist in the platform registry, otherwise INVALID_ORIGIN.
language(string) Notification language (ISO 639-1, e.g. it, en). Default: it. Must be a supported language, otherwise INVALID_LANGUAGE.
tag(string) Free-text tag of the shipment.
note(string) Free-text note of the shipment.
isRealTrackingNumber(bool) false when the tracking number is a placeholder not yet assigned by the courier. Default: true.
isReturnable(bool) Whether the shipment can be returned. Default: true.
commercialContactEmail(string) Email of the commercial contact for this order.
consignee(object) Recipient of the shipment. Email and phone are only needed to enable transactional notifications: a shipment without them is still created.
name(string) Full name.
street(string) Street address.
city(string) City.
postcode(string) ZIP / postal code.
state(string) State / province (e.g. MI).
country(string) Country (ISO 3166-1 alpha-2). Default: IT.
email(string) Recipient email (enables email notifications).
phone(string) Recipient phone (enables SMS notifications).
monetary(object) Monetary information of the shipment.
totalValue(float) Total order value.
codAmount(float) Cash on delivery amount. A value greater than zero marks the shipment as COD.
shippingCost(float) Shipping cost paid by the customer.
currency(string) Currency (ISO 4217). Only EUR is currently supported.
planning(object) Delivery planning.
deliveryDate(string) Expected delivery date (YYYY-MM-DD or ISO 8601 date-time with offset, e.g. 2026-08-10T15:00:00+02:00; always returned as YYYY-MM-DD).
latestShipDate(string) Latest useful ship date (YYYY-MM-DD or ISO 8601 date-time with offset, e.g. 2026-08-10T15:00:00+02:00; always returned as YYYY-MM-DD).
latestDeliveryDate(string) Latest useful delivery date (YYYY-MM-DD or ISO 8601 date-time with offset, e.g. 2026-08-10T15:00:00+02:00; always returned as YYYY-MM-DD).
customAttributes(object) Merchant-defined custom attributes, searchable via GET /shipments.
custom1(string) Custom field 1.
custom2(string) Custom field 2.
custom3(string) Custom field 3.
parcels(array) Parcels of the shipment (maximum 100). For each parcel: provide boxCode (dimensions come from the company box registry; weight is still required), or the full set weight + length + width + height. Otherwise the item is rejected with INVALID_BOX_CODE or MISSING_PARCEL_DIMENSIONS.
id(string) Client-side parcel identifier, referenced by orderItems[].parcelId.
trackingNumber(string) Parcel-specific tracking number, when the courier assigns one per parcel.
weight*(float) Weight in kg. Always required.
length(float) Length in cm. Required when boxCode is not provided.
width(float) Width in cm. Required when boxCode is not provided.
height(float) Height in cm. Required when boxCode is not provided.
boxCode(string) Code of a box from the company box registry (provides the dimensions).
content(string) Free-text description of the parcel content.
originCountry(string) Origin country of the goods (ISO 3166-1 alpha-2).
orderItems(array) Order lines of the shipment (maximum 500).
sku*(string) Product SKU.
name*(string) Product name.
quantity(int) Quantity. Default: 1.
price(float) Unit price.
total(float) Line total (price × quantity).
weight(float) Gross weight in kg.
netWeight(float) Net weight in kg.
unitOfMeasurement(string) Unit of measurement (e.g. pcs).
url(string) Product page URL.
imageUrl(string) Product image URL.
isReturnable(bool) Whether the item can be returned. Default: true.
customsCode(string) Customs (HS) code.
originCountry(string) Origin country of the item (ISO 3166-1 alpha-2).
parcelId(string) Id of the parcel containing the item (reference to parcels[].id).
transparencyCodes(array) Amazon Transparency codes (array of strings).
notes(string) Free-text notes of the line.
custom1…custom5(string) Line custom fields (custom1 to custom5).
Body 201 — all shipments created

            
summary(object) Batch summary.
totalRequested(int) Shipments in the request.
totalSuccess(int) Shipments created.
totalFailed(int) Shipments rejected.
items(array) Per-item outcomes, in the same order as the request.
status(string) Item outcome: success or error.
trackingNumber(string) Tracking number of the request item.
id(int) Id of the created shipment. null on error.
trackingUrl(string) Public tracking page URL of the created shipment. null on error.
errors(array) Item errors, present when status is error.
code(string) Machine-readable error code (see table below).
message(string) Human-readable message.
field(string) Field the error refers to, when applicable.
Body 207 — partial or total failure (Multi-Status)

            
Per-item error codes
INVALID_COURIER The courier value does not match any active courier (neither as channel transcoding, code nor name). Message: Invalid courier: 'X'.
COURIER_NOT_CONFIGURED The courier variant exists but is not configured on the authenticated channel. Message: Courier 'X' is not configured for this channel, field: courier.
INVALID_LANGUAGE The language specified in language is not supported.
INVALID_ORIGIN The platform specified in origin does not exist in the platform registry.
DUPLICATE_SHIPMENT A shipment with the same channel + courier + trackingNumber triple already exists. Duplicates are detected within the same batch as well.
INVALID_BOX_CODE The specified boxCode does not exist in the company box registry (or the registry is empty).
MISSING_PARCEL_DIMENSIONS A parcel without boxCode is missing the full set weight + length + width + height.
INTERNAL_ERROR Unexpected internal error while creating the item.
Errors
401 Unauthorized: missing or invalid token.
403 Forbidden: channel context missing from the token, or the token lacks the shipments:write scope.
422 Unprocessable Entity: static payload violations (RFC 7807 with violations). The whole request is rejected, no shipment is created.
429 Too Many Requests: rate limit exceeded.

POSTImport shipments (asynchronous)

Imports up to 5000 shipments in a single asynchronous request. The request queues a background job and immediately replies 202 with the job coordinates; the per-shipment outcome is obtained by polling the job.

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
Body
The request body must be a JSON containing the following parameters:

            

*Required parameter

shipments*(array) Shipments to import (minimum 1, maximum 5000). Each shipment has the same format documented in POST /shipments.
webhookUrl(string) URL notified when the import completes (optional). The notification is best-effort: always use job polling as the source of truth. Must be an https URL resolving to a public address: an http URL is rejected with 422.
Body 202 — job accepted

            
jobId(string) Identifier of the asynchronous job.
status(string) Initial job status: processing.
statusUrl(string) Relative URL to check the job status (/jobs/{jobId}).
totalShipments(int) Number of shipments queued.
Job polling

Poll GET /v2/jobs/{jobId} to follow the progress (statuses: pending, processing, completed, failed; required scope: jobs:read). Once the job is finished, the result field contains the summary, the successes in compact form and the errors in detailed form:


            
result.summary(object) Batch summary: totalRequested, totalSuccess, totalFailed.
result.successes(array) Created shipments, compact form: index (position in the request array), id, trackingNumber, trackingUrl (public tracking page URL).
result.errors(array) Rejected shipments, detailed form: index, trackingNumber and the errors[] array with code, message, field. The codes are the same as POST /shipments, plus VALIDATION_ERROR for statically invalid items.

The failed status is reserved for the case where every shipment failed (or an infrastructure error); a partial failure leaves the job completed with the errors in result.errors.

Webhook

If you provided webhookUrl, Qapla' sends a best-effort POST at the end of the job with body {"jobId": "...", "status": "completed|failed", "result": {...}}, where result has the same structure shown above.

Errors
401 Unauthorized: missing or invalid token.
403 Forbidden: channel context missing from the token, or the token lacks the shipments:write scope.
422 Unprocessable Entity: malformed body, empty shipments array or more than 5000 items, invalid webhookUrl (RFC 7807 with violations).
429 Too Many Requests: rate limit exceeded.

GETSearch shipments

Returns the paginated list of shipments of the authenticated channel or, with scope=company, of every active channel of the company. All filters are optional and combine with AND semantics; without filters the endpoint is a plain paginated listing.

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.

Reconciling every channel of the company
To fetch the updates of all channels in a single call (for example those of missed webhooks) combine scope=company, updatedAfter and sortBy=updatedAt_asc:

GEThttps://api.qapla.it/v2/shipments?scope=company&updatedAfter=2026-10-12 00:00:00&sortBy=updatedAt_asc&limit=100

Do not use page to continue: shipments that change status while you read move between pages and some would be missed. Instead, repeat the same call passing the statusUpdatedAt of the last item received as updatedAfter, until the response holds fewer than limit items. The boundary item is returned again: deduplicate by id. The channelId field of each item tells which channel it belongs to.
statusUpdatedAt is ISO 8601 in UTC (2026-08-03T10:00:00+00:00), the same format as the v2 webhook: the statusUpdatedAt of a response or of a webhook can be passed back as updatedAfter as it is, with no conversion. It must be encoded in the query string: the + of the offset becomes %2B, otherwise it is read as a space. Alternatively replace +00:00 with Z, which needs no encoding (updatedAfter=2026-08-03T10:00:00Z).

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}
Query Parameters
trackingNumber(string) Tracking number, exact match.
courier(string) Courier code, exact match: the same value as items[].courier. A canonical code (e.g. BRT) includes the shipments on its variants, a variant code returns only that variant. An unknown code returns an empty list.
orderReference(string) Order reference, exact match.
custom1(string) Custom attribute 1, exact match.
custom2(string) Custom attribute 2, exact match.
custom3(string) Custom attribute 3, exact match.
shipDateFrom(string) Ship date from, inclusive (YYYY-MM-DD).
shipDateTo(string) Ship date to, inclusive (YYYY-MM-DD).
status(string) Comma-separated list of tracking status names (e.g. IN_TRANSIT,OUT_FOR_DELIVERY,DELIVERED). Allowed values in the legend below; an integer or an unknown name returns 422.
updatedAfter(string) Only shipments whose tracking status changed at or after this moment. Accepts ISO 8601 with an offset (2026-08-03T10:00:00Z, 2026-08-03T10:00:00+00:00, 2026-08-03T12:00:00+02:00), or YYYY-MM-DD HH:MM:SS without an offset, interpreted as Rome time (Europe/Rome). ISO 8601 without an offset (2026-08-03T10:00:00) returns 422. Shipments never updated are excluded. Recommended for polling updates.
scope(string) Search perimeter: channel (default) the authenticated channel only, company every active channel of the company the API key belongs to. The other filters still apply in AND with company.
company requires an API key enabled for company-wide reads, otherwise it returns 403. Enabling is per API key and must be requested from Qapla' Support.
page(int) Page number. Default: 1.
limit(int) Results per page. Default: 20, maximum: 100.
sortBy(string) Sort order: id_desc (default), id_asc, shipDate_desc, shipDate_asc, updatedAt_desc, updatedAt_asc. The updatedAt_* orders sort by statusUpdatedAt, then by id.
Tracking statuses
WAITING_TO_COMPUTE Waiting to be processed.
PENDING Waiting for the first tracking event.
INFO_RECEIVED The courier received the shipment data.
IN_TRANSIT In transit.
OUT_FOR_DELIVERY Out for delivery.
FAILED_ATTEMPT Failed delivery attempt.
EXCEPTION Exception (e.g. held in depot).
DELAY Delayed.
PICKUP_POINT Delivered to the pickup point.
DEPARTED Departed.
PROCESSING Being processed by the courier.
RETURNED Returned to sender.
DELIVERED Delivered.
Body 200

            
items(array) Shipments of the current page (summary projection; for parcels, order lines, history and notifications use GET /shipments/{id}).
id(int) Shipment id.
channelId(int) Id of the channel the shipment belongs to. Useful with scope=company.
trackingNumber(string) Courier tracking number.
trackingUrl(string) Public tracking page URL. null when the tracking token is not available.
hash(string) Public tracking token, the last segment of trackingUrl. null when not available.
courier(string) Canonical courier code.
courierName(string) Canonical courier name.
courierVariant(object) Courier contract the shipment was generated with, when the merchant has several contracts with the same courier (currently BRT only): code (string), the variant code, e.g. BRT-V3; alias (string), the name the merchant gave that contract on the channel, null when not set. null for shipments of a courier without variants. courier and courierName stay those of the canonical courier.
status(string) Tracking status name, e.g. IN_TRANSIT (see the legend in the REQUEST tab).
statusDescription(string) Status description, localized in the shipment language.
statusDetail(int) Status detail id (0 = none).
statusDetailDescription(string) Status detail description, localized.
statusDate(string) Date of the last tracking event as reported by the courier.
statusUpdatedAt(string) When the tracking status last changed on Qapla', ISO 8601 in UTC (2026-08-03T10:00:00+00:00). This is the field the updatedAfter filter acts on.
statusPlace(string) Place of the last tracking event.
shipDate(string) Ship date (YYYY-MM-DD).
orderReference(string) Merchant order reference.
platformOrderId(string) Order id on the source platform.
orderDate(string) Order date (YYYY-MM-DD).
tag(string) Free-text tag of the shipment.
note(string) Free-text note of the shipment.
origin(string) Source platform of the order.
isReturn(bool) Whether this shipment is a return.
consignee(object) Recipient: name, street, city, postcode, state, country, email, phone.
monetary(object) Monetary information: totalValue, codAmount, shippingCost, currency.
customAttributes(object) Merchant-defined custom attributes: custom1, custom2, custom3.
total(int) Total number of shipments matching the filters.
page(int) Current page.
limit(int) Shipments per page.
pages(int) Total number of pages.
Errors
401 Unauthorized: missing or invalid token.
403 Forbidden: channel context missing from the token, the token lacks the shipments:read scope, or scope=company with an API key that is not enabled (This API key is not enabled for company-wide reads.).
422 Unprocessable Entity: invalid query parameters (e.g. unknown status values, scope or sortBy not allowed, malformed updatedAfter, limit > 100).
429 Too Many Requests: rate limit exceeded.

GETShipment details

Returns the full detail of a shipment: all the summary fields of GET /shipments plus delivery planning, parcels, order lines, tracking history, sent notifications and flag.

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}
Path
id*(int) Numeric id of the shipment (returned at creation time or by GET /shipments).
Body 200

            

The summary fields (id, channelId, trackingNumber, trackingUrl, hash, courier, courierName, courierVariant, status, statusDescription, statusDetail, statusDetailDescription, statusDate, statusUpdatedAt, statusPlace, shipDate, orderReference, platformOrderId, orderDate, tag, note, origin, isReturn, consignee, monetary, customAttributes) are documented in GET /shipments. In addition, the detail includes:

planning(object) Delivery planning: deliveryDate, latestShipDate, latestDeliveryDate.
parcels(array) Parcels of the shipment, as recorded at creation time.
id(string) Client-side parcel identifier.
trackingNumber(string) Parcel-specific tracking number.
weight(float) Weight in kg.
length(float) Length in cm.
width(float) Width in cm.
height(float) Height in cm.
boxCode(string) Box registry code used at creation.
content(string) Parcel content description.
originCountry(string) Origin country of the goods (ISO 3166-1 alpha-2).
orderItems(array) Order lines of the shipment: sku, name, quantity, price, total, weight, netWeight, unitOfMeasurement, url, imageUrl, isReturnable, customsCode, originCountry, parcelId, notes, custom1…custom5.
history(array) Tracking history, most recent first.
date(string) Event date (YYYY-MM-DD HH:MM:SS).
courierStatus(string) Raw status as reported by the courier.
place(string) Event place.
status(string) Mapped Qapla' status description.
statusCode(string) Mapped Qapla' status code (e.g. IN_TRANSIT, DELIVERED).
statusDetail(string) Status detail description, when present.
notifications(array) Notifications sent for this shipment.
type(string) Notification type: email, sms or webhook.
result(string) Outcome: OK or KO.
date(string) Sent at, ISO 8601 in UTC (2026-08-06T10:21:00+00:00).
recipient(string) Recipient (email address, phone number or URL).
shipmentStatus(string) Shipment status at notification time.
error(string) Error detail, when the outcome is KO.
flag(object) Flag of the shipment (set from the panel, or with PUT /shipments/{id}/flag), null when the shipment is not flagged. Detail only: GET /shipments does not return it.
reason(string) Reason code (list in PUT /shipments/{id}/flag).
description(string) The reason in English.
note(string) The note, or null.
flaggedAt(string) When the shipment was flagged, ISO 8601 in UTC. null when the date is not recorded.
Errors
401 Unauthorized: missing or invalid token.
403 Forbidden: channel context missing from the token, or the token lacks the shipments:read scope.
404 Not Found: the shipment does not exist, or does not belong to the authenticated channel. The detail stays per channel even when the API key is enabled for scope=company in the search.
429 Too Many Requests: rate limit exceeded.

DELETEDelete shipment

Deletes a shipment identified by its id. Returns HTTP 204 with no body. From then on the shipment no longer appears in GET /shipments or GET /shipments/{id}, and it is no longer tracked.

Note
Authentication requires the Bearer Token obtained from the authentication service. Required scope: shipments:write. The shipment must belong to the authenticated channel: a shipment of another channel returns 404, indistinguishable from a non-existing one.
Deletion is permanent: the API offers no way to restore the shipment. It is not blocked by the status, so a delivered or labelled shipment can be deleted too. It triggers no webhook or notification.

DELETEhttps://api.qapla.it/v2/shipments/{id}
Path
id*(int) Numeric id of the shipment (returned in items[].id by POST /shipments or GET /shipments).
Migrating from deleteShipment (1.2)

DELETE /1.2/deleteShipment/ identifies the shipment by courier + trackingNumber, v2 by its id. If the id was not stored from the creation response, get it in two steps:

  1. GET /v2/shipments?courier={COURIER}&trackingNumber={TN}: exact match on both, within the token's channel only. courier is the same code used in 1.2 and includes the courier's variants;
  2. DELETE /v2/shipments/{items[].id}.
Response

HTTP 204 No Content: no body in the response.

Errors
401 Unauthorized: missing or invalid token.
403 Forbidden: channel context missing from the token, or the token lacks the shipments:write scope.
404 Not Found: shipment does not exist, belongs to another channel or was already deleted. A second DELETE on the same shipment therefore returns 404.

PUTFlag a shipment

Flags a shipment with a reason and an optional note, as «Segnala questa spedizione» does in the panel: a flag set through the API is shown in the shipment detail of the panel too, and a flag set from the panel is returned in flag by GET /shipments/{id}.

A shipment has at most one flag: an existing one is replaced, reason and note included. A PUT without note therefore clears the previous note. To remove the flag use DELETE /shipments/{id}/flag.

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

PUThttps://api.qapla.it/v2/shipments/{id}/flag
Path
id*(int) Numeric id of the shipment.
Body
The request body must be a JSON containing the following parameters:

            

*Required parameter

reason*(string) Reason code, upper case (codes are case-sensitive). Next to it, the description returned in the response:
DAMAGED_GOODSDamaged goods
FAKE_OUT_FOR_DELIVERYFake "out for delivery"
RETURNEDReturned shipment/Generic return
CONSIGNEE_UNREACHABLEUnreachable/Not available customer
DAMAGED_ACCEPTEDAccepted damaged parcel
DAMAGED_REFUSEDRefused damaged parcel
LOSTLost parcel
CUSTOMS_DELAYCustoms clearance delay
COURIER_DELAYCourier delay
SENDER_DELAYSender delay
CONSIGNEE_DELAYRecipient delay
OTHER_DELAYOther delay
note(string) Free note, up to 255 characters. Optional: when missing or empty, the flag has no note.
Body 200
The flag as stored, in the same shape as the flag field of GET /shipments/{id}:

            
reason(string) Reason code.
description(string) The reason in English (Lost parcel).
note(string) The note, or null.
flaggedAt(string) When the shipment was flagged, ISO 8601 in UTC (2026-11-13T16:20:00Z). null when the date is not recorded.
Errors
401 Unauthorized: missing or invalid token.
403 Forbidden: channel context missing from the token, or the token lacks the shipments:write scope.
404 Not Found: the shipment does not exist, was deleted, or belongs to another channel.
422 Unprocessable Entity: reason missing or unknown (lower case included), or note longer than 255 characters.

DELETERemove the flag

Removes the flag of a shipment, set with PUT /shipments/{id}/flag or from the panel. Returns HTTP 204 with no body also when the shipment was not flagged, so the call can be repeated without errors. From then on flag in GET /shipments/{id} is null.

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

DELETEhttps://api.qapla.it/v2/shipments/{id}/flag
Path
id*(int) Numeric id of the shipment.
Response

HTTP 204 No Content: no body in the response.

Errors
401 Unauthorized: missing or invalid token.
403 Forbidden: channel context missing from the token, or the token lacks the shipments:write scope.
404 Not Found: the shipment does not exist, was deleted, or belongs to another channel.

POSTRequest a stock release

Asks the courier to act on a shipment currently held in depot (giacenza): re-deliver it, re-deliver it to a new address, or return it to the sender.

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
Path
id*(int) Numeric id of the shipment held in depot.
Body
The request body must be a JSON containing the following parameters:

            

*Required parameter

action*(string) Canonical action: redeliver, redeliver_new_address or return_to_sender.
notes(string) Free-text note for the courier (optional).
redeliveryDate(string) Requested redelivery date, ISO format (YYYY-MM-DD). Only allowed for redeliver and redeliver_new_address (a 422 is returned with return_to_sender). GLS requires a redelivery date: when omitted it defaults to the next Italian working day. Ignored by couriers that do not support it.
address(object) New delivery address. Required if and only if action is redeliver_new_address (a 422 is returned otherwise, either missing when required or present when not allowed).
name*(string) Recipient name.
street*(string) Street address.
city*(string) City.
zip*(string) ZIP / postal code.
province*(string) Province code (e.g. MI).
phone(string) Contact phone (optional).
Body 200

            
status(string) Always sent — the request was accepted and transmitted to the courier.
courierOutcome(string) Real courier outcome: ok or error for synchronous couriers (GLS, TNT), pending for deferred couriers (BRT).
message(string) Courier outcome message, when available. null otherwise.
releaseId(int) Internal id of the stored release request.
Errors
401 Unauthorized: missing or invalid token.
403 Forbidden: channel context missing from the token, or the token lacks the shipments:write scope.
404 Not Found: the shipment does not exist, or does not belong to the authenticated channel.
409 Conflict: no giacenza to release — the shipment is not currently held in depot, or the release was already requested.
422 Unprocessable Entity: validation error (invalid action, missing/unexpected address, invalid or not allowed redeliveryDate), stock release not configured for the channel (for BRT: giacenze FTP access missing), or a carrier communication error.
429 Too Many Requests: rate limit exceeded.

POSTSend a recipient notification for an event of yours

Sends the shipment's recipient the transactional email configured for an event you define: order being prepared, refund issued, item ready for in-store pickup — the steps only your system knows about and that Qapla' cannot detect from tracking. You choose the moment: before, during, or even months after the shipment.

The email goes through the same engine as the channel's other transactional emails: same sender, same languages, same variables. Each event's template is configured in the control panel, under Marketing → Transactional emails → At any time → "When you decide, via API": one template per event and language, plus an optional fallback template (default) that applies to every event without one of its own. The template is resolved in the order (event, language) → (event, English) → (fallback, language) → (fallback, English). Qapla' never sends anything on its own: only what you call goes out.

Delivery is asynchronous: the 202 response confirms the request was accepted, not that the email was delivered. The sent email shows up in the shipment detail, Notifications section. The same event on the same shipment is accepted once every 24 hours: a second call within the window gets a 409.

Note
Authentication requires the Bearer Token obtained from the authentication service. Required scope: shipments:write. The shipment must belong to the authenticated channel, and the channel must have its transactional emails managed by Qapla'.

POSThttps://api.qapla.it/v2/shipments/{id}/notifications
Path
id*(int) Numeric id of the shipment, the same returned by GET /shipments/{id} and POST /shipments.
Body
The request body must be a JSON containing the following parameters:

            

*Required parameter

event*(string) Event code, as configured in the control panel: 2 to 25 characters, lowercase letters, digits, hyphen and underscore, starting with a letter or digit (^[a-z0-9][a-z0-9_-]{1,24}$). default and amazon are reserved and rejected.
variables(object) Your own values for this message, available in the template as [*CUSTOM1*], [*CUSTOM2*], [*CUSTOM3*]. When omitted, the template uses the custom fields already stored on the shipment. They are never stored: they apply to this email only.
custom1(string) Max 255 characters.
custom2(string) Max 255 characters.
custom3(string) Max 255 characters.
Any other key returns a 422.
language(string) Two-letter code of the template language to use (it, en, de, fr, es, pt, zh, ru, ja, cs, ro, hu, ar, sk, pl, ko, nl). Defaults to the shipment language.
Body 202

            
notificationId(string) Identifier (UUID) of the accepted notification. Quote it to support if the email does not appear to have gone out.
shipmentId(int) Id of the shipment the notification refers to.
event(string) Event code, as sent.
status(string) Always accepted: the notification has been handed to the delivery engine. The email goes out asynchronously.
Errors
401 Unauthorized: missing or invalid token.
403 Forbidden: channel context missing from the token, or the token lacks the shipments:write scope.
404 Not Found: the shipment does not exist, or does not belong to the authenticated channel.
409 Conflict, two distinct cases told apart by the detail: the channel does not have its transactional emails managed by Qapla' (the notification cannot be delivered: the service must be enabled from the control panel); or the same event was already sent for this shipment within the last 24 hours — the message carries the date and notificationId of the previous send.
422 Unprocessable Entity: invalid or reserved event, unsupported variables key or value over 255 characters, unknown language, the shipment has no recipient email address, or the channel has no active template for the event in the requested language nor a fallback template.
429 Too Many Requests: rate limit exceeded.
503 Service Unavailable: the notification could not be queued because of a temporary problem with the delivery engine. No email went out: retry later.

Orders

The Orders APIs expose the orders of the authenticated channel: an order is the document that comes before the shipment and carries its data — recipient, amounts, planning, line items and parcels — before the label is generated.

An order is uniquely identified by its numeric Qapla' id, and on the channel also by the source + reference pair, the natural key the origin platform knows it by.

Required scope: orders:read for the listing, the detail and the courier check of addresses; orders:write to create, update and delete.

Version: 2.0 for GET /orders, GET /orders/{id}, POST /orders, PUT /orders/{id} and PATCH /orders/{id}; this page describes 2.0. DELETE /orders/{id}, POST /orders/{id}/restore and POST /orders/courier-checks have a single version. See Versioning.

Previous version (1.1)
Channels that used the orders before 2.0 are pinned to 1.1 and keep receiving the previous names until they ask for 2.0 with X-Endpoint-Version: 2.0. Only the names and shape of these fields differ between the two versions; the fields 2.0 adds appear in 1.1 too.

2.01.1Where
platformOrderIdorderIdrequest and response
couriercourierIdon write: courier code (string) instead of the id; an unknown code returns 422, null = no courier. courierId stays in the response
couriercourierCoderesponse
items[].parcelNumberitems[].parcelIdrequest and response: 1-based position of the parcel, 0 = none
parcels[]parcels[]response: in 1.1 these are not the stored parcels but parcelsCount parcels rebuilt from the order totals, the weight split evenly and the dimensions on the first one only
parcels[].boxIdparcels[].boxrequest
pudo.postcodepudo.postalCoderequest
pudo.streetpudo.addressrequest: address is no longer accepted
planning.deliveryOptionsplanning.deliveryOptionsalways an array of codes (a comma-separated string in 1.1); [] = no option, null = courier defaults
weight, length, width, heighttotalWeight, firstParcelLength, firstParcelWidth, firstParcelHeightresponse

GETList orders

Returns the paginated list of orders of the authenticated channel, newest first (order date descending). Deleted orders are excluded; with includeDeleted=true the source + reference lookup returns them, so you can get the id to pass to POST /orders/{id}/restore.

Exact lookup by natural key
When source and reference are provided together, the endpoint does not paginate: it looks up the order with that natural key on the channel and returns an array with a single element, or 404 if it does not exist. Providing only one of the two filters nothing: the other parameter is ignored and you get the paginated listing.

Note
The response is a JSON array of orders, not an envelope object: pagination information is returned in the X-Page, X-Limit and X-Total-Count headers.

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

GEThttps://api.qapla.it/v2/orders?page={PAGE}&limit={LIMIT}
Query Parameters
source(string) Origin platform of the order (e.g. shopify, magento2), exact match. To be used together with reference.
reference(string) Merchant order reference, exact match. To be used together with source.
includeDeleted(bool) Only with source + reference: with true the order is returned even when deleted (deleted: true), so you can get its id for POST /orders/{id}/restore. Default: false. Ignored by the paginated listing.
page(int) Page number. Default: 1. Values lower than 1 are clamped to 1.
limit(int) Results per page. Default: 50, maximum: 100. Out-of-range values do not raise an error, they are clamped into the range.
Response headers
X-Page(int) Current page. Not returned by the source + reference lookup.
X-Limit(int) Results per page actually applied. Not returned by the source + reference lookup.
X-Total-Count(int) Total number of orders of the channel. It is 1 for the source + reference lookup.
Body 200

            

Every element of the array is the full order representation, the same one returned by GET /orders/{id}: the listing is not a reduced projection and includes line items and parcels as well.

id(int) Qapla' order id.
deleted(bool) true when the order is deleted. Only the lookup with includeDeleted=true returns a deleted order.
channelId(int) Id of the channel the order belongs to.
reference(string) Human readable merchant order reference (e.g. ORD-2026-123).
platformOrderId(string) Order id on the origin platform.
source(string) Origin platform of the order.
courierId(int) Id of the assigned courier. 0 when not assigned yet.
courierService(string) Courier service/contract code.
courier(string) Code of the assigned courier (e.g. BRT), the same one POST /labels takes and that is sent on write. null when not assigned.
courierChecks(object) What the preassigned courier would refuse at label creation, checked on the order. A warning only: it never blocks anything, neither the order nor the label. null when the order has no courier (courierId 0) or the courier is unknown. The same field is also returned when the order is created or modified (POST, PUT, PATCH).
Postcode, province and locality checks apply to domestic destinations only (IT, SM, VA); lengths and required fields also apply abroad, depending on the courier.
courier(string) Code of the canonical courier the order was checked against: for a contract variant it is the parent courier (e.g. BRT-V1 → BRT).
status(string) OK when checks is empty, WARNING when it holds at least one check.
checks(array) Failed checks. Each one has code and field, the path of the field in this payload: consignee.name, consignee.street, consignee.city, consignee.state, consignee.postcode, consignee.phone, consignee.email, notes.
FIELD_TOO_LONG The field exceeds the length the courier accepts. Also: max (int), the maximum length, and length (int), that of the value.
FIELD_REQUIRED The field is empty but the courier requires it.
PROVINCE_NOT_CODE consignee.state is not a province code. Also: suggestion (string), the inferred code, null when it cannot be inferred.
POSTAL_CODE_INVALID Italian consignee.postcode that is not 5 digits.
POSTAL_CODE_UNKNOWN 5-digit consignee.postcode that does not exist. IT only.
LOCALITY_NOT_DELIVERED The postcode + city pair is not among those the courier has delivered to (usually the city does not match the postcode). Also: suggestions (array, at most 5), the localities the courier has delivered to with that postcode, or with that city and province, as {postcode, city, state}; when there are none, the official municipalities of the postcode.
ZONE_SUSPENDED The courier has suspended deliveries to the area consignee.postcode falls in. Also: until (string), the day (YYYY-MM-DD) the courier resumes deliveries, null when not announced.
Example: {"courier": "BRT", "status": "WARNING", "checks": [{"code": "FIELD_TOO_LONG", "field": "consignee.street", "max": 35, "length": 41}, {"code": "PROVINCE_NOT_CODE", "field": "consignee.state", "suggestion": "RM"}]}
senderId(int) Sender id from the channel dictionary. null when not assigned.
status(string) Current order status.
createdAt(string) Order date, ISO 8601 in UTC. It is the field the listing is sorted by.
updatedAt(string) Last update date of the order, ISO 8601 in UTC.
isReturnable(bool) Whether the order is returnable.
hasCustomParcels(bool) The order manages its parcels one by one: parcels is the source of truth and weight and parcelsCount are their aggregates, changed by editing the parcels rather than directly on the order.
costCenterCode(string) Poste Italiane cost centre chosen for the order. null when none is set: the label then uses the first cost centre configured on the channel.
notes(string) General order notes.
content(string) Content description.
tag(string) Free order tag.
pickupDate(string) Pickup date (YYYY-MM-DD).
pickupTime(string) Pickup time (HH:MM).
pickupPoint(string) Id of the chosen pickup point (PUDO).
consignee(object) Recipient: name, street, city, state, postcode, country, email, phone.
monetary(object) Monetary details: paymentMethod, isCod, codPaymentOption, value, shippingCost, currency, shippingInsurance.
planning(object) Planning: deliveryOptions (array of the courier's option codes, e.g. ["A", "P"]), requestedDeliveryDate, latestShipDate, latestDeliveryDate. Dates are returned as YYYY-MM-DD.
customAttributes(object) Merchant custom attributes: custom1, custom2, custom3.
weight(float) Total weight of all parcels, in kg.
parcelsCount(int) Number of physical parcels.
length(float) Length of the first parcel, in cm.
width(float) Width of the first parcel, in cm.
height(float) Height of the first parcel, in cm.
parcels(array) Physical parcels of the order.
id(int) Parcel id. null when readOnly is true.
boxId(int) Id of the box, from the channel's box registry, used for the parcel.
weight(float) Parcel weight, in kg.
length(float) Length, in cm.
width(float) Width, in cm.
height(float) Height, in cm.
content(string) Description of the parcel content.
originCountry(string) Country of origin for customs, ISO 3166-1 alpha-2.
insurance(float) Insured amount.
reference(string) Your own parcel code (e.g. the parcel id in your warehouse system): up to 25 characters among letters, digits, space and . _ / # -. It can also be written when creating or updating the order. It is not sent to the courier: it is copied into the shipment's parcel detail when the label is created, and printed on that parcel's label if the channel asks for it and the courier supports it.
readOnly(bool) true for the parcels of an order written by the control panel or by the 1.x APIs, whose detail is not yet managed parcel by parcel: their id is null and they cannot be edited one at a time.
parcelHash(string) The hash of the parcel created with POST /parcels this parcel was inherited from (the hash printed on its provisional label), otherwise null. Read-only.
items(array) Order line items. Empty array when the order has none.
sku(string) Product SKU.
name(string) Product name or description.
quantity(int) Quantity ordered.
weight(float) Unit weight in kg.
url(string) Product page URL.
imageUrl(string) Product image URL.
price(float) Unit price.
total(float) Row total (quantity × price).
isReturnable(bool) Whether the line item is returnable.
notes(string) Line item notes.
customsCode(string) Customs HS code.
originCountry(string) Origin country, ISO 3166-1 alpha-2.
netWeight(float) Net weight in kg.
unitOfMeasurement(string) Unit of measurement.
parcelNumber(int) Position (starting from 1) in parcels of the parcel holding this line item. 0 when the line item is not assigned to a parcel.
transparencyCodes(array) Amazon Transparency codes attached to the line item.
Errors
401 Unauthorized: missing or invalid token.
403 Forbidden: channel context missing from the token, or the token does not hold the orders:read scope.
404 Not Found: no order with that source + reference pair on the channel. Only for the natural-key lookup: a paginated listing with no results is a 200 with an empty array.
429 Too Many Requests: rate limit exceeded.

GETGet order

Returns a single order by its Qapla' id. The representation is the same one returned by GET /orders, as a single object instead of an array element.

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

GEThttps://api.qapla.it/v2/orders/{id}
Path
id*(int) Qapla' order id (returned at creation time or by GET /orders). It is not the merchant reference: to look up by reference use GET /orders with source + reference.
Body 200

            

Fields are the ones documented in GET /orders.

Errors
401 Unauthorized: missing or invalid token.
403 Forbidden: channel context missing from the token, or the token does not hold the orders:read scope.
404 Not Found: order not existing, deleted, or belonging to another channel.
429 Too Many Requests: rate limit exceeded.

POSTCreate an order

Creates an order on the authenticated channel and returns it, in the same representation as GET /orders/{id}. The order is the document the label is then generated from.

Natural key
The source + reference pair is unique on the channel: if an order with the same pair already exists the response is 409 and the existing order is left untouched. The pair stays taken even after the order has been deleted with DELETE: it cannot be reused for a new order. To change it use PUT or PATCH with its id, which GET /orders returns when given source and reference.

Messages to the recipient
An order created here is an imported order in every respect: if the channel has the order-received transactional message enabled, the recipient gets it at the address in consignee.email.

Note
Authentication requires the Bearer Token obtained from the authentication service. Required scope: orders:write. Keys the endpoint does not know, inside objects too, are not ignored: the response is 422 with the keys in detail (Unknown fields: customCharges.). A key inside an object is reported by its name only, without the path, and when there are some both at the top and inside an object the message lists only the nested ones. The same holds for PUT and PATCH; channels served in version 1.1 keep seeing them ignored.

POSThttps://api.qapla.it/v2/orders
Body

            
reference*(string) Merchant order reference, human readable (e.g. ORD-2026-124). Up to 255 characters. Together with source it is the natural key.
source*(string) Platform the order comes from (e.g. shopify, magento2, api). Up to 50 characters.
platformOrderId(string) Id of the order on the source platform. Up to 255 characters.
courier(string) Code of the pre-assigned courier (e.g. BRT, GLS-ITA), the same POST /labels takes. An unknown code returns 422; null or an empty string = no courier. Up to 50 characters.
courierService(string) Courier service/contract code. The codes of each courier are in services of GET /couriers/{code}. Up to 100 characters.
costCenterCode(string) Poste Italiane only (PTI and its variants): the cost centre to use for the label, among those configured on the channel. Ignored with any other courier. null or empty clears it. Up to 50 characters.
status(string) Status of the order on the source platform, free text. Up to 50 characters.
createdAt(string) Order date: ISO 8601 with offset (2026-11-02T09:30:00+01:00, or Z) or YYYY-MM-DD. Returned in UTC.
notes(string) General order notes; line breaks are removed.
content(string) Description of the contents. Up to 255 characters.
tag(string) Free tag of the order. Up to 50 characters.
pickupDate(string) Pickup date, YYYY-MM-DD.
pickupTime(string) Pickup time, HH:MM.
pickupPoint(string) Id of the pickup point (PUDO), as an alternative to pudo.id: when both are sent this one wins. Up to 100 characters.
isReturnable(bool) The order can be returned. Default false.
platformDeliveryType(string) The shipping method chosen on the source platform (e.g. Standard shipping). Up to 100 characters.
consignee(object) The recipient.
name(string)Full name or company name.
street(string)Street address with house number.
city(string)City.
state(string)Province code (e.g. PD). For Italy, when missing it is derived from city or postcode, and a province name spelled out is turned into its code.
postcode(string)Postcode.
country(string)Country, ISO 3166-1 alpha-2. Defaults to IT.
email(string)Recipient email: it must be a valid address.
phone(string)Recipient phone.
sender(object) The sender, picked by code among the channel's senders: the response shows it as senderId. A code the channel does not have returns 422. The other fields of the object are not saved: senders are managed in the channel's sender list.
pudo(object) The pickup point (PUDO) to deliver to. Only id, in the courier's format, is saved from the object, and the response shows it in pickupPoint.
monetary(object) Amounts and payment.
paymentMethod(string)Payment method of the order on the platform (e.g. paypal).
isCod(bool)Cash on delivery. Default false. It applies only to orders whose source is api: for all the others cash on delivery is decided by paymentMethod, at every write of the order, and it is cash on delivery when the method is one Qapla' recognises as such (e.g. cod, cashondelivery, contrassegno).
codPaymentOption(string)How the cash on delivery is collected, with the courier's code.
value(number)Order value, greater than or equal to 0; with isCod set to true it is the amount to collect.
shippingCost(number)Shipping cost paid by the customer, greater than or equal to 0.
currency(string)ISO 4217 currency, 3 characters. Default EUR.
shippingInsurance(number)Insured value, greater than or equal to 0.
planning(object) Delivery planning.
deliveryOptions(array of string)Courier accessory services, as a list of codes (e.g. ["A", "P"]). [] = no option, null = the courier's defaults.
requestedDeliveryDate(string)Requested delivery date, YYYY-MM-DD.
latestShipDate(string)Date by which to ship: YYYY-MM-DD, or ISO 8601 with offset to give the time too. Always returned as YYYY-MM-DD.
latestDeliveryDate(string)Date by which to deliver, in the same formats as latestShipDate. The time, when given, is the one the messages to the recipient use.
customAttributes(object) Merchant custom attributes: custom1, custom2, custom3.
parcels(array) The parcels of the order. The key behaves three ways: omitted, the parcels do not change; null or [], the parcels are deleted and hasCustomParcels goes back to false; a list, it becomes the complete set of parcels and hasCustomParcels becomes true. The order's total weight, parcel count and first-parcel dimensions are computed from here.
The parcels created with POST /parcels for the same order (same source and reference) become the order's parcels: without parcels (or with null or []) the order inherits them, each with its hash in parcelHash and its clientInternalCode as reference when it is a valid reference; with the same number of parcels the /parcels data is used; with a different number the response is 422. The copy is taken once: later changes to those parcels on /parcels do not reach the order. Parcels created asynchronously (more than 10 in one POST /parcels) are only inherited once their job has completed: create the order after that.
weight(number)Parcel weight in kg.
length, width, height(number)Dimensions in cm.
boxId(int)Id of the box, from the channel's box list, used for the parcel.
content(string)Parcel contents, for customs. Up to 255 characters.
originCountry(string)Country of origin of the goods in the parcel, ISO 3166-1 alpha-2.
insurance(number)Insured value of the parcel, greater than or equal to 0.
reference(string)Your parcel code (e.g. the parcel id of the warehouse system): up to 25 characters among letters, digits, space and . _ / # -. A parcel sent without reference has none: the code does not move from one parcel to another when the order of the list changes.
items(array) The order lines. When the key is present it replaces all the existing lines.
sku(string)Product code.
name(string)Product name or description.
quantity(int)Quantity ordered.
weight, netWeight(number)Unit gross and net weight, in kg.
url, imageUrl(string)URL of the product page and of its image.
price, total(number)Unit price and line total.
isReturnable(bool)The line can be returned. Default false.
notes(string)Line notes.
customsCode(string)HS customs code.
originCountry(string)Country of origin, ISO 3166-1 alpha-2.
unitOfMeasurement(string)Unit of measurement.
parcelNumber(int)Position in parcels, from 1, of the parcel holding the line; 0 = none.
transparencyCodes(array of string)Amazon Transparency codes of the line.
Body 201

            

The created order, with the fields documented in GET /orders: courierChecks already tells what the pre-assigned courier would refuse. The Location header holds the path of the order (/orders/{id}).

Errors
401 Unauthorized: missing or invalid token.
403 Forbidden: channel context missing from the token, or the token does not hold the orders:write scope.
409 Conflict: the channel already has an order with the same source + reference pair, even a deleted one.
422 Unprocessable Entity: validation error, with the fields in detail (e.g. reference: This value should not be blank.); unknown keys (Unknown fields: …); unknown courier code (courier: unknown courier "X".); sender code the channel does not have.
429 Too Many Requests: rate limit exceeded.

PUTReplace an order

Rewrites an existing order with the body sent and returns it updated. The fields are those of POST /orders, with the same rules.

Send the whole order
With PUT always send the whole order, as you would when creating it: it is the way to have on the channel exactly what you sent. To change only some fields use PATCH. items and parcels are replaced entirely when the key is present, and stay as they are when it is missing.

The natural key does not change
reference and source are required, but they do not change the order: it keeps the ones it was created with. An order with another natural key is another order, to create with POST.

Note
Authentication requires the Bearer Token obtained from the authentication service. Required scope: orders:write. The order must belong to the authenticated channel: an order of another channel returns 404, indistinguishable from a non-existent one.

PUThttps://api.qapla.it/v2/orders/{id}
Path
id*(int) Qapla' order id, returned at creation time or by GET /orders.
Body

            

The fields are documented in POST /orders; reference and source are required here too.

Body 200

            

The updated order, with the fields documented in GET /orders.

Errors
401 Unauthorized: missing or invalid token.
403 Forbidden: channel context missing from the token, or the token does not hold the orders:write scope.
404 Not Found: order not existing, deleted, or belonging to another channel.
422 Unprocessable Entity: validation error, with the fields in detail; unknown keys (Unknown fields: …); unknown courier code; sender code the channel does not have.
429 Too Many Requests: rate limit exceeded.

PATCHUpdate an order

Changes only the fields present in the body and returns the updated order: the omitted ones stay as they are. The fields are those of POST /orders, all optional, reference and source included.

Objects and lists
Inside objects (consignee, monetary, planning, customAttributes) the same rule applies: only the keys sent change, so {"consignee": {"phone": "3401122334"}} changes the phone and leaves the rest of the address. Lists instead are replaced entirely: items, when sent, takes the place of all the lines, and parcels follows the three rules of POST (omitted, null/[], list). A field sent as null is cleared.

Note
The natural key does not change: reference and source, if sent, are ignored.

Note
Authentication requires the Bearer Token obtained from the authentication service. Required scope: orders:write. The order must belong to the authenticated channel: an order of another channel returns 404, indistinguishable from a non-existent one.

PATCHhttps://api.qapla.it/v2/orders/{id}
Path
id*(int) Qapla' order id, returned at creation time or by GET /orders.
Body

            

A partial update: tag, recipient phone and requested delivery date. The fields that can be sent are documented in POST /orders.

Body 200

            

The whole order after the change, with the fields documented in GET /orders.

Errors
401 Unauthorized: missing or invalid token.
403 Forbidden: channel context missing from the token, or the token does not hold the orders:write scope.
404 Not Found: order not existing, deleted, or belonging to another channel.
422 Unprocessable Entity: validation error, with the fields in detail; unknown keys (Unknown fields: …); unknown courier code; sender code the channel does not have.
429 Too Many Requests: rate limit exceeded.

DELETEDelete an order

Deletes an order of the authenticated channel. From then on the order no longer appears in GET /orders and the other calls on that id return 404. The deletion can be undone with POST /orders/{id}/restore, using the same id.

Note
Authentication requires the Bearer Token obtained from the authentication service. Required scope: orders:write. The order must belong to the authenticated channel: an order of another channel returns 404, indistinguishable from a non-existent one.

DELETEhttps://api.qapla.it/v2/orders/{id}
Path
id*(int) Qapla' order id, returned at creation time or by GET /orders.
Response 204

No body.

Errors
401 Unauthorized: missing or invalid token.
403 Forbidden: channel context missing from the token, or the token does not hold the orders:write scope.
404 Not Found: order not existing, already deleted, or belonging to another channel.
429 Too Many Requests: rate limit exceeded.

POSTRestore a deleted order

Undoes the deletion of an order, made with DELETE /orders/{id}, from the control panel or with API v1: the order is active again and is returned as GET /orders/{id} returns it. It replaces undeleteOrder of API 1.2/1.3, which worked on the merchant reference; here the Qapla' id is used.

Note
Authentication requires the Bearer Token obtained from the authentication service. Required scope: orders:write. The order must belong to the authenticated channel: an order of another channel returns 404, indistinguishable from a non-existent one.
Deleted orders do not appear in GET /orders, not even when looked up by source + reference: use the id returned at creation time or by a read made before the deletion.

POSThttps://api.qapla.it/v2/orders/{id}/restore
Path
id*(int) Qapla' id of the deleted order. It is not the merchant reference.
Body

No body.

Body 200

            

The restored order; the fields are those documented in GET /orders.

Errors
401 Unauthorized: missing or invalid token.
403 Forbidden: channel context missing from the token, or the token does not hold the orders:write scope.
404 Not Found: order not existing, not deleted, or belonging to another channel.
429 Too Many Requests: rate limit exceeded.

POSTCheck addresses against the courier

Checks up to 100 addresses against what the courier would refuse at label creation, without creating an order. The checks are the same ones returned as courierChecks on the orders (see GET /orders): use it to catch an address the courier will not accept before the order exists, e.g. at checkout or before an import.

A warning only: nothing is saved and nothing is blocked. Each address is checked against its courier, or, when it names none, against every active courier of the channel (label creation enabled).

NB
Authentication uses the Bearer Token obtained from the authentication service. Required scope: orders:read.
A request counts as one against the rate limit, however many addresses it holds.

POSThttps://api.qapla.it/v2/orders/courier-checks
Body
The request body must be a JSON containing the following parameters:

            

*Required parameter

items*(array) From 1 to 100 addresses to check. Each one has the same fields as the order payload.
courier(string) Code of the courier to check against (e.g. BRT, GLS-ITA), the same as in POST /orders and POST /labels: the codes are listed by GET /couriers. A contract variant has its own code and is checked with its own channel configuration; the response carries the code of the canonical courier. Up to 30 characters. Omitted: every active courier of the channel.
consignee*(object) Recipient address, as consignee on the orders. Every field is optional: a field the courier requires and that is missing comes back as FIELD_REQUIRED.
name(string) Recipient full name.
street(string) Street address, house number included.
city(string) City.
state(string) Province / state code (e.g. PD).
postcode(string) Postal code.
country(string) Country, ISO 3166-1 alpha-2 (at most 2 characters).
email(string) Email address. When present it must be valid.
phone(string) Phone number.
notes(string) Order notes, as in the order payload: some couriers limit their length.
Body 200

            

An array with one element per item, in the same order as items. Each element is a list of outcomes, one per courier:

  • with courier: a single outcome;
  • without courier: one outcome per active courier of the channel, at most one per canonical courier (contract variants of the same courier are not repeated). An empty list [] when the channel has no active courier.

Each outcome is shaped exactly as courierChecks on the orders: courier (the code of the canonical courier), status (OK or WARNING) and checks, with the same codes, the same field paths (consignee.state, consignee.postcode, …) and the same extra fields. The full list of codes is in GET /orders, under courierChecks.

Errors
401 Unauthorized: missing or invalid token.
403 Forbidden: channel context missing from the token, or the token does not hold the orders:read scope.
422 Unprocessable Entity: validation error (no items or more than 100, consignee missing, courier longer than 30 characters, invalid email, country longer than 2 characters), or an unknown courier (courier: unknown courier "X".).
429 Too Many Requests: rate limit exceeded.

Labels

The Labels APIs generate the shipping label by calling the courier directly, and store it on the authenticated channel; at the end of the day the labels created are confirmed to the courier in one batch.

Beta test: for now use the Labels APIs only with the GENERIC courier, which produces a real A6 label without calling any courier. The compatible couriers will be released one by one.

A label is identified by its numeric id, and on the channel also by the courier + reference pair: calling the endpoint again with the same pair returns the label already created.

POSTCreate a label

BETA
The Labels APIs are in beta test: for now use them only with the GENERIC courier, which produces a real A6 label without calling any courier. The compatible couriers will be released one by one. The contract may change without notice; for production use v1.3 createLabel.

Calls the courier, generates the shipping label and stores it on the authenticated channel. The label is returned in the format (PDF or ZPL) configured on the channel for that courier.

The call is idempotent on reference: if a label with that reference already exists for the same channel and courier, the response is 200 with the existing label and isExisting set to true, and the courier is not called again.

Version 2.0
Request and response use the same names as orders 2.0 (items, parcelNumber, parcels[].reference, pudo as an object). See Versioning. Keys the endpoint does not know, nested ones included, are not ignored: the response is 422 with Unknown fields: ….

NB
Authentication uses the Bearer Token obtained from the authentication service. No dedicated scope is required: the label is created on the token's channel.

POSThttps://api.qapla.it/v2/labels
Body
The request body must be a JSON containing the following parameters:

            

*Required parameter

courier*(string) Qapla' courier code, with the dash (GLS-ITA, BRT, GENERIC…): the same the orders return in courier. Up to 50 characters.
courierService(string) Courier service code. The codes of each courier are in services of GET /couriers/{code}. For GLS it is the channel's contract code; for some couriers (e.g. BRT) there is no service to choose and the list is empty. Up to 50 characters.
costCenterCode(string) Poste Italiane (PTI) only: the cost center to use for this label. It applies to each call: when omitted or empty, the first cost center configured on the courier is used. Up to 50 characters.
reference*(string) Unique order reference. Up to 50 characters. It is the idempotency key.
source*(string) Platform the order comes from (e.g. shopify, magento, amazon, api). Up to 50 characters.
consignee*(object) The recipient.
name*(string)Full name or company name.
street*(string)Street with house number.
city*(string)City.
state*(string)Province code (2 characters for Italy, e.g. MI).
postcode*(string)Postcode.
country*(string)Country as ISO 3166-1 alpha-2.
email(string)Recipient email.
phone(string)Recipient phone.
weight(number) Total weight in kg, greater than 0. If parcels is missing, the shipment has a single parcel with this weight.
parcels(array) The shipment's parcels, 99 at most. GLS needs at least one of parcels and weight.
Parcels created with POST /parcels for the same order (same source and reference) take precedence: without parcels the label is created with them, and in the response each parcel ties its parcelHash to the courier's trackingNumber and label. A stored order that already inherited them uses its stored parcels; otherwise they are read now and become the order's parcels. With the same number of parcels the /parcels data is used; with a different number the response is 422, before the order is created or the courier called. Parcels created asynchronously (more than 10 in one POST /parcels) are only used once their job has completed.
weight(number)Parcel weight in kg.
length, width, height(number)Dimensions in cm.
boxId(int)Id of the parcel's box. Not sent to the courier: it is kept in the shipment's parcel detail and comes back in the response in parcels[].boxId. Not checked against the company's box catalogue.
content(string)Declared contents of the parcel, for customs, used by the couriers that describe each parcel separately to customs (Poste Italiane). When missing, the channel default applies. Up to 255 characters.
originCountry(string)Country of origin of the goods in the parcel, ISO 3166-1 alpha-2.
insurance(number)Insured value of the parcel, 0 or more. Read only by FedEx, and only on shipments with more than one parcel.
reference(string)Your own code for the parcel (e.g. your warehouse system's parcel id): up to 25 characters among letters, digits, space and . _ / # -. Not sent to the courier: it comes back in the response in parcels[].reference, next to that parcel's label, and is printed on the label when the channel asks for it and the courier supports it.
content(string) Description of the contents, for customs. Up to 100 characters.
pickupDate(string) Requested pickup date, Y-m-d.
pickupTime(string) Requested pickup time, HH:MM.
pudo(object) The pickup point (PUDO) to deliver to. When it cannot be used the response is 422 with code PUDO_NOT_USABLE.
id*(string)Id of the point, in the courier's format. Up to 100 characters.
type(string)Type of the point, as the courier's code (e.g. for TNT 3 = point, 5 = locker). Up to 100 characters.
monetary(object) Cash on delivery and insurance. E.g. {"isCod": true, "value": 49.99, "codPaymentOption": "CONT", "currency": "EUR"}.
isCod(bool)Cash on delivery shipment.
value(number)Order value; with isCod set to true it is the amount to collect.
codPaymentOption(string)Collection method, as the courier's code (e.g. CONT).
shippingInsurance(number)Insured value.
shippingCharge(string)Who pays the shipping charge for this shipment: SENDER or RECIPIENT. Overrides the channel courier setting; omit it to use the channel default. On GLS Italia it maps to carriage paid (SENDER) and carriage forward (RECIPIENT). Any other value, including THIRD_PARTY from v1.3, returns 422.
currency(string)ISO 4217 currency, 3 characters. Defaults to EUR.
planning(object)
deliveryOptions(array of string)Courier accessory services, as a list of codes (e.g. ["31", "39"]). The codes depend on the courier: no endpoint exposes them yet, they will come in GET /couriers/{code} in a later step.
requestedDeliveryDate(string)Requested delivery date, Y-m-d.
customAttributes(object) Free fields custom1, custom2, custom3.
items(array) The order rows.
sku*(string)Product code. Up to 100 characters.
name*(string)Product description. Up to 255 characters.
quantity*(int)Quantity, greater than 0.
price, total(number)Unit price and row total.
weight, netWeight(number)Gross and net unit weight, in kg.
customsCode(string)HS customs code. Up to 20 characters.
originCountry(string)Country of origin, ISO 3166-1 alpha-2.
unitOfMeasurement(string)Unit of measurement.
parcelNumber(int)Position in parcels, from 1, of the parcel that holds the item; 0 = none.
sender(object) The sender, when different from the channel's default: code, businessName, street, city, state, postcode, country, email, phone, referent, isDefault.
isReturnShipment(bool) When true, requests a return label instead of the outbound shipment: drop-off, no cash on delivery, signature or duties on the recipient. It can be asked on an order already closed too. Defaults to false.
Body 201 — label created (200 if it already existed)

            
id(int) The label id.
trackingNumbers(array) The tracking numbers returned by the courier, as {"number", "description"} objects. The first one is the main one; some couriers (e.g. GLS for international shipments) return more than one.
courier(string) The courier code.
reference(string) The order reference.
parcels(array) One object per parcel, in the order of the request parcels: it ties each parcel to its label.
parcelNumber(int)Position of the parcel, starting from 1.
reference(string)The reference sent for the parcel, otherwise null.
parcelHash(string)The hash of the parcel created with POST /parcels that this parcel inherited (the one on its provisional label), otherwise null.
trackingNumber(string)The courier's number for this parcel (for BRT, its parcel id); null when the courier gives none per parcel.
courierShipmentId(string)The courier's shipment id for this parcel, for couriers that make one shipment per parcel (Amazon Shipping); otherwise null.
weight, length, width, height(number)Weight in kg and dimensions in cm, as sent to the courier.
boxId(int)The parcel's box, when given.
label(object)This parcel's label, as {"format", "label"}: format is PDF or ZPL, label the PDF in base64 or the raw ZPL. null when the courier returns a single file for every parcel (Poste Italiane, TNT in PDF): the label is then in labels.
labels(array) Deprecated, use parcels. The labels as the courier returns them: one per parcel, or a single file for the whole shipment. PDF in base64 or raw ZPL.
labelFormat(string) PDF or ZPL.
extShipmentId(string) The courier's shipment id, when available; null otherwise.
isExisting(bool) true if the label already existed for this reference and the response is 200.
returnTrackingNumbers(array) The tracking numbers of the contextual return label, as {"number", "description"} objects. A contextual return is a second shipment, in the opposite direction, created straight after this one when the order asks for it and the channel has contextual returns enabled. Empty in every other case.
returnLabels(array) The contextual return label, encoded like labels. Empty when none was created.
returnLabelError(string) Why the contextual return label could not be created, when it could not; null otherwise. It does not mean the request failed: the outbound label in the same response is valid, and the return can be requested separately.
labelError(string) Set when the courier created the shipment but its label could not be retrieved (today BRT only): the shipment is saved (id) with an empty label, labels is empty, and this is the message to show. Delete the shipment from the Control Panel or the Qapla' app, since this API has no delete route; deleting it also voids it at the courier. Then create it again, on BRT only 5 minutes after it was created. null otherwise.
XL labels

When a label template is assigned to the channel and the courier, each 4x6" ZPL label is extended to 4x8" with the merchant block below the courier's label: in labels and in parcels[].label, also when the label already existed (isExisting). Without a template the label is the courier's. PDF labels do not change.

Error label (errorLabel)

If the courier rejects the shipment or does not respond correctly, and the channel has the "Error label from API" option enabled (Control Panel → Channel settings → Labels → Printers; off by default), the response is still an error — never a 2xx — but the problem document also contains the errorLabel field:


            
errorLabel.format(string) PDF or ZPL: the same format as the real label, to be sent to the same printer.
errorLabel.label(string) The label content, encoded like the items of labels: PDF in base64, ZPL raw.

It is a 10x15 label generated by Qapla' for the operator to print in place of the real one, with the error spelled out: it shows "DO NOT SHIP" in large type, "Label not created", the reference, the courier, date and time and the error message. The texts are in the company's language.

Warning: it is not a shipping label: no barcode, no tracking number, it is not stored. Always check the HTTP status: the presence of errorLabel does not mean the label was created. A client that retries automatically prints an error label at every attempt.

errorLabel is only present on courier-rejection 422s and on 502s; it is not present on body validation errors, nor when the courier is unknown or not configured on the channel. It is the same label returned by createLabel in v1.3.

Body 502 — the courier did not respond, with a ZPL error label


            
Errors

Errors are RFC 7807 problem documents (application/problem+json). When present, code names the case in a stable way: read it rather than the text of detail, which is in the language of the company's country (English for a language the Control Panel is not offered in).

400 Bad Request: unknown courier code (Unknown courier code: X: use the dashed code, e.g. GLS-ITA), or courier not available.
401 Unauthorized: missing or invalid token.
403 Forbidden: the token carries no channel context.
409 Conflict: the label cannot be created now. The order is not sent to the courier.
LABEL_CREATION_IN_PROGRESSAnother request is creating this order's label right now, with any courier: wait a few minutes and retry. The retry returns the label once it is saved (200, isExisting).
ORDER_ALREADY_QUEUEDThe order is in the queue of a label job in progress (from the Control Panel or the dashboard): wait for it to finish, then retry.
CARRIER_SHIPMENT_DUPLICATEThe courier has just created the shipment, but meanwhile another request (e.g. from the Control Panel) saved the order's label: the new shipment was not saved (detail names its tracking). Void it from the courier portal. Never retry.
ORDER_ALREADY_LABELLEDThe order is closed and already has the label of another courier. A closed order with a label of the courier asked returns that label instead, with 200.
ORDER_ALREADY_SHIPPEDThe order was shipped without a label of its own (manual shipment, closed in the Control Panel), or the same order (source + reference) was already shipped from a twin channel of the company.
The two closed-order cases do not apply to a return (isReturnShipment: true), which is asked precisely on a closed order.
422 Unprocessable Entity: body validation error (detail as field: message, …), unknown keys (Unknown fields: …), or the label is refused before the courier is called or by the courier.
Refused before the courier is called (when the order does not exist, it is created anyway):
COURIER_NOT_CONFIGUREDThe courier is not configured on the channel (GENERIC included), or its configuration is incomplete: for TNT, BRT and GLS the message lists the missing fields.
COURIER_NOT_AMAZON_COMPLIANTAn order with Amazon source under 150, shipped from outside the EU into the EU, with a courier Amazon does not know (e.g. GENERIC): pick another courier.
PRINT_FORMAT_NOT_CONFIGUREDNo printer configured for the courier, or one the courier does not know.
PUDO_NOT_USABLEThe pickup point of the request or of the order cannot be used: point of another courier, required fields missing, or a courier that handles no pickup points. GENERIC delivers home instead. A request pudo different from the order's point is judged on its own id and type.
SENDER_NOT_FOUNDThe order's sender no longer exists on the channel.
DEFAULT_SENDER_NOT_SETTNT channel with several senders and no default.
Refused by the courier: detail is Carrier API error (<courier>): <courier message>, with the courier's text unchanged, followed by  -  and what it means when Qapla' knows it. errorLabel may be present. code is CARRIER_REJECTED, or a more specific one:
DANGEROUS_GOODS_UNTYPEDDHL Express: dangerous goods without a type. This API cannot force the label: fix the order. Dangerous goods DHL does not take (more than one category, unsupported battery combination, unknown class) are CARRIER_REJECTED too.
CARRIER_CREDENTIALS_INVALID, CARRIER_CLIENT_SECRET_INVALID, CARRIER_CLIENT_ID_INVALIDPoste Italiane: the credentials of the courier configuration are refused. Fix them in the courier settings.
CARRIER_COST_CENTER_MISSINGPoste Italiane: no cost center in the courier configuration.
CARRIER_SHIPMENT_PENDINGBRT only: an earlier attempt left the shipment at BRT ([-64]) and may still be running, or BRT does not let it be voided yet (only 5 minutes after its creation). Retry in at least 5 minutes.
CARRIER_SHIPMENT_NOT_RECOVEREDBRT only: the shipment left by an earlier attempt could not be voided automatically. Void it from the Control Panel or the BRT portal, then retry.
429 Too Many Requests: request limit exceeded.
502 Bad Gateway, code CARRIER_UNAVAILABLE: the courier did not respond correctly (timeout, transport error, unreadable response, or any answer with a 5xx status, even one carrying an error message). detail explains the failure when the cause is known. When the courier may have created the shipment anyway, that is in every case but a refused connection or a failure before the shipment request, detail ends with the advice to check the courier portal before retrying. errorLabel may be present.

POSTConfirm labels to the courier

BETA
The Labels APIs are in beta test: for now use them only with the GENERIC courier, which produces a real A6 label without calling any courier. The compatible couriers will be released one by one. The contract may change without notice; for production use v1.3 createLabel.

Confirms to the courier a batch of labels created with POST /labels — the "end of day" closing, CloseWorkDay for GLS — and opens a transmission (manifest) that groups them.

The call is idempotent: labels already confirmed are not confirmed again, but returned in alreadyConfirmedIds. If no label in the request needs confirming, the response is 200 and no transmission is created.

NB
Authentication uses the Bearer Token obtained from the authentication service. No dedicated scope is required: the labels confirmed are those of the token's channel.

POSThttps://api.qapla.it/v2/labels/confirm
Body
The request body must be a JSON containing the following parameters:

            

*Required parameter

courier*(string) Qapla' courier code, with the dash (GLS-ITA, BRT, GENERIC…), variant included.
labelIds*(array of int) The ids of the labels to confirm, as returned by POST /labels. Required when labelCreationDate is missing; the two cannot be used together.
pickupDate(string) Pickup date requested from the courier, Y-m-d. Whether and how it is used depends on the courier: when the courier books no pickups for this channel the response is 422.
pickupTime(string) Pickup time, HH:MM. Requires pickupDate.
labelCreationDate(string) Instead of labelIds: confirms every label of the courier created on this date, Y-m-d, not yet transmitted.
includeManifest(bool) When true (default) the response carries the manifest PDF in manifest. With false it is not generated, and it is downloaded later from the address in the Location header.
pickUpDate, pickUpTime(string) Deprecated, use pickupDate and pickupTime: the spelling of v1.3 confirmLabel, accepted for compatibility.
Body 201 — transmission created

At least one label was confirmed. The response carries a Location header with the address of the transmission's manifest. A partial confirmation is still a 201: the labels rejected by the courier are in errors, also when the courier stops mid-batch.
No courier call starts later than 35 seconds after the request started: the labels left out are in remainingIds, they are not refused and must be confirmed again. It happens with large batches: for BRT beyond about 65 labels per call, for Poste Italiane and FedEx beyond about 15.


            
Body 200 — no new transmission

All labels were already confirmed or were not found: transmissionId and transmissionNumber are null.


            
transmissionId(int|null) The id of the transmission created; null when the response is 200.
transmissionNumber(string|null) The transmission number (e.g. 00001-25); null when the response is 200.
successCount(int) How many labels this call confirmed.
alreadyConfirmedIds(array of int) The labels already confirmed before this call.
nonExistentIds(array of int) The ids not found, or not belonging to this channel or this courier.
errors(array) The per-label problems, as {"shipmentId", "message", "code"} objects: courier errors first, then the labels skipped because already confirmed or not existing. message is the courier's text followed by  -  and its explanation, when Qapla' knows it, in the language of the company's country. Every label of remainingIds is listed here too, with code CONFIRM_TIME_LIMIT_REACHED; on the others code is absent.
remainingIds(array of int) The labels not sent to the courier because the request ran out of time: confirm them again.
remainingCount(int) How many labels are in remainingIds.
courier(string) The courier code the batch was confirmed for, the one of the request (variant included).
confirmedAt(string) When the confirmation completed, ISO 8601.
manifest(string|null) The manifest PDF in base64. null with includeManifest: false, when no transmission was created, when the transmission is too large to fit in the response (more than 300 shipments) or when the request has no time left to generate it: download it then from the address in the Location header, which always serves the same document.
Errors

Errors are RFC 7807 problem documents (application/problem+json).

400 Bad Request: unknown courier code (Unknown courier code: X: use the dashed code, e.g. GLS-ITA), a courier that does not support confirmation, or a courier that creates no labels (Invalid courier X: it has no labels to transmit).
401 Unauthorized: missing or invalid token.
403 Forbidden: the token does not carry the channel context.
422 Unprocessable Entity: body validation error — labelIds missing, labelIds and labelCreationDate together, pickupTime without pickupDate, no label to transmit on labelCreationDate —, courier not configured on the channel, or no label transmitted (the courier refused them all, or stopped before transmitting any) and none left out for lack of time: detail is Carrier confirm error (<courier>): all shipments failed. Errors: <messages>.
429 Too Many Requests: rate limit exceeded.

GETTransmission manifest

BETA
The Labels APIs are in beta test: for now use them only with the GENERIC courier, which produces a real A6 label without calling any courier. The compatible couriers will be released one by one. The contract may change without notice; for production use v1.3 createLabel.

Returns the PDF manifest — the handover list for the courier — of a transmission opened with POST /labels/confirm. The PDF is generated at request time, from the current shipment data.

NB
Authentication uses the Bearer Token obtained from the authentication service. No dedicated scope is required. The transmission must belong to the token's channel: a transmission of another channel returns 404, indistinguishable from a transmission that does not exist.

GEThttps://api.qapla.it/v2/transmissions/{id}/manifest
Path

*Required parameter

id*(int) The transmissionId returned by POST /labels/confirm, which also carries it in the Location header of the 201 response.
Body 200

            
transmissionId(int) The transmission id.
transmissionNumber(string) The transmission number (e.g. 00001-25).
courierCode(string) Qapla' courier code of the transmission.
fileName(string) Suggested file name for the PDF.
manifest(string) The manifest PDF, base64-encoded.
Errors

Errors are RFC 7807 problem documents (application/problem+json).

401 Unauthorized: missing or invalid token.
403 Forbidden: the token does not carry the channel context.
404 Not Found: the transmission does not exist, or belongs to another channel.
429 Too Many Requests: rate limit exceeded.

Pickups

The Pickups APIs book a parcel pickup with the courier, with no shipments or labels to collect in Qapla'. The courier comes to the address of a sender from the channel's sender list, or to an address given in the request, on the chosen day and time slot.

Required scope: pickups:write to book, pickups:read for the listing and the detail. Version: 1.0.

Poste Delivery Business (PTI): pickups in Italy only; weight and the parcel size, when given, are sent to Poste, and the province in sender.state must be a two-letter code or a name that converts into the code. The slots are Poste's (morning, afternoon, morning or afternoon). Poste emails the progress of the pickup to the sender's email. The credentials are the clientId and secretId of the Poste contract configured on the channel. reference stays in Qapla', it is not sent to Poste.

GLS Italy (GLS-ITA): the hours of the morning and afternoon slots come from the channel's GLS configuration; when those of the chosen slot are missing the response is 422. The pickup goes on the first GLS contract configured. reference is sent to GLS; without weight the declared weight is 1 kg; parcel sizes are not sent.

POSTBook a pickup

Books a parcel pickup with the courier and stores it on the authenticated channel. The pickup is not tied to any Qapla' shipment: it is for those who create their labels elsewhere, or who need an extra pickup. The response holds bookingCode, the code of the booking at the courier.

Couriers supported today: PTI (Poste Delivery Business) and GLS-ITA, contract variants included. The courier must be configured on the channel, with the credentials it creates labels with.

One booking per call
The call is not idempotent: every accepted POST is a new booking at the courier. To retry after a network error, first look the pickup up with GET /pickups. A pickup cannot be cancelled through the API today.

Note
Authentication requires the Bearer Token obtained from the authentication service. Required scope: pickups:write. Keys the endpoint does not know, inside objects too, are not ignored: the response is 422 with Unknown fields: ….

POSThttps://api.qapla.it/v2/pickups
Body — sender from the sender list

            
Body — explicit pickup address

            
courier*(string) Courier code: PTI, GLS-ITA or one of its variants (GLS-ITA-*).
sender*(object) Where the courier collects, in one of two forms, never both: code alone, or the address.
code(string)Code of a sender in the channel's sender list: the pickup happens at its address. A code the channel does not have returns 422. Up to 50 characters.
name(string)Name or company to collect from. Up to 100 characters.
street(string)Street address with house number. Up to 255 characters.
city(string)City. Up to 100 characters.
state(string)Province code (e.g. MI). For Italy a name spelled out (Napoli, Reggio Emilia) is turned into its code; with PTI, a name that cannot be converted returns 422.
postcode(string)Postcode. Up to 20 characters.
country(string)Country, ISO 3166-1 alpha-2 in upper case (IT).
phone(string)Contact phone. Up to 30 characters.
email(string)Contact email: with PTI it is the address Poste sends the pickup updates to.
Without code, name, street, city, state, postcode and country are required; phone and email stay optional.
pickupDate*(string) Pickup day, YYYY-MM-DD, today or later.
timeSlot*(string) Pickup slot: morning, afternoon or any (morning or afternoon, the courier picks). For the hours of each courier see Pickups.
parcels*(int) Number of parcels to collect, from 1 to 999.
weight(number) Total weight in kg, greater than 0.
length, width, height(number) Size of one parcel in cm, greater than 0. PTI sends them to Poste only when all three are given; GLS-ITA does not use them. They are not stored and do not come back in the response.
reference(string) Your reference for the pickup. Up to 50 characters.
notes(string) Notes for the driver. Up to 255 characters.
Body 201

            

The booked pickup. The Location header holds the path of the pickup (/pickups/{id}).

id(int) Qapla' id of the pickup.
courier(string) The courier code sent.
bookingCode(string) The code of the booking at the courier: Poste's bookingId, GLS's pickup number. It is the one to quote to the courier.
pickupDate(string) Pickup day, YYYY-MM-DD.
timeSlot(string) morning, afternoon or any.
sender(object) The address sent to the courier: code, name, street, city, state, postcode, country, phone, email. code is the sender code when the address comes from the sender list, otherwise null.
parcels(int) Number of parcels.
weight(number) Total weight in kg. null when not given.
reference, notes(string) As sent, null when missing.
createdAt(string) Booking date, ISO 8601 in UTC.
Errors
401 Unauthorized: missing or invalid token.
403 Forbidden: channel context missing from the token, or the token does not hold the pickups:write scope.
422 Unprocessable Entity, with the cause in detail:
  • validation error, with the fields (e.g. parcels: This value should be positive.), or code and address sent together;
  • unknown keys (Unknown fields: …);
  • unknown courier, courier without pickup booking (Pickup booking is not available for courier "X".), courier not configured on the channel;
  • sender code the channel does not have (Unknown sender code "X".);
  • pickupDate must be today or later.;
  • the courier refused the booking: <COURIER> did not book the pickup: <message>, with the courier's message. For Poste, for example, [E0029] there is already a pickup for the same data or [E0035] Time slot not compatible with today's date Channel configuration problems (credentials, GLS hours) and a courier that does not answer come in the same form.
429 Too Many Requests: rate limit exceeded.

GETList pickups

Returns the pickups booked by the authenticated channel whose pickup day is between from and to (both included), from the latest pickup day to the earliest. Without parameters it covers the past 30 days and the next 30.

Note
The response is a JSON array of pickups, without pagination: the range is at most 92 days.

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

GEThttps://api.qapla.it/v2/pickups?from={FROM}&to={TO}
Query Parameters
from(string) First pickup day, YYYY-MM-DD. Default: 30 days ago.
to(string) Last pickup day, YYYY-MM-DD, not before from and at most 92 days later. Default: 30 days from today.
Body 200

            

Each element has the fields documented in POST /pickups. No pickup in the range: 200 with an empty array.

Errors
401 Unauthorized: missing or invalid token.
403 Forbidden: channel context missing from the token, or the token does not hold the pickups:read scope.
422 Unprocessable Entity: from or to is not a YYYY-MM-DD date, to is before from, or the range is longer than 92 days.
429 Too Many Requests: rate limit exceeded.

GETGet pickup

Returns a pickup booked by the authenticated channel, in the same representation as the response of POST /pickups.

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

GEThttps://api.qapla.it/v2/pickups/{id}
Path
id*(int) Qapla' pickup id, returned by the booking or by GET /pickups.
Body 200

            

The fields are documented in POST /pickups.

Errors
401 Unauthorized: missing or invalid token.
403 Forbidden: channel context missing from the token, or the token does not hold the pickups:read scope.
404 Not Found: pickup not existing, or booked by another channel.
429 Too Many Requests: rate limit exceeded.

Parcels

The Parcels APIs allow you to pre-load the packages of an order before the shipment (label) is created. The uploaded packages are then automatically inherited by the order or shipment.

A parcel is uniquely identified by a hash and belongs to an order via the orderReference + orderOrigin pair.

Required scopes: parcels:create, parcels:read, parcels:update, parcels:delete.

Version: 2.0 for POST /parcels, GET /parcels, GET /parcels/{hash} and PATCH /parcels/{hash}; this page describes 2.0. The two DELETEs have a single version. See Versioning.

Previous version (1.0)
Channels that used the parcels before 2.0 are pinned to 1.0 and keep receiving the previous names until they ask for 2.0 with X-Endpoint-Version: 2.0. Only the names change: 2.0 names the parcel fields as the orders do, with the unit in the description instead of the name. The orderReference and orderOrigin query parameters are the same in both.

2.01.0Where
weight, length, width, heightweightKg, lengthCm, widthCm, heightCmparcel fields, request and response
originCountryoriginCountryIsoparcel fields, request and response
contentcontentsDescriptionparcel fields, request and response
referenceclientInternalCodeparcel fields, request and response
notesshippingNotesparcel fields, request and response
order.sourceorder.originPOST /parcels request

POSTParcels

Creates one or more parcels for an order. The response is synchronous (≤10 parcels, HTTP 201) or asynchronous (>10 parcels, HTTP 202 with jobId).

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

POSThttps://api.qapla.it/v2/parcels
Body
The request body must be a JSON containing the following parameters:

            

*Required parameter

order*(object) The order the parcels belong to.
reference*(string) The unique order reference.
source*(string) The order origin (e.g. shopify, amazon, woocommerce).
parcels*(array) List of parcels (minimum 1, maximum 100).
originCountry*(string) ISO 3166-1 alpha-2 country code of origin (e.g. IT, ES).
weight*(float) Weight in kg, max 2 decimal places. Maximum 99 kg.
length(float) Length in cm, max 2 decimal places.
width(float) Width in cm, max 2 decimal places.
height(float) Height in cm, max 2 decimal places.
content(string) Description of parcel contents.
reference(string) Client's internal code.
notes(string) Notes to be printed on the label.
webhookUrl(string) Callback URL for async notifications (optional). Must be an https URL resolving to a public address: an http URL is rejected with 422.
Header
x-label-format(string) PDF (default) or ZPL to get the label in the desired format.
Body 201 — Synchronous response (≤10 parcels)

            
parcelHash(string) Unique hash of the created parcel. Used to identify the parcel in GET, PATCH and DELETE calls.
parcelNumber(int) Progressive number of the parcel.
label The label in the requested format.
format(string) Label format (PDF or ZPL).
label(string) Label content in Base64 (PDF) or ZPL text.
totalParcelCount(int) Total number of parcels for the order.
Body 202 — Asynchronous response (>10 parcels)

            
jobId(string) Async job identifier. Use GET /v2/jobs/{jobId} to monitor status.
status(string) Job status: pending, processing, completed, failed.
statusUrl(string) URL to check job status.
hashes(array) Pre-assigned hashes for the parcels.
totalParcels(int) Total number of parcels to process.
Errors
422 Unprocessable Entity: validation error (e.g. empty parcels array or more than 100 parcels).
429 Too Many Requests: rate limit exceeded.

GETParcels

Returns a paginated list of parcels for an order, identified by the orderReference + orderOrigin pair passed as query parameters. Required scope: parcels:read.
GEThttps://api.qapla.it/v2/parcels?orderReference={REFERENCE}&orderOrigin={ORIGIN}
Query Parameters
orderReference*(string) The order reference.
orderOrigin*(string) The order origin (e.g. shopify, amazon).
page(int) Page number. Default: 1.
limit(int) Results per page. Default: 20.

*Required parameter

Body 200

            
items(array) List of parcels for the order.
total(int) Total number of parcels.
page(int) Current page.
limit(int) Parcels per page.
pages(int) Total number of pages.
Errors
All errors returned by the Qapla' API are represented using standard HTTP status codes.

GETParcels / {hash}

Retrieves data for a single parcel by its identifying hash. Required scope: parcels:read.
GEThttps://api.qapla.it/v2/parcels/{PARCEL-HASH}
Parameters
hash(string) The identifying hash of the parcel, obtained at creation time.
Body 200

            
parcelHash(string) Unique hash of the parcel.
parcelNumber(int) Progressive number of the parcel in the order.
label The label associated with the parcel (format + Base64 or ZPL content).
originCountry(string) ISO country code of origin.
reference(string) Client's internal code.
weight(float) Weight in kg.
length(float) Length in cm.
width(float) Width in cm.
height(float) Height in cm.
content(string) Contents description.
notes(string) Label notes.
createdAt(string) Creation date, ISO 8601 in UTC.
updatedAt(string) Last update date, ISO 8601 in UTC.
Errors
404 Not Found: parcel not found, or a parcel of another channel (the hash alone does not open it).

PATCHParcels / {hash}

Partially updates a parcel. Only the fields included in the body are modified. Required scope: parcels:update.
PATCHhttps://api.qapla.it/v2/parcels/{PARCEL-HASH}
Parameters
hash(string) The identifying hash of the parcel to update.
Body
All fields are optional. Only fields present in the body are updated.

            
weight(float) Weight in kg, max 2 decimal places.
length(float) Length in cm.
width(float) Width in cm.
height(float) Height in cm.
originCountry(string) ISO country code of origin.
content(string) Contents description.
reference(string) Client's internal code.
notes(string) Label notes.
Body 200

            
Errors
404 Not Found: parcel not found, or a parcel of another channel (the hash alone does not open it).
422 Unprocessable Entity: validation error on fields.

DELETEParcels / {hash}

Deletes a single parcel identified by its hash. Returns HTTP 204 with no body. Required scope: parcels:delete.
DELETEhttps://api.qapla.it/v2/parcels/{PARCEL-HASH}
Parameters
hash(string) The identifying hash of the parcel to delete.
Response

HTTP 204 No Content — no body in the response.

Errors
404 Not Found: parcel not found, or a parcel of another channel (the hash alone does not open it).

DELETEParcels (bulk)

Deletes all parcels of an order, identified by the orderReference + orderOrigin pair passed as query parameters. Returns HTTP 204 with no body. Required scope: parcels:delete.
DELETEhttps://api.qapla.it/v2/parcels?orderReference={REFERENCE}&orderOrigin={ORIGIN}
Query Parameters
orderReference*(string) The order reference.
orderOrigin*(string) The order origin.

*Required parameter

Response

HTTP 204 No Content — no body in the response.

Errors
404 Not Found: no parcels found for the specified order.

Couriers

The Couriers APIs list the couriers available in Qapla', with the code to use in the courier fields, and provide network-wide delivery benchmarks. Given a destination and a list of couriers, you can compare their delivery times and pick the fastest carrier for a specific lane, or score their overall efficiency on that lane.

The benchmark is anonymous and aggregated across all merchants (no PII); the origin macro-area is deduced server-side from the authenticated company.

Required scopes: none for the courier list and details; delivery-times:read for the delivery-time comparison, efficiency-index:read for the efficiency index.

GETList couriers

Returns the couriers available in Qapla', with the code to use in POST /labels (courier) and in the other endpoints.

NB
Authentication uses the Bearer Token obtained from the authentication service. No dedicated scope is required.

GEThttps://api.qapla.it/v2/couriers
Query parameters
countries(string) Comma-separated country codes (e.g. it,es). Not to be used together with code.
code(string) Filters on a courier code (e.g. BRT). Not to be used together with countries.
hasLabels(bool) true: only the couriers Qapla' generates labels with; false: only the others.
Body 200 — an array of couriers

            
code(string) Courier code, to use in courier.
name(string) Courier name.
country(string) Courier country, or global.
website(string|null) Courier website; null when missing.
trackingUrl(string|null) Public tracking address, with [TRACKING_NUMBER] in place of the number; null when missing.
Errors
401 Unauthorized: missing or invalid token.

GETCourier details

Returns a courier and its services: the codes to send in courierService of POST /labels.

The codes of planning.deliveryOptions (accessory services) are not exposed yet: they will come in this endpoint in a later step.

NB
Authentication uses the Bearer Token obtained from the authentication service. No dedicated scope is required.

GEThttps://api.qapla.it/v2/couriers/{code}
Path parameters

*Required parameter

code*(string) Courier code (e.g. PTI).
Body 200

            
code(string) Courier code, to use in courier.
name(string) Courier name.
country(string) Courier country, or global.
website(string|null) Courier website; null when missing.
trackingUrl(string|null) Public tracking address, with [TRACKING_NUMBER] in place of the number; null when missing.
services(object) The courier's services, split into domestic and international: lists of {"code", "name"} objects. code is the value to send in courierService. A contract variant (e.g. BRT-V1) shows the catalogue of its parent courier. The lists are empty when the courier has no service to choose: for example BRT, and GLS, for which courierService is the channel's contract code.
Errors
401 Unauthorized: missing or invalid token.
404 Not Found: the courier does not exist.

POSTCompare courier delivery times

Given a destination Italian postal code and a list of couriers, returns the couriers ranked fastest-first by average delivery time (lead time), so you can choose the fastest carrier for that 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). 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
Body
The request body must be a JSON containing the following parameters:

            

*Required parameter

destCap*(string) 5-digit destination Italian postal code (e.g. 20100).
couriers(array) List of courier codes to compare (max 50). Optional: if omitted, the shipping-enabled couriers of the authenticated channel are used.
weightKg(float) Parcel weight in kg (must be > 0). When provided, selects the matching weight band for a weight-specific estimate. If omitted, a weight-agnostic estimate is returned.
originCap(string) Optional origin postal code (5 digits). Overrides the authenticated company seat CAP used for the finest origin-CAP grains. If omitted, the company seat CAP is used.
detail(string) Response verbosity: summary (default) returns the best courier plus a slim ranking; full returns the complete ranking with all percentiles, grain, weightBand and the couriers with insufficient data.
Body 200

            
destCap(string) The destination postal code that was requested.
originArea(string) Origin macro-area deduced from the authenticated company: NORD, CENTRO or SUD. null if not resolvable.
originCap(string) Origin postal code used for the finest origin_cap_dest* grains (the request originCap, otherwise the company seat CAP). null when the seat CAP is not a valid Italian CAP.
requestedWeightBand(string) The weight band that weightKg maps to (e.g. 2-5). null if weightKg was omitted.
best(object) The fastest courier. null when no courier has sufficient data.
courierCode(string) The courier code, as supplied in the request.
leadMedian(int) Median lead time shipped→delivered, calendar days.
leadMean(float) Mean lead time shipped→delivered, calendar days, rounded to 1 decimal.
transitMedian(int) Median transit time departed→delivered, carrier-only, calendar days.
transitMean(float) Mean transit time departed→delivered, carrier-only, calendar days, rounded to 1 decimal.
sampleSize(int) Number of deliveries in the benchmark cell (last 12 months).
ranking(array) Couriers with data, ordered fastest-first; insufficient-data couriers are omitted (request detail: "full" to see them).
position(int) 1-based ranking position (fastest = 1).
courierCode(string) The courier code, as supplied in the request.
leadMedian(int) Median lead time (shipped→delivered) in calendar days. Primary ranking metric.
transitMedian(int) Median transit time (departed→delivered, carrier-only) in calendar days.
sampleSize(int) Number of deliveries in the benchmark cell (last 12 months).
Full detail (detail: "full")

When the request sets detail: "full", the response returns the complete ranking. Each row adds status (ok | insufficient_data), level (the benchmark grain, from finest to coarsest: origin_cap_dest_weight | origin_cap_dest | area_cap_weight | cap_weight | area_cap | cap), weightBand, leadMean, transitMean (means in calendar days, float rounded to 1 decimal), leadP90, transitP90 and transitSampleSize, and the couriers with no data are included at the end with status: insufficient_data and null metrics. The ranking is ordered by lead time: median, then mean, then p90. There is no best field in the full form.

Errors
401 Unauthorized: missing or invalid token.
403 Forbidden: the token lacks the delivery-times:read scope.
422 Unprocessable Entity: validation error (invalid destCap/originCap), or no couriers to compare (none provided and the channel has no shipping-enabled couriers).
429 Too Many Requests: rate limit exceeded.

POSTScore courier efficiency

Given a destination Italian postal code and a list of couriers, returns for each courier a 0–100 efficiency index on that lane, with a rank (best-first) and three sub-scores, so you can pick the best-performing carrier — not just the fastest.

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
Body
The request body must be a JSON containing the following parameters:

            

*Required parameter

destCap*(string) 5-digit destination Italian postal code (e.g. 20100).
couriers(array) List of courier codes to score (max 50). Optional: if omitted, the shipping-enabled couriers of the authenticated channel are used.
weightKg(float) Parcel weight in kg (must be > 0). When provided, selects the matching weight band for a weight-specific score. If omitted, a weight-agnostic score is returned.
originCap(string) Optional origin postal code (5 digits). Overrides the authenticated company seat CAP used for the finest origin-CAP grains. If omitted, the company seat CAP is used.
Body 200

            
destCap(string) The destination postal code that was requested.
originArea(string) Origin macro-area deduced from the authenticated company: NORD, CENTRO or SUD. null if not resolvable.
originCap(string) Origin postal code used for the finest origin_cap_dest* grains (the request originCap, otherwise the company seat CAP). null when the seat CAP is not a valid Italian CAP.
requestedWeightBand(string) The weight band that weightKg maps to (e.g. 2-5). null if weightKg was omitted.
ranking(array) Couriers ordered best-first by efficiencyIndex. Couriers whose lane cell is suppressed (fewer than 20 deliveries) or has no usable speed are appended at the end with status: "insufficient_data", a null rank and null metrics.
rank(int) 1-based rank by efficiency index (best = 1); ties share a rank. null for insufficient-data couriers.
courierCode(string) The courier code, as supplied in the request.
status(string) ok when the lane has a usable benchmark, insufficient_data otherwise.
efficiencyIndex(float) Overall efficiency index 0–100 (higher is better), rounded to 1 decimal. 0.40·scoreSpeed + 0.20·scoreConsistency + 0.40·scoreReliability.
scoreSpeed(float) Speed sub-score 0–100, from the speed median, rounded to 1 decimal.
scoreConsistency(float) Consistency sub-score 0–100, from the gap between the p90 and the median, rounded to 1 decimal.
scoreReliability(float) Reliability sub-score 0–100, from the failed/stock/exception rates of the lane, rounded to 1 decimal.
level(string) Benchmark grain used (most specific available): origin_cap_dest_weight | origin_cap_dest | area_cap_weight | cap_weight | area_cap | cap.
sampleSize(int) Number of deliveries in the benchmark cell.
speedMedian(int) Speed median in calendar days (transit median if available, otherwise lead median); the basis of scoreSpeed.
speedP90(int) Speed p90 in calendar days (transit p90 if available, otherwise lead p90); the basis of scoreConsistency.
failedRate(float) Failed-delivery rate of the lane cell (fraction 0–1).
stockRate(float) Stock/storage rate of the lane cell (fraction 0–1).
exceptionRate(float) Exception rate of the lane cell (fraction 0–1).
Errors
401 Unauthorized: missing or invalid token.
403 Forbidden: the token lacks the efficiency-index:read scope.
422 Unprocessable Entity: validation error (invalid destCap/originCap), or no couriers to score (none provided and the channel has no shipping-enabled couriers).
429 Too Many Requests: rate limit exceeded.

Addresses

The Addresses APIs check that a postal address exists and can be printed on a label, returning it normalised with a confidence score. They are meant to catch bad addresses before the shipment is created, while fixing them is still cheap.

Two providers sit behind the same contract, selected with the provider parameter: geocode (the default) covers the whole world and is the only one returning coordinates; gls queries the GLS Italia street registry, covers Italian addresses only and requires GLS to be configured on the channel, but reports ZTL, difficult areas, serving branch and zone, and proposes alternative addresses when the submitted one is not conformant.

Every accepted request is metered, whatever the provider and whatever the outcome: an address with no match is not an error, it is a 200 with match.status set to NONE.

Required scope: addresses:check. The feature must also be active on the contract and enabled on the channel.

POSTVerify an address

Check that a postal address exists and can be printed on a label, returning it normalised with a confidence score. Use it before creating the shipment, to catch bad addresses while fixing them is still cheap.

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
Body
The request body must be a JSON containing the following parameters:

            

*Required parameter

address*(object) The address to verify.
street*(string) Street address, house number included (e.g. Via Roma 1). Max 255 characters.
city*(string) City. Max 255 characters.
postcode(string) Postal code. Max 20 characters.
state(string) State / province code (e.g. MI). Max 50 characters.
country(string) Country, ISO 3166-1 alpha-2 (2 characters). Defaults to IT when omitted.
provider(string) Backend to query: geocode (default) or gls. gls only accepts addresses with country set to IT and requires GLS to be configured on the channel.
Body 200 — geocode provider

            
provider(string) The provider that answered: geocode or gls.
match(object) How closely the returned address matches the submitted one.
status(string) FULL when confidence is 90 or above, WARNING from 80 up, NONE below 80 or when nothing matched.
confidence(float) Score 0–100, comparable across both providers: it is 100 when the provider itself reports an exact hit, otherwise it measures how far the returned address is from the submitted one. null when nothing matched.
partial(bool) true when the provider matched only part of the address.
formatted(string) The normalised address on a single line. null when nothing matched.
components(object) The normalised address, part by part: street, city, postcode, state, region, country. null when nothing matched. region is only filled by providers that know about administrative regions.
coordinates(object) Geographic coordinates (latitude, longitude) of the matched address. Filled only by the geocode provider: the GLS street registry does not geocode.
candidates(array) Alternative addresses proposed by the provider, with the same fields as components. Filled only by the gls provider, when the submitted address is not in the street registry. Empty array otherwise.
delivery(object) Delivery constraints the courier knows about the address. Filled only by the gls provider, null otherwise.
restrictedTrafficZone(bool) The address is inside a restricted traffic zone (ZTL).
difficultArea(bool) The address is a difficult location: a surcharge usually applies. A ZTL always counts as a difficult area too.
branch(string) Courier branch serving the address.
zone(string) Courier delivery zone.
Body 200 — gls provider, conformant address

No coordinates, but the delivery block is filled: here the address is inside a ZTL, so difficultArea is true as well.


            
Body 200 — gls provider, non-conformant address

The address is not in the GLS street registry: components is null and candidates lists the addresses GLS would accept.


            
Errors
401 Unauthorized: missing or invalid token.
403 Forbidden: the token does not carry the addresses:check scope, address check is not active on your contract, or it is not enabled on the channel.
422 Unprocessable Entity: validation error, or the requested provider cannot serve the request (gls with a non-Italian address, or on a channel without GLS configured).
429 Too Many Requests: rate limit exceeded.
502 Bad Gateway: the address check provider is unreachable or answered unreadably.

Sandbox

The Sandbox APIs are test endpoints that allow you to verify your integration without side effects on real data. Each sandbox entity exposes all standard HTTP methods (CRUD) and includes values of every type (string, int, bool, float, datetime).

A Sandbox entity is uniquely identified by its numeric id.

Required scopes: sandbox:read for GET, sandbox:write for POST/PUT/PATCH/DELETE.

GETSandbox

Returns a paginated list of Sandbox entities. Supports temporal filters via query parameters.
GEThttps://api.qapla.it/v2/sandbox
Query Parameters
page(int) Page number. Default: 1.
limit(int) Results per page. Default: 20.
updatedAfter(string) Filter entities updated at or after this moment. ISO 8601 with an offset (2024-01-15T00:00:00Z, 2024-01-15T00:00:00+01:00; in the query string the + must be written %2B), or YYYY-MM-DD HH:MM:SS without an offset, read as Rome time. ISO 8601 without an offset returns 422.
updatedBefore(string) Filter entities updated at or before this moment. Same formats as updatedAfter.
Header
Authorization(string) Bearer ACCESS_TOKEN
Body 200

            
items(array) List of sandbox entities for the current page.
total(int) Total number of entities.
page(int) Current page.
limit(int) Items per page.
pages(int) Total number of pages.
Errors
All errors returned by the Qapla' API are represented using standard HTTP status codes.

GETSandbox / {id}

Retrieves data for a single Sandbox entity by its numeric identifier.
GEThttps://api.qapla.it/v2/sandbox/{id}
Parameters
id(int) The numeric identifier of the Sandbox entity.
Body 200

            
id(int) Unique identifier of the entity.
stringValue(string) String value.
intValue(int) Integer value.
boolValue(bool) Boolean value.
floatValue(float) Decimal value.
dateTimeValue(string) Datetime value sent by the client, returned as it is (YYYY-MM-DD HH:MM:SS), without conversion.
createdAt(string) Creation date, ISO 8601 in UTC.
updatedAt(string) Last update date, ISO 8601 in UTC.
Errors
400 Bad Request: id must be an integer greater than zero.
404 Not Found: entity not found.

POSTSandbox

Creates a new Sandbox entity. Returns the created entity with HTTP 201 and a Location header pointing to the new resource.
POSThttps://api.qapla.it/v2/sandbox
Body
The request body must be a JSON containing the following parameters:

            

*Required parameter

stringValue*(string) String value. Minimum length: 3 characters.
intValue*(int) Integer value.
boolValue*(bool) Boolean value.
floatValue*(float) Decimal value.
dateTimeValue(string) Datetime value in Y-m-d H:i:s format (optional).
Body 201

            
Header
Location(string) URL of the created resource, e.g. /v2/sandbox/42.
Errors
422 Unprocessable Entity: validation error on request fields.

PUTSandbox / {id}

Fully replaces a Sandbox entity. All fields are required.
PUThttps://api.qapla.it/v2/sandbox/{id}
Parameters
id(int) The numeric identifier of the entity to replace.
Body

            

*Required parameter

stringValue*(string) String value. Minimum length: 3 characters.
intValue*(int) Integer value.
boolValue*(bool) Boolean value.
floatValue*(float) Decimal value.
dateTimeValue(string) Datetime value in Y-m-d H:i:s format (optional).
Body 200

            
Errors
404 Not Found: entity not found.
422 Unprocessable Entity: validation error on request fields.

PATCHSandbox / {id}

Partially updates a Sandbox entity. Only the fields included in the body are modified.
PATCHhttps://api.qapla.it/v2/sandbox/{id}
Parameters
id(int) The numeric identifier of the entity to update.
Body
All fields are optional. Only fields present in the body are updated.

            
stringValue(string) String value. Minimum length: 3 characters.
intValue(int) Integer value.
boolValue(bool) Boolean value.
floatValue(float) Decimal value.
dateTimeValue(string) Datetime value in Y-m-d H:i:s format.
Body 200

            
Errors
404 Not Found: entity not found.
422 Unprocessable Entity: validation error on fields.

DELETESandbox / {id}

Deletes a Sandbox entity by its id. Returns HTTP 204 with no body.
DELETEhttps://api.qapla.it/v2/sandbox/{id}
Parameters
id(int) The numeric identifier of the entity to delete.
Response

HTTP 204 No Content — no body in the response.

Errors
404 Not Found: entity not found.