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

# Listar envíos

> Recuperar envíos filtrados por cita, pedido de kit a domicilio o estado

Obtén los envíos accesibles para tu clave de API, del más reciente al más antiguo. Todos los paquetes están en esta misma lista:
una recogida por mensajería en una clínica, el kit de camino a un paciente con kit de prueba en casa y la muestra de
vuelta. Filtra por un elemento padre con `appointment_id` o `home_kit_order_id`.

Requiere el scope `shipments_view` o `shipments_manage`.

La respuesta procede de nuestra base de datos y nunca llama al transportista. Una sincronización en segundo plano actualiza cada
envío (cada 10 minutos para GO! y cada hora para DHL), y `synced_at` en cada fila te indica cuándo se consultó
al transportista por última vez.

## Solicitud

### Parámetros de consulta

**appointment\_id** `string`

Solo los envíos vinculados a esta cita (UUID). `404` cuando la cita no existe, `403`
cuando está fuera de tu contexto de acceso.

**home\_kit\_order\_id** `string`

Solo los envíos vinculados a este pedido de kit de prueba en casa (UUID). Normalmente se devuelven dos filas: el kit de
camino al paciente y la muestra de vuelta al laboratorio (su `destination` es el laboratorio). Mismas
reglas de `404` / `403` que para `appointment_id`.

**status** `string`

Solo los envíos en este estado. Uno de `pending`, `in_transit`, `delivered`, `fault`, `cancelled`.

**limit** `integer`

Número máximo de envíos que se devuelven. Por defecto 100, máximo 500.

**offset** `integer`

Número de envíos que se omiten. Por defecto 0. El orden es estable (`created_at` descendente y luego
referencia), por lo que las páginas no se solapan.

## Respuesta

En caso de éxito, la API devuelve `200 OK` con un array de objetos de envío.

**id** `string` *required*

Identificador de referencia del envío.

**status** `string` *required*

Estado del ciclo de vida del envío. Uno de `pending`, `in_transit`, `delivered`, `fault` o `cancelled`.

**logistics\_provider** `string` *required*

Proveedor logístico. Puede ser `go`, `dhl_parcel`, `dhl_warenpost`, `rotrunner`, `rapido`,
`ups` o `dhl_express`. Un paquete de kit a domicilio es `dhl_parcel`, o `dhl_warenpost` cuando se envía al extranjero
como Warenpost International.

**tracking\_number** `string`

Número de seguimiento externo del proveedor logístico. Puede ser `null`.

**contents** `string`

Descripción en texto libre del contenido del paquete, tal como se indicó al crearlo (p. ej.,
`"Medizinisch
    freigestellte Probe"`, `"Home test kit"`). Solo informativo: si un paquete va dirigido a un
laboratorio se consulta en `destination`, y su envío asociado en `paired_with`. Puede ser `null`.

**booked\_by** `string` *required*

Quién imprimió la etiqueta: `aniva` o `external`. Solo los envíos `aniva` admiten
[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` tiene seguimiento, pero devuelve `501` en ambos casos.

**paired\_with** `string`

Referencia del otro paquete de una expedición de dos paquetes: el paquete que llevaba una
etiqueta de devolución y el paquete que vuelve con esa etiqueta. Definido en ambos. `null` para un paquete de solo ida.

**origin** `object`

Dirección de recogida. Puede ser `null`.

**objeto de dirección**

**name** `string` *required*

Nombre del destinatario, la empresa o la ubicación.

**company\_name** `string`

Línea de empresa / a la atención de. Puede ser `null`.

**street** `string` *required*

Nombre de la calle, sin el número.

**house\_number** `string`

Número de portal. Puede ser `null`.

**address\_line\_2** `string`

Edificio, entrada o planta. Puede ser `null`.

**city** `string` *required*

Ciudad.

**state** `string`

Estado o provincia. Puede ser `null`.

**postal\_code** `string` *required*

Código postal.

**country\_code** `string` *required*

Código de país ISO 3166-1 alfa-2.

**phone** `string`

Teléfono de contacto. Puede ser `null`.

**email** `string`

Correo electrónico de contacto. Puede ser `null`.

**destination** `object`

Dirección de entrega. Misma estructura que `origin`. Puede ser `null`.

**pickup** `object`

Franja de recogida programada. Puede ser `null`.

**Objeto pickup**

**from** `string` *required*

Inicio de la franja de recogida como instante UTC (ISO 8601 con sufijo `Z`).

**till** `string` *required*

Fin de la franja de recogida como instante UTC (ISO 8601 con sufijo `Z`).

**timezone** `string` *required*

Zona horaria IANA del lugar de recogida (p. ej., `Europe/Berlin`). Úsala para mostrar `from` / `till` en la hora local del lugar de recogida.

**notes** `string`

Notas opcionales. Puede ser `null`.

**status\_updates** `object[]` *required*

Eventos cronológicos del ciclo de vida procedentes del proveedor logístico (del más antiguo al más reciente). Array vacío si el
proveedor aún no ha comunicado ningún evento. Úsalo para la interfaz por evento, auditorías y las señales más detalladas del transportista;
básate en `status` para el estado actual canónico.

**campos de actualización de estado**

**state** `string | null` *required*

El evento en el vocabulario de estados del envío —`pending`, `in_transit`, `delivered` o
`fault`—, para que puedas leer una cronología sin conocer los códigos del transportista. `null` cuando el
evento no lleva estado (creación de la etiqueta, un escaneo sin información del transportista, registros guardados
antes de que existiera este campo). Nunca `cancelled`.

**code** `string | null` *required*

El código de estado propio del transportista: `GO10` / `GO90` / `GOY001` en GO!, `VA` / `ZF` / `LA`
/ `ZU` en DHL. `null` cuando el transportista no proporcionó ninguno. Estable entre las traducciones de
`status` a distintos idiomas.

**detail\_code** `string | null` *required*

El código más detallado del transportista cuando dispone de uno: el `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). `null` en transportistas que no lo tienen.

