Una sola llista, filtrada
GET /api/v1/shipments és l’única col·lecció. Un enviament és independent — té una relació de molts a molts amb les cites i pot pertànyer a una comanda de kit de prova a casa — així que no hi ha cap llista imbricada sota un recurs pare. Filtra la mateixa llista amb ?appointment_id= o ?home_kit_order_id=, pagina-la amb limit / offset i segueix la matriu shipments integrada del recurs pare ({ id, added_at } tant en cites com en comandes de kit de prova a casa) fins a Obtenir un enviament quan tinguis un ID.
Contingut i qui l’ha reservat
Cada enviament inclou dues dades que no són visibles a partir de les seves adreces:contents— text lliure que descriu què hi ha dins del paquet, definit en crear-lo ("Medizinisch freigestellte Probe","Home test kit") i mostrat al missatger. Només informatiu. La direcció no és un camp: si un paquet va cap a un laboratori es dedueix dedestination.booked_by— qui ha imprès l’etiqueta:anivaoexternal. Només els enviamentsanivaaccepten Actualitzar i Cancel·lar; un paquetexternalté seguiment a la mateixa llista, però retorna501en ambdós casos.
paired_with.
Accés
- Pots consultar un paquet quan almenys una cita o una comanda de kit de prova a casa vinculada és dins del teu context d’accés, o quan ha sortit d’una ubicació del teu context d’accés.
appointmentsihome_kit_ordersnomés llisten les cites i les comandes del teu context d’accés.- Actualitzar, Cancel·lar, Vincular cites i Desvincular cites requereixen que totes les comandes de kit de prova a casa vinculades siguin dins del teu context d’accés. En cas contrari, la crida retorna
403i només Aniva pot modificar el paquet.
Les lectures no criden mai el transportista
Cada lectura se serveix des de la nostra base de dades. Una sincronització en segon pla concilia cada enviament amb el seu transportista (cada 10 minuts per a GO!, cada hora per a DHL) i marcasynced_at, que indica l’antiguitat de cada resposta. No hi ha actualització forçada — DHL permet una crida de seguiment cada cinc segons, de manera que no es podria oferir una lectura que faci l’anada i tornada al transportista.
Crear un enviament
Quan crees un enviament, indiques ellocation_id d’origen — el punt de proves on ha de fer la recollida el missatger. També indiques el laboratori de destinació amb destination_lab. L’enviament va a l’adreça d’enviament registrada d’aquell laboratori.
La ubicació ha d’estar dins del context d’accés de la teva clau d’API. Fes servir Llistar ubicacions per trobar els ID d’ubicació disponibles.
Opcionalment pots passar appointment_id per vincular l’enviament a una cita específica en el moment
de la creació. El vincle apareix integrat a tots dos costats:
- a l’enviament, com una matriu
appointmentsd’entrades{ id, added_at }; - a la cita, com una matriu
shipmentsd’entrades{ id, added_at }.
id remet al punt final de detall canònic
(Obtenir una cita /
Obtenir un enviament) per obtenir la càrrega útil completa — els socis que vulguin
el progrés del missatger per cita segueixen cada entrada de la matriu shipments de la cita fins al
punt final de detall de l’enviament.
Un enviament es pot vincular a múltiples cites, i una cita es pot vincular a múltiples
enviaments. Després de crear-lo, gestiona la vinculació amb Vincular cites a un
enviament /
Desvincular cites d’un enviament. Cada
mutació retorna la llista de cites de l’enviament posterior a la mutació.
La regla de mutació és la següent: els vincles es poden crear o eliminar quan O BÉ la cita ha passat
l’extracció de sang (blood_drawn), o bé l’enviament s’ha creat fa menys de 24 hores. Fora d’aquesta
finestra el vincle queda bloquejat perquè els registres històrics es mantinguin estables.
Cicle de vida
Els enviaments passen pels estats següents:
Cada canvi d’estat envia un webhook
shipment.*, per exemple
shipment.delivered. shipment.updated s’activa amb cada canvi que pots llegir, com ara un nou escaneig.
Regles de l’horari de recollida
S’apliquen les regles següents en crear o actualitzar l’horari de recollida d’un enviament.pickup_date
(YYYY-MM-DD) i pickup_time_from / pickup_time_till (HH:MM, 24 h) són valors d’hora local
interpretats en la zona horària IANA de la ubicació d’origen; no hi envies cap zona horària.
Modificar enviaments
Pots actualitzar l’horari de recollida, el nombre de paquets, el pes i les notes d’un enviament ambPATCH /api/v1/shipments/{id}. Si canvia algun camp rellevant per a la logística (data de recollida, hora, nombre de paquets o pes), l’ordre logística existent es cancel·la automàticament i se’n crea una de nova. Els camps que ometis en el cos de l’actualització es conserven de l’enviament existent; per exemple, si només actualitzes weight, es torna a crear l’ordre amb el mateix horari de recollida. Els camps d’horari actualitzats es validen segons les mateixes regles de l’horari de recollida.
Si el proveïdor logístic rebutja la cancel·lació o la creació de la nova ordre durant una actualització, l’API retorna 502 Bad Gateway amb el missatge d’error del proveïdor.
Cancel·lar enviaments
Cancel·la un enviament ambDELETE /api/v1/shipments/{id}. Això crida l’API del proveïdor logístic per cancel·lar l’ordre i actualitza l’estat a cancelled.
El proveïdor logístic també pot rebutjar la cancel·lació pels seus propis motius (p. ex., ha passat el termini de cancel·lació). En aquest cas, l’API retorna 502 Bad Gateway amb el missatge d’error i el codi d’error del proveïdor.
Etiquetes de retorn
Una etiqueta de retorn de DHL forma part de la seva ordre d’anada. DHL no pot cancel·lar l’etiqueta per separat, així que cancel·lar la fila que fa el seguiment d’una etiqueta de retorn retorna409 Conflict. En lloc d’això, cancel·la el paquet d’anada mentre sigui pending. Això també cancel·la l’etiqueta: cada fila del trajecte de retorn en pending del paquet d’anada passa a cancelled i rep una entrada RETURN_LEG_CANCELLED al seu status_updates. Un paquet de retorn que el pacient ja ha enviat per correu continua el seu curs. Un cop enviat el paquet d’anada, l’etiqueta continua sent vàlida i Aniva tanca manualment la fila del trajecte de retorn.
ID de referència dels enviaments
Cada enviament té un ID de referència d’11 caràcters: una lletra, la data i quatre caràcters,{letter}YYMMDDXXXX (per exemple, P2611194821). La lletra indica a què pertany l’enviament, mai la seva direcció:
Un enviament del 20 al 22 de novembre de 2026 conserva el seu ID amb una paraula al davant:
API, MAN, AUTO o KIT (per exemple, AUTO261121UWKX). Tots dos formats continuen sent vàlids. No comprovis la longitud ni la primera lletra d’un ID. Fes servir l’ID per obtenir, actualitzar o cancel·lar l’enviament.
Adreces dels enviaments
Els campsorigin i destination de la resposta de l’enviament contenen objectes d’adreça resolts amb l’estructura següent:
origin es resol a partir de la ubicació de la prova que has
indicat en el moment de la creació i destination és el laboratori que has especificat a
destination_lab. Per a un paquet de kit a domicili, l’adreça de lliurament del pacient és
destination del kit i origin del retorn de la mostra; el centre que empaqueta el kit n’és
origin. L’adreça no porta cap location_id; relaciona un paquet de consulta mitjançant la cita a
la qual està vinculat.
Franja de recollida
El camppickup de la resposta de l’enviament conté la franja de recollida programada del
missatger. Inclou les marques de temps from i till com a instants UTC (ISO 8601 amb el sufix
Z, p. ex. 2026-04-15T07:00:00Z) i una cadena timezone (zona horària IANA de la ubicació de
recollida). Els valors d’hora local pickup_date / pickup_time_* que has enviat en crear o
actualitzar es resolen en aquests instants absoluts amb aquesta zona horària; fes servir timezone
per tornar a mostrar from / till en l’hora local de la ubicació de recollida. El camp és null
quan no s’ha programat cap franja de recollida.
Registre d’actualitzacions d’estat
Cada enviament inclou una matriustatus_updates amb tots els esdeveniments del cicle de vida que
ha informat el proveïdor logístic, del més antic al més recent. Cada entrada conté:
state— l’esdeveniment en el vocabulari d’estats d’enviament (pending,in_transit,delivered,fault), perquè puguis llegir la cronologia sense conèixer els codis del transportista.nullquan l’esdeveniment no comporta cap estat (creació d’etiqueta, un escaneig sense informació del transportista, entrades registrades abans que existís el camp). Maicancelled: una cancel·lació és nostra, no un esdeveniment del transportista.code— l’identificador d’estat propi del transportista (GO10,GO90,GOY001de GO!;VA,ZF,LA,ZUde DHL).nullquan el transportista no n’ha proporcionat cap. Es manté estable en les diferents traduccions destatus.detail_code— l’identificador més detallat del transportista quan en té un:statusDetailedde DHL, p. ex.CNRFC_NRQRD_ZF(redirigit a una oficina de correus),HLDCC_SERPT_LA(llest per recollir allà),DLVRD_SERPT_ZU(recollit).nullen la resta de casos.status— l’etiqueta llegible del transportista (p. ex.,"Shipment picked up","Die Sendung wurde abgeholt.").description— una explicació del codi o la frase més llarga del transportista.nullquan no existeix cap de les dues coses.location— on s’ha fet l’escaneig, tal com l’anomena el transportista: un dipòsit de GO!, una ciutat de DHL. Text lliure, no una coordenada.time— marca de temps ISO 8601 de l’esdeveniment, tal com l’ha informat el transportista (amb el seu desplaçament horari).
code
RETURNED_TO_SENDER. El seu camp status conté el motiu del transportista. L’enviament es manté
en fault, també després que el transportista ens retorni el paquet.
La llista pot estar buida si el transportista encara no ha informat de cap esdeveniment.
Fes servir el camp status de nivell superior per conèixer l’estat actual canònic. Avança en un sol
sentit —de pending a in_transit i a delivered—, amb fault superposat mentre l’esdeveniment
més recent n’informi; els transportistes no ordenen els seus esdeveniments per rellevància (DHL
afegeix un avís de redirecció amb codi pre-transit després de l’escaneig de lliurament), així que
l’entrada més recent per si sola no indica en quin punt es troba un paquet.
Exemple d’enviament
Exemple de paquets de kit a domicili
GET /api/v1/shipments?home_kit_order_id=d1e2f3a4-… retorna el kit de camí al pacient i la mostra de tornada, aparellats:
pending fins que el pacient enviï la mostra per correu; aquest és l’estat real, no un buit.