Formato delle risposte ed errori

Tutte le risposte, anche quelle di errore, sono in JSON (Content-Type: application/json).

Risorse e liste

Una risorsa singola è restituita come oggetto. Le liste sono paginate:


{
  "data": [ { "id": 1 }, { "id": 2 } ],
  "links": { "first": "...", "last": "...", "prev": null, "next": "..." },
  "meta": { "current_page": 1, "per_page": 50, "total": 132, "last_page": 3 }
}

Parametro	Valore
`per_page`	Elementi per pagina: predefinito 50, massimo 200
`page`	Numero di pagina, da 1

Tipi di dato

Dato	Formato	Esempio
Data e ora	ISO 8601 con fuso orario	`2026-09-03T10:26:54+02:00`
Data	`AAAA-MM-GG`	`2026-09-03`
Importo	Oggetto con `amount` e `currency`	`{ "amount": 12.5, "currency": "EUR" }`
Peso	Oggetto con `value` e `units` (`KG` o `G`)	`{ "value": 1.5, "units": "KG" }`
Misure	`length`, `width`, `height`, `units` (`CM` o `MM`)	`{ "length": 30, "width": 20, "height": 10, "units": "CM" }`
Paese	ISO 3166-1 a due lettere	`IT`

Stato della spedizione

Lo stato è sempre un oggetto con codice, chiave e descrizione:


{ "code": 5, "key": "delivered", "label": "Consegnata" }

Codice	Chiave	Significato
0, 1	`processing`	In lavorazione
2	`shipped`	Spedita
3	`in_transit`	In transito
4	`out_for_delivery`	In consegna
5	`delivered`	Consegnata
6	`held_at_depot`	In giacenza
7	`returned_to_sender`	Resa al mittente
8	`undelivered`	Non consegnata
9	`awaiting_instructions`	In attesa di istruzioni
10	`awaiting_collection`	In attesa di ritiro

Usa la chiave (key) nel tuo codice: è stabile e leggibile.

Errori

Ogni errore ha la stessa struttura:


{
  "error": {
    "code": "validation_failed",
    "message": "The given data was invalid.",
    "details": {
      "recipient.address.postalCode": ["Il campo CAP è obbligatorio."]
    }
  }
}

details è presente negli errori di validazione: ogni chiave è il percorso del campo non valido.

HTTP	`code`	Quando
401	`unauthenticated`	Token mancante, scaduto o revocato
402	`subscription_required`	Abbonamento assente
402	`subscription_payment_failed`	Pagamento dell’abbonamento non riuscito
402	`plan_limit_reached`	Limite mensile del piano raggiunto
403	`insufficient_scope`, `account_disabled`, `client_role_required`, `forbidden`	Token o utente non autorizzati
404	`not_found`	Risorsa inesistente o di un altro cliente
405	`method_not_allowed`	Metodo HTTP non previsto per l’endpoint
409	`invalid_state`	Operazione non più possibile, ad esempio annullare una spedizione già in transito
422	`validation_failed`	Dati della richiesta non validi
422	`shipment_rejected`	Spedizione rifiutata dalle regole della piattaforma o dal corriere; il motivo è in `message`
429	`rate_limited`	Troppe richieste
502	`carrier_error`	Il corriere o un servizio esterno non risponde
500	`internal_error`	Errore interno

Gli errori 402 riguardano solo gli endpoint che generano un costo.

Isolamento dei dati

Ogni chiamata vede solo i dati del cliente autenticato. Una spedizione, una giacenza, una distinta o un webhook di un altro cliente rispondono 404, come se non esistessero.

Limiti di frequenza

Endpoint	Limite
`POST /rates`	60 al minuto
`POST /shipments`	30 al minuto
`POST /orders`	30 al minuto
`POST /pickups`	10 al minuto
`POST /manifests`	5 al minuto
`GET /delivery-points`	30 al minuto
`GET /taric`	60 al minuto
`GET /invoices/{id}/pdf`	10 al minuto
`POST /webhooks/{id}/test`	5 al minuto

Oltre il limite la risposta è 429 rate_limited: attendi e riprova. Per il tracking usa i webhook al posto di interrogazioni ripetute.