Conventions & Errors

Requests

• Send Accept: application/json on every request and Content-Type: application/json when the request has a body.
• Path parameters {ldv} are tracking numbers (LDV), {id} are numeric identifiers, {bda} a BDA.
• Boolean query parameters accept true/false and 1/0.
• Dates in query parameters and request bodies use YYYY-MM-DD.

Responses

Responses are always JSON (Content-Type: application/json), including errors.

• A single resource is returned as a bare object.
• A collection is returned as { "data": [...] }. Large collections are paginated:

{
  "data": [ ... ],
  "links": { "first": "...?page=1", "last": "...?page=8", "prev": null, "next": "...?page=2" },
  "meta": { "current_page": 1, "from": 1, "last_page": 8, "per_page": 50, "to": 50, "total": 391 }
}

Lists are ordered from the most recent item.

Value objects

The same structures are used everywhere, in requests and responses.

Shipment statuses

Where a filter accepts a status (for example GET /shipments?status=), you can pass a key, a numeric code or a comma-separated mix: status=delivered,held_at_depot or status=5,6.

Recipient personal data

The API serves the Spedisci.online apps and the integrations of the clients (ERPs, shops, connectors). Only the Spedisci.online apps receive the personal data of the people shipments and orders are addressed to. An integration reads the same resources, but of the recipient it sees only where the parcel goes:

"recipient": { "address": { "city": "Roma", "province": "RM", "countryCode": "IT" } }

• The recipient’s name, street, street2, postalCode, phone, email and reference are not returned. You still send them in full when creating shipments and orders; they are stored and printed on the label.
• Free text that may quote the person is replaced by flags: on shipments notes and warning become hasWarning; on orders notes and error.message become hasError.
• The customs declaration is returned without its importer block (the recipient’s EORI, VAT number and tax id).
• The shipper is your own address and is returned in full.
• The filters that would look a person up are closed: recipientName and postalCode on GET /shipments answer 422 validation_failed, and q on GET /orders searches only order numbers and tracking numbers.

This applies to every response of the API, including the 201 of POST /shipments and POST /orders. Webhook payloads never carried personal data.

Errors

Every error uses the same envelope. code is stable and machine-readable, message is for humans (and may be localized), details is optional (field errors, carrier response, plan limits…).

{
  "error": {
    "code": "validation_failed",
    "message": "The given data was invalid.",
    "details": {
      "recipient.address.postalCode": ["The recipient.address.postal code field is required."]
    }
  }
}

Rate limits

Limits are per App, per minute. Exceeding one answers 429 rate_limited with the standard Retry-After / X-RateLimit-* headers.

For status updates prefer webhooks over polling the tracking endpoints.