Saltar al contingut principal
Un enviament és un paquet físic: una recollida per missatgeria que porta mostres de sang d’un punt de proves a un laboratori, el kit en camí cap a un pacient amb kit de prova a casa, o la mostra que aquest pacient envia de tornada per correu. L’API d’enviaments et permet crear, seguir, modificar i cancel·lar ordres d’enviament, i llista tots els paquets en un sol lloc, independentment de qui els hagi reservat.

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 de destination.
  • booked_by — qui ha imprès l’etiqueta: aniva o external. Només els enviaments aniva accepten Actualitzar i Cancel·lar; un paquet external té seguiment a la mateixa llista, però retorna 501 en ambdós casos.
Un paquet que portava una etiqueta de devolució i el paquet que torna amb aquella etiqueta s’apunten mútuament mitjançant 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.
  • appointments i home_kit_orders nomé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 403 i 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 marca synced_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 el location_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 appointments d’entrades { id, added_at };
  • a la cita, com una matriu shipments d’entrades { id, added_at }.
Ambdues matrius ordenen primer el vincle més antic. Cada 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 amb PATCH /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.
Els enviaments no es poden modificar després que el missatger hagi recollit el paquet. Els intents d’actualitzar un enviament en estat in_transit, delivered o fault retornen 409 Conflict.
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 amb DELETE /api/v1/shipments/{id}. Això crida l’API del proveïdor logístic per cancel·lar l’ordre i actualitza l’estat a cancelled.
Els enviaments no es poden cancel·lar després de la recollida. Els intents de cancel·lar un enviament que ja està en estat in_transit, delivered o fault retornen 409 Conflict. Cancel·lar-ne un que ja és cancelled no té cap efecte i retorna 200 amb l’enviament; consulta Idempotència.
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 retorna 409 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 camps origin i destination de la resposta de l’enviament contenen objectes d’adreça resolts amb l’estructura següent:
Per a un paquet de consulta, l’adreça 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 camp pickup 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 matriu status_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. null quan l’esdeveniment no comporta cap estat (creació d’etiqueta, un escaneig sense informació del transportista, entrades registrades abans que existís el camp). Mai cancelled: una cancel·lació és nostra, no un esdeveniment del transportista.
  • code — l’identificador d’estat propi del transportista (GO10, GO90, GOY001 de GO!; VA, ZF, LA, ZU de DHL). null quan el transportista no n’ha proporcionat cap. Es manté estable en les diferents traduccions de status.
  • detail_code — l’identificador més detallat del transportista quan en té un: statusDetailed de DHL, p. ex. CNRFC_NRQRD_ZF (redirigit a una oficina de correus), HLDCC_SERPT_LA (llest per recollir allà), DLVRD_SERPT_ZU (recollit). null en 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. null quan 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).
Quan el transportista retorna el paquet al remitent, la cronologia rep una entrada amb 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:
La fila del trajecte de retorn existeix des del moment en què s’imprimeix l’etiqueta de retorn i es manté en pending fins que el pacient enviï la mostra per correu; aquest és l’estat real, no un buit.