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

# Criar sessão de incorporação

> Obter um URL de utilização única que mostra os resultados laboratoriais de um perfil na tua app

Obtém um URL que mostra os resultados laboratoriais de um perfil numa página só de leitura. Abre o URL numa WebView da tua app ou num separador do navegador. Chama este endpoint a partir do teu servidor sempre que o utilizador abre os resultados e nunca guardes o URL em cache.

Requer os scopes `embed` e `results_view` num grupo de perfis do perfil. A Aniva concede o scope `embed` mediante pedido. Sem um dos dois scopes, o pedido devolve `403`.

> [!NOTE]
>
> O URL funciona uma vez e durante 5 minutos. Quando abre, a página inicia uma sessão de 60 minutos
> que só essa página mantém. Arquiva a tua chave API para fechar todas as páginas abertas de uma vez.

## Pedido

### Parâmetros de caminho

**id** `string` *required*

Identificador único (UUID) do perfil cujos resultados a página mostra.

### Corpo

O corpo é opcional. Sem corpo, o URL abre a lista de biomarcadores no idioma do perfil.

**language** `string`

Idioma da página: `en`, `bg`, `ca`, `cs`, `da`, `de`, `el`, `es`, `et`, `fi`, `fr`, `ga`, `hr`, `hu`, `is`, `it`, `lb`, `lt`, `lv`, `mt`, `nl`, `no`, `pl`, `pt`, `ro`, `ru`, `sk`, `sl`, `sr`, `sv`, `tr` ou `uk`. Predefinição: o idioma do perfil.

**route** `object`

A página que o URL abre. Predefinição: `{ "name": "biomarkers" }`. Qualquer outro `name` devolve `400`.

**páginas lançadas**

**name** `string` *required*

Um dos seguintes:

* `biomarkers`: a lista de todos os biomarcadores com os respetivos resultados mais recentes.
* `biomarker`: a página de detalhe de um biomarcador, com a sua tendência, intervalos e explicação. Requer `biomarker_id`.
* `twin`: o corpo 3D com uma classificação por área de saúde. O utilizador seleciona uma área para ver os respetivos biomarcadores.

**biomarker\_id** `integer`

Apenas para `biomarker`. O `biomarker_id` do biomarcador, tal como nos resultados, por exemplo `104`. Usa o id, não o slug: um slug pode mudar, o id mantém-se.

**report** `object`

Limita cada página a um relatório laboratorial do perfil. Predefinição: todos os relatórios do
perfil. Envia exatamente um dos três ids. A lista, a tendência de um biomarcador e o Twin passam
a mostrar apenas os resultados desse relatório, e a página oculta o filtro de marcações. O
utilizador não pode abrir outro relatório com este URL.

**propriedades**

**appointment\_id** `string`

