Vai al contenuto principale
Una spedizione è un singolo pacco fisico: un ritiro tramite corriere che trasporta campioni di sangue da una sede di test a un laboratorio, il kit diretto a un paziente con kit domiciliare o il campione che quel paziente rispedisce indietro. L’API Shipments ti permette di creare, tracciare, modificare e annullare ordini di spedizione, ed elenca ogni pacco in un unico posto indipendentemente da chi lo ha prenotato.

Un unico elenco, filtrato

GET /api/v1/shipments è l’unica raccolta. Una spedizione è autonoma — ha una relazione molti-a-molti con gli appuntamenti e può appartenere a un ordine di kit domiciliare — quindi non esiste un elenco annidato sotto una risorsa padre. Filtra lo stesso elenco con ?appointment_id= o ?home_kit_order_id=, paginalo con limit / offset e segui l’array inline shipments della risorsa padre ({ id, added_at } sia negli appuntamenti sia negli ordini di kit domiciliare) verso Ottieni spedizione quando hai un id.

Contenuto e chi l’ha prenotata

Ogni spedizione riporta due informazioni non visibili dai suoi indirizzi:
  • contents — testo libero che descrive cosa contiene il pacco, impostato alla creazione ("Medizinisch freigestellte Probe", "Home test kit") e mostrato al corriere. Solo informativo. La direzione non è un campo: se un pacco è diretto a un laboratorio si deduce da destination.
  • booked_by — chi ha stampato l’etichetta: aniva o external. Solo le spedizioni aniva accettano Aggiorna e Annulla; un pacco external è tracciato nello stesso elenco ma restituisce 501 per entrambe.
Un pacco che conteneva un’etichetta di reso e il pacco riportato indietro da quell’etichetta puntano l’uno all’altro tramite paired_with.

Accesso

  • Puoi leggere un pacco quando almeno un appuntamento o ordine di kit domiciliare collegato rientra nel tuo contesto di accesso, oppure quando è partito da una sede nel tuo contesto di accesso.
  • appointments e home_kit_orders elencano solo gli appuntamenti e gli ordini nel tuo contesto di accesso.
  • Aggiorna, Annulla, Associa appuntamenti e Dissocia appuntamenti richiedono che ogni ordine di kit domiciliare collegato sia nel tuo contesto di accesso. Altrimenti la chiamata restituisce 403 e solo Aniva può modificare il pacco.

Le letture non chiamano mai il corriere

Ogni lettura viene servita dal nostro database. Una sincronizzazione in background allinea ogni spedizione con il relativo corriere (ogni 10 minuti per GO!, ogni ora per DHL) e imposta synced_at, che indica l’età di ogni risposta. Non esiste un aggiornamento forzato — DHL consente una chiamata di tracciamento ogni cinque secondi, quindi non sarebbe possibile offrire una lettura che interpella direttamente il corriere.

Creazione di una spedizione

Quando crei una spedizione, specifichi il location_id di origine — la sede di test in cui il corriere deve effettuare il ritiro. Indichi anche il laboratorio di destinazione con destination_lab. La spedizione viene inviata all’indirizzo di spedizione registrato di quel laboratorio. La sede deve rientrare nel contesto di accesso della tua chiave API. Usa Elenca sedi per trovare gli ID delle sedi disponibili. Puoi passare facoltativamente appointment_id per collegare la spedizione a un appuntamento specifico al momento della creazione. Il collegamento appare inline su entrambi i lati:
  • sulla spedizione, come array appointments di elementi { id, added_at };
  • sull’appuntamento, come array shipments di elementi { id, added_at }.
Entrambi gli array sono ordinati dal collegamento più vecchio al più recente. Ogni id rimanda all’endpoint di dettaglio canonico (Ottieni appuntamento / Ottieni spedizione) per il payload completo — i partner che vogliono l’avanzamento del corriere per singolo appuntamento seguono ogni elemento nell’array shipments dell’appuntamento fino all’endpoint di dettaglio della spedizione. Una spedizione può essere collegata a più appuntamenti e un appuntamento può essere collegato a più spedizioni. Dopo la creazione, gestisci il collegamento con Associa appuntamenti alla spedizione / Dissocia appuntamenti dalla spedizione. Ogni modifica restituisce l’elenco degli appuntamenti della spedizione dopo la modifica. La regola per le modifiche è: i collegamenti possono essere creati o rimossi quando l’appuntamento ha già superato il prelievo di sangue (blood_drawn) OPPURE la spedizione è stata creata meno di 24 ore fa. Fuori da quella finestra il collegamento è bloccato affinché i record storici restino stabili.

