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

# Actualizar envío

> Modificar los detalles del envío antes de la recogida

Actualiza los detalles del envío, como el horario de recogida, el número de paquetes o las notas. Si cambia algún campo relevante para la logística (fecha de recogida, hora, número de paquetes o peso), la orden logística actual se cancela y se crea una nueva automáticamente. Los campos que omitas se conservan del envío actual. Los campos de horario actualizados se validan según las [reglas de horario de recogida](https://docs.anivahealth.com/es/concepts/shipments.md#reglas-del-horario-de-recogida).

> [!WARNING]
>
> Los envíos no se pueden modificar después de la recogida. Intentar actualizar un envío que ya ha sido
> recogido devuelve `409 Conflict`.

Un paquete de kit de prueba en casa ya tiene la etiqueta impresa, así que solo puede cambiar `notes`. Una nueva franja de recogida
o un nuevo peso en un paquete de kit de prueba en casa devuelve `409 Conflict`; cancélalo y crea un nuevo envío en su lugar.

Para actualizar un paquete de kit de prueba en casa, todos los pedidos de kit de prueba en casa vinculados deben estar dentro de tu contexto de acceso.
De lo contrario, la llamada devuelve `403`. Consulta [Acceso](https://docs.anivahealth.com/es/concepts/shipments.md#acceso).

## Solicitud

### Parámetros de ruta

**id** `string` *required*

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

### Parámetros del cuerpo

Todos los parámetros del cuerpo son opcionales — incluye solo los campos que quieras cambiar.

**pickup\_date** `string`

Nueva fecha de recogida en formato `YYYY-MM-DD`, interpretada en la zona horaria del lugar de origen.

**pickup\_time\_from** `string`

Nueva hora mínima de recogida en formato `HH:MM`, interpretada como hora local en la zona horaria
del lugar de origen.

**pickup\_time\_till** `string`

Nueva hora máxima de recogida en formato `HH:MM`, interpretada como hora local en la zona horaria
del lugar de origen.

**package\_count** `integer`

Nuevo número de paquetes.

**weight** `number`

Nuevo peso en kg.

**notes** `string`

Nuevas notas u observaciones. Máximo 128 caracteres.

## Respuesta

En caso de éxito, la API devuelve `200 OK` con el envío actualizado.

**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. Puede ser `null`.

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

Quién imprimió la etiqueta: `aniva` o `external`. Solo los envíos de `aniva` aceptan esta llamada.

**paired\_with** `string`

Referencia del otro paquete en un envío de dos paquetes. Es `null` para un paquete solo de 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 del proveedor logístico (del más antiguo al más reciente).
Cada entrada tiene `state`, `code`, `detail_code`, `status`, `description`, `location` y `time`.
Consulta [Obtener envío](https://docs.anivahealth.com/es/api/shipments/get-shipment.md) para cada campo. Array vacío si aún no se
han registrado eventos.

**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).
Solo se muestran las citas dentro de tu contexto de acceso.

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

Pedidos de kits a domicilio vinculados a este envío, del vínculo más antiguo al más reciente, con
el mismo formato `{ id, added_at }`. Solo se muestran los pedidos de tu contexto de acceso. Array
vacío para paquetes de consultas.

**synced\_at** `string`

Cuándo se sincronizó por última vez el envío con su transportista, como instante UTC. `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`.

## Respuestas de error

| Estado | Descripción |
| - | - |
| `400` | Error de validación: por ejemplo, formato de fecha u hora no válido. |
| `403` | Prohibido: tu clave API no tiene acceso a esta operación, el envío está fuera de tu contexto de acceso o un pedido de kit a domicilio vinculado está fuera de tu contexto de acceso. |
| `404` | Envío no encontrado. |
| `409` | El envío no se puede modificar después de la recogida, o es un paquete de kit a domicilio cuya etiqueta ya está impresa y la solicitud cambia más que `notes`. |
| `501` | El envío es `external`: no se reservó a través de Aniva y no se puede cambiar aquí. |
| `500` | Error interno del servidor. |
| `502` | El proveedor logístico rechazó la solicitud (por ejemplo, falló la cancelación o la nueva creación). Incluye el mensaje de error del proveedor. |

```bash cURL theme={null}
curl --request PATCH \
  --url https://anivahealth.com/api/v1/shipments/P2611194821 \
  --header 'x-api-key: YOUR_API_KEY' \
  --header 'Content-Type: application/json' \
  --data '{
    "pickup_date": "2026-04-16",
    "pickup_time_from": "10:00",
    "pickup_time_till": "13:00"
  }'
```

```json 200 theme={null}
{
  "id": "P2611194821",
  "status": "pending",
  "logistics_provider": "go",
  "tracking_number": null,
  "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-16T08:00:00Z",
    "till": "2026-04-16T11:00:00Z",
    "timezone": "Europe/Berlin"
  },
  "notes": null,
  "status_updates": [],
  "appointments": [],
  "home_kit_orders": [],
  "synced_at": "2026-04-03T15:00:00Z",
  "created_at": "2026-04-03T14:30:00Z",
  "updated_at": "2026-04-03T15:10:00Z"
}
```

```json 409 theme={null}
{
  "error": "Shipment cannot be modified after pickup"
}
```

```json 502 theme={null}
{
  "error": "Logistics provider error: The cancellation notice period has already been exceeded. Cancellation is no longer possible via the web service. Please contact the GO! station.",
  "logistics_error_code": 4006
}
```


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