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

# Resultados

> Como funcionam os resultados laboratoriais e os documentos na API da Aniva: valores de biomarcadores, intervalos de referência, relatórios laboratoriais e webhooks de resultados.

Depois de a colheita de sangue ser confirmada e de o laboratório processar as amostras, os resultados ficam disponíveis na marcação. Os resultados são obtidos através de `GET /api/v1/appointments/{id}/results` e incluem resultados de biomarcadores clínicos, resultados de biomarcadores genéticos e documentos de relatórios do laboratório para transferência.

## Estado dos resultados

O campo `status` de nível superior na resposta dos resultados indica o progresso geral do processamento:

| Estado | Significado |
| - | - |
| `in_progress` | Algumas submissões ainda estão a ser processadas pelo laboratório. |
| `completed` | Todas as submissões foram encerradas e pelo menos uma enviou resultados. |
| `fault` | Todas as submissões falharam sem enviar resultados. Já não há resultados pendentes. |

Os resultados individuais na resposta têm o seu próprio estado por resultado (vê abaixo), por isso podes mostrar resultados parciais enquanto o estado geral ainda está em `in_progress`.

Para saberes quando os resultados mudam, subscreve os [webhooks](https://docs.anivahealth.com/pt/concepts/webhooks.md). `appointment.results.updated` é acionado em cada alteração do corpo dos resultados e `appointment.results.completed` é acionado quando o estado de nível superior passa para `completed`. As encomendas de kit de teste em casa enviam os mesmos eventos com o prefixo `home_kit_order.`. Cada evento inclui o URL dos resultados a obter. Podes continuar a consultar este endpoint periodicamente para reconciliar.

O array `submissions` divide o estado de nível superior por requisição de laboratório. Uma colheita de sangue que abranja vários tubos ou vários laboratórios tem várias entradas, cada uma com o `lab_code` (código de barras do tubo) com que foi registada e o seu próprio estado `in_progress` / `completed` / `fault`. Uma entrada `fault` foi rejeitada ou abandonada no laboratório e nunca vai enviar resultados: muitas vezes a amostra foi transferida para outro laboratório, que regista então a sua própria entrada. O estado de nível superior fica `completed` quando todas as entradas estiverem encerradas e pelo menos uma tiver enviado resultados. Cada resultado recebido e cada documento inclui o mesmo `lab_code`, para que saibas de que tubo veio um valor.

## Resultados clínicos

Os resultados clínicos representam medições padrão de biomarcadores sanguíneos — como níveis de vitamina D, colesterol, hormonas da tiroide, entre outros.

Cada resultado clínico inclui:

* **`id`** — o identificador da linha de resultado do laboratório. Mantém-se igual quando o laboratório corrige essa linha, por isso usa-o para fazer upsert. `null` para um resultado `planned`.
* **`biomarker_name`** e **`category`** — o que foi medido e o seu grupo (por exemplo, Vitaminas, Hormonas).
* **`lab_code`** — o código de laboratório (código de barras do tubo) com que o resultado foi registado, um dos códigos de laboratório da encomenda. `null` para um resultado `planned` e para resultados que o laboratório comunicou sem código.
* **`value`** e **`value_operator`** — a medição efetiva. O operador é `eq` (igual) para valores exatos, ou `lt`/`gt` quando o laboratório comunica um valor abaixo ou acima do intervalo mensurável.
* **`unit`** — a unidade de medição (por exemplo, ng/mL, µIU/mL).
* **`reference_range_lab`** — limites mínimo/máximo normais e ótimos comunicados pelo laboratório para este resultado, convertidos para a mesma escala de `value`. Um limite deixado em aberto pelo laboratório é `null`, pelo que um intervalo unilateral como `< 50` chega como `normal_min: null, normal_max: 50`. Cada resultado inclui o intervalo com o qual foi medido, para que um paciente com resultados de várias colheitas de sangue ou laboratórios tenha o intervalo certo para cada resultado.
* **`reference_range_lab_absent_reason`** — o motivo pelo qual `reference_range_lab` é `null`. `null` quando o intervalo existe e num resultado `planned`. Vê [Quando não existe intervalo do laboratório](#quando-nao-existe-intervalo-do-laboratorio).
* **`aniva_range`** — Valores de comparação compilados pela Aniva, na mesma escala de `value`. Variam consoante a idade, o sexo e a semana de gravidez. `normal_*` é o intervalo geral. `optimal_*` é um intervalo mais restrito. 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 com base neles. Usa `reference_range_lab` como referência 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.
* **`tested_at`** — a data em que a análise foi realizada.
* **`comment`** — anotação em texto livre do laboratório sobre este resultado específico (por exemplo, orientações sobre o intervalo de referência, avisos sobre a qualidade da amostra). `null` quando o laboratório não anexou nenhuma.
* **`status_reason`** — o motivo pelo qual um resultado `likely_wrong` é duvidoso, ou um resultado `fault` ou `undeliverable` é inutilizável. `null` para todos os outros estados. Distinto de `comment`, que é a própria nota do laboratório e está muitas vezes vazia em resultados com erro.
* **`origin`** — quem entregou o documento de onde vem o valor, com os mesmos valores de `origin` do documento abaixo. Um valor de um documento carregado (`member_upload`, `staff_upload`, `partner_upload`) resulta da leitura do ficheiro pela Aniva, e não de um relatório do laboratório: verifica-o face ao ficheiro antes de uso clínico. `null` para um resultado `planned`.
* **`lab_reported`** — a linha do relatório do laboratório executor, tal como impressa e sem conversão. Vê abaixo.

### Intervalos Aniva

`aniva_range` contém valores de comparação que a Aniva compilou a partir de fontes publicadas e
da sua própria curadoria. Os intervalos variam consoante a idade, o sexo e a semana de gravidez.
`sources` lista as fontes publicadas que a Aniva registou para os valores. A lista pode estar vazia.

> [!WARNING]
>
> Os valores são informação geral. Não são aconselhamento médico, não são um diagnóstico, não são um
> achado médico nem uma avaliação de um resultado. A Aniva não os fornece como dispositivo
> médico. A Aniva não compara um resultado com eles nem define nenhum indicador com base neles.
> `reference_range_lab` e a avaliação por um médico continuam a ser a referência para um resultado.

Regras para o teu produto:

* Mostra o intervalo Aniva apenas em complemento ao intervalo do laboratório, nunca em seu lugar.
* Se derivares um indicador, um aviso ou uma recomendação a partir do intervalo Aniva, fazes isso em
  teu próprio nome e sob a tua própria responsabilidade.
* Mostra o aviso do teu contrato com a Aniva sempre que mostrares o intervalo Aniva.

Para obteres acesso, assina o breve contrato sobre os intervalos Aniva. Depois adicionamos o
scope `aniva_ranges_view` à tua chave. Os valores podem mudar sem aviso prévio.

### Valores normalizados versus a linha própria do laboratório

`value`, `unit` e `reference_range_lab` estão normalizados: convertemos cada medição para a unidade canónica do biomarcador e apresentamo-la com o nosso próprio nome de biomarcador, para que o mesmo analito seja comparável entre laboratórios e ao longo do tempo. É isso que queres para analisar tendências e comparar entre laboratórios, e não é o que um médico vê no PDF do laboratório — a fosfatase alcalina impressa como `48 U/l (40 - 129)` chega-te como `0.8 µkat/L`.

`lab_reported` traz essa linha impressa em paralelo: o nome e o código do analito do laboratório, o valor e a unidade tal como impressos, o intervalo de referência tanto em texto (`< 50`, `> 55`, `40 - 129`) como nos próprios limites não convertidos do laboratório, além do indicador de valor anormal, do estado do resultado e da nota.

Usa `lab_reported` quando um humano estiver a reconciliar os teus dados com o relatório do laboratório, e os campos canónicos para tudo o que for calculado. Só os campos que o laboratório realmente enviou são preenchidos; nada em `lab_reported` é inferido, preenchido por omissão ou convertido, e todo o objeto é `null` quando não temos registo bruto para um resultado.

### Quando não existe intervalo do laboratório

Quando `reference_range_lab` é `null`, `reference_range_lab_absent_reason` indica-te porquê:

| Valor | Significado | Mostrar |
| - | - | - |
| `not_provided` | Não existe intervalo. O laboratório não enviou nenhum. | "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 de vida. | O texto em `lab_reported.reference_range` |
| `not_measured` | O resultado está `undeliverable`, por isso não há valor para comparar. | O `status_reason` |

Alguns laboratórios imprimem um alvo ou um nível de risco em vez de um intervalo de referência, por exemplo
`Ziel: <200. >240 hoch` ou `<5.7 neg >=6.5 pos`. Estes não entram em `reference_range_lab`, pelo que os seus
limites são `null` e o motivo é `lab_text_only`. Mostra o texto impresso tal como está.

Um intervalo unilateral como `< 20` é um intervalo. Chega em `reference_range_lab` com um limite
`null` e o motivo é `null`. Mantém o lado aberto sem o fechar quando o mostrares.

### Estados dos resultados clínicos

| Estado | Significado |
| - | - |
| `planned` | A análise foi pedida, mas os resultados ainda não chegaram do laboratório. |
| `received` | O laboratório devolveu um resultado. |
| `corrected` | Um revisor humano reviu o valor comunicado pelo laboratório. |
| `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. Vê `status_reason`. |
| `fault` | O laboratório entregou um resultado confirmado como errado — **não o uses clinicamente**. `value` ainda contém o valor errado; vê `status_reason`. |
| `undeliverable` | O laboratório não conseguiu produzir um valor. `value` é `null`; vê `status_reason`. |

> [!TIP]
>
> Ao mostrares resultados aos pacientes, usa diretamente o campo `value` — já reflete o
> valor corrigido quando existe.

> [!WARNING]
>
> Nunca apresentes um resultado `fault` como um achado — o seu `value` está preenchido, mas confirmado como incorreto.

## Resultados genéticos

Os resultados genéticos representam achados ao nível do gene a partir de análises de ADN. Cada resultado corresponde a um gene (por exemplo, APOE, MTHFR) e inclui:

* **`id`** — o identificador da linha de resultado do laboratório. Mantém-se igual quando o laboratório corrige essa linha, por isso usa-o para fazer upsert. `null` para um resultado `planned`.
* **`gene`** — o símbolo do gene.
* **`lab_code`** — o código de laboratório (código de barras do tubo) com que o resultado foi registado. `null` para um resultado `planned` e para resultados que o laboratório comunicou sem código.
* **`genotype`** — o genótipo detetado (por exemplo, E3/E4).
* **`clinical_significance`** — uma classificação do achado baseada no ACMG.
* **`risk_description`** — uma explicação legível por humanos do que significa o genótipo.
* **`comment`** — anotação em texto livre do laboratório sobre este resultado específico. `null` quando o laboratório não anexou nenhuma.
* **`status_reason`** — o motivo pelo qual um resultado `likely_wrong` é duvidoso, ou um resultado `fault` ou `undeliverable` é inutilizável. `null` para todos os outros estados.
* **`origin`** — quem entregou o documento de onde vem o valor, tal como nos resultados clínicos.
* **`variants`** — as variantes genéticas específicas detetadas, cada uma com detalhe ao nível de SNV.

### Valores de significado clínico

| Valor | Categoria |
| - | - |
| `pathogenic`, `likely_pathogenic` | Causadora ou provavelmente causadora de doença |
| `uncertain` | Variante de significado incerto (VUS) |
| `likely_benign`, `benign` | Não causadora de doença |
| `high_risk`, `moderate_risk`, `low_risk` | Classificação de nível de risco |
| `protective` | Variante protetora |
| `drug_response`, `poor_metabolizer`, `rapid_metabolizer` | Achados farmacogenómicos |

### Estados de resultados genéticos

| Estado | Significado |
| - | - |
| `planned` | O teste foi pedido, mas os resultados ainda não chegaram. |
| `received` | O laboratório devolveu um resultado. |
| `likely_wrong` | A verificação automática da Aniva ou o membro duvida do genótipo. Não confirmado. Consulta `status_reason`. |
| `fault` | O laboratório entregou um resultado confirmado como errado — **não usar clinicamente**. Consulta `status_reason`. |
| `undeliverable` | O laboratório não conseguiu produzir um genótipo. Consulta `status_reason`. |

### Estrutura da variante

Cada resultado genético contém um array `variants`. Cada variante inclui:

* **`name`** — nome comum (p. ex., APOE E4).
* **`clinical_significance`** — significado ao nível da variante (pode diferir do significado ao nível do gene).
* **`conditions`** — doenças/condições associadas com descrições.
* **`snvs`** — as variantes de nucleótido único subjacentes, cada uma com `rs_id`, `allele`, `reference_allele` e notação HGVS opcional.

## Documentos

O array `documents` na resposta de resultados contém referências a ficheiros de relatórios laboratoriais para transferência. Cada documento tem:

* **`id`** — um UUID de ficheiro. Passa este valor a `GET /api/v1/documents/{id}` para transferir o ficheiro.
* **`file_name`** — o nome do ficheiro, o mesmo que a transferência envia (p. ex., `20260405 - Quade Befund - 7642001234.pdf`).
* **`original_file_name`** — o nome do ficheiro exatamente como foi entregue pelo laboratório ou por quem o carregou (p. ex., `7642001234_B0012_FA_E.pdf`).
* **`origin`** — quem entregou o ficheiro: `lab`, `member_upload`, `staff_upload` ou `partner_upload` (carregaste-o com [Carregar documento](https://docs.anivahealth.com/pt/api/documents/upload-document.md)).
* **`content_type`** — o tipo de média do ficheiro (p. ex., `application/pdf`). A maioria dos relatórios são PDFs. Digitalizações carregadas podem ser imagens ou ficheiros CSV.
* **`etag`** — a versão do conteúdo do ficheiro; muda sempre que os bytes mudam. Guarda-a e transfere novamente apenas quando mudar. É a entity tag HTTP padrão, tal como usada no S3 ou no Google Cloud Storage.
* **`size_bytes`** — o tamanho do ficheiro em bytes.
* **`lab_code`** — o código de laboratório (código de barras do tubo) a que o relatório pertence; `null` quando o laboratório não registou nenhum.

> [!NOTE]
>
> O acesso aos documentos é validado com base no perfil a que o documento pertence.

## Enviar resultados por e-mail ao cliente

Podes avisar o cliente por e-mail de que os resultados estão prontos. Chama
[Enviar resultados por e-mail](https://docs.anivahealth.com/pt/api/appointments/email-results.md) para uma marcação ou
[Enviar resultados por e-mail](https://docs.anivahealth.com/pt/api/home-kit-orders/email-results.md) para um pedido de kit de teste em casa. Cada chamada envia um e-mail.
As chamadas não são deduplicadas.

* O e-mail vai para o `email` do perfil. Um endereço `@aniva.email` provisório é recusado.
* O e-mail mostra o nome e o logótipo do grupo de perfis principal do perfil.
* O e-mail está no `language` do perfil, inglês por predefinição.
* Define `with_reports` como `true` para anexar os relatórios laboratoriais.
* Adiciona `note` para mostrar uma nota pessoal no e-mail, no máximo 1 000 caracteres.

Se o perfil tiver desativado os e-mails transacionais, a chamada devolve `409` com o motivo
`unsubscribed`. Para voltar a ativá-los, define `transactional_emails_enabled` como `true` com
[Atualizar perfil](https://docs.anivahealth.com/pt/api/profiles/update-profile.md).

## E-mails de resultados prontos

Podes receber um e-mail quando os resultados de uma reserva estiverem prontos. Define `results_ready_emails` com até 5
endereços em [Criar marcação](https://docs.anivahealth.com/pt/api/appointments/create-appointment.md) ou
[Criar pedido de kit de teste em casa](https://docs.anivahealth.com/pt/api/home-kit-orders/create-home-kit.md). Altera a lista mais tarde com
[Atualizar marcação](https://docs.anivahealth.com/pt/api/appointments/update-appointment.md) ou
[Atualizar pedido de kit de teste em casa](https://docs.anivahealth.com/pt/api/home-kit-orders/update-home-kit.md); `[]` desativa os e-mails.

* Pede-nos para definirmos endereços de e-mail predefinidos para o teu grupo de perfis. Uma reserva criada sem
  `results_ready_emails` recebe-os. Uma lista substitui-os nessa reserva, por isso inclui o teu
  endereço de e-mail predefinido para o manter. `[]` não envia nenhum e-mail.
* Cada endereço recebe um e-mail assim que todos os resultados laboratoriais da reserva forem finais.
* Um endereço adicionado depois de os resultados serem finais recebe o e-mail de imediato.
* O e-mail tem uma ligação para a página de resultados no painel de administração da Aniva. O cliente não o recebe.
* A tua chave precisa de acesso `results_view` ao paciente. Sem isso, o pedido devolve `403`.

## Mostrar resultados na tua app

[Criar sessão incorporada](https://docs.anivahealth.com/pt/api/profiles/create-embed-session.md) devolve um URL de utilização única para uma página de
resultados só de leitura. Abre-o numa WebView da tua app para que o paciente veja os resultados sem iniciar sessão.

* A tua chave precisa dos scopes `embed` e `results_view` para o paciente. Pede à Aniva o scope
  `embed`.
* Chama-o a partir do teu servidor sempre que o paciente abrir os resultados. O URL funciona uma vez e durante
  5 minutos, e a página mantém depois uma sessão de 60 minutos.
* `route` abre uma das páginas que disponibilizamos: a lista de biomarcadores, um biomarcador ou o Twin 3D.
* `appearance` define o tema, a cor dos botões e das ligações e se o teu logótipo é mostrado.
* `report` limita a página a uma marcação, a um pedido de kit de teste em casa ou a um relatório laboratorial que
  carregaste com `POST /api/v1/documents`. O paciente vê então apenas os resultados desse relatório.
* A página mostra apenas resultados laboratoriais, tal como esta API. Não mostra ficheiros, chat nem definições.

## Exemplo de resposta de resultados

```json theme={null}
{
  "status": "in_progress",
  "submissions": [
    {
      "lab_code": "7642001234",
      "status": "in_progress"
    }
  ],
  "clinical_results": [
    {
      "id": "3f2b8c1e-5d4a-4e7b-9a6c-2d1f0e8b7a54",
      "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": "b7e41d09-2c6f-4a83-8f15-6e9d3a0c4b21",
      "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"
    }
  ]
}
```


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