Ciclo di vita

Le spedizioni passano attraverso i seguenti stati:
Ogni cambio di stato invia un webhook shipment.*, ad esempio shipment.delivered. shipment.updated si attiva a ogni modifica che puoi leggere, come una nuova scansione.

Regole per la programmazione del ritiro

Quando crei o aggiorni la programmazione del ritiro di una spedizione si applicano le seguenti regole. pickup_date (YYYY-MM-DD) e pickup_time_from / pickup_time_till (HH:MM, 24h) sono valori di ora locale interpretati nel fuso orario IANA del luogo di origine — non devi inviare un fuso orario insieme a essi.

Modificare le spedizioni

Puoi aggiornare la programmazione del ritiro, il numero di colli, il peso e le note di una spedizione tramite PATCH /api/v1/shipments/{id}. Se cambia un campo rilevante per la logistica (data di ritiro, orario, numero di colli o peso), l’ordine logistico esistente viene annullato automaticamente e ne viene creato uno nuovo. I campi che ometti dal corpo dell’aggiornamento vengono mantenuti dalla spedizione esistente — ad esempio, aggiornando solo weight, l’ordine viene ricreato con la stessa programmazione del ritiro. I campi della programmazione aggiornati vengono validati in base alle stesse regole per la programmazione del ritiro.
Le spedizioni non possono essere modificate dopo che il corriere ha ritirato il pacco. I tentativi di aggiornare una spedizione in stato in_transit, delivered o fault restituiscono 409 Conflict.
Se il fornitore logistico rifiuta l’annullamento o la ricreazione durante un aggiornamento, l’API restituisce 502 Bad Gateway con il messaggio di errore del fornitore.

Annullare le spedizioni

Annulla una spedizione tramite DELETE /api/v1/shipments/{id}. Questa chiamata invoca l’API del fornitore logistico per annullare l’ordine e aggiorna lo stato a cancelled.
Le spedizioni non possono essere annullate dopo il ritiro. I tentativi di annullare una spedizione già in stato in_transit, delivered o fault restituiscono 409 Conflict. Annullarne una già cancelled non ha effetti e restituisce 200 con la spedizione — vedi Idempotenza.
Il fornitore logistico può anche rifiutare l’annullamento per motivi propri (ad es. se il termine per l’annullamento è scaduto). In tal caso, l’API restituisce 502 Bad Gateway con il messaggio di errore e il codice di errore del fornitore.

Etichette di reso

Un’etichetta di reso DHL fa parte del relativo ordine di andata. DHL non può annullare l’etichetta da sola, quindi annullare la riga che traccia un’etichetta di reso restituisce 409 Conflict. Annulla invece il pacco di andata, finché è in stato pending. Così annulli anche l’etichetta: ogni riga di ritorno pending del pacco di andata passa a cancelled e riceve una voce RETURN_LEG_CANCELLED in status_updates. Un pacco di reso già spedito dal paziente continua il suo percorso. Dopo la spedizione del pacco di andata, l’etichetta resta valida e Aniva chiude manualmente la riga di ritorno.

ID di riferimento delle spedizioni

Ogni spedizione ha un ID di riferimento di 11 caratteri: una lettera, la data e quattro caratteri, {letter}YYMMDDXXXX (ad esempio P2611194821). La lettera indica a cosa appartiene la spedizione, mai la sua direzione: Una spedizione dal 20 al 22 novembre 2026 mantiene il proprio ID con una parola davanti: API, MAN, AUTO o KIT (ad esempio AUTO261121UWKX). Entrambi i formati restano validi. Non controllare la lunghezza o la prima lettera di un ID. Usa l’ID per recuperare, aggiornare o annullare la spedizione.

