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

# Obtener envío

> Recuperar un envío por su ID de referencia

Obtiene un único envío por su ID de referencia. 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` te indica cuándo se consultó al transportista
por última vez.

Requiere el scope `shipments_view` o `shipments_manage`.

## Solicitud

### Parámetros de ruta

**id** `string` *required*

ID de referencia del envío (p. ej., `P2611194821`).

## Respuesta

Si tiene éxito, la API devuelve `200 OK` con el objeto del 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 guarda la respuesta de este endpoint durante 60 minutos por cada clave de API. Una llamada repetida dentro
de este plazo recibe la respuesta guardada mientras el envío no cambie. Tras un cambio, obtienes una respuesta
nueva. Las cabeceras `Cache-Status` y `Age` muestran que la respuesta está
guardada y cuál es su antigüedad.

En una respuesta guardada, `synced_at` y `updated_at` pueden ser más antiguos que en una respuesta nueva.

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` | Formato de ID no válido. |
| `403` | Prohibido: tu clave de API no tiene acceso a esta operación o el envío está fuera de tu contexto de acceso. Un paquete está en tu contexto de acceso cuando al menos una cita o un pedido de kit de prueba en casa vinculado lo está. |
| `404` | Envío no encontrado. |
| `500` | Error interno del servidor. |

```bash cURL theme={null}
curl --request GET \
  --url https://anivahealth.com/api/v1/shipments/P2611194821 \
  --header 'x-api-key: YOUR_API_KEY'
```

```json 200 theme={null}
{
  "id": "P2611194821",
  "status": "in_transit",
  "logistics_provider": "go",
  "tracking_number": "GO123456789",
  "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-03T14:30:00Z",
  "updated_at": "2026-04-15T11:20:00Z"
}
```

```json 404 theme={null}
{
  "error": "Shipment not found"
}
```


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