O `id` de uma marcação do perfil. A tua chave tem de ter acesso a ela, tal como em
[Obter resultados de laboratório](https://docs.anivahealth.com/pt/api/appointments/get-results.md). Se não tiver, este endpoint
devolve `404`, não `403`.

**home\_kit\_order\_id** `string`

O `id` de uma encomenda de kit de teste em casa do perfil. A tua chave tem de ter acesso a
ela, tal como em [Obter resultados de laboratório](https://docs.anivahealth.com/pt/api/home-kit-orders/get-results.md) para
encomendas de kit de teste em casa, e também precisa de `home_kit_orders_view` ou
`home_kit_orders_manage`.

**document\_id** `string`

O `id` de um relatório laboratorial que carregaste para o perfil com
[Carregar documento](https://docs.anivahealth.com/pt/api/documents/upload-document.md). A tua chave tem de ter acesso a ele, tal
como em [Obter resultados do documento](https://docs.anivahealth.com/pt/api/documents/get-document-results.md). Se não tiver,
este endpoint devolve `404`, não `403`. A página mostra a data da análise laboratorial, ou a
data de carregamento quando ainda não foi lido nenhum valor. Enquanto a Aniva lê o documento e
ainda não tem nenhum valor, cada página indica ao utilizador para a abrir novamente dentro de
alguns minutos.

**appearance** `object`

O aspeto da página. A API adiciona-o ao URL como parâmetros de pesquisa.

**propriedades**

**theme** `string`

`light` ou `dark`. Predefinição: a definição de sistema do dispositivo.

**primary\_color** `string`

Cor hexadecimal de botões e ligações, 3 ou 6 dígitos, com ou sem `#`, por exemplo `0f766e`.
Predefinição: a cor da marca do teu grupo de perfis, caso contrário o laranja da Aniva. Os
botões mantêm texto branco, por isso escolhe uma cor escura.

**show\_logo** `boolean`

Mostrar o logótipo do teu grupo de perfis acima dos resultados. Predefinição: `true`.

> [!TIP]
>
> Também podes acrescentar os parâmetros de aparência a um URL devolvido, antes do fragmento
> `#token=`: `theme=light|dark`, `primary=<hex>` e `logo=0`. A página ignora um valor inválido. A
> imagem do logótipo vem sempre do teu grupo de perfis, nunca do URL.

## Resposta

Em caso de sucesso, a API devolve `201 Created`.

**url** `string` *required*

O URL da página. O token de abertura está no fragmento `#token=`, pelo que um navegador nunca o
envia para um servidor. Abre-o uma vez.

**expires\_at** `string` *required*

Instante ISO 8601 após o qual o URL não pode ser aberto.

A sessão não está limitada a uma página. Dentro do embed, o utilizador pode passar do Twin para um biomarcador e alternar entre a lista e as páginas de detalhe. A página mostra apenas resultados de laboratório: não mostra valores calculados pela Aniva, ficheiros, chat nem definições.

## Respostas de erro

| Estado | Descrição |
| - | - |
| `400` | Erro de validação — ID de perfil inválido, `route.name` desconhecido, `biomarker_id` inválido, cor inválida ou um `report` sem exatamente um UUID válido. |
| `403` | Proibido — falta o scope `embed` ou `results_view` na tua chave API, ou o scope de kit de teste em casa para um relatório de encomenda de kit de teste em casa, ou o perfil está fora do teu contexto de acesso. |
| `404` | Perfil não encontrado, nenhum biomarcador tem este `biomarker_id`, o `report` não é uma marcação, encomenda de kit de teste em casa nem documento carregado deste perfil, ou o relatório está fora do teu acesso. Este endpoint devolve `404`, não `403`, para não mostrar que o relatório existe. |
| `500` | Erro interno do servidor. |

```bash cURL theme={null}
curl --request POST \
  --url https://anivahealth.com/api/v1/profiles/a3f1c2d4-8b7e-4f2a-9c1d-2e3f4a5b6c7d/embed-sessions \
  --header 'x-api-key: YOUR_API_KEY' \
  --header 'Content-Type: application/json' \
  --data '{
    "language": "de",
    "route": { "name": "biomarker", "biomarker_id": 104 },
    "report": { "appointment_id": "8d2e4f6a-1b3c-4d5e-9f70-a1b2c3d4e5f6" },
    "appearance": { "theme": "light", "primary_color": "0f766e" }
  }'
```

```bash One uploaded document theme={null}
curl --request POST \
  --url https://anivahealth.com/api/v1/profiles/{id}/embed-sessions \
  --header 'Authorization: Bearer <api_key>' \
  --header 'Content-Type: application/json' \
  --data '{
    "report": { "document_id": "3f9a7c2e-5d4b-4e1a-8c6f-0b1d2e3f4a5b" }
  }'
```

```json 201 theme={null}
{
  "url": "https://anivahealth.com/de/embed/biomarkers/vitamin-d?theme=light&primary=0f766e#token=eyJwdXJwb3NlIjoiZW1iZWRfbGF1bmNoIi4uLn0.k7Qm2V0sZ1yH",
  "expires_at": "2026-11-19T20:17:43.000Z"
}
```

```json 400 theme={null}
{
  "error": "route.name: Invalid discriminator value. Expected 'biomarkers' | 'biomarker' | 'twin'"
}
```

```json 403 theme={null}
{
  "error": "Access denied: profile is outside your permission scope"
}
```

```json 404 theme={null}
{
  "error": "Appointment not found"
}
```

```json 404 document theme={null}
{
  "error": "Document not found"
}
```


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