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

# Zrušit zásilku

> Zrušit objednávku zásilky

Zruš objednávku zásilky. Tím se zavolá API poskytovatele logistiky pro zrušení objednávky a stav zásilky se aktualizuje na `cancelled`.

Zrušení zásilky, která už je `cancelled`, vrátí `200` s touto zásilkou a poskytovatel se zavolá jen jednou. Odpověď obsahuje `Idempotent-Replayed: true`, takže poznáš opakované volání od toho, které akci provedlo. Viz [Idempotence](https://docs.anivahealth.com/cs/concepts/idempotency.md).

> [!WARNING]
>
> Zásilky nelze po vyzvednutí zrušit — vrátí se `409 Conflict`.

Zpáteční štítek DHL nelze zrušit samostatně; i to vrátí `409 Conflict`. Místo toho zruš
odchozí balík. Zrušením odchozího balíku DHL se zruší i jeho řádky zpáteční cesty ve stavu `pending`.
Každý z nich přejde na `cancelled` se záznamem `RETURN_LEG_CANCELLED` v `status_updates`. Viz
[Zpáteční štítky](https://docs.anivahealth.com/cs/concepts/shipments.md#zpetne-stitky).

V krabici s několika sadami má každá sada vlastní odchozí řádek a vlastní zpáteční štítek, i
když krabice cestuje na štítek jedné sady. Zrušením odchozího řádku sady se zruší i její
zpáteční štítek.

Pro zrušení balíku s domácí sadou musí být každá propojená objednávka domácí sady v tvém přístupovém kontextu.
Jinak volání vrátí `403`. Viz [Přístup](https://docs.anivahealth.com/cs/concepts/shipments.md#pristup).

## Požadavek

### Parametry cesty

**id** `string` *required*

Referenční ID zásilky (např. `P2611194821`).

## Odpověď

Při úspěchu API vrátí `200 OK` s objektem zrušené zásilky.

**id** `string` *required*

Referenční identifikátor zásilky.

**status** `string` *required*

Stav životního cyklu zásilky. Po úspěšném zrušení bude `cancelled`.

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

Poskytovatel logistiky. Jedna z hodnot `go`, `dhl_parcel`, `dhl_warenpost`, `rotrunner`, `rapido`,
`ups` nebo `dhl_express`. Balík s domácí sadou je `dhl_parcel`, případně `dhl_warenpost`, když jde do zahraničí
jako Warenpost International.

**tracking\_number** `string`

Externí sledovací číslo od poskytovatele logistiky. Může být `null`.

**contents** `string`

Volný textový popis obsahu balíku zadaný při vytvoření. Může být `null`.

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

Kdo štítek vytiskl: `aniva` nebo `external`. Toto volání přijímají jen zásilky `aniva`.

**paired\_with** `string`

Reference druhého balíku zásilky se dvěma balíky. Pro jednosměrný balík je `null`.

**origin** `object`

Adresa vyzvednutí. Může být `null`.

**objekt adresy**

**name** `string` *required*

Jméno příjemce, název firmy nebo místa.

**company\_name** `string`

Řádek firma / c/o. Může být `null`.

**street** `string` *required*

Název ulice bez čísla domu.

**house\_number** `string`

Číslo domu. Může být `null`.

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

Budova, vchod nebo patro. Může být `null`.

**city** `string` *required*

Město.

**state** `string`

Stát nebo provincie. Může být `null`.

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

PSČ.

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

Kód země podle ISO 3166-1 alpha-2.

**phone** `string`

Kontaktní telefonní číslo. Může být `null`.

**email** `string`

Kontaktní e-mail. Může být `null`.

**destination** `object`

Doručovací adresa. Stejná struktura jako `origin`. Může být `null`.

**pickup** `object`

Naplánované okno vyzvednutí. Může být `null`.

**objekt pickup**

**from** `string` *required*

Začátek okna vyzvednutí jako okamžik v UTC (ISO 8601 s příponou `Z`).

**till** `string` *required*

Konec okna vyzvednutí jako okamžik v UTC (ISO 8601 s příponou `Z`).

**timezone** `string` *required*

Časové pásmo IANA místa vyzvednutí (např. `Europe/Berlin`).

**notes** `string`

Volitelné poznámky. Může být `null`.

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

Chronologické události životního cyklu od poskytovatele logistiky (od nejstarší). Každá položka má
`state`, `code`, `detail_code`, `status`, `description`, `location` a `time`. Jednotlivá pole najdeš v [Získat
zásilku](https://docs.anivahealth.com/cs/api/shipments/get-shipment.md). Prázdné pole, pokud zatím nebyly zaznamenány žádné události.

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

Termíny, které byly k této zásilce přiřazeny před zrušením. Každá položka má tvar
`{ id, added_at }`; každé `id` dohledej přes
[Získat termín](https://docs.anivahealth.com/cs/api/appointments/get-appointment.md).
Uvedeny jsou pouze termíny v tvém přístupovém kontextu.

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

Objednávky domácích sad přiřazené k této zásilce, od nejstaršího přiřazení, ve stejném tvaru `{ id, added_at }`.
Uvedeny jsou pouze objednávky v tvém přístupovém kontextu. Prázdné pole pro balíky z ordinací.

**synced\_at** `string`

Kdy byla zásilka naposledy sladěna s přepravcem, jako okamžik v UTC. `null` až do první
synchronizace.

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

Časové razítko vytvoření (ISO 8601).

**updated\_at** `string`

Časové razítko poslední aktualizace (ISO 8601). Může být `null`.

## Chybové odpovědi

| Stav | Popis |
| - | - |
| `400` | Neplatný formát ID. |
| `403` | Zakázáno — tvůj API klíč nemá k této operaci přístup, zásilka je mimo tvůj přístupový kontext nebo je přiřazená objednávka domácí sady mimo tvůj přístupový kontext. |
| `404` | Zásilka nebyla nalezena. |
| `409` | Zásilku nelze zrušit — už byla vyzvednuta nebo doručena, případně jde o zpáteční štítek DHL (místo toho zruš odchozí balík). |
| `501` | Zásilka má hodnotu `external` — nebyla objednána přes Aniva a nelze ji zde zrušit. |
| `500` | Interní chyba serveru. |
| `502` | Poskytovatel logistiky požadavek zamítl (např. vypršela lhůta pro zrušení). Obsahuje chybovou zprávu poskytovatele. |

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