Client API 2026-09
The Client API lets you integrate the Spedisci.online platform into your own systems: shipments with labels, rate quotes, tracking, end-of-day manifests, pickups, held shipments (stocks), delivery points, customs codes and webhooks.
It is the OAuth2 successor of the API-key based API v2, which stays online until 28 February 2027.
Base URL
https://<subdomain>.spedisci.online/api/2026-09/<subdomain> is the platform your account belongs to (the same host you use to log in). Every endpoint in this documentation is relative to this base URL.
Quick start
- Create an App in Settings → API App (
/client/api-app) of your account to get aclient_idandclient_secret. - Exchange them for a bearer token (see Authentication).
- Call the API with
Authorization: Bearer <access_token>andAccept: application/json.
curl https://<subdomain>.spedisci.online/api/2026-09/carriers \
-H "Authorization: Bearer <access_token>" \
-H "Accept: application/json"Versioning
The URL prefix is a date (2026-09). Backward-compatible changes — new fields, new endpoints, new enum values — are released under the same prefix. A breaking change opens a new prefix and the previous one keeps being served for at least 12 months.
Clients must ignore fields they do not know: new fields can appear in any response at any time.
Access requirements
- A user with the
clientrole, active, belonging to an active client account. - On platforms that are not self-service, at least 3 validated documents on the client account (the same rule as the legacy API keys page).
- A token carrying the
client-apiscope. Tokens issued to administrator Apps do not have it and are rejected with403.
Endpoints
All resources are scoped to the authenticated client: shipments, stocks, orders, manifests and webhooks of another client answer 404, never 403.
| Method | Endpoint | Description | Rate limit |
|---|---|---|---|
GET | /carriers | Carriers and contracts of the client, with accessory services and COD methods | |
POST | /rates | One quote per available contract | 60/min |
GET | /shipments | List shipments with filters | |
POST | /shipments | Create a shipment and return its label | 30/min, subscription |
GET | /shipments/{ldv} | Shipment detail | |
DELETE | /shipments/{ldv} | Cancel (if not yet in a manifest / in transit) and refund the credit | |
GET | /shipments/{ldv}/label | Label in base64 (format=pdf|zpl) | |
GET | /shipments/{ldv}/tracking | Normalized tracking events | tracking |
GET | /tracking/bda/{bda} | Tracking by BDA (last 60 days) | tracking |
GET POST | /pickups | Requested pickups / request a pickup | 10/min, subscription |
GET | /pickups/{id} | Pickup detail | |
GET POST | /manifests | Manifests of the period / close the day | 5/min |
GET | /manifests/{id} | Manifest detail (pdf=1 to embed the PDF) | |
GET | /stocks | Held shipments (status=open|instructed|closed|all) | |
GET | /stocks/{id} | Stock detail | |
POST | /stocks/{id}/actions | Release instructions | |
GET | /delivery-points | Pickup / delivery points near an address (BRT) | 30/min |
GET | /taric | HS / TARIC code search | 60/min |
GET POST | /webhooks | Registered endpoints / register an endpoint | |
GET DELETE | /webhooks/{id} | Detail / delete | |
GET | /webhooks/{id}/deliveries | Deliveries of the last 10 days | |
POST | /webhooks/{id}/test | Send a real, signed tracking.update event | 5/min |
“Subscription” means the endpoint is gated by the account’s subscription and can answer 402 — see Conventions & Errors.
OpenAPI specification
The machine-readable OpenAPI 3.1 document of this API is available at /openapi/client-api-2026-09.yaml. Use it to generate clients or import the API in Postman / Insomnia.