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

# Añadir biomarcadores individuales

> Añadir biomarcadores individuales a una cita

Añade uno o más biomarcadores individuales a una cita como pruebas a la carta, fuera de cualquier
panel predefinido. Las decisiones de enrutamiento se toman posteriormente en el flujo de logística de
pedidos según las asignaciones por laboratorio de cada biomarcador.

El conjunto resultante se valida de forma síncrona según las reglas de cierre de cada laboratorio.
Algunos biomarcadores solo pueden obtenerse pidiéndolos junto con otros: un cociente LDL/HDL, por
ejemplo, se obtiene mediante un pedido que también devuelve LDL y HDL, por lo que pedir el cociente
por sí solo no es un pedido coherente. (Esos mismos componentes son los que determinan el *precio*
del cociente; consulta el desglose de `pricing` en [Listar biomarcadores](https://docs.anivahealth.com/es/api/biomarkers/list-biomarkers.md)).
Cuando el conjunto no puede pedirse correctamente, la llamada devuelve `400` con un payload `validation`
y **no se guarda nada**, así que puedes ir probando hasta dar con un conjunto válido:

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

El mismo bucle cubre los biomarcadores que Aniva solo vende dentro de una posición: si pides uno solo,
la llamada devuelve `400` con `error: "biomarker_requires_position"` y las posiciones que lo venden.
Consulta [Precios](https://docs.anivahealth.com/es/concepts/pricing.md).

[Listar biomarcadores](https://docs.anivahealth.com/es/api/biomarkers/list-biomarkers.md) muestra algunos biomarcadores con `price_cents: null`.
Estos biomarcadores **no están configurados**: Aniva no les ha fijado un precio. Si añades uno, la llamada
devuelve `400` con `error: "biomarker_not_priced"`. Ningún otro biomarcador corrige este error, porque `null`
significa que no tienes precio para comprar el marcador. Los marcadores de kit son la excepción. Añade el panel
que corresponde al kit y sus componentes vienen con el panel. La llamada también acepta un componente que
añadas a una cita que ya tenga ese panel.

En una extracción capilar (`draw_method: capillary`), la extracción se distribuye en microtainers. Los
paneles van primero, por orden de reserva. Después, los biomarcadores individuales llenan el espacio libre
de los microtainers de los paneles. Cuando necesitan más espacio, abren nuevos microtainers. Los repartimos
de forma uniforme. Cada microtainer admite como máximo 150 µl de biomarcadores individuales. Un biomarcador
que necesite más de 150 µl en un microtainer propio nunca cabe, y tampoco uno sin un volumen configurado.
Si el conjunto resultante incumple esta regla, la llamada devuelve `400` con un mensaje `error` y no se
guarda nada.

Esta llamada es idempotente: los biomarcadores que ya están en la cita se mantienen.

Requiere los scopes `appointments_schedule` y `schedule_appointments_with_individual_biomarker_selection`.

> [!WARNING]
>
> No se pueden añadir biomarcadores después de llamar a [Confirmar extracción de
> sangre](https://docs.anivahealth.com/es/api/appointments/confirm-blood-draw.md). Intentar modificar una cita confirmada devuelve
> `409 Conflict`.

## Solicitud

### Parámetros de ruta

**id** `string` *required*

Identificador único (UUID) de la cita.

### Parámetros del cuerpo

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

Array de ID de biomarcadores para añadir. Debe contener al menos un elemento. Usa [Listar
biomarcadores](https://docs.anivahealth.com/es/api/biomarkers/list-biomarkers.md) para consultar los ID.

## Respuesta

Si la operación tiene éxito, la API devuelve `200 OK` confirmando que se han añadido los biomarcadores.

**success** `boolean`

`true` cuando los biomarcadores se han añadido correctamente a la cita.

### Interpretar un `400`

Todo `400` de validación de cierre o de catálogo incluye una frase en `message`. Un `400` de validación
del cuerpo o de microtainer incluye solo `error`. Ramifica según `error`. En un fallo de validación de
cierre, `error` es una frase. En un fallo de catálogo, `error` es un código de máquina:
`biomarker_not_priced` o `biomarker_requires_position`.

**Validación de cierre** — el conjunto no se puede pedir correctamente en ningún laboratorio:

* `validation.failures[]` — presente solo en fallos de validación de cierre (ausente en simples
  errores de validación del cuerpo). Una entrada por cada grupo de biomarcadores que ningún laboratorio
  puede ofrecer, con los `biomarker_ids` que han fallado y `fix_options[]`, con la opción más pequeña
  primero. El `add_biomarkers` (`{ id, name }`) de cada opción es un conjunto del que debes añadir
  TODOS los elementos: mantén los originales, añade esos y vuelve a intentarlo. Un `fix_options` vacío
  significa que no servirá añadir nada; elimina el biomarcador en su lugar.

**Biomarcador sin precio** — Aniva no ha fijado un precio para este biomarcador. [Listar
biomarcadores](https://docs.anivahealth.com/es/api/biomarkers/list-biomarkers.md) lo muestra con `price_cents: null`, o lo omite si
es un cociente con un componente sin precio. `error` es `biomarker_not_priced` y `biomarker_id` indica
el marcador. Ningún otro biomarcador corrige este error, así que elimina el biomarcador. Dos condiciones
hacen que un biomarcador se pueda pedir: un laboratorio al que Aniva pueda enrutarlo debe ofrecerlo **y**
el catálogo de Aniva debe asignarle un precio.

**Biomarcador restringido** — un biomarcador que solo se vende dentro de una posición, sin ninguna
posición en el conjunto que lo cubra. `error` es `biomarker_requires_position`, `biomarker_id` indica
el marcador y `positions[]` enumera cada posición que lo vende, de la más barata a la más cara. Añade
todos los biomarcadores de una de ellas. Consulta [Precios](https://docs.anivahealth.com/es/concepts/pricing.md) para conocer el modelo y
`pricing.positions` en [Obtener biomarcador](https://docs.anivahealth.com/es/api/biomarkers/get-biomarker.md) para ver el conjunto completo
de componentes de una posición.

## Respuestas de error

| Estado | Descripción |
| - | - |
| `400` | `biomarker_ids` vacío o no entero, el conjunto falla la validación de cierre (`validation.failures`), añade un biomarcador al que Aniva no ha fijado precio (`error: "biomarker_not_priced"`), contiene un biomarcador restringido que ninguna posición del conjunto cubre (`error: "biomarker_requires_position"`) o, en una extracción capilar, los biomarcadores no caben en sus microtainers. |
| `403` | Prohibido — falta un scope o la cita está fuera del contexto de acceso. |
| `404` | No se ha encontrado la cita o uno o más biomarcadores. |
| `409` | Conflicto — no se pueden modificar los biomarcadores después de confirmar la extracción de sangre. |
| `500` | Error interno 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.