Giacenze
Una giacenza si apre quando il corriere non riesce a consegnare e attende istruzioni. Dalle API puoi leggere le giacenze e inviare le istruzioni di svincolo, come dalla pagina Giacenze del pannello.
Elenco – GET /stocks
| Parametro | Valori |
|---|---|
status | open (predefinito), instructed, closed, all |
trackingNumber | Cerca la giacenza di una spedizione |
per_page, page | Paginazione |
| Stato | Significato |
|---|---|
open | Aperta, in attesa delle tue istruzioni |
instructed | Istruzioni inviate |
confirmed | Istruzioni confermate dal corriere |
closed | Chiusa: la spedizione è ripartita, è stata consegnata o è stata resa |
Dettaglio – GET /stocks/{id}
{
"id": 912,
"trackingNumber": "3UW0WTQ069239",
"shipmentId": 48210,
"status": { "code": 0, "key": "open", "label": "Aperta" },
"notes": "Destinatario assente",
"totalPrice": 6.00,
"lastAction": null,
"openedAt": "2026-09-29T09:00:00+02:00",
"releasedAt": null
}totalPrice è il costo addebitato per la giacenza; lastAction riporta
l’ultima istruzione inviata.
Inviare le istruzioni – POST /stocks/{id}/actions
{
"action": "NEWADDRESS",
"notes": "Consegnare al nuovo indirizzo",
"newAddress": {
"name": "Giulia Russo",
"street": "Via Nomentana 20",
"city": "Roma",
"province": "RM",
"postalCode": "00161",
"phone": "+39 333 1234567"
}
}action | Istruzione |
|---|---|
RETRY | Nuovo tentativo di consegna allo stesso indirizzo |
NEWADDRESS | Consegna a un nuovo indirizzo: richiede newAddress |
RETURN | Reso al mittente |
DESTROY | Distruzione della merce |
ONSITECOLLECTION | Il destinatario ritira in sede |
Campi facoltativi:
| Campo | Uso |
|---|---|
scheduledAt | Data in cui eseguire l’istruzione |
notes | Note per il corriere |
cod.newAmount | Nuovo importo del contrassegno |
In newAddress sono obbligatori name, street, city, province e
postalCode.
La risposta 201 è la giacenza aggiornata. Le istruzioni vengono registrate e,
quando il corriere lo supporta, trasmesse direttamente al corriere.
| Risposta | Significato |
|---|---|
409 invalid_state | Le istruzioni sono già state inviate |
422 validation_failed | Dati mancanti, ad esempio newAddress con NEWADDRESS |
502 carrier_error | Il corriere non risponde |
Per sapere subito quando si apre o si chiude una giacenza, registra un
webhook sugli eventi stock.opened e stock.closed.
Last updated on