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

# Perfis

> Como funcionam os perfis de pacientes na API de parceiros da Aniva: criar, atualizar e associar as pessoas para quem marcas análises ao sangue e kits de teste em casa.

Um perfil é um registo que representa um paciente ou utilizador no sistema da Aniva. Todas as marcações, pedidos de laboratório e resultados estão associados a um perfil.

## Grupos de perfis

Quando crias um perfil, atribui-lo a um **grupo de perfis** usando o parâmetro `profile_group`. Um grupo de perfis organiza os perfis na tua conta de parceiro, limitando-os a um programa ou integração específicos.

O campo `profile_group` aceita o UUID imutável do grupo ou o seu slug legível. O UUID é a referência duradoura — nunca muda e mantém-se mesmo se o slug for alterado. O slug destina-se a URLs legíveis e integrações de parceiros.

É obrigatório indicar um valor de `profile_group` (UUID ou slug) na criação. O campo antigo `profile_group_slug` continua a ser aceite como um alias obsoleto.

## Campos

**id** `string` *required*

UUID gerado automaticamente pela Aniva. Usa este valor para referenciar o perfil noutras chamadas à API.

**handle** `string`

Um nome de utilizador ou handle opcional para o perfil. Pode ser null.

**first\_name** `string`

Nome próprio do paciente. Apenas caracteres latinos, 1–100 caracteres. Obrigatório na criação.

**last\_name** `string`

Apelido do paciente. Apenas caracteres latinos, 1–100 caracteres. Obrigatório na criação — os
laboratórios recusam pedidos de pacientes sem apelido. Pode ser null em perfis criados antes de se
tornar obrigatório.

**email** `string`

Endereço de email do paciente. Se não indicares um na criação, a Aniva gera automaticamente um
email provisório.

**phone** `string`

Número de telefone em [formato E.164](https://www.itu.int/rec/T-REC-E.164/en) (por exemplo,
`+14155552671`). Pode ser null.

**sex** `integer`

Sexo biológico segundo a norma [ISO/IEC 5218](https://www.iso.org/standard/36266.html): `1` =
masculino, `2` = feminino. Obrigatório na criação, salvo se o teu grupo de perfis permitir que o
paciente o introduza (ver abaixo). O laboratório precisa dele para os intervalos de referência,
por isso criar ou atualizar com `0` (desconhecido) devolve `400`. Os perfis criados antes de 30 de
setembro de 2026 ainda podem devolver `0`.

**date\_of\_birth** `string`

Data de nascimento no formato `YYYY-MM-DD`. Obrigatória na criação, salvo se o teu grupo de perfis
permitir que o paciente a introduza (ver abaixo). Tem de estar no passado, não pode ser anterior a
1900 e deve corresponder a uma idade entre 16 e 100 anos; valores implausíveis são rejeitados com
`400`. A data de nascimento é enviada ao laboratório no pedido e não pode ser alterada depois de o
pedido ser feito.

**height** `number`

Altura em centímetros. Pode ser null.

**weight** `number`

Peso em quilogramas. Pode ser null.

**language** `string`

Idioma preferido para as comunicações com o paciente. Valores aceites: `en`, `de`, `fi`.

**transactional\_emails\_enabled** `boolean`

Indica se o perfil recebe emails transacionais, como confirmações de marcação e avisos de
resultados prontos. Distinto da subscrição de marketing. Null quando nunca foi definido.

**created\_at** `string` *required*

Data e hora ISO 8601 da criação do perfil.

**updated\_at** `string`

Data e hora ISO 8601 da atualização mais recente. Null se o perfil nunca tiver sido atualizado.

> [!NOTE]
>
> Os campos `first_name`, `last_name`, `sex`, `date_of_birth` e `profile_group` são obrigatórios ao
> criar um perfil. Todos os outros campos são opcionais. O campo antigo `profile_group_slug`
> continua a ser aceite como um alias obsoleto de `profile_group`.

### Deixar o paciente introduzir a data de nascimento e o sexo

Podemos ativar uma definição para o teu grupo de perfis. Assim, podes criar um perfil sem
`date_of_birth` e `sex`. Pede-nos para a ativar. Sem ela, uma criação que omita qualquer um destes
campos devolve `400`.

O paciente introduz ambos na página de ativação do kit (`anivahealth.com/activate`), juntamente com
o código do kit. A página pede a data de nascimento duas vezes, porque o laboratório não pode
alterá-la mais tarde. Depois disso, o kit só abre com essa data de nascimento. Enquanto o paciente
não introduzir ambos, retemos o pedido ao laboratório. Usa esta definição apenas para kits de teste
em casa.

## Ciclo de vida

Os perfis seguem um ciclo de vida simples:

1. **Criar** — regista o perfil com os campos demográficos obrigatórios e um `profile_group` (UUID
   ou slug).
2. **Atualizar** (opcional) — adiciona ou altera campos como `phone`, `height` ou `weight`.
3. **Associar** — liga o perfil a marcações usando o seu `id` como `profile_id`.

Um [webhook](https://docs.anivahealth.com/pt/concepts/webhooks.md) `profile.*` avisa-te quando um perfil aparece, muda ou é eliminado.

## Exemplo de perfil

```json theme={null}
{
  "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "handle": "jdoe42",
  "first_name": "Jane",
  "last_name": "Doe",
  "email": "jane.doe@example.com",
  "phone": "+14155552671",
  "sex": 2,
  "date_of_birth": "1990-06-15",
  "height": 168.0,
  "weight": 65.0,
  "language": "en",
  "transactional_emails_enabled": true,
  "created_at": "2026-03-01T09:00:00Z",
  "updated_at": "2026-03-10T14:32:00Z"
}
```


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