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

# Kotitestipakkausten tilaukset

> Näin kotitestipakkausten tilaukset toimivat Aniva API:ssa: postitettavan pakkauksen tilaaminen, toimitus, näytteen palautus ja laboratoriotulokset.

**Kotitestipakkauksen tilaus** lähettää potilaalle itse tehtävän, kotiin postitettavan testipakkauksen. Aniva lähettää pakkauksen, potilas ottaa näytteen itse kotona ja postittaa sen takaisin. Tämä eroaa [ajanvarauksesta](https://docs.anivahealth.com/fi/concepts/appointments.md), jossa terveydenhuollon ammattilainen tekee laskimoverinäytteenoton fyysisessä testipisteessä.

> [!NOTE]
>
> Kotitestipakkausten tilausten päätepisteet vaativat `home_kit_orders_view`- (luku) tai
> `home_kit_orders_manage`-käyttöoikeusalueen (kirjoitus). [Aktivoi](https://docs.anivahealth.com/fi/api/home-kit-orders/activate-home-kit.md) hyväksyy myös suppeamman
> `home_kit_orders_activate`-käyttöoikeusalueen. [Hae tulokset](https://docs.anivahealth.com/fi/api/home-kit-orders/get-results.md) ja
> [Lähetä tulokset sähköpostilla](https://docs.anivahealth.com/fi/api/home-kit-orders/email-results.md) vaativat lisäksi `results_view`-käyttöoikeusalueen — laboratoriotulokset
> ja asiakirjat edellyttävät sitä aina.

## Kentät

**id** `string` *required*

Anivan automaattisesti luoma UUID. Käytä tätä tilauksen päivittämiseen, paneelin vaihtamiseen, aktivointiin,
peruuttamiseen ja tulosten hakemiseen.

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

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

**status** `string` *required*

Nykyinen elinkaaren tila. Jokin arvoista `pending`, `dispatched`, `activated` tai `cancelled`. Katso
[Elinkaari](#elinkaari) alla. Laboratoriotulosten valmistumisen tarkempi tila (`in_progress` vs. `completed`)
saadaan päätepisteestä [Hae tulokset](https://docs.anivahealth.com/fi/api/home-kit-orders/get-results.md).

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

Osoite, johon pakkaus postitetaan — jommassakummassa kahdesta muodosta: joko tunnettuun
testipisteeseen viittaava `{location_id}` 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 — sijaintiviite
tai suora osoite, ei molempia.

**toimitusosoite**

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

> [tab] Suora osoite
>
> **name** `string` *required*
>
> Vastaanottajan, yrityksen tai toimipisteen 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`
>
> Vastaanottajan puhelinnumero. Kuljetusyhtiö saa sen ilmoittaakseen vastaanottajalle paketista.
>
> **email** `string`
>
> Vastaanottajan sähköpostiosoite. Kuljetusyhtiö saa sen ilmoittaakseen vastaanottajalle paketista.

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

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

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

**updated\_at** `string`

Viimeisimmän päivityksen ISO 8601 -aikaleima. Null, jos kotitestipakkauksen tilausta ei ole koskaan päivitetty.

**profile** `object`

Potilaan täydellinen profiiliobjekti, upotettuna jokaiseen kotitestipakkauksen tilausvastaukseen.

**ominaisuudet**

**id** `string`

Liitetyn profiilin UUID.

**handle** `string`

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

**first\_name** `string`

Potilaan etunimi. Voi olla `null`.

**last\_name** `string`

Potilaan sukunimi. Voi olla `null`.

**email** `string`

Potilaan sähköpostiosoite. Voi olla `null`.

**phone** `string`

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

**sex** `integer`

Biologinen sukupuoli standardin ISO/IEC 5218 mukaan. 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: jokin päätepisteen [Luo profiili](https://docs.anivahealth.com/fi/api/profiles/create-profile.md) 32 koodista.

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

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

**created\_at** `string`

Profiilin luomisen ISO 8601 -aikaleima.

**updated\_at** `string`

Profiilin viimeisimmän päivityksen ISO 8601 -aikaleima. Voi olla `null`.

**panels** `object[]`

Kotitestipakkauksen tilaukseen liitetty paneeli — aina täsmälleen yksi `{ panel_id, added_at }` -merkintä,
koska kotitestipakkaus vastaa 1:1 fyysistä pakkaustuotetta. Tarkista `panel_id`-arvo
päätepisteestä [Listaa paneelit](https://docs.anivahealth.com/fi/api/panels/list-panels.md).

**individual\_biomarkers** `object[]`

Kotitestipakkauksen tilaukseen paneelin ulkopuolelta liitetyt biomarkkerit. Jokainen merkintä on
`{ biomarker_id, added_at }`. Tarkista jokainen `biomarker_id`-arvo
päätepisteestä [Listaa biomarkkerit](https://docs.anivahealth.com/fi/api/biomarkers/list-biomarkers.md) parametrilla `home_kit=true`. Tavallisessa tilauksessa nämä ovat yksittäisiä lisätestejä
paneelin päälle; [korvaavassa pakkauksessa](#korvaavat-pakkaukset) ne ovat testit, jotka laboratorio
ajaa uudelleen.

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

Kotitestipakkauksen tilaus, jonka tämä tilaus korvaa, kun kyseessä on [korvaava pakkaus](#korvaavat-pakkaukset). Tavallisessa tilauksessa
`null`.

**replacement\_reason** `string`

Syy korvaavan pakkauksen lähettämiseen yhdellä virkkeellä. Tavallisessa tilauksessa `null`.

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

Osoitteet pienin kirjaimin, joihin kuhunkin lähetetään yksi sähköposti, kun kaikki laboratoriotulokset ovat valmiit. Aina mukana —
tyhjä, kun pois käytöstä. Aseta päätepisteessä [Luo](https://docs.anivahealth.com/fi/api/home-kit-orders/create-home-kit.md) tai
[Päivitä](https://docs.anivahealth.com/fi/api/home-kit-orders/update-home-kit.md). Katso
[Tulokset valmiit -sähköpostit](https://docs.anivahealth.com/fi/concepts/results.md#saehkoepostit-tulosten-valmistumisesta).

**metadata** `object`

Omat avain-arvoparisi, jotka palautetaan sellaisinaan eikä Aniva koskaan tulkitse niitä. Aina mukana
luettaessa — `{}`, jos et aseta yhtään. Enintään 20 avainta; avaimet vastaavat muotoa `[A-Za-z0-9_-]` ja ovat enintään 40
merkkiä pitkiä; arvot ovat merkkijonoja, numeroita tai totuusarvoja, merkkijonot enintään 500 merkkiä; yhteensä 16 384
tavua sarjoitettuna. Alkuosalla `aniva_` alkavat avaimet on varattu.
[Päivitä](https://docs.anivahealth.com/fi/api/home-kit-orders/update-home-kit.md)-kutsussa metadata **yhdistetään**: pois jättämäsi avaimet säilyvät,
arvolla `null` lähetetty avain poistetaan ja `{}` tyhjentää kaiken. Validointi on joko kaikki tai ei mitään. Älä koskaan laita
henkilö- tai kliinisiä tietoja `metadata`-kenttään — sitä ei käsitellä potilastietona.

**lab\_code** `string`

Laboratorion näytekoodi. Yksi koodi, kolme roolia: koodi, jonka alla laboratoriotulokset raportoidaan, joka on painettu
fyysiseen pakkaukseen ja jonka potilas lukee rasiasta aktivointikoodina. Myönnetään, kun
pakkaus pakataan — `null` tilauksen ollessa tilassa `pending`, paitsi kun Aniva lähettää pakkauksen uudelleen (katso
[Elinkaari](#elinkaari)). Aina vain luku -muodossa. Etsi käsissä olevaa pakkausta
vastaava tilaus kutsulla `GET /api/v1/home-kit-orders?lab_code=…`.

**activated\_at** `string`

Päätepisteen [Aktivoi](https://docs.anivahealth.com/fi/api/home-kit-orders/activate-home-kit.md) kautta ilmoitettu näytteenottoaika — ajankohta, jolloin
potilas todellisuudessa otti näytteensä, UTC-aikana. `null`, kunnes pakkaus on aktivoitu.
Tämä on laboratorioraportissa näkyvä näytteenottoaika.

**shipments** `object[]`

Tähän tilaukseen liitetyt paketit vanhimmasta liitoksesta alkaen, kukin muodossa `{ id, added_at }` — potilaalle matkalla oleva pakkaus
ja seurattavalla palautuksella varustetuissa pakkauksissa takaisin laboratorioon matkalla oleva näyte, joka
ilmestyy heti pakettikorttien tulostuessa. Tyhjä tilauksen ollessa tilassa
`pending`, paitsi kun Aniva lähettää pakkauksen uudelleen. Lue
kaikkien pakettien täydet tiedot yhdellä kutsulla `GET /api/v1/shipments?home_kit_order_id={id}` — katso
[Lähetykset](https://docs.anivahealth.com/fi/concepts/shipments.md).

## Elinkaari

Kotitestipakkausten tilauksilla on neljä elinkaaren tilaa:

```
pending → dispatched → activated
   │          │
   │          ├──→ pending    (Aniva re-ships a lost kit)
   │          └──→ cancelled  (Aniva: the box came back undelivered)
   │
   └──→ cancelled
```

| Tila | Merkitys |
| - | - |
| `pending` | Tilaus on luotu, mutta pakkausta ei ole vielä pakattu. Voidaan [päivittää](https://docs.anivahealth.com/fi/api/home-kit-orders/update-home-kit.md) (osoite, paneelin vaihto, metatiedot) tai [perua](https://docs.anivahealth.com/fi/api/home-kit-orders/cancel-home-kit.md). |
| `dispatched` | Pakkaus on pakattu ja varustettu lähetystarralla – se on matkalla potilaalle (tai jo hänellä). Sen paneeli- ja biomarkkerikoostumus on nyt **lukittu**, etkä voi enää [perua](https://docs.anivahealth.com/fi/api/home-kit-orders/cancel-home-kit.md) sitä. Aniva voi silti muuttaa sen tilaa: takaisin tilaan `pending`, jos pakkaus katoaa ja Aniva lähettää uuden, tai tilaan `cancelled`, jos paketti palautuu toimittamattomana eikä sitä lähetetä uudelleen. |
| `activated` | Potilas on ottanut näytteensä, ja tämä on ilmoitettu [Aktivoi](https://docs.anivahealth.com/fi/api/home-kit-orders/activate-home-kit.md)-kutsulla näytteenottoajan kanssa. Laboratoriotilaus tehdään pakkauksen koodilla `lab_code`. Lopputila – vastaa ajanvarauksen tilaa `blood_drawn`. |
| `cancelled` | Kotitestipakkauksen tilaus on peruttu: joko sinä peruit sen tilasta `pending` tai Aniva tilasta `dispatched`, kun paketti palautui toimittamattomana. Lopputila – ei enää tilasiirtymiä, ja uusi peruutus ei tee mitään vaan palauttaa tilauksen. |

Kun Aniva lähettää kadonneen pakkauksen uudelleen, tilaus palaa tilaan `pending`, mutta säilyttää
koodinsa `lab_code` ja aiemmat pakettinsa kentässä `shipments`. Uudessa pakkauksessa on sama koodi.
Uuteen pakettiin laitetaan käyttämätön palautustarra. Vain Aniva tekee nämä kaksi siirtymää; API ei
tarjoa niitä. Kumpikin siirtymä lähettää [webhookin](https://docs.anivahealth.com/fi/concepts/webhooks.md) `home_kit_order.pending`
tai `home_kit_order.cancelled`.

> [!NOTE]
>
> Kotitestipakkauksen tilauksen tilamalli on tarkoituksella karkea. Toimituksen etenemistä potilaalle
> ja takaisin seurataan tilauksen [lähetyksistä](https://docs.anivahealth.com/fi/concepts/shipments.md) – `dispatched` tarkoittaa, että
> pakkauksella on lähetystarra ja laboratoriokoodi, ei sitä, että se on jo liikkeellä; lähtevän
> lähetyksen `status` kertoo, onko se liikkunut. Laboratoriotulosten käsittely tapahtuu
> laboratoriolähetteissä. Laboratoriotulosten valmistuminen (`in_progress` vs. `completed`) näkyy
> [Hae tulokset](https://docs.anivahealth.com/fi/api/home-kit-orders/get-results.md) -kutsussa – ylätason `status`-kenttä on
> `in_progress`, kunnes jokainen lähete sulkeutuu, ja sen jälkeen `completed` – tai `fault`, jos
> jokainen lähete keskeytyi raportoimatta tuloksia.

## Pakettien seuranta

```
GET /api/v1/shipments?home_kit_order_id={id}
```

Se, mitä palautuu, riippuu pakkauksesta. Verinäytepakkaus tulee kahtena lähetyksenä, kun Aniva on
pakannut sen: paketti Anivalta potilaalle ja paketti potilaalta laboratorioon (sen `destination` on
laboratorio), yhdistettynä kentällä `paired_with`. Palautuspaketti pysyy tilassa `pending` –
seurantakoodi on jo tiedossa – kunnes potilas postittaa sen. Suolistomikrobiomipakkaus tulee yhtenä
lähetyksenä: pakkaus potilaalle. Sen palautuskuori on valmiiksi maksettu ja seuraamaton, joten
paluumatkalle ei varata lähetystä. `booked_by` kertoo, kuka varasi lähetystarran: `"aniva"` tai
`"external"`. Vain `"aniva"`-pakettia voi muokata täällä, ja lähetystarran tulostamisen jälkeen vain
sen `notes`-kenttää. Jokaisessa paketissa on kuljetusyhtiön täydet `status_updates`-tiedot, mukaan
lukien DHL:n `detail_code` postitoimipaikkaan ohjaamisesta.

Lähetyksen `home_kit_orders` listaa vain oman käyttöoikeuskontekstisi tilaukset. Katso
[Käyttöoikeudet](https://docs.anivahealth.com/fi/concepts/shipments.md#kaeyttoeoikeudet).

> [!WARNING]
>
> Kotitestipakkauksen tilauksen koostumusta voi muuttaa vain, kun tila on `pending`. Kun tilaus on
> tilassa `dispatched` (tai myöhemmässä – `activated`/`cancelled`), paneelin vaihdot ja `/biomarkers`-päätepisteet
> palauttavat virheen `409 Conflict`: fyysinen pakkaus pakataan valitun paneelin mukaan, joten sen
> sisältö lukittuu sillä hetkellä, kun se lähtee potilaalle. Jos sinun täytyy muuttaa jo lukitun
> tilauksen testejä, ota suoraan yhteyttä Anivaan – se on yleensä vielä mahdollista, ja teemme
> muutoksen puolestasi, jotta pakkauksen sisältö pysyy yhtenäisenä. Jos pakkaus on jo käytetty eikä
> siitä saatu tuloksia, tilaa sen sijaan [korvaava pakkaus](#korvaavat-pakkaukset).

## Kotitestipakkaustilausten listaaminen

Hae kaikki API-avaimellesi näkyvät kotitestipakkaustilaukset:

```
GET /api/v1/home-kit-orders
```

Voit halutessasi välittää parametrin `?profile_id={uuid}` suodattaaksesi tietyn profiilin mukaan tai
`?lab_code={code}` selvittääksesi käsillä olevan fyysisen pakkauksen tilauksen – tämä on aktivointiprosessin
luonteva ensimmäinen vaihe.

## Kotitestipakkaustilauksen luominen

Tee kotitestipakkaustilaus potilasprofiilille:

```
POST /api/v1/home-kit-orders
```

Välitä `profile_id`, `delivery_address` ja yksi `panel_id`. Tilaus luodaan tilassa `pending`.

Välitä valinnainen `Idempotency-Key`-otsikko, jotta uudelleenyritys ei tilaa toista pakkausta – katso [Idempotenssi](https://docs.anivahealth.com/fi/concepts/idempotency.md).

Tarkalleen yksi paneeli, koska kotitestipakkaus vastaa 1:1 fyysistä pakkaustuotetta – paneeli on pakkaus. Vain paneelit, jotka Aniva on määrittänyt kotitestipakkauksiksi, ovat tilattavissa; muut paneelit hylätään koodilla `422`. Se vaaditaan luontivaiheessa, koska tilaus siirtyy heti pakkausjonoon ja pakkaaminen voi alkaa välittömästi. Kun tilaus on tilassa `pending`, voit vaihtaa paneelin [Päivitä](https://docs.anivahealth.com/fi/api/home-kit-orders/update-home-kit.md)-kutsulla.

Jos haluat lähettää toisen pakkauksen sellaisen tilalle, josta ei saatu tuloksia, välitä `replaces_home_kit_order_id` paneelin valitsemisen sijaan – katso [Korvaavat pakkaukset](#korvaavat-pakkaukset).

## Korvaavat pakkaukset

Joskus pakkauksesta ei saada tuloksia: potilas ei saanut putkea täyteen, näytteessä oli saapuessa liian vähän materiaalia tai laboratorio ei pystynyt analysoimaan osaa siitä. Tilaa sille **korvaava pakkaus**:

```
POST /api/v1/home-kit-orders
{
  "profile_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "delivery_address": { "...": "..." },
  "replaces_home_kit_order_id": "d1e2f3a4-5b6c-4d7e-8f9a-0b1c2d3e4f5a",
  "replacement_reason": "Too little material, HbA1c could not be analysed",
  "biomarker_ids": [103]
}
```

Korvaava pakkaus on **uusi tilaus uudella laboratoriokoodilla**, myös silloin kun ensimmäistä pakkausta ei koskaan aktivoitu: laboratorio tarvitsee uuden lähetteen, eikä kahta näytettä samalla koodilla voi erottaa toisistaan. Molemmat tilaukset pysyvät luettavina ja linkittyvät toisiinsa kentällä `replaces_home_kit_order_id`.

**Korvattavaan tilaukseen ei kosketa.** Se säilyttää tilansa, laboratoriokoodinsa ja kaikki sille jo kirjatut tulokset, joten jos potilas silti postittaa ensimmäisen pakkauksen, hän saa kaikki tulokset, jotka laboratorio pystyy siitä lukemaan.

**Paneeli periytyy.** Jätä `panel_id` pois, niin korvaava tilaus saa korvattavan tilauksen paneelin – sen potilas osti, ja sen mukaan paketti on brändätty. Lähetä eri paneeli vain koko paneelin korvaamista varten; paneeli ja biomarkkerien osajoukko yhdessä hylätään koodilla `422`, koska osajoukko tarkoittaa oikeaa asiaa vain sen paneelin alla, josta se on valittu. Korvaavan tilauksen paneelia ei myöskään voi vaihtaa jälkikäteen.

**Sinä valitset, mitä ajetaan uudelleen.** Lähetä `biomarker_ids`-kentässä epäonnistuneet biomarkkerit, niin laboratorio analysoi vain ne uudelleen ja pakkauksessa lähetetään vain niihin tarvittavat putket. Jätä se pois, jos haluat ajaa koko paneelin uudelleen – tämä on oikea valinta, kun mitään ei saatu analysoitua. Tämä ei vaadi erillistä käyttöoikeutta: potilaan jo maksamien biomarkkerien uudelleenajo ei ole à la carte -valinta. Näitä biomarkkereita ei voi poistaa jälkikäteen, koska ne muodostavat koko lähetteen.

> [!NOTE]
>
> Biomarkkerit ajetaan uudelleen paneelin **ryhminä**, ei yksitellen. Yhden ryhmään kuuluvan
> biomarkkerin nimeäminen ajaa koko ryhmän uudelleen, koska sellaista laboratoriotilausta ei voi
> tehdä, joka raportoi enemmän kuin on tilattu. Yhden biomarkkerin korvaava tilaus voi siksi
> palauttaa useamman tuloksen, ja putkien määrä voi olla suurempi kuin biomarkkerilista antaa
> ymmärtää.

Vain yksi korvaava pakkaus per pakkaus voi olla matkalla kerrallaan – kun korvaava tilaus on tilassa `pending` tai `dispatched`, toinen luontipyyntö samalle tilaukselle palauttaa virheen `409` ja nimeää kyseisen tilauksen. Tulokset saapuvat korvaavan tilauksen omalla koodilla `lab_code` sen oman [Hae tulokset](https://docs.anivahealth.com/fi/api/home-kit-orders/get-results.md) -kutsun kautta.

Korvaava tilaus ei ole oikea tapa hoitaa pakettia, joka ei koskaan saapunut perille. Kerro sen sijaan Anivalle: kyse on saman tilauksen uudelleenlähetyksestä samalla laboratoriokoodilla, ei uudesta tilauksesta.

## Kotitestipakkaustilauksen päivittäminen

Muuta toimitusosoitetta, vaihda paneeli, päivitä metatiedot tai korvaa tulosten valmistumisesta ilmoittavat sähköpostiosoitteet:

```
PATCH /api/v1/home-kit-orders/{id}
```

Sisällytä vain kentät, joita haluat muuttaa. `panel_id` **korvaa** liitetyn paneelin – kun pakkauksessa on tarkalleen yksi paneeli, vaihto on ainoa mielekäs paneelitoiminto, minkä vuoksi paneelin lisäys- tai poistopäätepisteitä ei ole. Osoitetta ja paneelia voi muokata vain tilassa `pending`; `metadata` pysyy muokattavana koko tilauksen elinkaaren ajan. `results_ready_emails` pysyy muokattavana, kunnes tilaus on tilassa `cancelled`.

## Kotitestipakkaustilauksen peruminen

Peru kotitestipakkaustilaus, jota ei enää tarvita:

```
DELETE /api/v1/home-kit-orders/{id}
```

Tämä asettaa kotitestipakkaustilauksen tilaksi `cancelled`. Peruttu kotitestipakkaustilaus palautetaan vastauksessa.

Vain tilassa `pending` olevan tilauksen voi perua. Tilasta `dispatched` alkaen pakkaus on pakattu ja varustettu lähetystarralla – automaattista takaisinkutsua ei ole – ja kutsu palauttaa virheen `409`. Jos jo lähetetty pakkaus pitää pysäyttää, ota suoraan yhteyttä Anivaan.

Jos perut `pending`-tilauksen, jonka pakkaus on jo tilattu logistiikkakumppanilta, se perutaan myös siellä, ja kutsu onnistuu vain, jos logistiikkakumppani hyväksyy peruutuksen:

* `409` – pakkaus oli jo pakattu ja varustettu lähetystarralla, joten sitä ei voi enää kutsua takaisin, vaikka tilauksen tilana näkyy yhä `pending`.
* `502` – logistiikkakumppani hylkäsi peruutuksen (virhe sisältää heidän perustelunsa) tai siihen ei saatu yhteyttä. **Mitään ei muutettu** – tilaus on yhä voimassa ja sen voi perua uudelleen.

Virheen palauttava peruutus jättää tilauksen täsmälleen ennalleen, joten `200` on ainoa vahvistus siitä, ettei pakkausta ole tulossa.

Jo tilassa `cancelled` olevan tilauksen peruminen palauttaa saman `200`-vastauksen riippumatta siitä, mistä tilasta se peruttiin.

## Kotitestipakkaustilauksen aktivointi

Kun potilas on ottanut näytteensä, ilmoita siitä:

```
POST /api/v1/home-kit-orders/{id}/activate
```

Välitä `activated_at` – hetki, jolloin potilas todellisuudessa otti näytteen, UTC-aikaleimana. Tämä on näytteenottoaika, joka tulee laboratorioraporttiin, joten lähetä todellinen näytteenottohetki, älä omaa käsittelyaikaasi. Aktivointi on lopullinen: tilaus siirtyy tilaan `activated`, eikä sitä voi enää perua tai muuttaa. Kotitestipakkauksen vastine [Vahvista verinäytteenotto](https://docs.anivahealth.com/fi/api/appointments/confirm-blood-draw.md) -kutsulle ilman viivakoodia – pakkauksen koodi kiinnitetään pakkaamisen yhteydessä, joten sinun ei tarvitse koskaan tietää sitä. Tilauksella on oltava `lab_code` siihen mennessä; tilaus ilman sitä palauttaa virheen `409`.

Aktivointi tekee myös laboratoriotilauksen: pakkauksen paneeli tilataan laboratoriosta sen koodilla `lab_code`, jotta palautuvaa näytettä osataan odottaa ja tulokset liitetään tilaukseen laboratorion raportoidessa ne. Tämä ajetaan vastauksen jälkeen, ja laboratorion puolen ongelmat hoitaa Aniva sen sijaan, että ne näkyisivät pyynnössäsi.

## Yksittäiset biomarkkerit

Voit liittää kotitestipakkaustilaukseen yksittäisiä biomarkkereita à la carte -testeinä paneelin ulkopuolelta. Tämä on hyödyllistä, kun haluat räätälöidyn valikoiman pakkauksen lisäksi. Liitetyt biomarkkerit näkyvät kotitestipakkaustilauksen vastauksessa `individual_biomarkers`-taulukkona (`panels`-kentän rinnalla).

Molemmat biomarkkeripäätepisteet vaativat `home_kit_orders_individual_biomarker_selection`-oikeusalueen `home_kit_orders_manage`-oikeusalueen lisäksi — kotitestipakkaukset tilataan paneeleittain, joten yksittäiset markkerit otetaan käyttöön kumppanikohtaisesti. Kysy Anivalta, jos integraatiosi tarvitsee sitä.

Lisää biomarkkereita (idempotentti — jo liitetyt biomarkkerit säilytetään):

```
PATCH /api/v1/home-kit-orders/{id}/biomarkers
```

Poista biomarkkereita (idempotentti — liittämätön ID ohitetaan):

```
DELETE /api/v1/home-kit-orders/{id}/biomarkers
```

Molemmat päätepisteet ottavat `biomarker_ids`-taulukon. Hae biomarkkerien ID:t [Listaa biomarkkerit](https://docs.anivahealth.com/fi/api/biomarkers/list-biomarkers.md) -päätepisteellä parametrilla `home_kit=true`. Biomarkkereita voi muuttaa vain, kun pakkaus on tilassa `pending` (katso [Elinkaari](#elinkaari)).

## Laboratoriotulosten hakeminen

Kun laboratorio on käsitellyt palautetun näytteen, hae kliiniset ja geneettiset tulokset:

```
GET /api/v1/home-kit-orders/{id}/results
```

Vastaus sisältää suunnitellut testit (tila `planned`) saatujen tulosten ohella, joten voit seurata, mikä on vielä kesken. Tulokset kirjautuvat tilauksen `lab_code`-koodin alle ja saapuvat markkeri kerrallaan laboratorion analysoidessa niitä, joten osittaiset vastaukset ovat normaaleja. Ylätason `status`-kenttä on `in_progress` lopulliseen raporttiin asti ja sen jälkeen `completed` (tai `fault`, jos jokainen laboratoriotilaus epäonnistui raportoimatta) — päättele tästä, onko kotitestipakkaustilauksen laboratoriotyö valmis. `home_kit_order.results.completed`-[webhook](https://docs.anivahealth.com/fi/concepts/webhooks.md) kertoo, kun näin tapahtuu, joten sinun ei tarvitse tehdä toistuvia kyselyjä. Laboratorioraporttien PDF-tiedostoihin viitataan `documents`-taulukossa — lataa ne kutsulla `GET /api/v1/documents/{id}`.

## Esimerkki kotitestipakkaustilauksesta

```json theme={null}
{
  "id": "d1e2f3a4-5b6c-4d7e-8f9a-0b1c2d3e4f5a",
  "profile_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "status": "dispatched",
  "delivery_address": {
    "name": "Jane Doe",
    "street": "Friedrichstraße",
    "house_number": "123",
    "postal_code": "10117",
    "city": "Berlin",
    "country_code": "DE",
    "phone": "+4930123456789",
    "email": "jane.doe@example.com"
  },
  "created_at": "2026-04-01T10:00:00Z",
  "updated_at": "2026-04-02T08:00:00Z",
  "profile": {
    "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    "handle": null,
    "first_name": "Jane",
    "last_name": "Doe",
    "email": "jane.doe@example.com",
    "phone": "+4930123456789",
    "sex": 2,
    "date_of_birth": "1990-06-15",
    "height": 170,
    "weight": 62,
    "language": "de",
    "transactional_emails_enabled": true,
    "created_at": "2026-04-01T09:30:00Z",
    "updated_at": null
  },
  "panels": [
    {
      "panel_id": "f1c2d4a3-7b8e-4f2a-9c1d-2e3f4a5b6c7d",
      "added_at": "2026-04-01T10:05:00Z"
    }
  ],
  "individual_biomarkers": [
    {
      "biomarker_id": 42,
      "added_at": "2026-04-01T10:07:00Z"
    }
  ],
  "metadata": { "your_order_ref": "ORD-10482" },
  "replaces_home_kit_order_id": null,
  "replacement_reason": null,
  "results_ready_emails": [],
  "lab_code": "7642000123",
  "activated_at": null,
  "shipments": [
    { "id": "K2604021FQ7", "added_at": "2026-04-02T08:00:00Z" },
    { "id": "K260402P3XD", "added_at": "2026-04-02T08:00:00Z" }
  ]
}
```


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