Indirizzi delle spedizioni

I campi origin e destination nella risposta della spedizione contengono oggetti indirizzo risolti con la seguente struttura:
Per un pacco di uno studio medico, l’indirizzo origin viene risolto dalla sede del test che hai indicato alla creazione e destination è il laboratorio che hai indicato in destination_lab. Per un pacco di kit domiciliare, l’indirizzo di consegna del paziente è la destination del kit e l’origin del reso del campione; la sede che confeziona il kit è la sua origin. L’indirizzo non contiene location_id — collega un pacco di uno studio medico tramite l’appuntamento a cui è associato.

Finestra di ritiro

Il campo pickup nella risposta della spedizione contiene la finestra di ritiro del corriere programmata. Include i timestamp from e till come istanti UTC (ISO 8601 con suffisso Z, ad es. 2026-04-15T07:00:00Z) e una stringa timezone (fuso orario IANA del luogo di ritiro). I valori locali pickup_date / pickup_time_* che hai inviato in fase di creazione o aggiornamento vengono convertiti in questi istanti assoluti usando quel fuso orario — usa timezone per riportare from / till all’ora locale del luogo di ritiro. Il campo è null quando non è stata programmata alcuna finestra di ritiro.

Registro degli aggiornamenti di stato

Ogni spedizione include un array status_updates — ogni evento del ciclo di vita segnalato dal fornitore logistico, dal più vecchio al più recente. Ogni voce contiene:
  • state — l’evento nel vocabolario degli stati di spedizione (pending, in_transit, delivered, fault), così puoi leggere la cronologia senza conoscere i codici del corriere. null quando l’evento non ha uno stato (creazione dell’etichetta, scansione senza informazioni del corriere, voci registrate prima che il campo esistesse). Mai cancelled — un annullamento è nostro, non un evento del corriere.
  • code — il token di stato proprio del corriere (GO10, GO90, GOY001 di GO!; VA, ZF, LA, ZU di DHL). null quando il corriere non ne fornisce alcuno. Stabile tra le traduzioni linguistiche di status.
  • detail_code — il token più dettagliato del corriere, se presente: statusDetailed di DHL, ad es. CNRFC_NRQRD_ZF (reindirizzato a un ufficio postale), HLDCC_SERPT_LA (pronto per il ritiro lì), DLVRD_SERPT_ZU (ritirato). null negli altri casi.
  • status — l’etichetta leggibile del corriere (ad es. "Shipment picked up", "Die Sendung wurde abgeholt.").
  • description — una spiegazione del codice oppure la descrizione più lunga del corriere. null quando non esiste né l’una né l’altra.
  • location — dove è avvenuta la scansione, con il nome usato dal corriere: un deposito GO!, una città DHL. Testo libero, non una coordinata.
  • time — timestamp ISO 8601 dell’evento, come segnalato dal corriere (con il relativo offset).
Quando il corriere rispedisce il pacco al mittente, la cronologia riceve una voce con code RETURNED_TO_SENDER. Il campo status riporta il motivo del corriere. La spedizione resta poi fault, anche dopo che il corriere ci riconsegna il pacco. L’elenco può essere vuoto se il corriere non ha ancora segnalato alcun evento. Usa il campo status di primo livello per conoscere lo stato attuale canonico. Avanza in una sola direzione — da pending a in_transit fino a delivered — con fault sovrapposto finché l’evento più recente ne segnala uno; i corrieri non ordinano gli eventi per rilevanza (DHL aggiunge un avviso di reindirizzamento con codice pre-transit dopo la scansione di consegna), quindi la voce più recente da sola non indica a che punto è il pacco.

Esempio di spedizione

Esempio di pacchi di kit domiciliare

GET /api/v1/shipments?home_kit_order_id=d1e2f3a4-… restituisce in coppia il kit in viaggio verso il paziente e il campione di ritorno:
La riga di ritorno esiste dal momento in cui viene stampata l’etichetta di reso e resta pending finché il paziente non spedisce il campione — è lo stato reale, non una lacuna.