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

# Carregar documento

> Carregar um relatório laboratorial ou qualquer outro documento para um perfil e, opcionalmente, extrair os seus valores laboratoriais

Carrega um ficheiro para um perfil. Envia-o como `multipart/form-data`. Sem `extract_results`, a Aniva apenas
guarda o ficheiro. Com `extract_results: true`, a Aniva também lê os valores de laboratório a partir do ficheiro.

Não indicas que tipo de relatório é o ficheiro. A Aniva decide. Um ficheiro sem resultados de laboratório, como
uma carta médica, termina como `stored` e não é um erro.

Lê os valores com [Obter resultados do documento](https://docs.anivahealth.com/pt/api/documents/get-document-results.md). Não precisas de
fazer polling: subscreve os [webhooks](https://docs.anivahealth.com/pt/concepts/webhooks.md) `document.results.*`.

Requer o âmbito `documents_upload` num grupo de perfis do perfil. `extract_results: true`
também requer o âmbito `documents_extract_results` no mesmo grupo. Pede à Aniva para os adicionar. O
documento pertence a esse grupo: as chaves com `results_view` nesse grupo leem o documento e os seus resultados.

Envia um cabeçalho opcional `Idempotency-Key` para tornar seguro repetir o carregamento. Consulta
[Idempotência](https://docs.anivahealth.com/pt/concepts/idempotency.md).

## O que faz a extração

Com `extract_results: true`:

1. A Aniva envia o ficheiro aos seus subcontratantes de OCR e IA para ler os valores.
2. Os valores aparecem na app Aniva do membro, como qualquer outro resultado.
3. Cada valor inclui `origin: partner_upload` e o mesmo `status` que qualquer outro resultado. Um valor
   de que a verificação automática da Aniva duvida tem o estado `likely_wrong`.

Sem isso, o ficheiro não vai para nenhum serviço externo quando também envias `document_date`.

> [accordion] Precisão e proteção de dados
>
> * A leitura automática pode ler mal um valor, uma unidade ou uma data. O ficheiro original continua
>   a ser a fonte de verdade. Confirma o valor com ele antes de o usares para uma decisão médica.
>   Os valores extraídos não são um diagnóstico.
> * Os subcontratantes são a Mistral AI (OCR, UE) e o Google Cloud Vertex AI, acedido através do
>   Vercel AI Gateway (extração, pode processar fora da UE). Processam o ficheiro apenas para o
>   ler.
> * Precisas de uma base legal para carregar os dados de saúde de um membro, normalmente o
>   consentimento explícito do membro. És responsável por isso.

## Pedido

### Campos do formulário

**file** `file` *required*

O ficheiro. PDF, DOC, DOCX, PNG ou JPEG, no máximo 4 MB.

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

UUID do perfil a que o documento pertence.

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

`true` para ler os valores laboratoriais do ficheiro. Envia `true` ou `false`.

**document\_date** `string`

A data da amostra no formato `YYYY-MM-DD`, quando a conheces. Sem ela, a Aniva lê a data do
ficheiro.

## Resposta

A API devolve `201 Created` quando apenas guardou o ficheiro e `202 Accepted` quando a extração é executada.

**id** `string` *required*

ID do documento (UUID). Usa-o com [Obter resultados do documento](https://docs.anivahealth.com/pt/api/documents/get-document-results.md) e
[Transferir documento](https://docs.anivahealth.com/pt/api/documents/download-document.md).

**status** `string` *required*

`processing` enquanto a Aniva extrai os valores, ou `stored` quando o ficheiro é apenas guardado.

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

O perfil a que o documento pertence.

**document\_date** `string`

A data da amostra que enviaste, ou a que a Aniva leu de um ficheiro guardado. Pode ser `null`.

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

O URL de [Obter resultados do documento](https://docs.anivahealth.com/pt/api/documents/get-document-results.md) deste documento.

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

Nome do ficheiro a apresentar, o mesmo que [Transferir documento](https://docs.anivahealth.com/pt/api/documents/download-document.md) envia.

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

O nome do ficheiro que carregaste.

**origin** `string` *required*

Sempre `partner_upload`.

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

Tipo de média do ficheiro, por ex., `application/pdf`.

**etag** `string`

Versão do conteúdo do ficheiro. Pode ser `null`.

**size\_bytes** `integer`

Tamanho do ficheiro em bytes. Pode ser `null`.

**lab\_code** `string`

Sempre `null` para um documento carregado.

## Respostas de erro

| Estado | Descrição |
| - | - |
| `400` | Um campo do formulário é inválido ou o corpo não é `multipart/form-data`. |
| `403` | Falta um âmbito à tua chave de API, o perfil está fora do teu contexto de acesso ou enviaste `extract_results: true` sem `documents_extract_results`. |
| `404` | Perfil não encontrado. |
| `409` | `duplicate_document`: o mesmo ficheiro já existe neste perfil. `document_id` indica-o, ou é `null` quando não o podes ler. Também enviado em caso de conflito de `Idempotency-Key`. |
| `413` | `file_too_large`: o ficheiro tem mais de 4 MB. |
| `415` | `unsupported_media_type`: o ficheiro não é um PDF, DOC, DOCX, PNG ou JPEG. O nome do ficheiro tem de terminar em `.pdf`, `.doc`, `.docx`, `.png`, `.jpg` ou `.jpeg`. |
| `500` | Erro interno do servidor. `extraction_not_started`: o ficheiro está guardado como `document_id`, mas a extração não pôde começar. Contacta a 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.