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

# Início rápido

> Faz a tua primeira chamada à API de parceiros da Aniva em minutos: encontra um local de análises, cria um perfil e marca uma colheita de sangue.

Este guia acompanha-te no fluxo principal: encontrar um local de análise, criar um perfil de paciente, agendar uma marcação e confirmar uma colheita de sangue.

## Pré-requisitos

Precisas de uma chave de API de parceiro emitida pela Aniva.

> [!NOTE]
>
> Se ainda não tens uma chave de API, contacta a Aniva para que seja emitida uma para a tua conta de parceiro.

## Passos

**1. Listar locais disponíveis**

Obtém a lista de locais de análise para encontrar um `location_id` para a marcação que vais agendar.

```bash theme={null}
curl https://anivahealth.com/api/v1/locations \
  -H "x-api-key: YOUR_API_KEY"
```

**Exemplo de resposta**

```json theme={null}
[
  {
    "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    "name": "Aniva Berlin Mitte",
    "company_name": "Aniva GmbH",
    "street": "Unter den Linden",
    "house_number": "42",
    "address_line_2": null,
    "city": "Berlin",
    "state": "Berlin",
    "postal_code": "10117",
    "country_name": "Germany",
    "country_code": "DE",
    "timezone": "Europe/Berlin",
    "contact_phone": "+4930987654321",
    "email": "berlin-mitte@anivahealth.com",
    "website": "https://anivahealth.com",
    "google_maps_url": null,
    "image_url": null,
    "open_hours": {
      "monday": [{ "open": "08:00", "close": "18:00" }],
      "tuesday": [{ "open": "08:00", "close": "18:00" }],
      "wednesday": [{ "open": "08:00", "close": "18:00" }],
      "thursday": [{ "open": "08:00", "close": "18:00" }],
      "friday": [{ "open": "08:00", "close": "16:00" }],
      "saturday": [],
      "sunday": []
    }
  }
]
```

Anota o `id` do local que queres usar. Vais precisar dele no passo 3.

**2. Criar um perfil**

Cria um perfil de paciente enviando os respetivos dados demográficos. O `profile_group` associa o perfil à tua conta de parceiro — aceita o UUID imutável do grupo ou o respetivo slug legível por humanos.

```bash theme={null}
curl -X POST https://anivahealth.com/api/v1/profiles \
  -H "x-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "first_name": "Jordan",
    "last_name": "Rivera",
    "sex": 1,
    "date_of_birth": "1990-04-15",
    "profile_group": "your-profile-group"
  }'
```

**Campos do corpo do pedido**

| Campo | Tipo | Obrigatório | Descrição |
| - | - | - | - |
| `first_name` | string | Sim | Nome próprio do paciente |
| `last_name` | string | Sim | Apelido do paciente |
| `sex` | integer | Sim\*\* | `1` = masculino, `2` = feminino (ISO/IEC 5218) |
| `date_of_birth` | string | Sim\*\* | Data de nascimento no formato `YYYY-MM-DD`. Tem de ser no passado, não anterior a 1900, e implicar uma idade de 16–100 anos. |
| `profile_group` | string | Sim\* | UUID ou slug do teu grupo de perfis de parceiro. O UUID é a referência estável; o slug também é aceite. |
| `profile_group_slug` | string | Não | **Descontinuado.** Alias de slug para `profile_group`. É obrigatório indicar `profile_group` ou `profile_group_slug`. |
| `email` | string | Não | Email do paciente. Gerado automaticamente se omitido. |
| `language` | string | Não | `en`, `de` ou `fi`. Por predefinição, `en`. |
| `phone` | string | Não | Número de telefone no formato E.164, por exemplo `+4915123456789`. |
| `height` | number | Não | Altura em centímetros. |
| `weight` | number | Não | Peso em quilogramas. |
| `transactional_emails_enabled` | boolean | Não | Substitui a predefinição do grupo de perfis para emails operacionais. |
| `marketing_emails_enabled` | boolean | Não | Substitui a predefinição do grupo de perfis para emails de marketing. |

