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

# Obter resultados laboratoriais

> Obter os resultados laboratoriais clínicos e genéticos de uma encomenda de kit de teste em casa

Obtém os resultados de laboratório clínicos e genéticos de uma encomenda de kit de teste em casa, juntamente com as referências de documento dos PDF de relatórios de laboratório.

Todos os biomarcadores pedidos para o kit aparecem na resposta, para que possas acompanhar toda a encomenda e não apenas o que já chegou. Os resultados são registados sob o `lab_code` da encomenda — o pedido ao laboratório é feito na [ativação](https://docs.anivahealth.com/pt/api/home-kit-orders/activate-home-kit.md) e o laboratório comunica os marcadores individualmente à medida que são analisados, pelo que um payload parcial é normal e o `status` de nível superior mantém-se `in_progress` até ao relatório final. Lê o `status` de cada resultado antes de usares o respetivo `value`:

* As análises ainda pendentes aparecem com o estado `planned` enquanto a encomenda está `in_progress`. Podes chamar este endpoint antes da ativação — todos os marcadores pedidos surgem então como `planned`.
* Os resultados que o laboratório entregou mas que **não** devem ser usados clinicamente aparecem com o estado `fault` ou `undeliverable`, e incluem um `status_reason` a explicar porquê. Um resultado `fault` ainda tem o seu `value` preenchido — esse valor está errado. Nunca o apresentes como um resultado válido.
* Os resultados de que a Aniva ou o membro duvida aparecem com o estado `likely_wrong` e um `status_reason`. O valor não está confirmado. Não o mostres como um resultado válido sem revisão.

Usa [Descarregar documento](https://docs.anivahealth.com/pt/api/documents/download-document.md) para descarregar os PDF dos relatórios laboratoriais referenciados no array `documents`.

Não precisas de fazer polling a este endpoint. Subscreve os [webhooks](https://docs.anivahealth.com/pt/concepts/webhooks.md) `home_kit_order.results.updated` ou `home_kit_order.results.completed` e chama-o quando chegar um evento. O polling continua a funcionar como alternativa.

Requer o scope `results_view` — os resultados de laboratório e os documentos estão sempre protegidos por ele, tal como os resultados de marcações e [Transferir documento](https://docs.anivahealth.com/pt/api/documents/download-document.md) — bem como o scope `home_kit_orders_view` ou `home_kit_orders_manage` para aceder à própria encomenda do kit.

## Pedido

### Parâmetros de caminho

**id** `string` *required*

Identificador único (UUID) da encomenda de kit de teste em casa da qual obter resultados.

## Resposta

Em caso de sucesso, a API devolve `200 OK` com o objeto de resultados.

**status** `string` *required*

Estado geral dos resultados. Um de:

* `in_progress` — algumas requisições ainda estão no laboratório.
* `completed` — todas as requisições foram fechadas e pelo menos uma enviou relatório.
* `fault` — todas as requisições falharam sem enviar relatório. Nada é devido.

**submissions** `object[]` *required*

Uma entrada por requisição laboratorial — uma colheita de sangue repartida por vários tubos ou laboratórios tem
várias. O `status` de nível superior passa a `completed` assim que todas as entradas forem fechadas e uma tiver enviado relatório.

**objeto submission**

**lab\_code** `string`

Código laboratorial (código de barras do tubo) sob o qual esta requisição foi registada. Pode ser `null` quando o laboratório não registou
nenhum.

**status** `string` *required*

`in_progress` enquanto o laboratório ainda estiver a trabalhar nela, `completed` assim que o relatório for
final, ou `fault` quando a requisição foi rejeitada ou abandonada e nunca enviará relatório — a
amostra é frequentemente transferida para outro laboratório, que depois regista a sua própria entrada.

**clinical\_results** `object[]` *required*

Array de resultados de biomarcadores clínicos.

**objeto de resultado clínico**

**id** `string`

Identificador da linha de resultado laboratorial (UUID). Mantém-se igual quando o laboratório corrige essa linha, por isso usa-o para fazer upsert. `null` para um resultado `planned`.

**status** `string` *required*

Estado do resultado. Um dos seguintes:

* `planned` — pedido, ainda não devolvido pelo laboratório. `value` é `null`.
* `received` — entregue pelo laboratório.
* `corrected` — entregue e depois revisto por uma pessoa. `value` é o valor corrigido.
* `likely_wrong` — a verificação automática da Aniva ou o membro duvida do valor. Não confirmado: não o mostres como um achado sem revisão. Consulta `status_reason`.
* `fault` — entregue, mas confirmado como errado; **não uses clinicamente**. `value` é preenchido com o valor errado. Consulta `status_reason`.
* `undeliverable` — o laboratório não conseguiu produzir um valor. `value` é `null`. Consulta `status_reason`.

**status\_reason** `string` *required*

Motivo pelo qual o resultado é duvidoso ou inutilizável. Preenchido para `likely_wrong`, `fault` e `undeliverable`, `null` para todos os outros estados.

Distinto de `comment`, que é a nota do próprio laboratório no relatório — `comment` está vazio na maioria dos resultados com erro, por isso trata `status_reason` como a explicação oficial.

**lab\_code** `string`

Código laboratorial (código de barras do tubo) sob o qual o resultado foi registado — um dos códigos laboratoriais do pedido. `null` para um resultado `planned` e para resultados que o laboratório reportou sem código.

**biomarker\_id** `integer` *required*

Identificador do biomarcador.

**biomarker\_name** `string` *required*

Nome de apresentação do biomarcador.

**category** `string`

Categoria do biomarcador (p. ex., Hormonas, Vitaminas). Pode ser `null`.

**value** `number`

Valor efetivo do resultado (corrigido se disponível, caso contrário em bruto). Pode ser `null`.

**value\_operator** `string`

Operador de comparação para o valor: `eq` (igual a), `lt` (menor que) ou `gt` (maior que). Pode ser `null`.

**unit\_id** `integer`

Identificador da unidade de medida. Pode ser `null`.

**unit** `string`

Nome de apresentação da unidade de medida. Pode ser `null`.

**reference\_range\_lab** `object`

Intervalos de referência reportados pelo laboratório para **este** resultado, convertidos para a mesma unidade que `value`. `null` quando o laboratório não reportou nenhum intervalo.

Um limite deixado em aberto pelo laboratório mantém-se `null`, pelo que um intervalo unilateral preenche apenas a sua própria extremidade — um limite superior chega como `normal_min: null, normal_max: 50`, e um inferior como `normal_min: 55, normal_max: null`. Não leias um limite `null` como zero ou sem limite por omissão; lê-o como "o laboratório não definiu nenhum limite desse lado".

Cada resultado inclui o intervalo face ao qual foi medido, pelo que um paciente cujos resultados abrangem várias colheitas de sangue ou vários laboratórios obtém o intervalo correto por resultado, em vez do mais recente.

**intervalo de referência**

**normal\_min** `number`

Limite inferior do intervalo normal. Pode ser `null`.

**normal\_max** `number`

Limite superior do intervalo normal. Pode ser `null`.

**optimal\_min** `number`

Limite inferior do intervalo ótimo. Pode ser `null`.

**optimal\_max** `number`

Limite superior do intervalo ótimo. Pode ser `null`.

**reference\_range\_lab\_absent\_reason** `string`

Motivo pelo qual `reference_range_lab` é `null`. `null` quando `reference_range_lab` está presente e num resultado `planned`.

* `not_provided`: não existe intervalo. O laboratório não enviou nenhum. Mostra "Não aplicável".
* `lab_text_only`: o laboratório imprimiu apenas texto, como um alvo, um nível de risco ou um intervalo por fase da vida. Mostra `lab_reported.reference_range`.
* `not_measured`: o resultado é `undeliverable`, pelo que não há valor para comparar. Mostra `status_reason`.

**aniva\_range** `object`

Valores de comparação compilados pela Aniva, na mesma escala que `value`. Variam consoante a idade, o sexo e a semana de gravidez. `normal_*` é o intervalo geral. `optimal_*` é um intervalo mais estreito. Os valores são apenas informativos. Não são aconselhamento médico, não são um diagnóstico nem uma avaliação do resultado. A Aniva não define nenhum indicador face a eles. Usa `reference_range_lab` como padrão para o resultado. `null` quando a tua chave não tem o scope `aniva_ranges_view` ou quando a Aniva não tem valores para este biomarcador.

**intervalo de referência**

**normal\_min** `number`

Limite inferior do intervalo normal. Pode ser `null`.

**normal\_max** `number`

Limite superior do intervalo normal. Pode ser `null`.

**optimal\_min** `number`

Limite inferior do intervalo ótimo. Pode ser `null`.

**optimal\_max** `number`

Limite superior do intervalo mais estreito. Pode ser `null`.

**sources** `object[]`

Fontes publicadas que a Aniva registou para estes valores. Cada entrada tem um `title` e um `url`. O `url` pode ser `null`. A lista está vazia quando a Aniva não registou nenhuma fonte.

**tested\_at** `string`

Data em que o teste foi realizado no formato `YYYY-MM-DD`. Pode ser `null`.

**comment** `string`

Comentário opcional sobre o resultado. Pode ser `null`.

**origin** `string`

Quem entregou o documento de onde provém este valor, tal como `origin` no documento. Um valor proveniente de um documento carregado resulta da leitura do ficheiro pela Aniva, não de um relatório laboratorial. `null` para um resultado `planned`.

**lab\_reported** `object`

A linha do relatório do próprio laboratório executante, literalmente — para comparar este payload com o PDF do laboratório. Pode ser `null` quando não temos registo em bruto do resultado.

Todos os outros campos de um resultado são normalizados: `value` e `unit` são convertidos para a unidade por omissão do biomarcador, e `biomarker_name` é o nosso nome para o analito, não o do laboratório. Os campos abaixo não o são. Trata-os como a referência tal como impressa e os campos canónicos como a verificação cruzada de consistência.

Os números aqui são os próprios limites do laboratório na sua própria escala — `reference_range_min` e `reference_range_max` **não** têm conversão de unidade e irão diferir de `reference_range_lab` sempre que as duas escalas forem diferentes. Um limite deixado em aberto pelo laboratório mantém-se `null`; nada é inferido nem preenchido por omissão.

**reportado pelo laboratório**

**name** `string`

Nome do analito tal como impresso pelo laboratório. Pode ser `null`.

**code** `string`

Código de analito próprio do laboratório. Pode ser `null`.

**category** `string`

Título da secção do relatório, p. ex., `Klinische Chemie`. Pode ser `null`.

**value** `string`

Valor tal como impresso. Uma string, para que resultados não numéricos se mantenham intactos (`<0.04`, `negativ`, `1:100`). Pode ser `null`.

**unit** `string`

Unidade tal como impressa, p. ex., `U/l`. Pode ser `null`.

**reference\_range** `string`

Intervalo de referência tal como impresso, incluindo limites unilaterais: `40 - 129`, `< 50`, `> 55`. Pode ser `null`.

**reference\_range\_min** `number`

Limite inferior do laboratório, sem conversão. `null` para um intervalo que o laboratório deixou aberto em baixo.

**reference\_range\_max** `number`

Limite superior do laboratório, sem conversão. `null` para um intervalo que o laboratório deixou aberto em cima.

**flag** `string`

Indicador de anomalia do laboratório para esta linha: `normal`, `high`, `low`, `critical_high`, `critical_low`, `abnormal`. Um código que não reconhecemos passa tal como o laboratório o enviou. Pode ser `null`.

**result\_status** `string`

Estado do resultado do laboratório: `final`, `preliminary`, `correction`, `incomplete`, `partial`, `deleted`, `cannot_be_obtained`. Um valor `preliminary` ainda pode ser revisto. Um [webhook](https://docs.anivahealth.com/pt/concepts/webhooks.md)`results.updated` posterior indica-te quando voltar a obter os dados. Pode ser `null`.

**comment** `string`

Nota própria do laboratório sobre esta linha. O espaçamento de colunas é reduzido; o texto mantém-se inalterado. Pode ser `null`.

**genetic\_results** `object[]` *required*

Array de resultados de biomarcadores genéticos.

**objeto de resultado genético**

**id** `string`

Identificador da linha de resultado laboratorial (UUID). Mantém-se igual quando o laboratório corrige essa linha, por isso usa-o para fazer upsert. `null` para um resultado `planned`.

**status** `string` *required*

Estado do resultado. Um dos seguintes:

* `planned` — pedido, ainda não devolvido pelo laboratório.
* `received` — entregue pelo laboratório.
* `likely_wrong` — a verificação automática da Aniva ou o membro duvida do genótipo. Não confirmado. Consulta `status_reason`.
* `fault` — entregue, mas confirmado como errado; **não uses clinicamente**. Consulta `status_reason`.
* `undeliverable` — o laboratório não conseguiu produzir um genótipo. Consulta `status_reason`.

**status\_reason** `string` *required*

Motivo pelo qual o resultado é duvidoso ou inutilizável. Preenchido para `likely_wrong`, `fault` e `undeliverable`, `null` para todos os outros estados.

**lab\_code** `string`

Código laboratorial (código de barras do tubo) sob o qual o resultado foi registado. `null` para um resultado `planned` e para resultados que o laboratório reportou sem código.

**biomarker\_id** `integer` *required*

Identificador do biomarcador (gene).

**gene** `string` *required*

Símbolo do gene (p. ex., APOE, MTHFR).

**genotype** `string`

Apresentação do genótipo (p. ex., E3/E4). Pode ser `null`.

**clinical\_significance** `string`

Significado clínico geral. Um dos seguintes: `pathogenic`, `likely_pathogenic`, `uncertain`, `likely_benign`, `benign`, `high_risk`, `moderate_risk`, `low_risk`, `protective`, `drug_response`, `poor_metabolizer` ou `rapid_metabolizer`. Pode ser `null`.

**risk\_description** `string`

Descrição do risco para este genótipo. Pode ser `null`.

**tested\_at** `string`

Data em que o teste foi realizado no formato `YYYY-MM-DD`. Pode ser `null`.

**comment** `string`

Comentário opcional sobre o resultado. Pode ser `null`.

**origin** `string`

Quem entregou o documento de onde provém este valor, tal como `origin` no documento. Um valor proveniente de um documento carregado resulta da leitura do ficheiro pela Aniva, não de um relatório laboratorial. `null` para um resultado `planned`.

**variants** `object[]` *required*

Variantes genéticas detetadas.

**objeto de variante**

**name** `string` *required*

Nome comum da variante (por ex., APOE E4).

**clinical\_significance** `string`

Significado clínico ao nível da variante. Pode ser `null`.

**description** `string`

Descrição da variante. Pode ser `null`.

**hgvs\_c** `string`

Notação HGVS de ADN codificante. Pode ser `null`.

**hgvs\_p** `string`

Notação HGVS de proteína. Pode ser `null`.

**conditions** `object[]` *required*

Condições associadas.

**objeto de condição**

**condition** `string` *required*

Nome da condição/doença.

**association\_description** `string`

Descrição da associação entre a variante e a condição. Pode ser `null`.

**badge** `string`

Texto curto da etiqueta para apresentação. Pode ser `null`.

**snvs** `object[]` *required*

Variantes de nucleótido único que definem esta variante.

**objeto SNV**

**rs\_id** `string` *required*

Identificador dbSNP (por ex., rs429358).

**allele** `string` *required*

Alelo da variante (`A`, `C`, `G`, `T`, `del`, `ins` ou `undetermined`).

**reference\_allele** `string` *required*

Alelo de referência populacional.

**hgvs\_c** `string`

Notação HGVS de ADN codificante. Pode ser `null`.

**hgvs\_p** `string`

Notação HGVS de proteína. Pode ser `null`.

**documents** `object[]` *required*

Documentos de relatório de laboratório. Usa `GET /api/v1/documents/{id}` para transferir cada ficheiro.

**objeto de documento**

**id** `string` *required*

Identificador do ficheiro (UUID). Passa-o a [Transferir documento](https://docs.anivahealth.com/pt/api/documents/download-document.md) para obter o ficheiro.

**file\_name** `string` *required*

Nome do ficheiro. [Transferir documento](https://docs.anivahealth.com/pt/api/documents/download-document.md) envia o mesmo nome em `Content-Disposition`. Contém uma data, o título do documento e o código de laboratório, por ex. `20260405 - Quade Befund - 7642001234.pdf`. Usa-o apenas para apresentação. Lê o código de laboratório em `lab_code`, não no nome.

**original\_file\_name** `string` *required*

Nome do ficheiro exatamente como a origem o entregou, por ex. `7642100312_B0012_FA_V.pdf` do laboratório ou o nome dado pelo membro num carregamento. A Aniva não o altera.

**origin** `string` *required*

Quem entregou o ficheiro. Um de `lab` (o laboratório enviou-o), `member_upload` (o membro carregou-o), `staff_upload` (a equipa da Aniva carregou-o) ou `partner_upload` (tu carregaste-o com [Carregar documento](https://docs.anivahealth.com/pt/api/documents/upload-document.md)).

**content\_type** `string` *required*

Tipo de conteúdo do ficheiro, por ex. `application/pdf`, `image/jpeg` ou `text/csv`. A maioria dos relatórios de laboratório está em PDF.

**etag** `string`

Versão do conteúdo do ficheiro. Muda sempre que os bytes mudam, por isso compara-a com o valor que guardaste para ver se precisas de transferir novamente. [Transferir documento](https://docs.anivahealth.com/pt/api/documents/download-document.md) envia-a entre aspas como o cabeçalho HTTP padrão `ETag`. Pode ser `null` quando o ficheiro guardado está em falta.

**size\_bytes** `integer`

Tamanho do ficheiro em bytes. Pode ser `null` quando o ficheiro guardado está em falta.

**lab\_code** `string`

Código de laboratório (código de barras do tubo) a que o relatório pertence. Pode ser `null` quando o laboratório não registou nenhum.

## Chamadas repetidas

A Aniva guarda a resposta deste endpoint durante 60 minutos para cada chave de API. Uma chamada repetida dentro
deste período recebe a resposta guardada enquanto a encomenda de kit de teste em casa e os respetivos resultados não sofrerem alterações. Após uma alteração, recebes uma nova
resposta. Os cabeçalhos `Cache-Status` e `Age` mostram que a resposta está
guardada e há quanto tempo.

Para saberes de uma alteração de imediato, subscreve os eventos de webhook `home_kit_order.results.updated`, `home_kit_order.results.completed` e `home_kit_order.results.fault`.
Consulta [Leituras repetidas](https://docs.anivahealth.com/pt/concepts/webhooks.md#leituras-repetidas).

## Respostas de erro

| Estado | Descrição |
| - | - |
| `400` | Formato de ID inválido — o valor fornecido não é um UUID válido. |
| `403` | Proibido — falta o scope `results_view` na tua chave de API, faltam ambos os scopes `home_kit_orders_view` e `home_kit_orders_manage`, ou a encomenda de kit de teste em casa está fora do teu contexto de acesso. |
| `404` | Encomenda de kit de teste em casa não encontrada. |
| `500` | Erro interno do servidor. |

```bash cURL theme={null}
curl --request GET \
  --url https://anivahealth.com/api/v1/home-kit-orders/d1e2f3a4-5b6c-4d7e-8f9a-0b1c2d3e4f5a/results \
  --header 'x-api-key: YOUR_API_KEY'
```

```json 200 theme={null}
{
  "status": "in_progress",
  "submissions": [
    {
      "lab_code": "7642001234",
      "status": "in_progress"
    }
  ],
  "clinical_results": [
    {
      "id": "e9f1a3c5-6b7d-4c2e-8a4f-1d3b5c7e9f02",
      "status": "received",
      "status_reason": null,
      "lab_code": "7642001234",
      "biomarker_id": 104,
      "biomarker_name": "Vitamin D",
      "category": "Vitamins",
      "value": 38.5,
      "value_operator": "eq",
      "unit_id": 1,
      "unit": "ng/mL",
      "reference_range_lab": {
        "normal_min": 30,
        "normal_max": 100,
        "optimal_min": null,
        "optimal_max": null
      },
      "reference_range_lab_absent_reason": null,
      "aniva_range": {
        "normal_min": 30,
        "normal_max": 100,
        "optimal_min": 30,
        "optimal_max": 60,
        "sources": [
          {
            "title": "Example source title",
            "url": "https://example.com/source"
          }
        ]
      },
      "tested_at": "2026-04-05",
      "comment": null,
      "origin": "lab",
      "lab_reported": {
        "name": "Vitamin D (25-OH)",
        "code": "vitd",
        "category": "Endokrinologie",
        "value": "38.5",
        "unit": "ng/ml",
        "reference_range": "30 - 100",
        "reference_range_min": 30,
        "reference_range_max": 100,
        "flag": "normal",
        "result_status": "final",
        "comment": null
      }
    },
    {
      "id": null,
      "status": "planned",
      "status_reason": null,
      "lab_code": null,
      "biomarker_id": 79,
      "biomarker_name": "Thyroid-Stimulating Hormone (TSH)",
      "category": "Hormones",
      "value": null,
      "value_operator": null,
      "unit_id": null,
      "unit": null,
      "reference_range_lab": null,
      "reference_range_lab_absent_reason": null,
      "aniva_range": null,
      "tested_at": null,
      "comment": null,
      "origin": null,
      "lab_reported": null
    }
  ],
  "genetic_results": [
    {
      "id": "1b3d5f7a-9c2e-4a6b-8d0f-2e4a6c8b0d13",
      "status": "received",
      "status_reason": null,
      "lab_code": "7642001234",
      "biomarker_id": 348,
      "gene": "APOE",
      "genotype": "E3/E4",
      "clinical_significance": "moderate_risk",
      "risk_description": "Carriers of one APOE E4 allele have a moderately increased risk of Alzheimer's disease.",
      "tested_at": "2026-04-05",
      "comment": null,
      "origin": "lab",
      "variants": [
        {
          "name": "APOE E4",
          "clinical_significance": "moderate_risk",
          "description": "The E4 allele is associated with increased Alzheimer's risk.",
          "hgvs_c": "c.388T>C",
          "hgvs_p": "p.Cys130Arg",
          "conditions": [
            {
              "condition": "Alzheimer's disease",
              "association_description": "Increased risk with one E4 allele",
              "badge": "Moderate Risk"
            }
          ],
          "snvs": [
            {
              "rs_id": "rs429358",
              "allele": "C",
              "reference_allele": "T",
              "hgvs_c": "c.388T>C",
              "hgvs_p": "p.Cys130Arg"
            }
          ]
        }
      ]
    }
  ],
  "documents": [
    {
      "id": "f8a1b2c3-d4e5-4f6a-7b8c-9d0e1f2a3b4c",
      "file_name": "20260405 - Quade Befund - 7642001234.pdf",
      "original_file_name": "7642001234_B0012_FA_E.pdf",
      "origin": "lab",
      "content_type": "application/pdf",
      "etag": "56104b36f860cfd5b41efc716fdf7b6f",
      "size_bytes": 258341,
      "lab_code": "7642001234"
    }
  ]
}
```

```json 404 theme={null}
{
  "error": "Home kit order not found"
}
```


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