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

# Peruuta lähetys

> Peruuta lähetystilaus

Peru lähetystilaus. Tämä kutsuu logistiikkapalveluntarjoajan API:a tilauksen perumiseksi ja päivittää lähetyksen tilaksi `cancelled`.

Jo `cancelled`-tilassa olevan lähetyksen peruminen palauttaa `200` ja kyseisen lähetyksen, ja palveluntarjoajaa kutsutaan vain kerran. Vastauksessa on `Idempotent-Replayed: true`, jotta voit erottaa toiston varsinaisen työn tehneestä kutsusta. Katso [Idempotenssi](https://docs.anivahealth.com/fi/concepts/idempotency.md).

> [!WARNING]
>
> Lähetyksiä ei voi perua noudon jälkeen — tämä palauttaa `409 Conflict`.

DHL-palautustarraa ei voi perua erikseen; myös se palauttaa `409 Conflict`. Peru sen sijaan
lähtevä paketti. Lähtevän DHL-paketin peruminen peruu myös sen `pending`-tilassa olevat paluumatkan
rivit. Jokaisen tilaksi tulee `cancelled`, ja `status_updates`-kenttään lisätään merkintä `RETURN_LEG_CANCELLED`. Katso
[Palautustarrat](https://docs.anivahealth.com/fi/concepts/shipments.md#palautustarrat).

Laatikossa, jossa on useita pakkauksia, jokaisella pakkauksella on oma lähtevä rivinsä ja oma palautustarransa, vaikka
laatikko kulkee yhden pakkauksen tarralla. Pakkauksen lähtevän rivin peruminen peruu myös kyseisen pakkauksen
palautustarran.

Kotitestipaketin lähetyksen perumiseksi jokaisen linkitetyn kotitestipakettitilauksen on oltava pääsykontekstissasi.
Muuten kutsu palauttaa `403`. Katso [Pääsyoikeudet](https://docs.anivahealth.com/fi/concepts/shipments.md#kaeyttoeoikeudet).

## Pyyntö

### Polkuparametrit

**id** `string` *required*

Lähetyksen viitetunnus (esim. `P2611194821`).

## Vastaus

Onnistuessaan API palauttaa `200 OK` ja perutun lähetysobjektin.

**id** `string` *required*

Lähetyksen viitetunniste.

**status** `string` *required*

Lähetyksen elinkaaren tila. On `cancelled` onnistuneen perumisen jälkeen.

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

Logistiikkapalveluntarjoaja. Yksi arvoista `go`, `dhl_parcel`, `dhl_warenpost`, `rotrunner`, `rapido`,
`ups` tai `dhl_express`. Kotitestipaketin lähetys on `dhl_parcel`, tai `dhl_warenpost`, kun se lähetetään ulkomaille
Warenpost International -lähetyksenä.

**tracking\_number** `string`

Logistiikkapalveluntarjoajan ulkoinen seurantanumero. Voi olla `null`.

**contents** `string`

Vapaamuotoinen kuvaus paketin sisällöstä sellaisena kuin se annettiin luotaessa. Voi olla `null`.

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

Kuka tulosti lähetystarran: `aniva` tai `external`. Vain `aniva`-lähetykset hyväksyvät tämän kutsun.

**paired\_with** `string`

Kahden paketin lähetyksen toisen paketin viite. `null` yhdensuuntaiselle paketille.

**origin** `object`

Nouto-osoite. Voi olla `null`.

**osoiteobjekti**

**name** `string` *required*

Vastaanottajan, yrityksen tai toimipisteen nimi.

**company\_name** `string`

Yritys / c/o-rivi. Voi olla `null`.

**street** `string` *required*

Kadunnimi ilman talon numeroa.

**house\_number** `string`

Talon numero. Voi olla `null`.

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

Rakennus, porras tai kerros. Voi olla `null`.

**city** `string` *required*

Kaupunki.

**state** `string`

Osavaltio tai maakunta. Voi olla `null`.

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

Postinumero.

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

ISO 3166-1 alpha-2 -maakoodi.

**phone** `string`

Yhteyspuhelinnumero. Voi olla `null`.

**email** `string`

Yhteyssähköposti. Voi olla `null`.

**destination** `object`

Toimitusosoite. Sama rakenne kuin kentässä `origin`. Voi olla `null`.

**pickup** `object`

Ajoitettu noutoaikaikkuna. Voi olla `null`.

**pickup-objekti**

**from** `string` *required*

Noutoaikaikkunan alku UTC-ajankohtana (ISO 8601 ja `Z`-pääte).

**till** `string` *required*

Noutoaikaikkunan loppu UTC-ajankohtana (ISO 8601 ja `Z`-pääte).

**timezone** `string` *required*

Noutopaikan IANA-aikavyöhyke (esim. `Europe/Berlin`).

**notes** `string`

Valinnaiset muistiinpanot. Voi olla `null`.

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

Logistiikkapalveluntarjoajan elinkaaritapahtumat aikajärjestyksessä (vanhin ensin). Jokaisessa merkinnässä on
`state`, `code`, `detail_code`, `status`, `description`, `location` ja `time`. Katso kenttien kuvaukset kohdasta [Hae
lähetys](https://docs.anivahealth.com/fi/api/shipments/get-shipment.md). Tyhjä taulukko, jos tapahtumia ei ole vielä havaittu.

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

Ajanvaraukset, jotka oli liitetty tähän lähetykseen ennen peruutusta. Jokainen merkintä on muodossa
`{ id, added_at }`; tarkista kunkin `id`-arvon tiedot päätepisteestä
[Hae ajanvaraus](https://docs.anivahealth.com/fi/api/appointments/get-appointment.md).
Vain käyttöoikeusalueeseesi kuuluvat ajanvaraukset listataan.

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

Tähän lähetykseen liitetyt kotitestitilaukset, vanhin liitos ensin, samassa `{ id, added_at }` -muodossa.
Vain käyttöoikeusalueeseesi kuuluvat tilaukset listataan. Tyhjä taulukko vastaanottojen paketeille.

**synced\_at** `string`

Milloin lähetys täsmäytettiin viimeksi kuljetusyhtiön kanssa (UTC-ajankohta). `null` ensimmäiseen
synkronointiin asti.

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

Luontiaikaleima (ISO 8601).

**updated\_at** `string`

Viimeisimmän päivityksen aikaleima (ISO 8601). Voi olla `null`.

## Virhevastaukset

| Tila | Kuvaus |
| - | - |
| `400` | Virheellinen ID-muoto. |
| `403` | Estetty – API-avaimellasi ei ole oikeutta tähän toimintoon, lähetys on käyttöoikeusalueesi ulkopuolella tai siihen liitetty kotitestitilaus on käyttöoikeusalueesi ulkopuolella. |
| `404` | Lähetystä ei löytynyt. |
| `409` | Lähetystä ei voi peruuttaa – se on jo noudettu tai toimitettu, tai se on DHL-palautustarra (peruuta sen sijaan lähtevä paketti). |
| `501` | Lähetys on `external` – sitä ei ole varattu Anivan kautta, eikä sitä voi peruuttaa täällä. |
| `500` | Sisäinen palvelinvirhe. |
| `502` | Logistiikkapalveluntarjoaja hylkäsi pyynnön (esim. peruutuksen määräaika on umpeutunut). Sisältää palveluntarjoajan virheilmoituksen. |

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