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

# Aggiungi singoli biomarcatori

> Aggiungi singoli biomarcatori a un appuntamento

Aggiungi uno o più biomarcatori singoli a un appuntamento come test à la carte, al di fuori di qualsiasi
pannello predefinito. Le decisioni di instradamento vengono prese a valle dalla pipeline di logistica degli ordini in base
alle mappature per laboratorio di ciascun biomarcatore.

Il set risultante viene convalidato in modo sincrono rispetto alle regole di chiusura di ciascun laboratorio. Alcuni biomarcatori
possono essere ottenuti solo ordinandoli insieme ad altri — un rapporto LDL/HDL, per esempio, viene
fornito da un ordine che restituisce anche LDL e HDL, quindi richiedere il rapporto da solo non è un
ordine coerente. (Questi stessi componenti determinano il *prezzo* del rapporto — vedi il dettaglio `pricing`
in [Elenco biomarcatori](https://docs.anivahealth.com/it/api/biomarkers/list-biomarkers.md).) Quando il set non può essere ordinato
in modo valido, la chiamata restituisce `400` con un payload `validation` e **non viene salvato nulla**, così puoi
procedere per tentativi fino a ottenere un set valido:

1. `PATCH … { "biomarker_ids": [45] }` (solo rapporto LDL/HDL) → `400`;
   `validation.failures[].fix_options[].add_biomarkers` elenca LDL e HDL.
2. `PATCH … { "biomarker_ids": [45, 43, 42] }` (rapporto + LDL + HDL) → `200`.

Lo stesso ciclo riguarda i biomarcatori che Aniva vende solo all'interno di una posizione: richiedine uno da solo e la chiamata
restituisce `400` con `error: "biomarker_requires_position"` e le posizioni che lo vendono. Vedi
[Prezzi](https://docs.anivahealth.com/it/concepts/pricing.md).

[Elenco biomarcatori](https://docs.anivahealth.com/it/api/biomarkers/list-biomarkers.md) riporta alcuni biomarcatori con `price_cents: null`.
Questi biomarcatori sono **non configurati**: Aniva non ha definito un prezzo per loro. Se ne aggiungi uno, la chiamata restituisce
`400` con `error: "biomarker_not_priced"`. Nessun altro biomarcatore risolve questo errore, perché `null`
significa che non hai un prezzo a cui acquistare il marcatore. I marcatori dei kit fanno eccezione. Collega il pannello
che rappresenta il kit e i suoi elementi vengono inclusi nel pannello. La chiamata accetta anche un elemento che aggiungi a
un appuntamento che include già quel pannello.

In un prelievo capillare (`draw_method: capillary`), il prelievo viene suddiviso in microtainer. I pannelli vanno per primi, in
ordine di prenotazione. I biomarcatori singoli riempiono poi lo spazio libero dei microtainer dei pannelli. Quando
hanno bisogno di più spazio, aprono nuovi microtainer. Li distribuiamo in modo uniforme. Ogni microtainer contiene al massimo
150 µl di biomarcatori singoli. Un biomarcatore che richiede più di 150 µl in un proprio microtainer non
entra mai, e lo stesso vale per un biomarcatore senza un volume configurato. Se il set risultante viola questa regola,
la chiamata restituisce `400` con un messaggio `error` e non viene salvato nulla.

Questa chiamata è idempotente: i biomarcatori già presenti nell'appuntamento vengono mantenuti.

Richiede gli scope `appointments_schedule` e `schedule_appointments_with_individual_biomarker_selection`.

> [!WARNING]
>
> Non è possibile aggiungere biomarcatori dopo aver chiamato [Conferma prelievo di
> sangue](https://docs.anivahealth.com/it/api/appointments/confirm-blood-draw.md). Il tentativo di modificare un appuntamento confermato restituisce
> `409 Conflict`.

## Richiesta

### Parametri di percorso

**id** `string` *required*

Identificatore univoco (UUID) dell'appuntamento.

### Parametri del body

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

Array di ID dei biomarcatori da aggiungere. Deve contenere almeno un elemento. Usa [Elenco
biomarcatori](https://docs.anivahealth.com/it/api/biomarkers/list-biomarkers.md) per trovare gli ID.

## Risposta

In caso di successo, l'API restituisce `200 OK` a conferma che i biomarcatori sono stati aggiunti.

**success** `boolean`

`true` quando i biomarcatori sono stati aggiunti correttamente all'appuntamento.

### Come leggere un `400`

Ogni `400` di validazione della chiusura o di catalogo contiene una frase in `message`. Un `400` di validazione del body o
dei microtainer contiene solo `error`. Dirama la logica su `error`. In caso di
errore di validazione della chiusura, `error` è una frase. In caso di errore di catalogo, `error` è un codice macchina:
`biomarker_not_priced` o `biomarker_requires_position`.

**Validazione della chiusura** — il set non può essere ordinato in modo valido presso alcun laboratorio:

* `validation.failures[]` — presente solo negli errori di validazione della chiusura (assente nei semplici
  errori di validazione del body). Una voce per ogni gruppo di biomarcatori che nessun laboratorio può gestire, con i
  `biomarker_ids` non validi e `fix_options[]`, a partire dall'opzione più piccola. Il campo
  `add_biomarkers` (`{ id, name }`) di ogni opzione è un set da aggiungere TUTTO — mantieni quelli originali, aggiungi questi e
  riprova. Un `fix_options` vuoto significa che nessuna aggiunta risolve il problema; rimuovi invece il biomarcatore.

**Biomarcatore senza prezzo** — Aniva non ha definito un prezzo per questo biomarcatore. [Elenco
biomarcatori](https://docs.anivahealth.com/it/api/biomarkers/list-biomarkers.md) lo riporta con `price_cents: null`, oppure lo omette quando
è un rapporto con un componente senza prezzo. `error` è `biomarker_not_priced` e `biomarker_id` indica
il marcatore. Nessun altro biomarcatore risolve questo errore, quindi rimuovi il biomarcatore. Due condizioni rendono un
biomarcatore ordinabile: un laboratorio a cui Aniva può instradare l'ordine deve fornirlo **e** il catalogo Aniva deve definirne il
prezzo.

**Biomarcatore vincolato** — un biomarcatore venduto solo all'interno di una posizione, senza una posizione che lo copra nel
set. `error` è `biomarker_requires_position`, `biomarker_id` indica il marcatore e `positions[]`
elenca tutte le posizioni che lo vendono, dalla più economica. Aggiungi tutti i biomarcatori di una di esse. Vedi
[Prezzi](https://docs.anivahealth.com/it/concepts/pricing.md) per il modello e `pricing.positions` in [Ottieni
biomarcatore](https://docs.anivahealth.com/it/api/biomarkers/get-biomarker.md) per l'intero set di elementi di una posizione.

## Risposte di errore

| Stato | Descrizione |
| - | - |
| `400` | `biomarker_ids` vuoto / non intero, il set non supera la validazione della chiusura (`validation.failures`), aggiunge un biomarcatore per cui Aniva non ha definito un prezzo (`error: "biomarker_not_priced"`), contiene un biomarcatore vincolato non coperto da alcuna posizione nel set (`error: "biomarker_requires_position"`), oppure, in un prelievo capillare, i biomarcatori non entrano nei rispettivi microtainer. |
| `403` | Forbidden — scope mancante o appuntamento al di fuori del contesto di accesso. |
| `404` | Appuntamento o uno o più biomarcatori non trovati. |
| `409` | Conflict — non è possibile modificare i biomarcatori dopo la conferma del prelievo di sangue. |
| `500` | Errore interno del server. |

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