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

# Lisää yksittäisiä biomarkkereita

> Lisää yksittäisiä biomarkkereita ajanvaraukseen

Lisää yksi tai useampi yksittäinen biomarkkeri ajanvaraukseen à la carte -testeinä valmiiden
paneelien ulkopuolelta. Reitityspäätökset tehdään myöhemmin tilauslogistiikkaputkessa kunkin
biomarkkerin laboratoriokohtaisten vastaavuuksien perusteella.

Muodostuva joukko validoidaan synkronisesti kunkin laboratorion sulkeumasääntöjä vasten. Joitakin
biomarkkereita saa vain tilaamalla ne yhdessä muiden kanssa — esimerkiksi LDL/HDL-suhde
toimitetaan tilauksella, joka palauttaa myös LDL:n ja HDL:n, joten pelkän suhteen pyytäminen ei
ole yhtenäinen tilaus. (Suhde on *hinnoiteltu* juuri näiden samojen osatekijöiden mukaan — katso
`pricing`-erittely sivulta [Listaa biomarkkerit](https://docs.anivahealth.com/fi/api/biomarkers/list-biomarkers.md).) Kun joukkoa ei
voi tilata ongelmitta, kutsu palauttaa `400` ja `validation`-sisällön eikä **mitään tallenneta**,
joten voit hakea kelvollisen joukon kokeilemalla:

1. `PATCH … { "biomarker_ids": [45] }` (pelkkä LDL/HDL-suhde) → `400`;
   `validation.failures[].fix_options[].add_biomarkers` listaa LDL:n ja HDL:n.
2. `PATCH … { "biomarker_ids": [45, 43, 42] }` (suhde + LDL + HDL) → `200`.

Sama silmukka koskee biomarkkereita, joita Aniva myy vain osana nimikettä: jos pyydät yhtä
yksinään, kutsu palauttaa `400`, `error: "biomarker_requires_position"` sekä nimikkeet, joissa
sitä myydään. Katso [Hinnoittelu](https://docs.anivahealth.com/fi/concepts/pricing.md).

[Listaa biomarkkerit](https://docs.anivahealth.com/fi/api/biomarkers/list-biomarkers.md) ilmoittaa joillekin biomarkkereille arvon
`price_cents: null`. Nämä biomarkkerit ovat **kuratoimattomia**: Aniva ei ole hinnoitellut niitä.
Jos lisäät sellaisen, kutsu palauttaa `400` ja `error: "biomarker_not_priced"`. Mikään muu
biomarkkeri ei korjaa tätä virhettä, koska `null` tarkoittaa, ettei sinulla ole hintaa markkerin
ostamiseen. Testipakkauksen markkerit ovat poikkeus. Liitä testipakkauksena toimiva paneeli, niin
sen jäsenet tulevat paneelin mukana. Kutsu hyväksyy myös jäsenen, jonka lisäät ajanvaraukseen,
jolla kyseinen paneeli jo on.

Kapillaarinäytteenotossa (`draw_method: capillary`) verinäyte pakataan mikroputkiin. Paneelit menevät
ensin varausjärjestyksessä. Yksittäiset biomarkkerit täyttävät sitten paneelien mikroputkien vapaan
tilan. Kun ne tarvitsevat lisää tilaa, ne avaavat uusia mikroputkia. Jaamme ne tasaisesti. Jokaiseen
mikroputkeen mahtuu enintään 150 µl yksittäisiä biomarkkereita. Biomarkkeri, joka tarvitsee yli
150 µl omassa mikroputkessaan, ei mahdu koskaan, eikä myöskään biomarkkeri ilman kuratoitua
tilavuutta. Jos muodostuva joukko rikkoo tätä sääntöä, kutsu palauttaa `400` ja `error`-viestin
eikä mitään tallenneta.

Tämä kutsu on idempotentti: ajanvarauksella jo olevat biomarkkerit säilytetään.

Vaatii scope-oikeudet `appointments_schedule` ja `schedule_appointments_with_individual_biomarker_selection`.

> [!WARNING]
>
> Biomarkkereita ei voi lisätä sen jälkeen, kun olet tehnyt [Vahvista
> verinäytteenotto](https://docs.anivahealth.com/fi/api/appointments/confirm-blood-draw.md) -kutsun. Vahvistetun ajanvarauksen
> muokkausyritys palauttaa `409 Conflict`.

## Pyyntö

### Polkuparametrit

**id** `string` *required*

Ajanvarauksen yksilöllinen tunniste (UUID).

### Runkoparametrit

**biomarker\_ids** `number[]` *required*

Taulukko liitettävien biomarkkereiden tunnisteista. Täytyy sisältää vähintään yksi alkio. Hae
tunnisteet [Listaa biomarkkerit](https://docs.anivahealth.com/fi/api/biomarkers/list-biomarkers.md) -kutsulla.

## Vastaus

Onnistuessaan API palauttaa `200 OK` vahvistuksena siitä, että biomarkkerit on liitetty.

**success** `boolean`

`true`, kun biomarkkerit on lisätty ajanvaraukseen onnistuneesti.

### `400`-vastauksen lukeminen

Jokainen sulkeumavalidoinnin ja luettelon `400`-vastaus sisältää lauseen kentässä `message`.
Runkovalidoinnin tai mikroputkien `400`-vastaus sisältää vain kentän `error`. Haaroita `error`-arvon
perusteella. Sulkeumavalidointivirheessä `error` on lause. Luettelovirheessä `error` on
koneluettava koodi: `biomarker_not_priced` tai `biomarker_requires_position`.

**Sulkeumavalidointi** — joukkoa ei voi tilata ongelmitta mistään laboratoriosta:

* `validation.failures[]` — mukana vain sulkeumavalidointivirheissä (puuttuu tavallisissa
  runkovalidointivirheissä). Yksi merkintä jokaista biomarkkeriryhmää kohden, jota yksikään
  laboratorio ei voi toimittaa; sisältää epäonnistuneet `biomarker_ids`-arvot ja `fix_options[]`-vaihtoehdot
  pienin vaihtoehto ensin. Kunkin vaihtoehdon `add_biomarkers` (`{ id, name }`) on joukko, josta lisäät
  KAIKKI — pidä alkuperäiset, lisää nämä ja yritä uudelleen. Tyhjä `fix_options` tarkoittaa, ettei
  minkään lisääminen auta; poista sen sijaan biomarkkeri.

**Hinnoittelematon biomarkkeri** — Aniva ei ole hinnoitellut tätä biomarkkeria. [Listaa
biomarkkerit](https://docs.anivahealth.com/fi/api/biomarkers/list-biomarkers.md) ilmoittaa sen arvolla `price_cents: null` tai jättää
sen pois, jos kyseessä on suhde, jossa on hinnoittelematon osatekijä. `error` on
`biomarker_not_priced`, ja `biomarker_id` nimeää markkerin. Mikään muu biomarkkeri ei korjaa tätä
virhettä, joten poista biomarkkeri. Kaksi ehtoa tekee biomarkkerista tilattavan: laboratorion,
johon Aniva voi reitittää, on toimitettava se, **ja** sen on oltava hinnoiteltu Anivan luettelossa.

**Rajoitettu biomarkkeri** — biomarkkeri, jota myydään vain osana nimikettä ilman kattavaa nimikettä
joukossa. `error` on `biomarker_requires_position`, `biomarker_id` nimeää markkerin, ja
`positions[]` listaa kaikki nimikkeet, joissa sitä myydään, halvin ensin. Lisää yhden niistä kaikki
biomarkkerit. Katso malli sivulta [Hinnoittelu](https://docs.anivahealth.com/fi/concepts/pricing.md) ja nimikkeen koko jäsenjoukko
kentästä `pricing.positions` sivulla [Hae biomarkkeri](https://docs.anivahealth.com/fi/api/biomarkers/get-biomarker.md).

## Virhevastaukset

| Tila | Kuvaus |
| - | - |
| `400` | `biomarker_ids` on tyhjä tai ei-kokonaisluku, joukko ei läpäise sulkeumavalidointia (`validation.failures`), se lisää biomarkkerin, jota Aniva ei ole hinnoitellut (`error: "biomarker_not_priced"`), se sisältää rajoitetun biomarkkerin, jota mikään joukon nimike ei kata (`error: "biomarker_requires_position"`), tai kapillaarinäytteenotossa biomarkkerit eivät mahdu mikroputkiinsa. |
| `403` | Kielletty — puuttuva scope-oikeus tai ajanvaraus käyttöoikeuskontekstin ulkopuolella. |
| `404` | Ajanvarausta tai yhtä tai useampaa biomarkkeria ei löytynyt. |
| `409` | Ristiriita — biomarkkereita ei voi muokata verinäytteenoton vahvistamisen jälkeen. |
| `500` | Sisäinen palvelinvirhe. |

```bash cURL theme={null}
curl --request PATCH \
  --url https://anivahealth.com/api/v1/appointments/c9f3e2a1-7d6b-4c5e-b3a2-1f0e9d8c7b6a/biomarkers \
  --header 'x-api-key: YOUR_API_KEY' \
  --header 'Content-Type: application/json' \
  --data '{
    "biomarker_ids": [45, 43, 42]
  }'
```

```json 200 theme={null}
{
  "success": true
}
```

```json 400 (closure validation) theme={null}
{
  "error": "LDL / HDL Ratio cannot be ordered cleanly with this set — add LDL Cholesterol / HDL Cholesterol (see validation.failures for every option).",
  "message": "LDL / HDL Ratio cannot be ordered cleanly with this set — add LDL Cholesterol / HDL Cholesterol (see validation.failures for every option).",
  "validation": {
    "failures": [
      {
        "biomarker_ids": [45],
        "fix_options": [
          {
            "add_biomarkers": [
              { "id": 43, "name": "LDL Cholesterol" },
              { "id": 42, "name": "HDL Cholesterol" }
            ]
          }
        ]
      }
    ]
  }
}
```

```json 400 (biomarker Aniva has not priced) theme={null}
{
  "error": "biomarker_not_priced",
  "message": "Adrenaline, 24h urine carries no price in the catalog you can order from — GET /api/v1/biomarkers/1465 reports price_cents: null for it, and a marker with no price cannot be ordered.",
  "biomarker_id": 1465
}
```

```json 400 (biomarker sold only inside a position) theme={null}
{
  "error": "biomarker_requires_position",
  "message": "Mean Platelet Volume (MPV) is not sold on its own — it comes only inside a position. Add every biomarker of one of the positions listed here; the cheapest is \"Blood Count (extended)\".",
  "biomarker_id": 77,
  "positions": [
    {
      "id": "3f1a8c22-64bd-4e57-8a90-1c2d3e4f5a6b",
      "name": "Blood Count (extended)",
      "price_cents": 460,
      "retail_cents": 529
    }
  ]
}
```

```json 400 (capillary, does not fit) theme={null}
{
  "error": "Some individual biomarkers need more than 150 µl of one lab's microtainer. Remove some of them."
}
```

```json 409 theme={null}
{
  "error": "Individual biomarkers cannot be modified after blood draw has been confirmed"
}
```

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


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