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

# Afegeix biomarcadors individuals

> Afegeix biomarcadors individuals a una cita

Afegeix un o més biomarcadors individuals a una cita com a proves a la carta, fora de qualsevol
panell predefinit. Les decisions d'encaminament es prenen més endavant al flux de logística de comandes segons
les correspondències per laboratori de cada biomarcador.

El conjunt resultant es valida de manera síncrona segons les regles de tancament de cada laboratori. Alguns biomarcadors
només es poden obtenir demanant-los juntament amb altres — una ràtio LDL/HDL, per exemple,
s'obté amb una comanda que també retorna LDL i HDL, de manera que demanar la ràtio sola no és una
comanda coherent. (Aquests mateixos components són els que determinen el *preu* de la ràtio — consulta el desglossament de `pricing`
a [Llista els biomarcadors](https://docs.anivahealth.com/ca/api/biomarkers/list-biomarkers.md).) Quan el conjunt no es pot demanar correctament,
la crida retorna `400` amb una càrrega útil `validation` i **no es desa res**, de manera que pots
anar provant fins a arribar a un conjunt vàlid:

1. `PATCH … { "biomarker_ids": [45] }` (només la ràtio LDL/HDL) → `400`;
   `validation.failures[].fix_options[].add_biomarkers` llista LDL i HDL.
2. `PATCH … { "biomarker_ids": [45, 43, 42] }` (ràtio + LDL + HDL) → `200`.

El mateix cicle cobreix els biomarcadors que Aniva ven només dins d'una posició: demana'n un de sol i la crida
retorna `400` amb `error: "biomarker_requires_position"` i les posicions que el venen. Consulta
[Preus](https://docs.anivahealth.com/ca/concepts/pricing.md).

[Llista els biomarcadors](https://docs.anivahealth.com/ca/api/biomarkers/list-biomarkers.md) indica alguns biomarcadors amb `price_cents: null`.
Aquests biomarcadors **no estan configurats**: Aniva no els ha posat preu. Si n'afegeixes un, la crida retorna
`400` amb `error: "biomarker_not_priced"`. Cap altre biomarcador resol aquest error, perquè `null`
vol dir que no tens cap preu per comprar el marcador. Els marcadors de kit en són l'excepció. Afegeix el panell
que correspon al kit i els seus membres s'inclouen amb el panell. La crida també accepta un membre que afegeixis a
una cita que ja inclou aquest panell.

En una extracció capil·lar (`draw_method: capillary`), l'extracció s'envasa en microtubs. Els panells van primer, per
ordre de reserva. Després, els biomarcadors individuals omplen l'espai lliure dels microtubs dels panells. Quan
necessiten més espai, obren microtubs nous. Els repartim de manera uniforme. Cada microtub admet com a màxim
150 µl de biomarcadors individuals. Un biomarcador que necessiti més de 150 µl en un microtub propi no hi cap
mai, i tampoc un biomarcador sense un volum configurat. Si el conjunt resultant incompleix aquesta regla,
la crida retorna `400` amb un missatge `error` i no es desa res.

Aquesta crida és idempotent: els biomarcadors que ja són a la cita es mantenen.

Requereix els abasts `appointments_schedule` i `schedule_appointments_with_individual_biomarker_selection`.

> [!WARNING]
>
> No es poden afegir biomarcadors després de cridar [Confirma l'extracció
> de sang](https://docs.anivahealth.com/ca/api/appointments/confirm-blood-draw.md). Intentar modificar una cita confirmada retorna
> `409 Conflict`.

## Sol·licitud

### Paràmetres de ruta

**id** `string` *required*

Identificador únic (UUID) de la cita.

### Paràmetres del cos

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

Matriu d'ID de biomarcadors per afegir. Ha de contenir almenys un element. Fes servir [Llista els
biomarcadors](https://docs.anivahealth.com/ca/api/biomarkers/list-biomarkers.md) per trobar els ID.

## Resposta

Si té èxit, l'API retorna `200 OK` per confirmar que els biomarcadors s'han afegit.

**success** `boolean`

`true` quan els biomarcadors s'han afegit correctament a la cita.

### Com interpretar un `400`

Cada `400` de validació de tancament o de catàleg inclou una frase a `message`. Un `400` de validació del cos o
de microtub inclou només `error`. Ramifica segons `error`. En un
error de validació de tancament, `error` és una frase. En un error de catàleg, `error` és un codi de màquina:
`biomarker_not_priced` o `biomarker_requires_position`.

**Validació de tancament** — el conjunt no es pot demanar correctament a cap laboratori:

* `validation.failures[]` — present només en errors de validació de tancament (absent en errors simples
  de validació del cos). Una entrada per cada grup de biomarcadors que cap laboratori pot servir, amb els
  `biomarker_ids` que han fallat i `fix_options[]`, començant per l'opció més petita. El camp
  `add_biomarkers` (`{ id, name }`) de cada opció és un conjunt que has d'afegir SENCER — mantén els originals, afegeix aquests i
  torna-ho a provar. Un `fix_options` buit vol dir que no servirà de res afegir-hi res més; elimina el biomarcador.

**Biomarcador sense preu** — Aniva no ha posat preu a aquest biomarcador. [Llista els
biomarcadors](https://docs.anivahealth.com/ca/api/biomarkers/list-biomarkers.md) l'indica amb `price_cents: null`, o l'omet quan
és una ràtio amb un component sense preu. `error` és `biomarker_not_priced`, i `biomarker_id` indica
el marcador. Cap altre biomarcador resol aquest error, així que elimina el biomarcador. Dues condicions fan que un
biomarcador es pugui demanar: un laboratori al qual Aniva pugui encaminar-lo l'ha d'oferir, **i** el catàleg d'Aniva li ha de posar
preu.

**Biomarcador restringit** — un biomarcador que es ven només dins d'una posició, sense cap posició que el cobreixi al
conjunt. `error` és `biomarker_requires_position`, `biomarker_id` indica el marcador i `positions[]`
llista totes les posicions que el venen, començant per la més econòmica. Afegeix tots els biomarcadors d'una d'elles. Consulta
[Preus](https://docs.anivahealth.com/ca/concepts/pricing.md) per veure el model, i `pricing.positions` a [Obtén un
biomarcador](https://docs.anivahealth.com/ca/api/biomarkers/get-biomarker.md) per veure el conjunt complet de membres d'una posició.

## Respostes d'error

| Estat | Descripció |
| - | - |
| `400` | `biomarker_ids` buit o no enter, el conjunt falla la validació de tancament (`validation.failures`), afegeix un biomarcador al qual Aniva no ha posat preu (`error: "biomarker_not_priced"`), conté un biomarcador restringit que cap posició del conjunt cobreix (`error: "biomarker_requires_position"`), o, en una extracció capil·lar, els biomarcadors no caben als seus microtubs. |
| `403` | Prohibit — falta un abast o la cita és fora del context d'accés. |
| `404` | No s'ha trobat la cita o un o més biomarcadors. |
| `409` | Conflicte — els biomarcadors no es poden modificar un cop confirmada l'extracció de sang. |
| `500` | Error intern del servidor. |

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