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 dadestination.booked_by— chi ha stampato l’etichetta:anivaoexternal. Solo le spedizionianivaaccettano Aggiorna e Annulla; un paccoexternalè tracciato nello stesso elenco ma restituisce501per entrambe.
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.
appointmentsehome_kit_orderselencano 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
403e 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 impostasynced_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 illocation_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
appointmentsdi elementi{ id, added_at }; - sull’appuntamento, come array
shipmentsdi elementi{ id, added_at }.
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 tramitePATCH /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.
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 tramiteDELETE /api/v1/shipments/{id}. Questa chiamata invoca l’API del fornitore logistico per annullare l’ordine e aggiorna lo stato a cancelled.
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 restituisce409 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 campiorigin e destination nella risposta della spedizione contengono oggetti indirizzo risolti con la seguente struttura:
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 campopickup 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 arraystatus_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.nullquando l’evento non ha uno stato (creazione dell’etichetta, scansione senza informazioni del corriere, voci registrate prima che il campo esistesse). Maicancelled— un annullamento è nostro, non un evento del corriere.code— il token di stato proprio del corriere (GO10,GO90,GOY001di GO!;VA,ZF,LA,ZUdi DHL).nullquando il corriere non ne fornisce alcuno. Stabile tra le traduzioni linguistiche distatus.detail_code— il token più dettagliato del corriere, se presente:statusDetaileddi DHL, ad es.CNRFC_NRQRD_ZF(reindirizzato a un ufficio postale),HLDCC_SERPT_LA(pronto per il ritiro lì),DLVRD_SERPT_ZU(ritirato).nullnegli 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.nullquando 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).
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:
pending finché il paziente non spedisce il campione — è lo stato reale, non una lacuna.