> ## Documentation Index
> Fetch the complete documentation index at: https://docs.anivahealth.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Envíos

> Cómo funciona la logística en la API de Aniva: envíos de muestras al laboratorio y paquetes de kits de prueba en casa, con seguimiento y estado.

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](https://docs.anivahealth.com/es/api/shipments/get-shipment.md) 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](https://docs.anivahealth.com/es/api/shipments/update-shipment.md) y [Cancelar](https://docs.anivahealth.com/es/api/shipments/cancel-shipment.md); 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](https://docs.anivahealth.com/es/api/shipments/update-shipment.md), [Cancelar](https://docs.anivahealth.com/es/api/shipments/cancel-shipment.md), [Vincular citas](https://docs.anivahealth.com/es/api/shipments/attach-appointments-to-shipment.md) y [Desvincular citas](https://docs.anivahealth.com/es/api/shipments/detach-appointments-from-shipment.md) 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](https://docs.anivahealth.com/es/api/locations/list-locations.md) 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](https://docs.anivahealth.com/es/api/appointments/get-appointment.md) /
[Obtener envío](https://docs.anivahealth.com/es/api/shipments/get-shipment.md)) 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](https://docs.anivahealth.com/es/api/shipments/attach-appointments-to-shipment.md) /
[Desvincular citas del envío](https://docs.anivahealth.com/es/api/shipments/detach-appointments-from-shipment.md). 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:

```text theme={null}
pending → in_transit → delivered
              ↓
            fault
    ↓
 cancelled
```

| Estado | Significado |
| - | - |
| `pending` | El pedido de mensajería se ha realizado y está pendiente de recogida. |
| `in_transit` | El mensajero ha recogido el paquete y está en tránsito. |
| `delivered` | El paquete se ha entregado. |
| `fault` | Ha ocurrido un problema durante el tránsito o el transportista ha devuelto el paquete al remitente. |
| `cancelled` | El envío se ha cancelado. |

Cada cambio de estado envía un [webhook](https://docs.anivahealth.com/es/concepts/webhooks.md) `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.

| Regla | Detalle |
| - | - |
| **Solo días laborables** | `pickup_date` debe ser de lunes a viernes. |
| **Hoy o en el futuro** | `pickup_date` no puede estar en el pasado. |
| **Hora límite el mismo día** | Las recogidas para el mismo día se rechazan después de las 16:00 Europe/Berlin. |
| **Rango de la franja** | `pickup_time_from` y `pickup_time_till` deben estar entre las 09:00 y las 19:00. |
| **Franja mínima de 2 h** | La franja de recogida debe durar al menos 2 horas. |

## 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](#reglas-del-horario-de-recogida).

> [!WARNING]
>
> 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`.

> [!WARNING]
>
> 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](https://docs.anivahealth.com/es/concepts/idempotency.md).

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:

| Letra | Envío |
| - | - |
| `P` | Un envío que creas a través de esta API. |
| `M` | Un envío que crea el equipo de Aniva. |
| `C` | Un envío de la expedición diaria de Aniva. |
| `K` | Un paquete de kit a domicilio. |
| `F`, `S` | Paquetes de stock propios de Aniva. |

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:

```json theme={null}
{
  "name": "Aniva Berlin Mitte",
  "company_name": null,
  "street": "Unter den Linden",
  "house_number": "42",
  "address_line_2": null,
  "postal_code": "10117",
  "city": "Berlin",
  "state": null,
  "country_code": "DE",
  "phone": "+4930987654321",
  "email": "berlin-mitte@anivahealth.com"
}
```

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

```json theme={null}
{
  "id": "P2611194821",
  "status": "pending",
  "logistics_provider": "go",
  "tracking_number": null,
  "contents": null,
  "booked_by": "aniva",
  "paired_with": null,
  "origin": {
    "name": "Aniva Berlin Mitte",
    "company_name": null,
    "street": "Unter den Linden",
    "house_number": "42",
    "address_line_2": null,
    "postal_code": "10117",
    "city": "Berlin",
    "state": null,
    "country_code": "DE",
    "phone": "+4930987654321",
    "email": "berlin-mitte@anivahealth.com"
  },
  "destination": {
    "name": "LabClinic GmbH",
    "company_name": null,
    "street": "Laborstraße",
    "house_number": "10",
    "address_line_2": null,
    "postal_code": "80331",
    "city": "München",
    "state": null,
    "country_code": "DE",
    "phone": null,
    "email": null
  },
  "pickup": {
    "from": "2026-04-15T07:00:00Z",
    "till": "2026-04-15T10:00:00Z",
    "timezone": "Europe/Berlin"
  },
  "notes": "Handle with care — temperature-sensitive samples",
  "status_updates": [],
  "appointments": [
    {
      "id": "c9f3e2a1-7d6b-4c5e-b3a2-1f0e9d8c7b6a",
      "added_at": "2026-04-03T14:30:00Z"
    }
  ],
  "home_kit_orders": [],
  "synced_at": null,
  "created_at": "2026-04-03T14:30:00Z",
  "updated_at": null
}
```

## 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:

```json theme={null}
[
  {
    "id": "K2609041FQ7",
    "status": "in_transit",
    "logistics_provider": "dhl_parcel",
    "tracking_number": "00340434779457841299",
    "contents": "Home test kit",
    "booked_by": "aniva",
    "paired_with": "K260904P3XD",
    "origin": { "name": "Aniva Health", "street": "Wilhelmstraße", "house_number": "118", "postal_code": "10963", "city": "Berlin", "country_code": "DE", "company_name": null, "address_line_2": null, "state": null, "phone": null, "email": null },
    "destination": { "name": "Jane Doe", "street": "Friedrichstraße", "house_number": "123", "postal_code": "10117", "city": "Berlin", "country_code": "DE", "company_name": null, "address_line_2": null, "state": null, "phone": null, "email": null },
    "pickup": null,
    "notes": null,
    "status_updates": [
      {
        "state": "pending",
        "code": "VA",
        "detail_code": "PARCV_NRQRD_VA",
        "status": "Die Auftragsdaten zu dieser Sendung wurden vom Absender elektronisch an DHL übermittelt.",
        "description": "Electronic advice from DHL — not a parcel scan",
        "location": null,
        "time": "2026-09-02T18:17:00+02:00"
      },
      {
        "state": "in_transit",
        "code": "ES",
        "detail_code": "SHRCU_SERPT_ES",
        "status": "Die Sendung wurde in der Filiale eingeliefert.",
        "description": "Shipment in transit",
        "location": "Berlin",
        "time": "2026-09-04T18:13:00+02:00"
      }
    ],
    "appointments": [],
    "home_kit_orders": [{ "id": "d1e2f3a4-5b6c-4d7e-8f9a-0b1c2d3e4f5a", "added_at": "2026-09-02T18:20:00Z" }],
    "synced_at": "2026-09-05T10:00:00Z",
    "created_at": "2026-09-02T18:20:00Z",
    "updated_at": "2026-09-05T10:00:00Z"
  },
  {
    "id": "K260904P3XD",
    "status": "pending",
    "logistics_provider": "dhl_parcel",
    "tracking_number": "00340434850359000004",
    "contents": "Sample return to lab",
    "booked_by": "aniva",
    "paired_with": "K2609041FQ7",
    "origin": { "name": "Jane Doe", "street": "Friedrichstraße", "house_number": "123", "postal_code": "10117", "city": "Berlin", "country_code": "DE", "company_name": null, "address_line_2": null, "state": null, "phone": null, "email": null },
    "destination": { "name": "Labor Quade", "street": "Laborstraße", "house_number": "10", "postal_code": "50667", "city": "Köln", "country_code": "DE", "company_name": null, "address_line_2": null, "state": null, "phone": null, "email": null },
    "pickup": null,
    "notes": null,
    "status_updates": [],
    "appointments": [],
    "home_kit_orders": [{ "id": "d1e2f3a4-5b6c-4d7e-8f9a-0b1c2d3e4f5a", "added_at": "2026-09-02T18:20:00Z" }],
    "synced_at": "2026-09-05T10:00:00Z",
    "created_at": "2026-09-02T18:20:00Z",
    "updated_at": null
  }
]
```

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.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.