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

# Cancelar envío

> Cancelar una orden de envío

Cancela una orden de envío. Llama a la API del proveedor logístico para cancelar la orden y actualiza el estado del envío a `cancelled`.

Cancelar un envío que ya está en estado `cancelled` devuelve `200` con ese envío y solo se llama al proveedor una vez. La respuesta incluye `Idempotent-Replayed: true` para que puedas distinguir una repetición de la llamada que realizó la operación. Consulta [Idempotencia](https://docs.anivahealth.com/es/concepts/idempotency.md).

> [!WARNING]
>
> Los envíos no se pueden cancelar después de la recogida: eso devuelve `409 Conflict`.

Una etiqueta de devolución de DHL no puede cancelarse por separado; eso también devuelve `409 Conflict`. En su lugar, cancela el
paquete de ida. Cancelar un paquete de ida de DHL también cancela sus filas de tramo de devolución en estado
`pending`. Cada una pasa a `cancelled` con una entrada `RETURN_LEG_CANCELLED` en `status_updates`. Consulta
[Etiquetas de devolución](https://docs.anivahealth.com/es/concepts/shipments.md#etiquetas-de-devolucion).

En una caja con varios kits, cada kit tiene su propia fila de ida y su propia etiqueta de devolución, incluso
cuando la caja viaja con la etiqueta de uno solo. Cancelar la fila de ida de un kit también cancela la
etiqueta de devolución de ese kit.

Para cancelar un paquete de kit a domicilio, todos los pedidos de kit a domicilio vinculados deben estar en 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`).

## Respuesta

Si la operación tiene éxito, la API devuelve `200 OK` con el objeto del envío cancelado.

**id** `string` *required*

Identificador de referencia del envío.

**status** `string` *required*

Estado del ciclo de vida del envío. Será `cancelled` tras una cancelación correcta.

**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`).

**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 que estaban vinculadas a este envío antes de la cancelación. 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 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` | Formato de ID no válido. |
| `403` | Prohibido: tu clave de 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` | No se puede cancelar el envío: ya se ha recogido o entregado, o es una etiqueta de devolución de DHL (cancela en su lugar el paquete de ida). |
| `501` | El envío es `external`: no se reservó a través de Aniva y no se puede cancelar aquí. |
| `500` | Error interno del servidor. |
| `502` | El proveedor logístico rechazó la solicitud (p. ej., plazo de cancelación superado). Incluye el mensaje de error del proveedor. |

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

```json 200 theme={null}
{
  "id": "P2611194821",
  "status": "cancelled",
  "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": [],
  "appointments": [],
  "home_kit_orders": [],
  "synced_at": "2026-04-03T15:00:00Z",
  "created_at": "2026-04-03T14:30:00Z",
  "updated_at": "2026-04-03T16:45:00Z"
}
```

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

```json 409 (return label) theme={null}
{
  "error": "Shipment K260904P3XD is the return label of K2609041FQ7. DHL cannot cancel a return label on its own. Cancel the outbound parcel while it is pending. After the outbound parcel ships, the label stays valid and Aniva closes this shipment manually."
}
```

```json 403 (Aniva-managed parcel) theme={null}
{
  "error": "Access denied: only Aniva can change this parcel."
}
```

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

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