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

# Carica documento

> Carica un referto di laboratorio o qualsiasi altro documento su un profilo e, facoltativamente, estrai i relativi valori di laboratorio

Carica un file su un profilo. Invialo come `multipart/form-data`. Senza `extract_results`, Aniva si
limita a salvare il file. Con `extract_results: true`, Aniva legge anche i valori di laboratorio dal file.

Non devi indicare di che tipo di referto si tratta. Decide Aniva. Un file senza risultati di laboratorio, come
una lettera medica, termina in stato `stored` e non è un errore.

Leggi i valori con [Ottieni risultati del documento](https://docs.anivahealth.com/it/api/documents/get-document-results.md). Non devi fare
polling: iscriviti ai [webhook](https://docs.anivahealth.com/it/concepts/webhooks.md) `document.results.*`.

Richiede lo scope `documents_upload` su un gruppo di profili del profilo. `extract_results: true`
richiede anche lo scope `documents_extract_results` sullo stesso gruppo. Chiedi ad Aniva di aggiungerli. Il
documento appartiene a quel gruppo: le chiavi con `results_view` su quel gruppo possono leggere il documento e i suoi risultati.

Invia un header opzionale `Idempotency-Key` per rendere sicuro un nuovo tentativo di caricamento. Consulta
[Idempotenza](https://docs.anivahealth.com/it/concepts/idempotency.md).

## Cosa fa l'estrazione

Con `extract_results: true`:

1. Aniva invia il file ai suoi sub-responsabili OCR e AI per leggere i valori.
2. I valori compaiono nell'app Aniva del membro, come ogni altro risultato.
3. Ogni valore ha `origin: partner_upload` e lo stesso `status` di ogni altro risultato. Un valore
   su cui il controllo automatico di Aniva ha dubbi ha stato `likely_wrong`.

Senza di essa, il file non viene inviato a nessun servizio esterno se invii anche `document_date`.

> [accordion] Accuratezza e protezione dei dati
>
> * La lettura automatica può leggere in modo errato un valore, un'unità o una data. Il file
>   originale resta la fonte di riferimento. Verifica un valore sul file prima di usarlo per una
>   decisione medica. I valori estratti non sono una diagnosi.
> * I sub-responsabili sono Mistral AI (OCR, UE) e Google Cloud Vertex AI, raggiunto tramite Vercel
>   AI Gateway (estrazione, può elaborare dati fuori dall'UE). Elaborano il file solo per leggerlo.
> * Ti serve una base giuridica per caricare i dati sanitari di un membro, di norma il suo consenso
>   esplicito. La responsabilità è tua.

## Richiesta

### Campi del modulo

**file** `file` *required*

Il file. PDF, DOC, DOCX, PNG o JPEG, al massimo 4 MB.

**profile\_id** `string` *required*

UUID del profilo a cui appartiene il documento.

**extract\_results** `boolean` (default: false)

`true` per leggere i valori di laboratorio dal file. Invia `true` o `false`.

**document\_date** `string`

La data del campione in formato `YYYY-MM-DD`, se la conosci. Se non la invii, Aniva legge la data
dal file.

## Risposta

L'API restituisce `201 Created` quando ha solo archiviato il file e `202 Accepted` quando esegue l'estrazione.

**id** `string` *required*

ID del documento (UUID). Usalo con [Ottieni risultati del documento](https://docs.anivahealth.com/it/api/documents/get-document-results.md) e
[Scarica documento](https://docs.anivahealth.com/it/api/documents/download-document.md).

**status** `string` *required*

`processing` mentre Aniva estrae i valori, oppure `stored` quando il file viene solo archiviato.

**profile\_id** `string` *required*

Il profilo a cui appartiene il documento.

**document\_date** `string`

La data del campione che hai inviato o quella letta da Aniva da un file archiviato. Può essere `null`.

**results\_url** `string` *required*

L'URL di [Ottieni risultati del documento](https://docs.anivahealth.com/it/api/documents/get-document-results.md) per questo documento.

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

Nome del file da mostrare, lo stesso inviato da [Scarica documento](https://docs.anivahealth.com/it/api/documents/download-document.md).

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

Il nome del file che hai caricato.

**origin** `string` *required*

Sempre `partner_upload`.

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

Tipo di media del file, ad es. `application/pdf`.

**etag** `string`

Versione del contenuto del file. Può essere `null`.

**size\_bytes** `integer`

Dimensione del file in byte. Può essere `null`.

**lab\_code** `string`

Sempre `null` per un documento caricato.

## Risposte di errore

| Stato | Descrizione |
| - | - |
| `400` | Un campo del modulo non è valido oppure il body non è `multipart/form-data`. |
| `403` | Alla tua chiave API manca uno scope, il profilo è fuori dal tuo contesto di accesso oppure hai inviato `extract_results: true` senza `documents_extract_results`. |
| `404` | Profilo non trovato. |
| `409` | `duplicate_document`: lo stesso file è già presente su questo profilo. `document_id` lo indica, oppure è `null` se non puoi leggerlo. Inviato anche in caso di conflitto di `Idempotency-Key`. |
| `413` | `file_too_large`: il file supera i 4 MB. |
| `415` | `unsupported_media_type`: il file non è un PDF, DOC, DOCX, PNG o JPEG. Il nome del file deve terminare con `.pdf`, `.doc`, `.docx`, `.png`, `.jpg` o `.jpeg`. |
| `500` | Errore interno del server. `extraction_not_started`: il file è archiviato come `document_id`, ma non è stato possibile avviare l'estrazione. Contatta Aniva. |

```bash cURL theme={null}
curl --request POST \
  --url https://anivahealth.com/api/v1/documents \
  --header 'x-api-key: YOUR_API_KEY' \
  --header 'Idempotency-Key: 5f0c2d9e-3b7a-4c1e-9f62-1d8a4e7b0c55' \
  --form 'file=@lab-report.pdf' \
  --form 'profile_id=b2c3d4e5-f6a7-4b8c-9d0e-1f2a3b4c5d6e' \
  --form 'extract_results=true'
```

```json 202 theme={null}
{
  "id": "f8a1b2c3-d4e5-4f6a-8b8c-9d0e1f2a3b4c",
  "status": "processing",
  "profile_id": "b2c3d4e5-f6a7-4b8c-9d0e-1f2a3b4c5d6e",
  "document_date": null,
  "results_url": "https://anivahealth.com/api/v1/documents/f8a1b2c3-d4e5-4f6a-8b8c-9d0e1f2a3b4c/results",
  "file_name": "20261023 - lab-report.pdf",
  "original_file_name": "lab-report.pdf",
  "origin": "partner_upload",
  "content_type": "application/pdf",
  "etag": "56104b36f860cfd5b41efc716fdf7b6f",
  "size_bytes": 312480,
  "lab_code": null
}
```

```json 409 theme={null}
{
  "error": "duplicate_document",
  "message": "This file is already on this profile",
  "document_id": "f8a1b2c3-d4e5-4f6a-8b8c-9d0e1f2a3b4c"
}
```


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