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

# Listar biomarcadores

> Explorar o catálogo de biomarcadores

Devolve um catálogo paginado dos biomarcadores que a tua chave de API pode pedir numa origem. Associa-os a [marcações](https://docs.anivahealth.com/pt/api/appointments/add-individual-biomarkers.md) ou a [kits de teste em casa](https://docs.anivahealth.com/pt/api/home-kit-orders/add-individual-biomarkers.md). Os biomarcadores arquivados são excluídos.

Um biomarcador aparece na lista quando um pedido num laboratório que a tua chave pode usar o disponibiliza e o pedido faz a colheita apenas para recipientes que a origem tem. O que decide são os tubos de amostra, não o tipo de analito.

Requer o scope `panels_access`. O objeto `pricing` também requer o scope `prices_view`.

## Pedido

### Parâmetros de consulta

A origem tem uma de duas formas: um local de teste ou um kit de teste em casa. Envia exatamente uma. Enviar nenhuma ou ambas devolve `400`.

> [tab] Local de teste
>
> **location\_id** `string` *required*
>
> O local onde são feitas as colheitas das marcações. Um biomarcador aparece na lista quando o
> seu pedido faz a colheita apenas para recipientes que esse local tem. Relaciona com [Listar
> locais](https://docs.anivahealth.com/pt/api/locations/list-locations.md).

> [tab] Kit de teste em casa
>
> **home\_kit** `boolean` *required*
>
> Define como `true`. Um biomarcador aparece na lista quando um pedido num laboratório de kits
> de teste em casa faz a colheita apenas para os recipientes que um kit contém: soro capilar e
> EDTA, gota de sangue seco, urina e zaragatoa. Biomarcadores exclusivamente venosos ficam de
> fora.

**rate\_card** `string`

Substitui a tabela de preços que `price_cents` usa: `retail`, ou o `id` de uma tabela de preços que a tua chave pode usar. [Obter tabela de preços](https://docs.anivahealth.com/pt/api/pricing/get-rate-card.md) devolve esse `id`. Por predefinição, usa a tabela da conta de faturação da tua chave de API; caso contrário, a de venda ao público.
`retail_cents` usa sempre a tabela de venda ao público.

**limit** `number`

Número máximo de resultados a devolver (1–1 000). Omite para devolver todo o catálogo
correspondente — é limitado (alguns milhares de registos, no máximo). Quando omitido,
`pagination.limit` devolve o mesmo valor de `total`.

**offset** `number` (default: 0)

Deslocamento de paginação. Tem de ser ≥ 0.

## Resposta

**data** `Biomarker[]`

Array de biomarcadores correspondentes à consulta.

**Campos do biomarcador**

**id** `number`

Identificador estável do biomarcador — passa este valor para [Adicionar biomarcadores
personalizados](https://docs.anivahealth.com/pt/api/appointments/add-individual-biomarkers.md).

**slug** `string`

Identificador seguro para URL.

**name** `string`

Nome de apresentação.

**description** `string | null`

Descrição detalhada, quando disponível.

**primary\_category** `string | null`

Categoria principal (por ex., `Hormones`, `Vitamins`).

**secondary\_category** `string | null`

Categoria secundária.

**type** `"clinical" | "genetic"`

Indica se este biomarcador é uma medição clínica ou um marcador genético.

**material** `string | null`

Material de amostra necessário (por ex., `serum`, `whole_blood`).

**unit** `object | null`

Unidade de medida predefinida. Usa `id` para referenciar em [Listar unidades](https://docs.anivahealth.com/pt/api/units/list-units.md)
se precisares de uma identidade estável mesmo após alterações de nome.

**Campos da unidade**

**id** `number`

Identificador estável da unidade de medida.

**title** `string`

Título canónico da unidade (por ex., `nmol/L`).

**display\_title** `string | null`

Título de apresentação legível.

**pricing** `object | null`

Quanto custa este biomarcador e como é vendido — consulta [objetos de preço](#objetos-de-preco). É
`null` **apenas** quando a tua chave não tem o scope `prices_view`; um biomarcador sem preço
definido pela Aniva continua a ser devolvido, com `pricing.price_cents: null`.

**pagination** `object`

**Campos de paginação**

**total** `number`

Total de registos correspondentes à consulta em todas as páginas.

**limit** `number`

Limite aplicado a esta página. Devolve o mesmo valor de `total` quando o parâmetro de consulta
`limit` foi omitido (todo o catálogo foi devolvido).

**offset** `number`

Deslocamento aplicado a esta página.

**has\_more** `boolean`

`true` quando existem mais páginas disponíveis.

## Objetos de preço

Os preços têm o mesmo formato em todos os locais onde aparecem — biomarcadores, painéis, a
[pré-visualização](https://docs.anivahealth.com/pt/api/appointments/preview-containers.md) da marcação e um [orçamento](https://docs.anivahealth.com/pt/api/pricing/quote-cart.md). [Preços](https://docs.anivahealth.com/pt/concepts/pricing.md) explica o modelo
subjacente; esta é a referência dos campos.

Todos os montantes são números inteiros em cêntimos.

**price\_cents** `integer | null`

Quanto isto custa na **tua** tabela de preços. `0` é um preço real de zero — o item não é vendido
separadamente e o bloco `requires` ou `positions` ao lado indica como é vendido. `null` é
diferente: a Aniva não definiu preço para ele, não é sem custo, não pode ser pedido e não soma
nada a nenhum total.

**retail\_cents** `integer | null`

O mesmo montante na tabela recomendada de venda ao público. Está sempre presente; é igual a
`price_cents` quando a tua chave já usa a tabela de venda ao público.

**tier** `"routine" | "specialty"`

Qual das duas tarifas Aniva da tua tabela definiu o preço deste marcador. Presente apenas quando
tem preço próprio.

**positions** `object[]`

As ofertas comerciais que incluem este biomarcador, da mais barata para a mais cara. Com
`price_cents: 0`, estas são a única forma de o pedir; com um `price_cents` positivo, são os
pacotes a que também pertence. Uma posição é faturada **uma vez** e é sempre entregue por inteiro.

**id** `string`

Identificador estável da posição. Liga-se a `via_position` na fatura de uma marcação.

**name** `string`

Nome da posição visível para o parceiro.

**price\_cents** `integer | null`

Quanto custa a posição inteira na tua tabela de preços, faturada uma vez. `retail_cents` surge ao lado.

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

Todos os biomarcadores que a posição fornece, incluindo o que consultaste.

**includes** `number[]`

Os restantes elementos além do biomarcador que consultaste — o que vem junto quando o compras.

**requires** `object[]`

Presente quando este biomarcador é um **rácio**. Encomendá-lo adiciona estes componentes ao carrinho com
os respetivos preços, e cada componente é pago uma só vez por carrinho, independentemente de quantos rácios dependam dele. O
`price_cents` do próprio rácio é faturado além dos seus componentes. A maioria dos rácios custa `0`. Cada
entrada inclui `id`, `name`, `price_cents` e `retail_cents`.

Um rácio cujos componentes não tenham todos preço fica totalmente fora do catálogo — nunca
aparece com `price_cents: null`.

Os painéis trazem apenas `price_cents` e `retail_cents`: um painel tem um único preço de catálogo,
sem posições nem componentes.

## Respostas de erro

| Estado | Descrição |
| - | - |
| `400` | Erro de validação — por exemplo, sem origem ou com duas origens, `limit` fora do intervalo ou `rate_card` desconhecido/não autorizado. |
| `403` | Proibido — falta o âmbito `panels_access`. |
| `404` | `location_id` não corresponde a nenhum local de análise. |
| `500` | Erro interno do servidor. |

```bash cURL theme={null}
curl --url 'https://anivahealth.com/api/v1/biomarkers?home_kit=true&limit=5' \
  --header 'x-api-key: YOUR_API_KEY'
```

```json 200 theme={null}
{
  "data": [
    {
      "id": 42,
      "slug": "vitamin-d-25-oh",
      "name": "Vitamin D (25-OH)",
      "description": "Serum 25-hydroxyvitamin D …",
      "primary_category": "Vitamins",
      "secondary_category": null,
      "type": "clinical",
      "material": "serum",
      "unit": { "id": 1, "title": "nmol/L", "display_title": null },
      "pricing": {
        "price_cents": 3952,
        "retail_cents": 4549,
        "tier": "specialty",
        "positions": [
          {
            "id": "b7d4c2e1-9a3f-4c8b-91d2-5e6f7a8b9c0d",
            "name": "Vitamin panel",
            "price_cents": 6900,
            "retail_cents": 7935,
            "biomarker_ids": [42, 43, 44],
            "includes": [43, 44]
          }
        ]
      }
    }
  ],
  "pagination": { "total": 17, "limit": 5, "offset": 0, "has_more": true }
}
```


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.