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

# Crea sessione embed

> Ottieni un URL monouso che mostra i risultati di laboratorio di un profilo nella tua app

Ottieni un URL che mostra i risultati di laboratorio di un profilo come pagina in sola lettura. Apri l'URL in una WebView della tua app o in una scheda del browser. Chiama questo endpoint dal tuo server ogni volta che l'utente apre i risultati e non mettere mai in cache l'URL.

Richiede gli scope `embed` e `results_view` su un gruppo di profili del profilo. Aniva concede lo scope `embed` su richiesta. Senza uno dei due scope, la richiesta restituisce `403`.

> [!NOTE]
>
> L'URL funziona una sola volta e per 5 minuti. Quando si apre, la pagina avvia una sessione di 60
> minuti valida solo per quella pagina. Archivia la tua chiave API per chiudere subito tutte le
> pagine aperte.

## Richiesta

### Parametri di percorso

**id** `string` *required*

Identificatore univoco (UUID) del profilo di cui la pagina mostra i risultati.

### Body

Il body è facoltativo. Senza body, l'URL apre l'elenco dei biomarcatori nella lingua del profilo.

**language** `string`

Lingua della pagina: `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` o `uk`. Predefinito: la lingua del profilo.

**route** `object`

La pagina aperta dall'URL. Predefinito: `{ "name": "biomarkers" }`. Qualsiasi altro `name` restituisce `400`.

**pagine rilasciate**

**name** `string` *required*

Uno tra:

* `biomarkers`: l'elenco di tutti i biomarcatori con i loro ultimi risultati.
* `biomarker`: la pagina di dettaglio di un biomarcatore, con andamento, intervalli e spiegazione. Richiede `biomarker_id`.
* `twin`: il corpo 3D con un voto per ogni area della salute. L'utente seleziona un'area per vederne i biomarcatori.

**biomarker\_id** `integer`

Solo per `biomarker`. Il `biomarker_id` del biomarcatore, come nei risultati, ad esempio `104`. Usa l'ID, non lo slug: uno slug può cambiare, l'ID resta.

**report** `object`

Limita ogni pagina a un singolo referto di laboratorio del profilo. Predefinito: tutti i referti
del profilo. Invia esattamente uno dei tre ID. L'elenco, l'andamento di un biomarcatore e il Twin
mostrano quindi solo i risultati di quel referto e la pagina nasconde il filtro degli appuntamenti.
L'utente non può aprire un altro referto con questo URL.

**proprietà**

**appointment\_id** `string`

L'`id` di un appuntamento del profilo. La tua chiave deve potervi accedere, come per
[Ottieni risultati di laboratorio](https://docs.anivahealth.com/it/api/appointments/get-results.md). In caso contrario, questo
endpoint restituisce `404`, non `403`.

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

L'`id` di un ordine di kit domiciliare del profilo. La tua chiave deve potervi accedere, come
per [Ottieni risultati di laboratorio](https://docs.anivahealth.com/it/api/home-kit-orders/get-results.md) per gli ordini di kit
domiciliare, e richiede anche `home_kit_orders_view` o `home_kit_orders_manage`.

**document\_id** `string`

L'`id` di un referto di laboratorio che hai caricato per il profilo con
[Carica documento](https://docs.anivahealth.com/it/api/documents/upload-document.md). La tua chiave deve potervi accedere, come
per [Ottieni risultati del documento](https://docs.anivahealth.com/it/api/documents/get-document-results.md). In caso contrario,
questo endpoint restituisce `404`, non `403`. La pagina mostra la data dell'esame di
laboratorio oppure la data di caricamento se nessun valore è ancora stato letto. Mentre Aniva
legge il documento e non ha ancora alcun valore, ogni pagina invita l'utente a riaprirla tra
qualche minuto.

**appearance** `object`

L'aspetto della pagina. L'API lo aggiunge all'URL come parametri di query.

**proprietà**

**theme** `string`

`light` o `dark`. Predefinito: l'impostazione di sistema del dispositivo.

**primary\_color** `string`

Colore esadecimale di pulsanti e link, 3 o 6 cifre, con o senza `#`, ad esempio `0f766e`.
Predefinito: il colore del brand del tuo gruppo di profili, altrimenti l'arancione Aniva. I
pulsanti mantengono il testo bianco, quindi scegli un colore scuro.

**show\_logo** `boolean`

Mostra il logo del tuo gruppo di profili sopra i risultati. Predefinito: `true`.

> [!TIP]
>
> Puoi anche aggiungere direttamente i parametri di aspetto a un URL restituito, prima del frammento
> `#token=`: `theme=light|dark`, `primary=<hex>` e `logo=0`. La pagina ignora un valore non valido.
> L'immagine del logo proviene sempre dal tuo gruppo di profili, mai dall'URL.

## Risposta

In caso di successo, l'API restituisce `201 Created`.

**url** `string` *required*

L'URL della pagina. Il token di avvio si trova nel frammento `#token=`, quindi il browser non lo
invia mai a un server. Aprilo una sola volta.

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

Timestamp ISO 8601 dopo il quale l'URL non può essere aperto.

La sessione non è vincolata a una sola pagina. All'interno dell'embed, l'utente può passare dal Twin a un biomarcatore e tra l'elenco e le pagine di dettaglio. La pagina mostra solo i risultati di laboratorio: non mostra i valori calcolati da Aniva, i file, la chat o le impostazioni.

## Risposte di errore

| Stato | Descrizione |
| - | - |
| `400` | Errore di validazione — ID profilo non valido, `route.name` sconosciuto, `biomarker_id` non valido, colore non valido o un `report` senza esattamente un UUID valido. |
| `403` | Accesso negato — alla tua chiave API manca lo scope `embed` o `results_view`, oppure lo scope per il kit domiciliare per un referto di ordine di kit domiciliare, oppure il profilo è fuori dal tuo contesto di accesso. |
| `404` | Profilo non trovato, oppure nessun biomarcatore ha questo `biomarker_id`, oppure il `report` non è un appuntamento, un ordine di kit domiciliare o un documento caricato di questo profilo, oppure il referto è fuori dal tuo accesso. Questo endpoint restituisce `404`, non `403`, per non mostrare che il referto esiste. |
| `500` | Errore interno del server. |

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