Preventivi e spedizioni

Il flusso tipico è in due chiamate: un preventivo per conoscere prezzo e contratti disponibili, poi la creazione della spedizione, che restituisce subito l’etichetta.

Preventivo – `POST /rates`

Restituisce un preventivo per ogni contratto disponibile sul tuo account.


{
  "recipient": {
    "address": { "city": "Roma", "province": "RM", "postalCode": "00183", "countryCode": "IT" }
  },
  "packages": [
    {
      "weight": { "value": 1.5, "units": "KG" },
      "dimensions": { "length": 30, "width": 20, "height": 10, "units": "CM" }
    }
  ],
  "options": {
    "cod": { "amount": 49.90, "currency": "EUR" },
    "insurance": { "amount": 200, "currency": "EUR" },
    "pickupFromAddress": false
  }
}

Campo	Obbligatorio	Note
`recipient.address.postalCode`, `countryCode`	Sì	Città e provincia sono facoltative
`packages[]`	Sì	Ogni collo con il proprio peso e le proprie misure
`shipper.address`	No	Se omesso vale il punto di ritiro
`warehouseId`	No	ID del punto di ritiro da cui parte la merce; se omesso vale quello predefinito
`options.cod`, `options.insurance`	No	Contrassegno e assicurazione, per includerne il costo
`options.pickupFromAddress`	No	Include il costo del ritiro; è zero se il punto ha il ritiro gratuito approvato

Risposta (un elemento per contratto):


{
  "data": [
    {
      "carrierCode": "poste",
      "carrierName": "Poste Delivery Business",
      "contractCode": "poste-express",
      "contractName": "Poste Express",
      "price": {
        "total": 8.42,
        "currency": "EUR",
        "breakdown": { "weight": 6.90, "fuel": 0.52, "insurance": 0, "cod": 1.00, "services": 0, "extra": 0, "pickup": 0 }
      },
      "billableWeight": { "value": 1.5, "units": "KG" },
      "volumetricWeight": { "value": 1.2, "units": "KG" },
      "zone": "Italia",
      "cashOnDeliveryMethods": { "CONT": "Contanti" },
      "services": [ { "serviceId": 3, "serviceName": "Consegna al sabato" } ]
    }
  ]
}

I valori dell’esempio sono indicativi. Dalla risposta ti servono in particolare:

contractCode: è il valore da passare come serviceType quando crei la spedizione o il ritiro. Va usato esattamente come ricevuto.
services[].serviceId: gli ID dei servizi accessori del contratto, da passare in options.accessoryServices.
cashOnDeliveryMethods: le modalità di incasso del contrassegno accettate dal contratto, da passare in options.cod.method.

Creare una spedizione – `POST /shipments`


{
  "reference": "ORD-1234",
  "serviceType": "<contractCode ricevuto da /rates>",
  "recipient": {
    "name": "Giulia Russo",
    "address": { "street": "Via Appia 10", "city": "Roma", "province": "RM", "postalCode": "00183", "countryCode": "IT" },
    "phone": "+39 333 1234567",
    "email": "giulia@example.com"
  },
  "packages": [
    {
      "weight": { "value": 1.5, "units": "KG" },
      "dimensions": { "length": 30, "width": 20, "height": 10, "units": "CM" }
    }
  ],
  "options": {
    "notes": "Citofonare Russo",
    "contentDescription": "Abbigliamento",
    "labelFormat": "PDF",
    "cod": { "amount": 49.90, "currency": "EUR", "method": "CONT" },
    "insurance": { "amount": 200, "currency": "EUR" },
    "accessoryServices": [3]
  }
}

Regole