\*\* Opcional quando o teu grupo de perfis permite ao paciente introduzir ambos na página de ativação do kit. Consulta
[Perfis](https://docs.anivahealth.com/pt/concepts/profiles.md#deixar-o-paciente-introduzir-a-data-de-nascimento-e-o-sexo).

**Exemplo de resposta (201 Created)**

```json theme={null}
{
  "id": "b2c3d4e5-f6a7-8901-bcde-f12345678901",
  "handle": null,
  "first_name": "Jordan",
  "last_name": "Rivera",
  "email": "jordan.rivera@example.com",
  "phone": null,
  "sex": 1,
  "date_of_birth": "1990-04-15",
  "height": null,
  "weight": null,
  "language": "en",
  "transactional_emails_enabled": null,
  "created_at": "2026-04-01T10:00:00Z",
  "updated_at": null
}
```

Anota o `id` da resposta. Vais usá-lo como `profile_id` no passo seguinte.

**3. Agendar uma marcação**

Cria uma marcação usando o `profile_id` do passo 2 e o `location_id` do passo 1. Define `scheduled_at` para o início de um horário que [Obter disponibilidade](https://docs.anivahealth.com/pt/api/locations/get-availability.md) devolve para esse local. A API rejeita uma hora que não faça parte da grelha de horários.

```bash theme={null}
curl -X POST https://anivahealth.com/api/v1/appointments \
  -H "x-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "profile_id": "b2c3d4e5-f6a7-8901-bcde-f12345678901",
    "location_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    "scheduled_at": "2026-04-10T09:00:00Z"
  }'
```

**Exemplo de resposta (201 Created)**

```json theme={null}
{
  "id": "c3d4e5f6-a7b8-9012-cdef-123456789012",
  "profile_id": "b2c3d4e5-f6a7-8901-bcde-f12345678901",
  "location_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "scheduled_at": "2026-04-10T09:00:00Z",
  "status": "confirmed",
  "cancellation_reason": null,
  "results_ready_emails": [],
  "created_at": "2026-04-01T10:05:00Z",
  "updated_at": null,
  "profile": {
    "id": "b2c3d4e5-f6a7-8901-bcde-f12345678901",
    "handle": null,
    "first_name": "Jordan",
    "last_name": "Rivera",
    "email": "jordan.rivera@example.com",
    "phone": null,
    "sex": 1,
    "date_of_birth": "1990-04-15",
    "height": null,
    "weight": null,
    "language": "en",
    "transactional_emails_enabled": null,
    "created_at": "2026-04-01T10:00:00Z",
    "updated_at": null
  },
  "panels": [],
  "individual_biomarkers": [],
  "shipments": [],
  "lab_codes": []
}
```

Anota o `id` da marcação. Vais usá-lo para confirmar a colheita de sangue.

**4. Confirmar a colheita de sangue**

Depois de concluída a colheita de sangue, submete o código de laboratório (código de barras do tubo) para confirmar a colheita e acionar o pipeline de pedidos laboratoriais. Numa colheita cujos tubos tenham vários códigos, envia antes `lab_codes` — consulta [Confirmar colheita de sangue](https://docs.anivahealth.com/pt/api/appointments/confirm-blood-draw.md).

```bash theme={null}
curl -X POST https://anivahealth.com/api/v1/appointments/c3d4e5f6-a7b8-9012-cdef-123456789012/confirm \
  -H "x-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "lab_code": "7642001234"
  }'
```

**Exemplo de resposta (200 OK)**

```json theme={null}
{
  "success": true
}
```

Depois de confirmada, o pipeline de pedidos laboratoriais é acionado. Podes obter a marcação para verificar se o estado mudou para `"blood_drawn"`.

## Próximos passos

* [Adicionar painéis a uma marcação](https://docs.anivahealth.com/pt/api/appointments/add-panels.md) para especificar que análises laboratoriais realizar.
* [Atualizar uma marcação](https://docs.anivahealth.com/pt/api/appointments/update-appointment.md) para reagendar ou alterar o local antes da colheita de sangue.
* [Cancelar uma marcação](https://docs.anivahealth.com/pt/api/appointments/cancel-appointment.md) se já não for necessária.
* [Obter resultados laboratoriais](https://docs.anivahealth.com/pt/api/appointments/get-results.md) para recuperar resultados clínicos e genéticos após o processamento.
* [Transferir documentos](https://docs.anivahealth.com/pt/api/documents/download-document.md) para obter PDFs de relatórios laboratoriais.
* [Obter um perfil](https://docs.anivahealth.com/pt/api/profiles/get-profile.md) para verificar ou mostrar dados do paciente.
* Consultar a [Referência da API](https://docs.anivahealth.com/pt/api/profiles/create-profile.md) completa para todos os endpoints e parâmetros disponíveis.


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