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

# Adicionar biomarcadores individuais

> Adicionar biomarcadores individuais a uma marcação

Adiciona um ou mais biomarcadores individuais a uma marcação como testes avulso, fora de qualquer
painel predefinido. As decisões de encaminhamento são tomadas a jusante pelo pipeline de logística
de pedidos com base nos mapeamentos por laboratório de cada biomarcador.

O conjunto resultante é validado de forma síncrona face às regras de fecho de cada laboratório. Alguns
biomarcadores só podem ser obtidos se forem pedidos em conjunto com outros — um rácio LDL/HDL, por
exemplo, é fornecido por um pedido que também devolve LDL e HDL, pelo que pedir o rácio sozinho não é
um pedido coerente. (Esses mesmos componentes são também a base do *preço* do rácio — vê o detalhe de
`pricing` em [Listar biomarcadores](https://docs.anivahealth.com/pt/api/biomarkers/list-biomarkers.md).) Quando o conjunto não pode ser
pedido de forma válida, a chamada devolve `400` com um payload `validation` e **nada é guardado**,
para que possas chegar a um conjunto válido por tentativa e erro:

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

O mesmo ciclo aplica-se aos biomarcadores que a Aniva só vende dentro de uma posição: se pedires um
sozinho, a chamada devolve `400` com `error: "biomarker_requires_position"` e as posições que o
vendem. Vê [Preços](https://docs.anivahealth.com/pt/concepts/pricing.md).

[Listar biomarcadores](https://docs.anivahealth.com/pt/api/biomarkers/list-biomarkers.md) apresenta alguns biomarcadores com `price_cents: null`.
Estes biomarcadores estão **sem curadoria**: a Aniva não definiu preço para eles. Se adicionares um,
a chamada devolve `400` com `error: "biomarker_not_priced"`. Nenhum outro biomarcador resolve esta
falha, porque `null` significa que não tens preço para comprar o marcador. Os marcadores de kit são a
exceção. Associa o painel correspondente ao kit e os seus membros vêm com o painel. A chamada também
aceita um membro que adiciones a uma marcação que já tenha esse painel.

Numa colheita capilar (`draw_method: capillary`), a colheita é distribuída por microtainers. Os painéis
entram primeiro, por ordem de marcação. Os biomarcadores individuais preenchem depois o espaço livre
dos microtainers dos painéis. Quando precisam de mais espaço, abrem novos microtainers. Distribuímo-los
de forma uniforme. Cada microtainer comporta no máximo 150 µl de biomarcadores individuais. Um biomarcador
que precise de mais de 150 µl num microtainer próprio nunca cabe, tal como um biomarcador sem volume
definido. Se o conjunto resultante violar esta regra, a chamada devolve `400` com uma mensagem em `error`
e nada é guardado.

Esta chamada é idempotente: os biomarcadores que já estão na marcação mantêm-se.

Requer os scopes `appointments_schedule` e `schedule_appointments_with_individual_biomarker_selection`.

> [!WARNING]
>
> Não é possível adicionar biomarcadores depois de chamares [Confirmar colheita de
> sangue](https://docs.anivahealth.com/pt/api/appointments/confirm-blood-draw.md). Tentar modificar uma marcação confirmada devolve
> `409 Conflict`.

## Pedido

### Parâmetros de caminho

**id** `string` *required*

Identificador único (UUID) da marcação.

### Parâmetros do corpo

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

Array de IDs de biomarcadores a associar. Tem de conter pelo menos um item. Usa [Listar
biomarcadores](https://docs.anivahealth.com/pt/api/biomarkers/list-biomarkers.md) para descobrir os IDs.

## Resposta

Em caso de sucesso, a API devolve `200 OK` a confirmar que os biomarcadores foram associados.

**success** `boolean`

`true` quando os biomarcadores foram adicionados com sucesso à marcação.

### Ler um `400`

Todos os `400` de validação de fecho e de catálogo incluem uma frase em `message`. Um `400` de validação
do corpo ou de microtainer inclui apenas `error`. Faz a ramificação com base em `error`. Numa falha
de validação de fecho, `error` é uma frase. Numa falha de catálogo, `error` é um código de máquina:
`biomarker_not_priced` ou `biomarker_requires_position`.

**Validação de fecho** — o conjunto não pode ser pedido de forma válida em nenhum laboratório:

* `validation.failures[]` — presente apenas em falhas de validação de fecho (ausente em erros simples
  de validação do corpo). Uma entrada por cada grupo de biomarcadores que nenhum laboratório consegue
  processar, com os `biomarker_ids` que falharam e `fix_options[]`, da opção mais pequena para a maior.
  O `add_biomarkers` (`{ id, name }`) de cada opção é um conjunto que tens de adicionar na TOTALIDADE —
  mantém os teus originais, adiciona esses e tenta novamente. Um `fix_options` vazio significa que não há
  nada que possas adicionar para resolver; em vez disso, remove o biomarcador.

**Biomarcador sem preço** — a Aniva não definiu preço para este biomarcador. [Listar
biomarcadores](https://docs.anivahealth.com/pt/api/biomarkers/list-biomarkers.md) apresenta-o com `price_cents: null`, ou omite-o quando
é um rácio com um componente sem preço. `error` é `biomarker_not_priced` e `biomarker_id` identifica
o marcador. Nenhum outro biomarcador resolve esta falha, por isso remove o biomarcador. Duas condições
permitem pedir um biomarcador: um laboratório para onde a Aniva possa encaminhar tem de o fornecer,
**e** o catálogo da Aniva tem de ter preço para ele.

**Biomarcador restrito** — um biomarcador vendido apenas dentro de uma posição, sem nenhuma posição
que o cubra no conjunto. `error` é `biomarker_requires_position`, `biomarker_id` identifica o marcador
e `positions[]` lista todas as posições que o vendem, da mais barata para a mais cara. Adiciona todos
os biomarcadores de uma delas. Vê [Preços](https://docs.anivahealth.com/pt/concepts/pricing.md) para o modelo e `pricing.positions` em
[Obter biomarcador](https://docs.anivahealth.com/pt/api/biomarkers/get-biomarker.md) para o conjunto completo de membros de uma posição.

## Respostas de erro

| Estado | Descrição |
| - | - |
| `400` | `biomarker_ids` vazio / não inteiro, o conjunto falha a validação de fecho (`validation.failures`), adiciona um biomarcador sem preço na Aniva (`error: "biomarker_not_priced"`), contém um biomarcador restrito sem posição que o cubra no conjunto (`error: "biomarker_requires_position"`), ou, numa colheita capilar, os biomarcadores não cabem nos microtainers. |
| `403` | Proibido — scope em falta ou marcação fora do contexto de acesso. |
| `404` | Marcação ou um ou mais biomarcadores não encontrados. |
| `409` | Conflito — os biomarcadores não podem ser modificados depois de a colheita de sangue ter sido confirmada. |
| `500` | Erro interno do 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.