Campo	Regola
`recipient`, `packages`	Obbligatori. Fino a 50 colli, ognuno con il proprio peso
`serviceType`	Facoltativo: se omesso viene usato il primo contratto del preventivo
`shipper`	Facoltativo: se omesso il mittente è il punto di ritiro
`warehouseId`	Facoltativo: il punto di ritiro da cui parte la spedizione. Mittente, riferimento mittente e indirizzo di reso vengono presi dal punto
`reference`	Il tuo riferimento d’ordine, fino a 100 caratteri
`options.labelFormat`	`PDF` o `ZPL`
`options.deliveryPoint`	Consegna presso un punto Poste: vedi Punti di consegna
`customsDetail`	Obbligatorio per le destinazioni fuori dal territorio doganale UE: vedi Spedizioni extra UE

Pesi in KG o G, misure in CM o MM.

Risposta

La risposta 201 contiene la spedizione e la sua etichetta:


{
  "id": 48210,
  "trackingNumber": "3UW0WTQ069239",
  "reference": "ORD-1234",
  "status": { "code": 2, "key": "shipped", "label": "Spedita" },
  "carrier": { "code": "poste", "name": "Poste Delivery Business", "contractCode": "poste-express", "contractName": "Poste Express" },
  "warehouseId": 19,
  "parcels": 1,
  "packages": [ { "number": 1, "trackingNumber": "3UW0WTQ069239" } ],
  "cost": { "total": 8.42, "currency": "EUR" },
  "createdAt": "2026-09-30T10:26:54+02:00",
  "label": { "format": "PDF", "pdf": "<base64>", "zpl": null }
}

L’etichetta è codificata in base64: decodificala e salvala come file .pdf (o inviala alla stampante termica, per lo ZPL). Ogni collo ha il proprio numero in packages[].trackingNumber.

Se la spedizione viene creata ma c’è qualcosa da segnalare, ad esempio una restituzione automatica Poste non creata, la risposta contiene il campo warning. La spedizione resta valida.

Errori frequenti

Risposta	Causa
`422 validation_failed`	Un campo manca o non è valido: guarda `details`
`422 shipment_rejected`	Il corriere o le regole della piattaforma rifiutano la spedizione: il motivo è in `message`
`402`	Abbonamento assente, non pagato o limite del piano raggiunto
`502 carrier_error`	Il corriere non risponde: riprova più tardi

Elenco – `GET /shipments`

Senza filtri restituisce le spedizioni degli ultimi 30 giorni.

Filtro	Descrizione
`from`, `to`	Periodo (`AAAA-MM-GG`)
`status`	Chiave o codice dello stato, anche più valori separati da virgola: `delivered,held_at_depot`
`carrierCode`, `serviceType`	Corriere e contratto
`trackingNumber`, `reference`	Numero di spedizione o tuo riferimento
`recipientName`, `city`, `postalCode`, `countryCode`	Destinatario
`hasCod`, `hasInsurance`	`true` o `false`
`storeId`	Negozio online di provenienza
`per_page`, `page`	Paginazione


curl "https://demo.spedisci.online/api/2026-09/shipments?from=2026-09-01&status=delivered&per_page=100" \
    -H "Authorization: Bearer <access_token>"

Dettaglio – `GET /shipments/{ldv}`

{ldv} è il numero di spedizione (lettera di vettura). La risposta è la spedizione completa: mittente, destinatario, colli, costo con il dettaglio, contrassegno e relativo stato, date di spedizione, ritiro e consegna, e il numero dell’eventuale restituzione in returnTrackingNumber.

Etichetta – `GET /shipments/{ldv}/label`

Restituisce di nuovo l’etichetta in base64. Con ?format=pdf o ?format=zpl scegli il formato; senza parametro ricevi tutti i formati disponibili.

Per le spedizioni Poste con restituzione automatica, la restituzione è la seconda pagina dello stesso PDF.

Annullare – `DELETE /shipments/{ldv}`

Annulla la spedizione e rimborsa il credito:


{ "trackingNumber": "3UW0WTQ069239", "cancelled": true, "refunded": 8.42 }

L’annullamento è possibile finché la spedizione non è in distinta o in transito; dopo, la risposta è 409 invalid_state.

Preventivi e spedizioni

Preventivo – POST /rates

Creare una spedizione – POST /shipments