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

# Додати окремі біомаркери

> Додати окремі біомаркери до запису

Додай один або кілька окремих біомаркерів до запису як аналізи на вибір, поза будь-якою
готовою панеллю. Рішення щодо маршрутизації ухвалює далі конвеєр логістики замовлень на основі
прив’язок кожного біомаркера до кожної лабораторії.

Отриманий набір синхронно перевіряється за правилами замикання кожної лабораторії. Деякі біомаркери
можна отримати, лише замовивши їх разом з іншими — наприклад, співвідношення LDL/HDL
повертається в замовленні, яке також містить LDL і HDL, тому запит самого лише співвідношення не є
цілісним замовленням. (Саме за цими компонентами *розраховується ціна* співвідношення — див. розбивку `pricing`
на сторінці [Список біомаркерів](https://docs.anivahealth.com/uk/api/biomarkers/list-biomarkers.md).) Якщо набір неможливо коректно
замовити, виклик повертає `400` із даними `validation`, і **нічого не зберігається**, тож ти
можеш методом спроб і помилок дібрати валідний набір:

1. `PATCH … { "biomarker_ids": [45] }` (лише співвідношення LDL/HDL) → `400`;
   `validation.failures[].fix_options[].add_biomarkers` містить LDL і HDL.
2. `PATCH … { "biomarker_ids": [45, 43, 42] }` (співвідношення + LDL + HDL) → `200`.

Той самий цикл охоплює біомаркери, які Aniva продає лише у складі позиції: запитай його окремо, і виклик
поверне `400` з `error: "biomarker_requires_position"` та позиціями, які його продають. Див.
[Ціноутворення](https://docs.anivahealth.com/uk/concepts/pricing.md).

[Список біомаркерів](https://docs.anivahealth.com/uk/api/biomarkers/list-biomarkers.md) зазначає для деяких біомаркерів `price_cents: null`.
Ці біомаркери **некуровані**: Aniva не встановила для них ціну. Якщо ти додаси такий біомаркер, виклик поверне
`400` з `error: "biomarker_not_priced"`. Жоден інший біомаркер не виправить цю помилку, бо `null`
означає, що ти не маєш ціни для купівлі цього маркера. Винятком є маркери з наборів. Додай панель,
яка є цим набором, і її складові увійдуть разом із панеллю. Виклик також приймає складову, яку ти додаєш до
запису, що вже містить цю панель.

Під час капілярного забору крові (`draw_method: capillary`) зразки розподіляються по мікротейнерах. Спочатку йдуть панелі в
порядку бронювання. Потім окремі біомаркери заповнюють вільний простір мікротейнерів панелей. Коли їм
потрібно більше місця, відкриваються нові мікротейнери. Ми розподіляємо їх рівномірно. Кожен мікротейнер вміщує щонайбільше
150 µl окремих біомаркерів. Біомаркер, якому потрібно понад 150 µl в окремому мікротейнері, ніколи не
поміститься, так само як і біомаркер без визначеного об’єму. Якщо отриманий набір порушує це правило,
виклик повертає `400` із повідомленням `error`, і нічого не зберігається.

Цей виклик ідемпотентний: біомаркери, які вже є в записі, зберігаються.

Потребує дозволів `appointments_schedule` і `schedule_appointments_with_individual_biomarker_selection`.

> [!WARNING]
>
> Біомаркери не можна додавати після виклику [Підтвердити забір
> крові](https://docs.anivahealth.com/uk/api/appointments/confirm-blood-draw.md). Спроба змінити підтверджений запис повертає
> `409 Conflict`.

## Запит

### Параметри шляху

**id** `string` *required*

Унікальний ідентифікатор (UUID) запису.

### Параметри тіла запиту

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

Масив ID біомаркерів для додавання. Має містити щонайменше один елемент. Використай [Список
біомаркерів](https://docs.anivahealth.com/uk/api/biomarkers/list-biomarkers.md), щоб дізнатися ID.

## Відповідь

У разі успіху API повертає `200 OK`, підтверджуючи, що біомаркери додано.

**success** `boolean`

`true`, коли біомаркери успішно додано до запису.

### Як читати `400`

Кожна відповідь `400` через помилку валідації замикання або каталогу містить речення в полі `message`. Відповідь `400` через помилку валідації тіла запиту або
мікротейнерів містить лише `error`. Розгалужуй логіку за `error`. У разі
помилки валідації замикання `error` — це речення. У разі помилки каталогу `error` — це машинний код:
`biomarker_not_priced` або `biomarker_requires_position`.

**Валідація замикання** — набір неможливо коректно замовити в жодній лабораторії:

* `validation.failures[]` — наявне лише в разі помилок валідації замикання (відсутнє при звичайних
  помилках валідації тіла запиту). По одному елементу на кожну групу біомаркерів, яку не може виконати жодна лабораторія: він містить
  `biomarker_ids`, що не пройшли перевірку, та `fix_options[]`, починаючи з найменшого варіанта. У кожному варіанті
  `add_biomarkers` (`{ id, name }`) — це набір, який потрібно додати ПОВНІСТЮ: залиш свої початкові, додай ці й
  повтори спробу. Порожнє поле `fix_options` означає, що додавання не допоможе; натомість прибери біомаркер.

**Біомаркер без ціни** — Aniva не встановила ціну для цього біомаркера. [Список
біомаркерів](https://docs.anivahealth.com/uk/api/biomarkers/list-biomarkers.md) зазначає для нього `price_cents: null` або пропускає його, якщо це
співвідношення з компонентом без ціни. `error` має значення `biomarker_not_priced`, а `biomarker_id` вказує на
цей маркер. Жоден інший біомаркер не виправить цю помилку, тому прибери біомаркер. Біомаркер можна замовити за двох
умов: його має виконувати лабораторія, куди Aniva може спрямувати замовлення, **і** в каталозі Aniva для нього має бути
встановлена ціна.

**Обмежений біомаркер** — біомаркер, який продається лише у складі позиції, без відповідної позиції в
наборі. `error` має значення `biomarker_requires_position`, `biomarker_id` вказує на маркер, а `positions[]`
перелічує всі позиції, що його продають, від найдешевшої. Додай усі біомаркери однієї з них. Див.
[Ціноутворення](https://docs.anivahealth.com/uk/concepts/pricing.md), щоб дізнатися про модель, і `pricing.positions` на сторінці [Отримати
біомаркер](https://docs.anivahealth.com/uk/api/biomarkers/get-biomarker.md), щоб побачити повний склад позиції.

## Відповіді з помилками

| Статус | Опис |
| - | - |
| `400` | `biomarker_ids` порожній або містить нецілі числа, набір не проходить валідацію замикання (`validation.failures`), додається біомаркер без ціни Aniva (`error: "biomarker_not_priced"`), набір містить обмежений біомаркер, не покритий жодною позицією в наборі (`error: "biomarker_requires_position"`), або під час капілярного забору крові біомаркери не вміщуються у свої мікротейнери. |
| `403` | Заборонено — бракує дозволу або запис поза контекстом доступу. |
| `404` | Запис або один чи кілька біомаркерів не знайдено. |
| `409` | Конфлікт — біомаркери не можна змінювати після підтвердження забору крові. |
| `500` | Внутрішня помилка сервера. |

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