**status** `string` *required*

Etiqueta de estado proporcionada por el proveedor (texto libre, p. ej., `"Shipment picked up"`,
`"Die Sendung wurde abgeholt."`).

**description** `string | null` *required*

Una explicación del código o la frase más larga del transportista. `null` cuando no existe ninguna de las dos.

**location** `string | null` *required*

Dónde se produjo el escaneo, tal como lo nombra el transportista: un centro de GO! (`"HUB Niederaula"`) o una
ciudad de DHL. Texto libre, no una coordenada. `null` cuando el transportista no lo comunicó.

**time** `string` *required*

Hora en la que se observó el evento (ISO 8601, con el desfase horario comunicado por el transportista).

**appointments** `ShipmentAppointmentLink[]` *required*

Citas vinculadas a este envío, empezando por el vínculo más antiguo. Cada entrada es `{ id, added_at }`;
consulta cada `id` en [Obtener cita](https://docs.anivahealth.com/es/api/appointments/get-appointment.md) para obtener los
datos completos de la cita. Array vacío cuando no hay citas vinculadas.
Solo se muestran las citas dentro de tu contexto de acceso.

**home\_kit\_orders** `ShipmentHomeKitOrderLink[]` *required*

Pedidos de kit de prueba en casa vinculados a este envío, empezando por el vínculo más antiguo, con la misma estructura `{ id, added_at }`.
Consulta cada `id` en [Obtener pedido de kit de prueba en casa](https://docs.anivahealth.com/es/api/home-kit-orders/get-home-kit.md). Array
vacío para paquetes de clínicas. Solo se muestran los pedidos dentro de tu contexto de acceso. Consulta
[Acceso](https://docs.anivahealth.com/es/concepts/shipments.md#acceso).

**synced\_at** `string`

Cuándo se contrastó por última vez el envío con su transportista, como instante UTC. Las lecturas nunca llaman al
transportista —una sincronización en segundo plano mantiene actualizados los envíos—, así que esto indica la antigüedad de la respuesta. `null` hasta
la primera sincronización.

**created\_at** `string` *required*

Marca de tiempo de creación (ISO 8601).

**updated\_at** `string`

Marca de tiempo de la última actualización (ISO 8601). Puede ser `null`.

## Llamadas repetidas

Aniva almacena la respuesta de este endpoint durante 5 minutos para cada clave de API. Una llamada repetida dentro
de este plazo obtiene la respuesta almacenada. Las cabeceras `Cache-Status` y `Age` indican que la respuesta está
almacenada y cuál es su antigüedad.

Para enterarte de un cambio al instante, suscríbete a los eventos de webhook `shipment.created` y `shipment.updated`.
Consulta [Lecturas repetidas](https://docs.anivahealth.com/es/concepts/webhooks.md#lecturas-repetidas).

## Respuestas de error

| Estado | Descripción |
| - | - |
| `400` | Parámetro de consulta no válido. |
| `403` | Prohibido: falta un scope o la cita / el pedido de kit de prueba en casa filtrado está fuera de tu alcance. |
| `404` | No se encontró la cita o el pedido de kit de prueba en casa filtrado. |
| `500` | Error interno del servidor. |

```bash cURL (all shipments, first page) theme={null}
curl --request GET \
  --url 'https://anivahealth.com/api/v1/shipments?limit=100&offset=0' \
  --header 'x-api-key: YOUR_API_KEY'
```

```bash cURL (one home-kit order) theme={null}
curl --request GET \
  --url 'https://anivahealth.com/api/v1/shipments?home_kit_order_id=d1e2f3a4-5b6c-4d7e-8f9a-0b1c2d3e4f5a' \
  --header 'x-api-key: YOUR_API_KEY'
```

```bash cURL (one appointment, in transit) theme={null}
curl --request GET \
  --url 'https://anivahealth.com/api/v1/shipments?appointment_id=c9f3e2a1-7d6b-4c5e-b3a2-1f0e9d8c7b6a&status=in_transit' \
  --header 'x-api-key: YOUR_API_KEY'
```

```json 200 theme={null}
[
  {
    "id": "P2611194821",
    "status": "in_transit",
    "logistics_provider": "go",
    "tracking_number": "GO1234567890",
    "contents": "Medizinisch freigestellte Probe",
    "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": null,
    "status_updates": [
      {
        "state": "in_transit",
        "code": "GO10",
        "detail_code": null,
        "status": "Shipment picked up",
        "description": "Picked up at the consignor",
        "location": "Berlin",
        "time": "2026-04-15T09:22:00+02:00"
      },
      {
        "state": "in_transit",
        "code": "GO50",
        "detail_code": null,
        "status": "Receiving station",
        "description": null,
        "location": "HUB Niederaula",
        "time": "2026-04-15T11:18:00+02:00"
      }
    ],
    "appointments": [
      {
        "id": "c9f3e2a1-7d6b-4c5e-b3a2-1f0e9d8c7b6a",
        "added_at": "2026-04-15T08:30:00Z"
      }
    ],
    "home_kit_orders": [],
    "synced_at": "2026-04-15T11:20:00Z",
    "created_at": "2026-04-14T16:00:00Z",
    "updated_at": "2026-04-15T11:20:00Z"
  }
]
```


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