> ## 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 kotitestipakkauksen tilaus

> Tilaa kotiin postitettava kotitestipakkaus profiilille

Pyydä kotitestipakkauksen tilausta potilasprofiilille. Kotitestipakkauksen tilauksella lähetetään kotiin postitettava itsetestipakkaus — Aniva lähettää pakkauksen toimitusosoitteeseen, potilas ottaa näytteen itse kotona ja postittaa sen takaisin. Tämä eroaa [ajanvarauksesta](https://docs.anivahealth.com/fi/api/appointments/create-appointment.md), joka on laskimoverinäytteenotto testauspaikassa.

**Tasan yksi paneeli vaaditaan.** Kotitestipakkaus vastaa 1:1 fyysistä pakkaustuotetta — paneeli on pakkaus — ja tilaus siirtyy pakkausjonoon heti luonnin jälkeen, joten sisällön on oltava lopullinen jo alussa. Voit silti vaihtaa paneelin kutsulla [Päivitä kotitestipakkauksen tilaus](https://docs.anivahealth.com/fi/api/home-kit-orders/update-home-kit.md), kun tilaus on tilassa `pending`.

## Korvaavat pakkaukset

Kun pakkauksesta ei saada tuloksia — potilas ei saanut putkea täyteen, näyte saapui liian pienellä näytemäärällä tai laboratorio ei pystynyt analysoimaan sitä — tilaa **korvaava pakkaus** lähettämällä `replaces_home_kit_order_id`.

Korvaava pakkaus on uusi tilaus uudella laboratoriokoodilla, myös silloin kun ensimmäistä pakkausta ei koskaan aktivoitu: laboratorio tarvitsee uuden lähetteen, eikä kahta samalla koodilla olevaa näytettä voi erottaa toisistaan. Korvattavaan tilaukseen ei kosketa — se säilyttää oman tilansa, oman laboratoriokoodinsa ja kaikki sille jo kirjatut tulokset.

Tästä seuraa kaksi asiaa:

* **Paneeli periytyy.** Jätä `panel_id` pois, jolloin korvaava tilaus saa korvattavan tilauksen paneelin, joka vastaa potilaan ostamaa tuotetta ja pakkauksen brändäystä.
* **Sinä valitset, mitä analysoidaan uudelleen.** Lähetä epäonnistuneet biomarkkerit kentässä `biomarker_ids`, niin laboratorio analysoi vain ne uudelleen ja pakkaus sisältää vain niihin tarvittavat putket. Jätä kenttä pois, jos haluat analysoida koko paneelin uudelleen.

Biomarkkerit analysoidaan uudelleen paneelin ryhminä, ei yksitellen. Yhdenkin ryhmään kuuluvan biomarkkerin nimeäminen johtaa koko ryhmän uudelleenanalysointiin, koska laboratoriolle ei voi tehdä tilausta, joka raportoi enemmän kuin pyydettiin. Yhden biomarkkerin korvaava tilaus voi siksi tuottaa useamman kuin yhden tuloksen, ja sen putkimäärä voi olla suurempi kuin biomarkkeriluettelo antaa ymmärtää.

Kustakin pakkauksesta voi olla matkalla vain yksi korvaava pakkaus kerrallaan.

> [!NOTE]
>
> Jos teit integraation ennen näiden kenttien julkaisua, Aniva lukee tilausta luotaessa myös kentät
> `metadata.original_kit_id` ja `metadata.replacement_reason` ja käsittelee tilauksen korvaavana.
> Tämä on ainoa paikka, jossa metatietoja tulkitaan; se on olemassa vain aiemman integraation
> tukemiseksi, ja yllä olevat kentät menevät aina edelle. Lähetä nämä kentät.

Vastaus `201` tarkoittaa, että tilaus on vahvistettu ja siirtyy toimitukseen — sinun ei tarvitse tehdä mitään muuta, jotta pakkaus pakataan ja lähetetään.

Vaatii `home_kit_orders_manage`-laajuuden.

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

**profile\_id** `string` *required*

Potilasprofiilin UUID, jolle kotitestipakkauksen tilaus luodaan.

**panel\_id** `string` *required*

Valikoimasta tilattavan paneelin UUID. Tasan yksi — kotitestipakkaus vastaa 1:1 fyysistä
pakkaustuotetta, joten paneeli on pakkaus. Aniva toimittaa paneelitunnukset kumppanitilillesi;
katso [Listaa paneelit](https://docs.anivahealth.com/fi/api/panels/list-panels.md). Valinnainen korvaavassa tilauksessa, jolloin
oletuksena käytetään korvattavan tilauksen paneelia.

**replaces\_home\_kit\_order\_id** `string`

Korvattavan kotitestipakkauksen tilauksen UUID. Tämän lähettäminen tekee tilauksesta korvaavan
pakkauksen — katso [Korvaavat pakkaukset](#korvaavat-pakkaukset) yllä. Tilauksen on kuuluttava samalle
profiilille, eikä sille saa jo olla korvaavaa pakkausta matkalla.

**replacement\_reason** `string`

Syy korvaavan pakkauksen tarpeelle yhdellä lauseella (esimerkiksi `Zu wenig Material, HbA1c nicht
    auswertbar`). Pakollinen, kun lähetät kentän `replaces_home_kit_order_id`, ja muuten ohitetaan.
Enintään 500 merkkiä.

**biomarker\_ids** `integer[]`

Korvaavassa tilauksessa biomarkkerit, jotka laboratorio analysoi uudelleen — tavallisesti ne,
joita ensimmäisellä pakkauksella ei saatu. Jokaisen on kuuluttava korvattavan tilauksen
pyytämiin biomarkkereihin; tarkista ne kutsulla [Listaa biomarkkerit](https://docs.anivahealth.com/fi/api/biomarkers/list-biomarkers.md)
parametrilla `home_kit=true`. Jätä pois, jos haluat analysoida koko paneelin uudelleen.
Hyväksytään vain yhdessä kentän `replaces_home_kit_order_id` kanssa, eikä yhdessä eri
`panel_id`-arvon kanssa. Tämä ei vaadi lisäkäyttöoikeutta: potilaan jo maksamien biomarkkerien
uudelleenanalysointi ei ole erillinen yksittäisvalinta.

**metadata** `object`

Omat avain–arvo-parisi, jotka palautetaan sellaisinaan jokaisella lukukerralla ja joita Aniva ei
koskaan tulkitse. Käytä kenttää oman tilausviitteesi välittämiseen, jotta voit yhdistää tiedot
tallentamatta tunnuksiamme. Enintään 20 avainta; avaimet noudattavat mallia `[A-Za-z0-9_-]` ja
ovat enintään 40 merkkiä pitkiä; arvot ovat merkkijonoja, lukuja tai totuusarvoja, joista
merkkijonot ovat enintään 500 merkkiä; yhteensä enintään 16 384 tavua sarjoitettuna.
Etuliitteellä `aniva_` alkavat avaimet on varattu. Älä koskaan tallenna henkilö- tai kliinisiä
tietoja kenttään `metadata` — sitä ei käsitellä potilastietona.

**results\_ready\_emails** `string[]`

Enintään 5 osoitetta, joista kukin saa yhden sähköpostin, kun kaikki laboratoriotulokset ovat
valmiit. Sähköpostissa on linkki tulossivulle Anivan hallintapaneelissa. Avaimesi tarvitsee
`results_view`-oikeuden potilaaseen, muutoin palautetaan `403`. Jätä kenttä pois, jos haluat
käyttää potilaan ryhmälle asetettuja oletusosoitteita. Tyhjä lista poistaa sähköpostit käytöstä.
Katso [Sähköpostit valmiista tuloksista](https://docs.anivahealth.com/fi/concepts/results.md#saehkoepostit-tulosten-valmistumisesta).

**delivery\_address** `object` *required*

Osoite, johon pakkaus postitetaan — jompikumpi kahdesta muodosta: joko `{ location_id }`, joka viittaa tunnettuun testauspaikkaan, tai suorat osoitekentät (`name`, `street`, `city`, `postal_code`, `country_code`; `company_name` / `house_number` / `address_line_2` / `state` / `phone` / `email` valinnaisia — sama sanasto kuin locations-rajapinnassa). Anna tasan yksi — sijaintiviite tai suora osoite, älä molempia.

**toimitusosoite**

> [tab] Viittaa sijaintiin
>
> **location\_id** `string` *required*
>
> Tunnetun testauspaikan UUID, johon pakkaus lähetetään. Tarkista vastaavuus kutsulla [Listaa
> sijainnit](https://docs.anivahealth.com/fi/api/locations/list-locations.md).

> [tab] Suora osoite
>
> **name** `string` *required*
>
> Vastaanottajan, yrityksen tai sijainnin nimi.
>
> **company\_name** `string`
>
> Yritys, joka ottaa paketin vastaan vastaanottajan puolesta — `c/o`-taho tai osasto.
>
> **street** `string` *required*
>
> Kadunnimi ilman talonnumeroa (esim. `Wilhelmstraße`).
>
> **house\_number** `string`
>
> Talonnumero (esim. `118` tai `12a`).
>
> **address\_line\_2** `string`
>
> Rakennus, sisäänkäynti tai kerros.
>
> **city** `string` *required*
>
> **state** `string`
>
> Osavaltio tai maakunta. Valinnainen.
>
> **postal\_code** `string` *required*
>
> Postinumero. Saksalainen osoite (`country_code` `DE`) vaatii tasan 5 numeroa, esim. `10117`.
>
> **country\_code** `string` *required*
>
> ISO 3166-1 alpha-2 -koodi (kaksi kirjainta, esim. `DE`). Pienet kirjaimet hyväksytään ja
> tallennetaan isoina.
>
> **phone** `string`
>
> Vastaanottajan puhelinnumero maatunnuksella (esim. `+4791234567`). Kuljetusyhtiö ilmoittaa
> sen avulla vastaanottajalle paketista, esimerkiksi että se odottaa noutopisteessä. Jos jätät
> kentän pois, kuljetusyhtiö ei saa puhelinnumeroa.
>
> **email** `string`
>
> Vastaanottajan sähköpostiosoite. Kuljetusyhtiö käyttää sitä samoin kuin kenttää `phone`. Jos
> jätät kentän pois, kuljetusyhtiö ei saa sähköpostiosoitetta.

> [!NOTE]
>
> **Packstation tai Postfiliale (vain Saksa):** aseta `street`-kenttään `Packstation` tai
> `Postfiliale`, `house_number`-kenttään kolminumeroinen aseman numero ja `address_line_2`-kenttään
> vastaanottajan DHL Postnummer (6–10 numeroa, välilyönnit sallittu). Ilman Postnummer-tunnusta
> pakettia ei voi varata. Postfach ei ole tuettu.

## Vastaus

Onnistuessaan rajapinta palauttaa `201 Created` sekä uuden kotitestipakkauksen tilauksen.

**id** `string` *required*

Kotitestipakkauksen tilauksen yksilöllinen tunniste (UUID).

**profile\_id** `string` *required*

Sen profiilin UUID, jolle tämä kotitestipakkauksen tilaus kuuluu.

**status** `string` *required*

Kotitestipakkauksen tilauksen nykyinen tila. Yksi arvoista `pending`, `dispatched`, `activated` tai
`cancelled`. Juuri luotu tilaus alkaa tilasta `pending`.

**delivery\_address** `object` *required*

Osoite, johon pakkaus postitetaan — toinen kahdesta muodosta: joko `{ location_id }`, joka viittaa tunnettuun testipaikkaan, tai suorat osoitekentät (`name`, `street`, `city`, `postal_code`, `country_code`; `company_name` / `house_number` / `address_line_2` / `state` / `phone` / `email` valinnaisia — sama sanasto kuin locations-API:ssa). Anna täsmälleen toinen — sijaintiviittaus tai suora osoite, ei molempia.

**toimitusosoite**

> [tab] Sijaintiviittaus
>
> **location\_id** `string` *required*
>
> Sen testipaikan UUID, johon pakkaus lähetetään.

> [tab] Suora osoite
>
> **name** `string` *required*
>
> Vastaanottajan, yrityksen tai sijainnin nimi.
>
> **company\_name** `string`
>
> Yritys, joka ottaa paketin vastaan vastaanottajan puolesta — `c/o`-taho tai osasto.
>
> **street** `string` *required*
>
> Kadunnimi ilman talon numeroa (esim. `Wilhelmstraße`).
>
> **house\_number** `string`
>
> Talon numero (esim. `118` tai `12a`).
>
> **address\_line\_2** `string`
>
> Rakennus, sisäänkäynti tai kerros.
>
> **city** `string` *required*
>
> **state** `string`
>
> Osavaltio tai maakunta. Valinnainen.
>
> **postal\_code** `string` *required*
>
> **country\_code** `string` *required*
>
> ISO 3166-1 alpha-2 -koodi (kaksi kirjainta, esim. `DE`).
>
> **phone** `string`
>
> **email** `string`

**metadata** `object` *required*

Antamasi avain–arvo-parit. Aina mukana — `{}`, jos et asettanut yhtään.

**replaces\_home\_kit\_order\_id** `string`

Kotitestipakkauksen tilaus, jonka tämä tilaus korvaa. `null` tavallisessa tilauksessa.

**replacement\_reason** `string`

Antamasi syy. `null` tavallisessa tilauksessa.

**results\_ready\_emails** `string[]` *required*

Osoitteet pienillä kirjaimilla, joista jokainen saa yhden sähköpostin kaikkien laboratoriotulosten
valmistuttua. Tyhjä, kun toiminto on pois päältä. Katso
[Tulokset valmiit -sähköpostit](https://docs.anivahealth.com/fi/concepts/results.md#saehkoepostit-tulosten-valmistumisesta).

**lab\_code** `string`

Laboratorion näytekoodi, jonka alla tulokset raportoidaan — painettu fyysiseen pakkaukseen, ja sen
potilas lukee rasiasta aktivointikoodina. `null`, kunnes pakkaus on pakattu.
Vain luku.

**activated\_at** `string` *required*

Näytteenoton aikaleima, joka on ilmoitettu kutsulla [Aktivoi](https://docs.anivahealth.com/fi/api/home-kit-orders/activate-home-kit.md).
`null`, kunnes pakkaus on aktivoitu.

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

ISO 8601 -aikaleima siitä, milloin kotitestipakkauksen tilaus luotiin.

**updated\_at** `string`

ISO 8601 -aikaleima viimeisimmästä päivityksestä. Voi olla `null`.

**profile** `object` *required*

Tähän kotitestipakkauksen tilaukseen liittyvä potilasprofiili.

**profiili**

**id** `string`

Profiilin yksilöllinen tunniste (UUID).

**handle** `string`

Profiilin nimimerkki tai käyttäjätunnus. Voi olla `null`.

**first\_name** `string`

Etunimi. Voi olla `null`.

**last\_name** `string`

Sukunimi. Voi olla `null`.

**email** `string`

Sähköpostiosoite. Voi olla `null`.

**phone** `string`

Puhelinnumero E.164-muodossa. Voi olla `null`.

**sex** `integer`

Biologinen sukupuoli standardin ISO/IEC 5218 mukaisesti. Voi olla `null`.

**date\_of\_birth** `string`

Syntymäaika muodossa `YYYY-MM-DD`. Voi olla `null`.

**height** `number`

Pituus senttimetreinä. Voi olla `null`.

**weight** `number`

Paino kilogrammoina. Voi olla `null`.

**language** `string`

Ensisijainen kieli: yksi 32 koodista sivulla [Luo profiili](https://docs.anivahealth.com/fi/api/profiles/create-profile.md).

**transactional\_emails\_enabled** `boolean`

Saako tämä profiili tapahtumapohjaisia (automaattisia) sähköposteja. Voi olla `null`.

**created\_at** `string`

ISO 8601 -aikaleima profiilin luontihetkestä.

**updated\_at** `string`

ISO 8601 -aikaleima profiilin viimeisimmästä päivityksestä. Voi olla `null`.

**panels** `HomeKitOrderPanel[]` *required*

Tähän kotitestipakkauksen tilaukseen liitetty paneeli — kentässä `panel_id` antamasi paneeli
tilauksen luontiaikaleimalla. Aina tasan yksi. Hae paneelin tiedot (nimi, biomarkkerit) kutsulla
[Listaa paneelit](https://docs.anivahealth.com/fi/api/panels/list-panels.md).

**Paneelin liittämiskentät**

**panel\_id** `string`

Paneelin UUID — tarkista vastaavuus [Listaa paneelit](https://docs.anivahealth.com/fi/api/panels/list-panels.md) -päätepisteestä.

**added\_at** `string`

ISO 8601 -aikaleima siitä, milloin paneeli liitettiin ensimmäisen kerran tähän kotitestipakkauksen tilaukseen.

**individual\_biomarkers** `HomeKitOrderIndividualBiomarker[]` *required*

Paneelin ulkopuolelta liitetyt biomarkkerit. Tyhjä tavallisessa luonnissa — kotitestipakkaukset
tilataan paneeleittain, ja tämän luettelon muokkaaminen jälkikäteen vaatii
`home_kit_orders_individual_biomarker_selection`-käyttöoikeuden. Korvaavassa tilauksessa kenttä
sisältää lähettämäsi `biomarker_ids`-tunnukset, jotka laboratorio analysoi uudelleen.

**Yksittäisen biomarkkerin kentät**

**biomarker\_id** `integer`

Biomarkkerin tunniste — tarkista vastaavuus
[Listaa biomarkkerit](https://docs.anivahealth.com/fi/api/biomarkers/list-biomarkers.md) -päätepisteestä parametrilla `home_kit=true`.

**added\_at** `string`

ISO 8601 -aikaleima siitä, milloin biomarkkeri liitettiin ensimmäisen kerran tähän kotitestipakkauksen tilaukseen.

**shipments** `HomeKitOrderShipmentLink[]` *required*

Tähän kotitestipakkauksen tilaukseen linkitetyt paketit vanhimmasta linkistä alkaen. Aina tyhjä
luotaessa — lue pakettien tarkat tiedot kutsulla [Listaa lähetykset](https://docs.anivahealth.com/fi/api/shipments/list-shipments.md)
ja parametrilla `?home_kit_order_id=`.

**Lähetyslinkityksen kentät**

**id** `string`

Lähetysviite — tarkista vastaavuus [Hae lähetys](https://docs.anivahealth.com/fi/api/shipments/get-shipment.md) -päätepisteestä.

**added\_at** `string`

ISO 8601 -aikaleima siitä, milloin lähetys linkitettiin tähän kotitestipakkauksen tilaukseen.

## Virhevastaukset

| Tila | Kuvaus |
| - | - |
| `400` | Validointivirhe — esim. `delivery_address`-kentästä puuttuu kenttä tai sen saksalaisessa postinumerossa ei ole 5 numeroa, `panel_id` ei ole kelvollinen UUID tai `replacement_reason` puuttuu korvaavasta tilauksesta. |
| `403` | Estetty — API-avaimellasi ei ole oikeutta tähän toimintoon, profiili on käyttöoikeuksiesi ulkopuolella tai asetit `results_ready_emails` ilman `results_view`-oikeutta potilaaseen. |
| `404` | Profiilia, paneelia tai korvattavaa kotitestipakkauksen tilausta ei löytynyt. |
| `409` | Ristiriita — `Idempotency-Key` on jo käytetty eri pyynnön rungolla, alkuperäinen pyyntö ei ole vielä valmistunut tai korvattavalle pakkaukselle on jo korvaava pakkaus matkalla. |
| `422` | Paneelia ei voi tilata kotitestipakkauksena — sille ei ole määritetty toimitettavaa pakkaustuotetta. Korvaavassa tilauksessa: korvattava tilaus kuuluu toiselle profiilille, `biomarker_ids`-arvo ei kuulu alkuperäiseen tilaukseen tai lähetit biomarkkereita yhdessä eri `panel_id`-arvon kanssa. |
| `500` | Sisäinen palvelinvirhe. |

```bash cURL theme={null}
curl --request POST \
  --url https://anivahealth.com/api/v1/home-kit-orders \
  --header 'x-api-key: YOUR_API_KEY' \
  --header 'Content-Type: application/json' \
  --data '{
    "profile_id": "a3f1c2d4-8b7e-4f2a-9c1d-2e3f4a5b6c7d",
    "panel_id": "f1c2d4a3-7b8e-4f2a-9c1d-2e3f4a5b6c7d",
    "metadata": { "your_order_ref": "ORD-10482", "priority": true },
    "delivery_address": {
      "name": "Maria Schmidt",
      "company_name": "c/o Weber",
      "street": "Friedrichstraße",
      "house_number": "123",
      "postal_code": "10117",
      "city": "Berlin",
      "country_code": "DE",
      "phone": "+4930123456789",
      "email": "maria.schmidt@example.com"
    }
  }'
```

```bash Replacement kit theme={null}
curl --request POST \
  --url https://anivahealth.com/api/v1/home-kit-orders \
  --header 'x-api-key: YOUR_API_KEY' \
  --header 'Content-Type: application/json' \
  --data '{
    "profile_id": "a3f1c2d4-8b7e-4f2a-9c1d-2e3f4a5b6c7d",
    "replaces_home_kit_order_id": "d1e2f3a4-5b6c-4d7e-8f9a-0b1c2d3e4f5a",
    "replacement_reason": "Too little material, HbA1c could not be analysed",
    "biomarker_ids": [103],
    "metadata": { "your_order_ref": "ORD-10482-R1" },
    "delivery_address": {
      "name": "Maria Schmidt",
      "street": "Friedrichstraße",
      "house_number": "123",
      "postal_code": "10117",
      "city": "Berlin",
      "country_code": "DE"
    }
  }'
```

```json 201 theme={null}
{
  "id": "d1e2f3a4-5b6c-4d7e-8f9a-0b1c2d3e4f5a",
  "profile_id": "a3f1c2d4-8b7e-4f2a-9c1d-2e3f4a5b6c7d",
  "status": "pending",
  "delivery_address": {
    "name": "Maria Schmidt",
    "company_name": "c/o Weber",
    "address_line_2": null,
    "street": "Friedrichstraße",
    "house_number": "123",
    "postal_code": "10117",
    "city": "Berlin",
    "country_code": "DE",
    "phone": "+4930123456789",
    "email": "maria.schmidt@example.com"
  },
  "created_at": "2026-04-01T09:45:00Z",
  "updated_at": null,
  "profile": {
    "id": "a3f1c2d4-8b7e-4f2a-9c1d-2e3f4a5b6c7d",
    "handle": null,
    "first_name": "Maria",
    "last_name": "Schmidt",
    "email": "maria.schmidt@example.com",
    "phone": "+4930123456789",
    "sex": 2,
    "date_of_birth": "1985-03-22",
    "height": 168,
    "weight": 65,
    "language": "de",
    "transactional_emails_enabled": true,
    "created_at": "2026-04-01T09:14:32Z",
    "updated_at": null
  },
  "panels": [
    {
      "panel_id": "f1c2d4a3-7b8e-4f2a-9c1d-2e3f4a5b6c7d",
      "added_at": "2026-04-01T09:45:00Z"
    }
  ],
  "individual_biomarkers": [],
  "metadata": { "your_order_ref": "ORD-10482", "priority": true },
  "replaces_home_kit_order_id": null,
  "replacement_reason": null,
  "results_ready_emails": [],
  "lab_code": null,
  "activated_at": null,
  "shipments": []
}
```

```json 400 theme={null}
{
  "error": "panel_id: panel_id must be a valid UUID"
}
```

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

```json 409 theme={null}
{
  "error": "Idempotency-Key \"ORD-10482\" was already used with a different request body. Use a new key for a different request, or resend the original body to read back its result."
}
```


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