Una sola lista, filtrada
GET /api/v1/shipments es la única colección. Un envío es independiente — tiene una relación de muchos a muchos con las citas y puede pertenecer a un pedido de kit de prueba en casa —, por lo que no hay ninguna lista anidada bajo un recurso padre. Filtra la misma lista con ?appointment_id= o ?home_kit_order_id=, pagínala con limit / offset y sigue el array shipments integrado del recurso padre ({ id, added_at } tanto en citas como en pedidos de kit de prueba en casa) hacia Obtener envío cuando tengas un id.
Contenido y quién lo reservó
Cada envío incluye dos datos que no son visibles en sus direcciones:contents— texto libre que describe qué hay en el paquete, definido al crearlo ("Medizinisch freigestellte Probe","Home test kit") y mostrado al mensajero. Solo informativo. El sentido no es un campo: si un paquete va hacia un laboratorio se deduce dedestination.booked_by— quién imprimió la etiqueta:anivaoexternal. Solo los envíosanivaaceptan Actualizar y Cancelar; un paqueteexternalse sigue en la misma lista, pero devuelve501en ambas operaciones.
paired_with.
Acceso
- Puedes leer un paquete cuando al menos una cita o un pedido de kit de prueba en casa vinculado está en tu contexto de acceso, o cuando salió de una ubicación de tu contexto de acceso.
appointmentsyhome_kit_orderssolo muestran las citas y pedidos de tu contexto de acceso.- Actualizar, Cancelar, Vincular citas y Desvincular citas requieren que todos los pedidos de kit de prueba en casa vinculados estén en tu contexto de acceso. De lo contrario, la llamada devuelve
403y solo Aniva puede modificar el paquete.
Las lecturas nunca llaman al transportista
Cada lectura se sirve desde nuestra base de datos. Una sincronización en segundo plano concilia cada envío con su transportista (cada 10 minutos para GO! y cada hora para DHL) y registrasynced_at, que indica la antigüedad de cualquier respuesta. No existe actualización forzada: DHL solo permite una llamada de seguimiento cada cinco segundos, por lo que no se puede ofrecer una lectura que consulte en directo al transportista.
Crear un envío
Al crear un envío, especificas ellocation_id de origen — la ubicación de pruebas donde debe realizar la recogida el mensajero. También indicas el laboratorio de destino con destination_lab. El envío va a la dirección de envío registrada de ese laboratorio.
La ubicación debe estar dentro del contexto de acceso de tu clave de API. Usa Listar ubicaciones para encontrar los ID de ubicación disponibles.
Opcionalmente puedes pasar appointment_id para vincular el envío a una cita concreta al
crearlo. El vínculo aparece integrado en ambos lados:
- en el envío, como un array
appointmentscon entradas{ id, added_at }; - en la cita, como un array
shipmentscon entradas{ id, added_at }.
id remite al endpoint de detalle canónico
(Obtener cita /
Obtener envío) para obtener la carga útil completa: los socios que quieran
seguir el avance del mensajero por cita consultan cada entrada del array shipments de la cita en
el endpoint de detalle del envío.
Un envío puede vincularse a varias citas, y una cita puede vincularse a varios
envíos. Después de crearlo, gestiona los vínculos con Vincular citas al
envío /
Desvincular citas del envío. Cada
modificación devuelve la lista de citas del envío tras el cambio.
La regla de modificación es: los vínculos pueden crearse o eliminarse cuando O BIEN la cita ya ha pasado
la extracción de sangre (blood_drawn), o el envío se creó hace menos de 24 horas. Fuera de ese
plazo, el vínculo queda bloqueado para que los registros históricos se mantengan estables.
Ciclo de vida
Los envíos pasan por los siguientes estados:
Cada cambio de estado envía un webhook
shipment.*, por ejemplo
shipment.delivered. shipment.updated se activa con cada cambio que puedes leer, como un nuevo escaneo.
Reglas del horario de recogida
Las siguientes reglas se aplican al crear o actualizar el horario de recogida de un envío.pickup_date
(YYYY-MM-DD) y pickup_time_from / pickup_time_till (HH:MM, 24 h) son horas locales
interpretadas en la zona horaria IANA de la ubicación de origen: no envías una zona horaria junto con ellos.
Modificar envíos
Puedes actualizar el horario de recogida, el número de paquetes, el peso y las notas de un envío mediantePATCH /api/v1/shipments/{id}. Si cambia algún campo relevante para la logística (fecha u hora de recogida, número de paquetes o peso), el pedido logístico existente se cancela automáticamente y se crea uno nuevo. Los campos que omitas en el cuerpo de la actualización se conservan del envío existente; por ejemplo, si actualizas solo weight, el pedido se vuelve a crear con el mismo horario de recogida. Los campos de horario actualizados se validan con las mismas reglas del horario de recogida.
Si el proveedor logístico rechaza la cancelación o la nueva creación durante una actualización, la API devuelve 502 Bad Gateway con el mensaje de error del proveedor.
Cancelar envíos
Cancela un envío medianteDELETE /api/v1/shipments/{id}. Esto llama a la API del proveedor logístico para cancelar el pedido y actualiza el estado a cancelled.
El proveedor logístico también puede rechazar la cancelación por motivos propios (por ejemplo, si ya ha pasado el plazo de cancelación). En ese caso, la API devuelve 502 Bad Gateway con el mensaje y el código de error del proveedor.
Etiquetas de devolución
Una etiqueta de devolución de DHL forma parte de su pedido de ida. DHL no puede cancelar la etiqueta por separado, por lo que cancelar el registro que hace el seguimiento de una etiqueta de devolución devuelve409 Conflict. En su lugar, cancela el paquete de ida mientras esté pending. Eso cancela también la etiqueta: cada registro de devolución en estado pending asociado al paquete de ida pasa a cancelled y recibe una entrada RETURN_LEG_CANCELLED en su status_updates. Si el paciente ya ha enviado un paquete de devolución, este sigue su curso. Una vez enviado el paquete de ida, la etiqueta sigue siendo válida y Aniva cierra manualmente el registro de devolución.
ID de referencia de los envíos
Cada envío tiene un ID de referencia de 11 caracteres: una letra, la fecha y cuatro caracteres,{letter}YYMMDDXXXX (por ejemplo, P2611194821). La letra indica a qué pertenece el envío, nunca su sentido:
Un envío del 20 al 22 de noviembre de 2026 conserva su ID con una palabra delante:
API, MAN, AUTO o KIT (por ejemplo, AUTO261121UWKX). Ambos formatos siguen siendo válidos. No compruebes la longitud ni la primera letra de un ID. Usa el ID para obtener, actualizar o cancelar el envío.
Direcciones de envío
Los camposorigin y destination de la respuesta del envío contienen objetos de dirección resueltos con la siguiente estructura:
origin se resuelve a partir de la ubicación de pruebas que especificaste al
crearlo y destination es el laboratorio que indicaste en destination_lab.
Para un paquete de kit a domicilio, la dirección de entrega del paciente es el destination del kit y el
origin de la devolución de la muestra; el centro que empaqueta el kit es su origin. La
dirección no incluye location_id: relaciona un paquete de clínica a través de la cita a la que está
vinculado.
Franja de recogida
El campopickup de la respuesta del envío contiene la franja de recogida programada para el mensajero. Incluye
marcas de tiempo from y till como instantes UTC (ISO 8601 con sufijo Z, p. ej.,
2026-04-15T07:00:00Z) y una cadena timezone (zona horaria IANA de la ubicación de recogida). Los valores
de hora local pickup_date / pickup_time_* que enviaste al crear o actualizar se resuelven en estos
instantes absolutos usando esa zona horaria: usa timezone para volver a mostrar from / till en la
hora local de la ubicación de recogida. El campo es null cuando no se ha programado ninguna franja de recogida.
Registro de actualizaciones de estado
Cada envío incluye un arraystatus_updates con todos los eventos del ciclo de vida comunicados por el proveedor
logístico, del más antiguo al más reciente. Cada entrada contiene:
state— el evento en el vocabulario de estados del envío (pending,in_transit,delivered,fault), para que puedas leer el historial sin conocer los códigos del transportista. Esnullcuando el evento no conlleva estado (creación de etiqueta, un escaneo sin información del transportista o entradas registradas antes de que existiera el campo). Nunca escancelled: una cancelación es nuestra, no un evento del transportista.code— el código de estado propio del transportista (GO10,GO90,GOY001de GO!;VA,ZF,LA,ZUde DHL). Esnullcuando el transportista no proporciona ninguno. Se mantiene estable independientemente del idioma destatus.detail_code— el código más detallado del transportista cuando dispone de él:statusDetailedde DHL, p. ej.,CNRFC_NRQRD_ZF(redirigido a una oficina de correos),HLDCC_SERPT_LA(listo para recoger allí),DLVRD_SERPT_ZU(recogido). Esnullen el resto de casos.status— la etiqueta legible del transportista (p. ej.,"Shipment picked up","Die Sendung wurde abgeholt.").description— una explicación del código o la frase más larga del transportista. Esnullcuando no existe ninguna de las dos.location— dónde se realizó el escaneo, tal como lo nombra el transportista: un depósito de GO!, una ciudad de DHL. Texto libre, no una coordenada.time— marca de tiempo ISO 8601 del evento, tal como la comunica el transportista (con su desfase horario).
code
RETURNED_TO_SENDER. Su campo status contiene el motivo del transportista. El envío permanece en fault, incluso
después de que el transportista nos devuelva el paquete.
La lista puede estar vacía si el transportista aún no ha comunicado ningún evento.
Usa el campo status de nivel superior para conocer el estado actual canónico. Avanza en un solo sentido —de pending
a in_transit y a delivered—, con fault superpuesto mientras el evento más reciente indique una incidencia;
los transportistas no ordenan sus eventos por relevancia (DHL añade un aviso de redirección con código pre-transit
después del escaneo de entrega), por lo que la entrada más reciente por sí sola no indica en qué punto está un paquete.
Ejemplo de envío
Ejemplo de paquetes de kit a domicilio
GET /api/v1/shipments?home_kit_order_id=d1e2f3a4-… devuelve el kit de camino al paciente y la muestra de vuelta, emparejados:
pending hasta que el paciente envía la muestra: ese es el estado real, no un vacío.