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

# Luo lähetys

> Luo logistiikan lähetystilaus määritetyllä lähtöpaikalla ja määränpäällä

Luo lähetystilaus määritetystä lähtötoimipisteestä. Määrität kohdelaboratorion kentällä `destination_lab`. Lähetys menee kyseisen laboratorion rekisteröityyn toimitusosoitteeseen.

Vaatii `shipments_manage`-käyttöoikeuden.

Lähetä valinnainen `Idempotency-Key`-otsikko, jotta luontipyynnön voi yrittää turvallisesti uudelleen — saman avaimen toistaminen palauttaa alkuperäisen vastauksen toisen luomisen sijaan. Katso [Idempotenssi](https://docs.anivahealth.com/fi/concepts/idempotency.md).

## Pyyntö

### Runkoparametrit

**location\_id** `string` *required*

Lähtöpaikkana toimivan testitoimipisteen UUID. Toimipisteen on oltava aktiivinen ja API-avaimesi käyttöoikeusalueella.
Löydät käytettävissä olevat toimipistetunnukset kohdasta [Listaa toimipisteet](https://docs.anivahealth.com/fi/api/locations/list-locations.md).

**destination\_lab** `string` *required*

Kohdelaboratorio. Yksi arvoista `zotzklimas`, `labclinic`, `nordicgroup`, `biomes`, `imd` tai
`quade`. Lähetys menee tälle laboratoriolle rekisteröityyn toimitusosoitteeseen. Laboratorio,
jolla ei ole rekisteröityä toimitusosoitetta, palauttaa koodin `400`.

**appointment\_id** `string`

Valinnainen ajanvarauksen UUID, johon tämä lähetys liitetään luontihetkellä. Ajanvarauksen on oltava
API-avaimesi käyttöoikeusalueella. Liitos näkyy suoraan merkintänä lähetyksen
`appointments`-taulukossa ja vastaavasti merkintänä ajanvarauksen `shipments`-taulukossa. Jos haluat liittää
lisää ajanvarauksia luonnin jälkeen tai poistaa alkuperäisen liitoksen, käytä päätepisteitä [Liitä ajanvarauksia
lähetykseen](https://docs.anivahealth.com/fi/api/shipments/attach-appointments-to-shipment.md) ja [Irrota ajanvarauksia
lähetyksestä](https://docs.anivahealth.com/fi/api/shipments/detach-appointments-from-shipment.md).

**pickup\_date** `string` *required*

Noutopäivä muodossa `YYYY-MM-DD` (esim. `2026-04-15`), tulkittuna lähtötoimipisteen
aikavyöhykkeessä. Päivän on oltava arkipäivä (maanantai–perjantai), tänään tai tulevaisuudessa. Saman päivän noudot eivät
ole saatavilla klo 16.00 Europe/Berlin jälkeen.

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

Aikaisin noutoaika muodossa `HH:MM` (esim. `09:00`), tulkittuna paikallisena kellonaikana
lähtötoimipisteen aikavyöhykkeessä. Arvon on oltava välillä `09:00`–`19:00`.

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

Viimeisin noutoaika muodossa `HH:MM` (esim. `12:00`), tulkittuna paikallisena kellonaikana
lähtötoimipisteen aikavyöhykkeessä. Arvon on oltava välillä `09:00`–`19:00`. Aikaikkunan (`pickup_time_till -
    pickup_time_from`) on oltava vähintään 2 tuntia.

**package\_count** `integer` (default: 1)

Pakettien määrä. Oletus on `1`.

**weight** `number` (default: 0.5)

Paino (kg). Oletus on `0.5`.

**pickup\_remarks** `string`

Ohjeet kuriirille noutoa varten (lähettäjän huomautukset). Jos kenttä jätetään pois, käytetään nouto-osoitteeseen
tallennettuja huomautuksia (tai ei mitään, jos osoitteella ei ole niitä). Enintään 128 merkkiä.

**contents** `string`

Vapaamuotoinen kuvaus paketin sisällöstä, joka näytetään kuriirille ja palautetaan kentässä
`contents`. Enintään 40 merkkiä (esim. `Medizinisch freigestellte Probe`).

**notes** `string`

Valinnaiset sisäiset muistiinpanot. Enintään 128 merkkiä.

## Vastaus

Onnistuessaan API palauttaa tilakoodin `201 Created` ja uuden lähetyksen.

**id** `string` *required*

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

**status** `string` *required*

Lähetyksen elinkaaritila. Yksi arvoista `pending`, `in_transit`, `delivered`, `fault` tai `cancelled`.

**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`. Luomasi lähetyksen arvo on `aniva`.

**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`). Käytä tätä kenttien `from` / `till` esittämiseen noutopaikan paikallisessa ajassa.

**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 heti luonnin jälkeen.
Taustasynkronointi lisää tapahtumia sitä mukaa kun palveluntarjoaja ilmoittaa niistä.

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

Tähän lähetykseen liitetyt ajanvaraukset, vanhin liitos ensin. 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).
Sisältää heti luonnin jälkeen mahdollisen `appointment_id`-kentässä annetun ajanvarauksen.

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

Tähän lähetykseen liitetyt kotitestitilaukset samassa `{ id, added_at }` -muodossa. Tyhjä taulukko
luomallesi lähetykselle.

**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` | Validointivirhe – esim. virheellinen päivämäärämuoto, viikonloppupäivä, liian lyhyt noutoaikaikkuna tai saman päivän määräaika umpeutunut. Palautetaan myös, jos `destination_lab`-laboratoriolla tai lähtötoimipisteellä ei ole rekisteröityä osoitetta. |
| `403` | Estetty – API-avaimellasi ei ole oikeutta tähän toimintoon tai toimipiste on käyttöoikeusalueesi ulkopuolella. |
| `404` | Toimipistettä ei löytynyt tai se ei ole aktiivinen, tai `appointment_id` annettiin, mutta ajanvarausta ei ole olemassa. |
| `409` | Otsikkoa `Idempotency-Key` on jo käytetty toisen pyynnön rungon kanssa, tai sen alkuperäinen pyyntö ei ole vielä valmistunut. |
| `500` | Sisäinen palvelinvirhe. |
| `502` | Logistiikkapalveluntarjoaja hylkäsi pyynnön. Sisältää palveluntarjoajan virheilmoituksen. |

```bash cURL theme={null}
curl --request POST \
  --url https://anivahealth.com/api/v1/shipments \
  --header 'x-api-key: YOUR_API_KEY' \
  --header 'Content-Type: application/json' \
  --data '{
    "location_id": "b7e2d1f5-3c4a-4e8b-a2f1-9d0c1e2f3a4b",
    "destination_lab": "labclinic",
    "appointment_id": "c9f3e2a1-7d6b-4c5e-b3a2-1f0e9d8c7b6a",
    "pickup_date": "2026-04-15",
    "pickup_time_from": "09:00",
    "pickup_time_till": "12:00",
    "notes": "Handle with care — temperature-sensitive samples"
  }'
```

```json 201 theme={null}
{
  "id": "P2611194821",
  "status": "pending",
  "logistics_provider": "go",
  "tracking_number": null,
  "contents": null,
  "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": "Handle with care — temperature-sensitive samples",
  "status_updates": [],
  "appointments": [
    {
      "id": "c9f3e2a1-7d6b-4c5e-b3a2-1f0e9d8c7b6a",
      "added_at": "2026-04-15T07:00:00Z"
    }
  ],
  "home_kit_orders": [],
  "synced_at": null,
  "created_at": "2026-04-15T07:00:00Z",
  "updated_at": null
}
```

```json 400 theme={null}
{
  "error": "pickup_date must be a weekday (Monday–Friday)"
}
```

```json 404 theme={null}
{
  "error": "Location not found or inactive"
}
```

```json 502 theme={null}
{
  "error": "Logistics provider error: Pickup on weekend/holiday not possible",
  "logistics_error_code": 2001
}
```


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