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

# Einzelne Biomarker hinzufügen

> Einzelne Biomarker zu einem Termin hinzufügen

Füge einem Termin einen oder mehrere einzelne Biomarker als À-la-carte-Tests hinzu, außerhalb eines
vorgefertigten Panels. Die Routing-Entscheidungen trifft nachgelagert die Bestelllogistik-Pipeline anhand
der Zuordnungen jedes Biomarkers pro Labor.

Die resultierende Auswahl wird synchron gegen die Closure-Regeln jedes Labors geprüft. Manche Biomarker
lassen sich nur zusammen mit anderen bestellen – ein LDL/HDL-Verhältnis etwa wird
über eine Bestellung geliefert, die auch LDL und HDL zurückgibt, sodass das Verhältnis allein keine
stimmige Bestellung ergibt. (Genau diese Bestandteile bestimmen auch, wie das Verhältnis *bepreist* ist – siehe die
`pricing`-Aufschlüsselung unter [Biomarker auflisten](https://docs.anivahealth.com/de/api/biomarkers/list-biomarkers.md).) Lässt sich die Auswahl nicht sauber
bestellen, gibt der Aufruf `400` mit einer `validation`-Payload zurück und **es wird nichts gespeichert**, sodass du
dich durch Ausprobieren an eine gültige Auswahl herantasten kannst:

1. `PATCH … { "biomarker_ids": [45] }` (LDL/HDL-Verhältnis allein) → `400`;
   `validation.failures[].fix_options[].add_biomarkers` listet LDL und HDL auf.
2. `PATCH … { "biomarker_ids": [45, 43, 42] }` (Verhältnis + LDL + HDL) → `200`.

Derselbe Ablauf gilt für Biomarker, die Aniva nur innerhalb einer Position verkauft: Fragst du einen davon allein an, gibt der Aufruf
`400` mit `error: "biomarker_requires_position"` und den Positionen zurück, über die er verkauft wird. Siehe
[Preise](https://docs.anivahealth.com/de/concepts/pricing.md).

[Biomarker auflisten](https://docs.anivahealth.com/de/api/biomarkers/list-biomarkers.md) weist manche Biomarker mit `price_cents: null` aus.
Diese Biomarker sind **nicht kuratiert**: Aniva hat keinen Preis für sie festgelegt. Fügst du einen davon hinzu, gibt der Aufruf
`400` mit `error: "biomarker_not_priced"` zurück. Kein anderer Biomarker behebt diesen Fehler, denn `null`
bedeutet, dass es keinen Preis gibt, zu dem du den Marker kaufen kannst. Kit-Marker sind die Ausnahme. Füge das Panel
hinzu, das dem Kit entspricht, und die zugehörigen Marker kommen mit dem Panel. Der Aufruf akzeptiert auch einen zugehörigen Marker, den du einem
Termin hinzufügst, der dieses Panel bereits enthält.

Bei einer kapillaren Blutabnahme (`draw_method: capillary`) wird die Blutabnahme auf Microtainer aufgeteilt. Panels kommen zuerst, in
Buchungsreihenfolge. Einzelne Biomarker füllen dann den freien Platz in den Panel-Microtainern. Wenn sie
mehr Platz brauchen, öffnen sie neue Microtainer. Wir verteilen sie gleichmäßig. Jeder Microtainer fasst höchstens
150 µl an einzelnen Biomarkern. Ein Biomarker, der in einem eigenen Microtainer mehr als 150 µl braucht, passt nie,
und ein Biomarker ohne kuratiertes Volumen ebenfalls nicht. Verstößt die resultierende Auswahl gegen diese Regel,
gibt der Aufruf `400` mit einer `error`-Meldung zurück und es wird nichts gespeichert.

Dieser Aufruf ist idempotent: Biomarker, die bereits im Termin enthalten sind, bleiben erhalten.

Erfordert die Scopes `appointments_schedule` und `schedule_appointments_with_individual_biomarker_selection`.

> [!WARNING]
>
> Nachdem du [Blutabnahme
> bestätigen](https://docs.anivahealth.com/de/api/appointments/confirm-blood-draw.md) aufgerufen hast, können keine Biomarker mehr hinzugefügt werden. Der Versuch, einen bestätigten Termin zu ändern, gibt
> `409 Conflict` zurück.

## Anfrage

### Pfadparameter

**id** `string` *required*

Eindeutige Kennung (UUID) des Termins.

### Body-Parameter

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

Array mit Biomarker-IDs, die hinzugefügt werden sollen. Muss mindestens ein Element enthalten. Nutze [Biomarker
auflisten](https://docs.anivahealth.com/de/api/biomarkers/list-biomarkers.md), um IDs zu ermitteln.

## Antwort

Bei Erfolg gibt die API `200 OK` zurück und bestätigt, dass die Biomarker hinzugefügt wurden.

**success** `boolean`

`true`, wenn die Biomarker erfolgreich zum Termin hinzugefügt wurden.

### Eine `400`-Antwort lesen

Jede `400`-Antwort aus der Closure-Validierung oder dem Katalog enthält einen Satz in `message`. Eine `400`-Antwort aus der Body-Validierung oder
zu Microtainern enthält nur `error`. Verzweige anhand von `error`. Bei einem
Fehler in der Closure-Validierung ist `error` ein Satz. Bei einem Katalogfehler ist `error` ein Maschinencode:
`biomarker_not_priced` oder `biomarker_requires_position`.

**Closure-Validierung** – die Auswahl lässt sich bei keinem Labor sauber bestellen:

* `validation.failures[]` – nur bei Fehlern in der Closure-Validierung vorhanden (nicht bei einfachen
  Body-Validierungsfehlern). Ein Eintrag pro Biomarker-Gruppe, die kein Labor bedienen kann, mit den
  fehlgeschlagenen `biomarker_ids` und `fix_options[]`, kleinste Option zuerst. Das Feld
  `add_biomarkers` (`{ id, name }`) jeder Option ist eine Auswahl, die du KOMPLETT hinzufügst – behalte deine ursprünglichen bei, füge diese hinzu und
  versuche es erneut. Ein leeres `fix_options` bedeutet, dass Hinzufügen nicht hilft; entferne stattdessen den Biomarker.

**Biomarker ohne Preis** – Aniva hat keinen Preis für diesen Biomarker festgelegt. [Biomarker
auflisten](https://docs.anivahealth.com/de/api/biomarkers/list-biomarkers.md) weist ihn mit `price_cents: null` aus oder lässt ihn weg, wenn es
ein Verhältnis mit einem Bestandteil ohne Preis ist. `error` ist `biomarker_not_priced` und `biomarker_id` nennt
den Marker. Kein anderer Biomarker behebt diesen Fehler, also entferne den Biomarker. Zwei Bedingungen machen einen
Biomarker bestellbar: Ein Labor, an das Aniva routen kann, muss ihn liefern, **und** der Aniva-Katalog muss einen Preis für ihn
enthalten.

**Positionsgebundener Biomarker** – ein Biomarker, der nur innerhalb einer Position verkauft wird, ohne abdeckende Position in der
Auswahl. `error` ist `biomarker_requires_position`, `biomarker_id` nennt den Marker und `positions[]`
listet jede Position auf, über die er verkauft wird, günstigste zuerst. Füge alle Biomarker einer dieser Positionen hinzu. Siehe
[Preise](https://docs.anivahealth.com/de/concepts/pricing.md) für das Modell und `pricing.positions` unter [Biomarker
abrufen](https://docs.anivahealth.com/de/api/biomarkers/get-biomarker.md) für alle enthaltenen Biomarker einer Position.

## Fehlerantworten

| Status | Beschreibung |
| - | - |
| `400` | `biomarker_ids` ist leer / enthält keine Ganzzahlen, die Auswahl besteht die Closure-Validierung nicht (`validation.failures`), sie fügt einen Biomarker ohne Preis von Aniva hinzu (`error: "biomarker_not_priced"`), sie enthält einen positionsgebundenen Biomarker ohne abdeckende Position in der Auswahl (`error: "biomarker_requires_position"`), oder bei einer kapillaren Blutabnahme passen die Biomarker nicht in ihre Microtainer. |
| `403` | Verboten – fehlender Scope oder Termin außerhalb des Zugriffskontexts. |
| `404` | Termin oder ein oder mehrere Biomarker nicht gefunden. |
| `409` | Konflikt – Biomarker können nach Bestätigung der Blutabnahme nicht mehr geändert werden. |
| `500` | Interner Serverfehler. |

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