Saltar al contenido principal
Un envío es un paquete físico: una recogida por mensajería que lleva muestras de sangre desde una ubicación de pruebas hasta un laboratorio, el kit de camino a un paciente de kit de prueba en casa o la muestra que ese paciente devuelve por correo postal. La API de envíos te permite crear, rastrear, modificar y cancelar órdenes de envío, y muestra todos los paquetes en un solo lugar, sin importar quién los haya reservado.

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 de destination.
  • booked_by — quién imprimió la etiqueta: aniva o external. Solo los envíos aniva aceptan Actualizar y Cancelar; un paquete external se sigue en la misma lista, pero devuelve 501 en ambas operaciones.
Un paquete que llevaba una etiqueta de devolución y el paquete que regresa con esa etiqueta se apuntan mutuamente mediante 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.
  • appointments y home_kit_orders solo 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 403 y 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 registra synced_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 el location_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 appointments con entradas { id, added_at };
  • en la cita, como un array shipments con entradas { id, added_at }.
Ambos arrays muestran primero el vínculo más antiguo. Cada 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 mediante PATCH /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.
Los envíos no se pueden modificar una vez que el mensajero ha recogido el paquete. Los intentos de actualizar un envío en estado in_transit, delivered o fault devuelven 409 Conflict.
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 mediante DELETE /api/v1/shipments/{id}. Esto llama a la API del proveedor logístico para cancelar el pedido y actualiza el estado a cancelled.
Los envíos no se pueden cancelar después de la recogida. Los intentos de cancelar un envío que ya está en estado in_transit, delivered o fault devuelven 409 Conflict. Cancelar uno que ya está en cancelled no realiza ninguna acción y devuelve 200 con el envío; consulta Idempotencia.
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 devuelve 409 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 campos origin y destination de la respuesta del envío contienen objetos de dirección resueltos con la siguiente estructura:
Para un paquete de clínica, la dirección 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 campo pickup 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 array status_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. Es null cuando 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 es cancelled: una cancelación es nuestra, no un evento del transportista.
  • code — el código de estado propio del transportista (GO10, GO90, GOY001 de GO!; VA, ZF, LA, ZU de DHL). Es null cuando el transportista no proporciona ninguno. Se mantiene estable independientemente del idioma de status.
  • detail_code — el código más detallado del transportista cuando dispone de él: statusDetailed de DHL, p. ej., CNRFC_NRQRD_ZF (redirigido a una oficina de correos), HLDCC_SERPT_LA (listo para recoger allí), DLVRD_SERPT_ZU (recogido). Es null en 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. Es null cuando 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).
Cuando el transportista devuelve el paquete al remitente, el historial recibe una entrada con 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:
El registro de devolución existe desde el momento en que se imprime la etiqueta de devolución y permanece en pending hasta que el paciente envía la muestra: ese es el estado real, no un vacío.