Purpose

A single, courier-agnostic contract for pushing parcel tracking events to Qapla'.

If you asked us for a webhook URL to send tracking events to, this is the specification of that webhook: what to send, in what shape, and how we answer. The URL is neither public nor shared — we assign one to you together with your credentials, at the first step of onboarding.

Qapla' tracks shipments for thousands of European merchants. Historically we pull status from each courier's own API — different auth, different polling limits, different payloads, and a delay between the real-world event and the notification the consumer receives.

This specification is the opposite: you push, we listen. One endpoint, one JSON shape, one retry policy. It removes polling load from your infrastructure and it gets the event to the end consumer in seconds instead of tens of minutes.

Endpoints

We issue one URL at onboarding. The URLs are not listed here: they are per courier, and handing them out outside the onboarding path would serve no purpose.

What is stable is the shape of the paths under the base you are given — https://{endpoint-host} below stands for it:

Content-Type: application/json, UTF-8. Content-Encoding: gzip is supported and recommended for batches.

Authentication

Required — bearer token

POST /v1/events HTTP/1.1
Host: {endpoint-host}
Authorization: Bearer <token>
Content-Type: application/json

Qapla' issues one token per courier per environment. The token identifies you; it does not expire on a schedule and it can be rotated on request, with an overlap window during which both the old and the new token are accepted.

Optional — payload signature

If you prefer not to rely on a bearer token alone, add:

X-Qapla-Signature: t=1787654400,v1=5257a869e7ecebeda32affa62cdca3fa793333cd8b3f7a0d3d9ed3c1f0b1b1ab

v1 is the hex-encoded HMAC-SHA256 of "<t>.<raw request body>", keyed with a shared secret we issue alongside the token. We reject a signature whose t is more than 5 minutes away from our clock. If the header is present we verify it; if it is absent we accept the request on the bearer token alone. Signature enforcement can be switched to mandatory for your courier code on request.

Optional — source IP allowlist

Send us your egress ranges and we will only accept your traffic from them.

POST/v1/events

A message is an envelope carrying a flat list of events. An event is one fact about one parcel at one point in time. There is no separate "current status" and "history": the most recent event is the current status.

Send the whole history, send only what changed since your last call, send events out of order — all three are valid, because every event carries its own identity and timestamp.

POSThttps://{endpoint-host}/v1/events

The whole call, with nothing omitted:

curl -X POST https://{endpoint-host}/v1/events \
  -H "Authorization: Bearer $QAPLA_TOKEN" \
  -H "Content-Type: application/json" \
  --data-binary @event.json

POST/v1/events/validate

Identical to /v1/events in auth and payload, but stores nothing: it validates the message against the schema and returns the same results[], with outcome ACCEPTED for the events that would have been accepted.

POSThttps://{endpoint-host}/v1/events/validate

GET/v1/ping

GEThttps://{endpoint-host}/v1/ping

{
  "courier": "ACME_EXPRESS",
  "environment": "production",
  "schemaVersions": ["1.0"]
}

Envelope

^* Required field

Event fields — required

Event fields — optional

Every one of these is genuinely optional; send what you have.

Tracking number change

Some parcels get a provisional identifier at label creation and their definitive tracking number only later; others are reassigned mid-journey. Both cases are the same event: send it under the number the consumer currently knows, and put the new one in trackingNumberChange.

From the next event onwards, use the new number as trackingNumber.

Alternative reference

Some courier event feeds are keyed off the merchant's order reference rather than the tracking number. Send that value as externalId, together with senderAccount — the account, contract or customer code the shipment was booked under.

At least one of trackingNumber and externalId must be present. Send both whenever you have both: it is the most reliable input we can get, because it lets us match the parcel two ways and detect a mismatch.

Expected delivery

Send the expected delivery inside delivery, attached to an event like any other piece of information: estimatedDeliveryDate for the day, estimatedDeliveryWindow for the time window where you have one. Both are optional and may appear together.

There is no endpoint to update it. An estimate changes — the parcel misses a leg, the day's round slips — and the way to revise it is to send a new event carrying the updated value. The current estimate is the one on the most recent event that carries it: an event without delivery does not clear the previous estimate, it leaves it standing.

One practical consequence: if the estimate changes and there is no status progress to report, send an event anyway — with your current status code, a new eventId and the updated delivery. It is the only way we can see the change, and it is the case the consumer cares about most.

Status codes: send yours, not ours

We deliberately do not publish an enum for you to map onto.

Every courier's status vocabulary is finer-grained than any shared enum, and forcing a mapping at the source destroys exactly the detail that makes an event useful — "delivery attempted, recipient absent" and "delivery attempted, address not found" both collapse to EXCEPTION, and the merchant loses the ability to react differently. Worse, that mapping then lives in your code, where we cannot fix it when it turns out to be wrong.

So: send status.code exactly as it appears in your own systems. Qapla' maintains the mapping from your codes to our normalised statuses, and we own the consequences of getting it wrong.

Per-event outcome — 200 OK

We answer per event. A batch is never rejected as a whole because one of its events was not usable.

Message-level failures

Every 4xx body is an RFC 7807 problem document.

Retry policy

Retry on 429, on 5xx, on connection failures, and on timeouts. Exponential backoff with jitter, at least 5 attempts spread over ~15 minutes (e.g. 10s → 30s → 2m → 5m → 10m).

Read timeout: 10 seconds. We answer well inside 1 second in normal operation. A timeout is not a failure to deliver — we may already have stored the events. Retrying the same messageId and the same eventIds is the correct and safe response. If you retry per event, you may also put a failed event into a later batch: what counts is the eventId, not the messageId.

Versioning

schemaVersion is a top-level field, major.minor.

• Minor bump: new optional fields, new outcome values. Backward compatible; we deploy it and your integration keeps working untouched. Ignore fields you do not know.
• Major bump: anything that could break a sender. Announced with at least 90 days' notice, and the previous major stays accepted for at least 12 months after the announcement.

We never remove or repurpose a field inside a major version.

Limits

X-RateLimit-Limit and X-RateLimit-Remaining are returned on every response.

Onboarding

1. You send us your expected daily event volume and peak rate, and your logo in vector format (SVG, transparent background, no margins): we use it in tracking emails and on the public tracking page. We assign you your endpoint URL, a token, a signing secret, and your courier code.
2. You send us your status code catalogue.
3. You develop against POST /v1/events/validate, at whatever pace suits you. The JSON Schema and the example payloads are the normative artefacts — a validator run against them is the fastest way to know you are done.
4. We activate /v1/events for your courier code and compare the first day of real traffic against the tracking we already collect for the same parcels, which catches mapping and timezone mistakes before they reach a consumer.
5. You are live. You can keep your existing pull integration running in parallel for as long as you like; duplicate events are free, thanks to eventId.

Schema and examples

Questions this specification does not answer

Raised here deliberately, because they are worth deciding together rather than assuming:

• Do you want an acknowledgement channel? We can expose a signed callback telling you which events produced a consumer notification. Nobody has asked yet.
• Do you want us to push back? Some couriers want the merchant's re-delivery instruction to arrive as an API call rather than as a consumer clicking a link. Out of scope for v1.
• Consignment-level vs parcel-level identity. v1 keys everything off the tracking number the consumer knows. If your model is consignment-first with parcels underneath, tell us and we will look at it before v1 freezes.

Contact: tech@qapla.it