> ## 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 um perfil

> Guia passo a passo: criar e atualizar perfis de pacientes na API de parceiros da Aniva antes de marcares uma análise ao sangue.

Usa este guia para criar um perfil de paciente e atribuí-lo ao teu grupo de perfis. Os perfis são o ponto de partida para agendar marcações e iniciar pedidos laboratoriais.

**1. Obter a referência do teu grupo de perfis**

Cada perfil tem de ser atribuído a um grupo de perfis que pertença à tua conta de parceiro. O campo `profile_group` aceita o UUID imutável do grupo ou o seu slug legível — o UUID é preferível porque nunca muda e mantém-se válido se o slug for renomeado.

Se não souberes a referência do teu grupo de perfis, contacta a Aniva para a obter. Não podes criar perfis sem uma referência válida.

**2. Criar o perfil**

Envia um pedido `POST` para `/api/v1/profiles` com os dados demográficos do paciente.

> [!NOTE]
>
> `first_name` e `last_name` são ambos obrigatórios. Aceitam apenas letras do alfabeto latino (incluindo letras acentuadas como ü), espaços, hífenes e apóstrofos. Translitera nomes noutros alfabetos antes de os submeteres.

> [!NOTE]
>
> Se omitires `email`, a Aniva gera automaticamente um endereço de email provisório para o perfil. Podes atualizá-lo mais tarde com um pedido `PATCH`.

> [!TIP]
>
> O campo `language` controla o idioma que a Aniva usa ao comunicar com o paciente — por exemplo, lembretes de marcação e notificações de resultados. Define-o de acordo com o idioma preferido do paciente. [Criar perfil](https://docs.anivahealth.com/pt/api/profiles/create-profile.md) lista os valores suportados. O valor predefinido é `en`.

```bash cURL theme={null}
curl --request POST \
  --url https://anivahealth.com/api/v1/profiles \
  --header 'Content-Type: application/json' \
  --header 'x-api-key: YOUR_API_KEY' \
  --data '{
    "first_name": "Emma",
    "last_name": "Müller",
    "sex": 2,
    "date_of_birth": "1990-04-15",
    "profile_group": "my-clinic-group",
    "email": "emma.muller@example.com",
    "language": "de"
  }'
```

```javascript JavaScript theme={null}
const response = await fetch('https://anivahealth.com/api/v1/profiles', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
    'x-api-key': 'YOUR_API_KEY',
  },
  body: JSON.stringify({
    first_name: 'Emma',
    last_name: 'Müller',
    sex: 2,
    date_of_birth: '1990-04-15',
    profile_group: 'my-clinic-group',
    email: 'emma.muller@example.com',
    language: 'de',
  }),
});

const profile = await response.json();
```

Um pedido bem-sucedido devolve `201 Created` com o novo objeto de perfil:

```json theme={null}
{
  "id": "a3f1c2e4-58b7-4d9e-b012-3c7f8a2e1d56",
  "handle": null,
  "first_name": "Emma",
  "last_name": "Müller",
  "email": "emma.muller@example.com",
  "phone": null,
  "sex": 2,
  "date_of_birth": "1990-04-15",
  "height": null,
  "weight": null,
  "language": "de",
  "transactional_emails_enabled": null,
  "created_at": "2026-04-01T09:14:22Z",
  "updated_at": null
}
```

Guarda o `id` — vais precisar dele para agendar marcações e atualizar o perfil.

**3. Atualizar o perfil (opcional)**

Usa `PATCH /api/v1/profiles/{id}` para atualizar quaisquer campos do perfil após a criação. Todos os campos são opcionais — inclui apenas os campos que queres alterar.

O exemplo seguinte adiciona um número de telefone e a altura:

```bash cURL theme={null}
curl --request PATCH \
  --url https://anivahealth.com/api/v1/profiles/a3f1c2e4-58b7-4d9e-b012-3c7f8a2e1d56 \
  --header 'Content-Type: application/json' \
  --header 'x-api-key: YOUR_API_KEY' \
  --data '{
    "phone": "+4915123456789",
    "height": 168.5
  }'
```

```javascript JavaScript theme={null}
const response = await fetch(
  'https://anivahealth.com/api/v1/profiles/a3f1c2e4-58b7-4d9e-b012-3c7f8a2e1d56',
  {
    method: 'PATCH',
    headers: {
      'Content-Type': 'application/json',
      'x-api-key': 'YOUR_API_KEY',
    },
    body: JSON.stringify({
      phone: '+4915123456789',
      height: 168.5,
    }),
  }
);

const updated = await response.json();
```

Um pedido bem-sucedido devolve `200 OK` com o objeto de perfil atualizado completo.

## Tratamento de erros

| Estado | Causa | Resolução |
| - | - | - |
| `400 Bad Request` | Falta um campo obrigatório, um valor está fora do intervalo ou `date_of_birth` não é plausível (no futuro, anterior a 1900 ou implica uma idade fora de 16–100). | Consulta o corpo da resposta de erro para ver a mensagem de validação específica e corrige o pedido. |
| `403 Forbidden` | A tua chave API não tem acesso a esta operação ou não tens acesso ao grupo de perfis especificado. | Contacta a Aniva para confirmar as permissões da tua chave API e o acesso ao grupo de perfis. |
| `404 Not Found` | O valor de `profile_group` não corresponde a nenhum grupo de perfis da tua conta (nem por UUID nem por slug). | Verifica se a referência está correta. Contacta a Aniva se tiveres dúvidas sobre o teu UUID ou slug. |
| `409 Conflict` | Já existe um perfil para este `email` (`error_name: "email_exists_error"`) ou foi reutilizada uma `Idempotency-Key` com um corpo diferente. | Usa o perfil existente para esse email ou envia uma nova `Idempotency-Key`. |


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