> ## 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 marcação

> Agendar uma marcação de colheita de sangue para um perfil num local de análises

Agenda uma marcação de colheita de sangue para um perfil de paciente num local de análise específico. Depois de criada, a marcação fica no estado `confirmed` por predefinição (alguns locais podem usar `pending` por predefinição — esta é uma definição por local). Usa [Adicionar painéis](https://docs.anivahealth.com/pt/api/appointments/add-panels.md) para associar painéis de análises ao sangue antes de [confirmar a colheita de sangue](https://docs.anivahealth.com/pt/api/appointments/confirm-blood-draw.md).

> [!NOTE]
>
> Um perfil pode ter no máximo **uma** marcação por local e horário. Criar uma marcação para um
> horário que o perfil já ocupa devolve `409` com o `appointment_id` existente em vez de uma segunda
> marcação — assim, um pedido reenviado ou repetido por engano nunca duplica uma marcação. Vê
> [Marcações duplicadas](#marcacoes-duplicadas).

Envia um cabeçalho opcional `Idempotency-Key` para tornar esta criação segura para repetir — repetir a mesma chave devolve a resposta original em vez de criar outra. Vê [Idempotência](https://docs.anivahealth.com/pt/concepts/idempotency.md).

Requer o scope `appointments_schedule`.

## Pedido

### Parâmetros do corpo

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

UUID do perfil de paciente para o qual criar a marcação.

**location\_id** `string` *required*

UUID do local de análise onde a colheita de sangue vai decorrer. Usa [Listar
locais](https://docs.anivahealth.com/pt/api/locations/list-locations.md) para encontrar os IDs de locais disponíveis.

**scheduled\_at** `string` *required*

Data e hora da marcação no formato ISO 8601 (por exemplo, `2026-05-15T10:30:00Z` ou
`2026-05-15T12:30:00+02:00`). **Tem de incluir um indicador de fuso horário** — `Z` ou um
desfasamento explícito como `+02:00`; datas e horas sem fuso horário são rejeitadas. Tem de ser no
futuro.

Tem de corresponder ao início exato de um horário na grelha do local e esse horário ainda tem de
ter vagas — consulta primeiro [Obter disponibilidade](https://docs.anivahealth.com/pt/api/locations/get-availability.md). Horários fora
da grelha devolvem `400`; um horário já esgotado devolve `409`. Nos locais geridos pela Aniva, tem
também de ter pelo menos 12 horas de antecedência — vê [Antecedência mínima](#antecedencia-minima).

**results\_ready\_emails** `string[]`

Até 5 endereços que recebem um e-mail cada assim que todos os resultados laboratoriais forem
finais. O e-mail inclui uma ligação para a página de resultados no painel de administração da
Aniva. A tua chave precisa de acesso `results_view` ao paciente, caso contrário devolve `403`.
Omite este campo para usar os endereços predefinidos para o grupo do paciente. Uma lista vazia
desativa os e-mails. Vê [E-mails de resultados prontos](https://docs.anivahealth.com/pt/concepts/results.md#e-mails-de-resultados-prontos).

**draw\_method** `string`

Como o sangue é colhido: `capillary` ou `venous`. Omite este campo para usar o
`default_draw_method` do local. O local tem de incluir o método em `draw_methods`, caso contrário
devolve `400`.

## Resposta

Em caso de sucesso, a API devolve `201 Created` com a nova marcação.

**id** `string` *required*

Identificador único da marcação (UUID).

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

UUID do perfil a que pertence esta marcação.

**location\_id** `string`

UUID do local de teste onde decorre a colheita de sangue.

**scheduled\_at** `string`

Data e hora agendada da marcação como instante UTC (ISO 8601 com sufixo `Z`, p. ex.,
`2026-05-15T10:30:00Z`). Pode ser `null`.

**status** `string` *required*

Estado atual da marcação. Um de `pending`, `confirmed`, `blood_drawn` ou `cancelled`. O detalhe
sobre a conclusão dos resultados laboratoriais obtém-se em
[Obter resultados](https://docs.anivahealth.com/pt/api/appointments/get-results.md); a progressão detalhada dos envios obtém-se a
partir de cada entrada no array `shipments` incorporado (vê abaixo) seguindo para
[Obter envio](https://docs.anivahealth.com/pt/api/shipments/get-shipment.md).

**cancellation\_reason** `string`

Motivo em texto livre registado quando a marcação foi cancelada (p. ex., falta de comparência, cancelamento tardio,
'Falhou. Repetição necessária'). `null`, exceto quando `status` é `cancelled`.

**results\_ready\_emails** `string[]` *required*

Endereços que recebem um e-mail assim que todos os resultados laboratoriais forem definitivos, em minúsculas. Vazio quando desativado. Consulta
[E-mails de resultados prontos](https://docs.anivahealth.com/pt/concepts/results.md#e-mails-de-resultados-prontos).

**draw\_method** `string` *required*

Como o sangue é colhido: `capillary` (ponta do dedo ou parte superior do braço, em microtubos) ou `venous` (na veia,
em tubos). É o método definido na marcação ou, caso contrário, o `default_draw_method` do respetivo
[local](https://docs.anivahealth.com/pt/concepts/locations.md). Após a colheita de sangue, é o método que foi utilizado.

**profile** `object` *required*

O perfil do paciente associado a esta marcação.

**perfil**

**id** `string`

Identificador único do perfil (UUID).

**handle** `string`

Identificador ou nome de utilizador do perfil. Pode ser `null`.

**first\_name** `string`

Nome próprio. Pode ser `null`.

**last\_name** `string`

Apelido. Pode ser `null`.

**email** `string`

Endereço de e-mail. Pode ser `null`.

**phone** `string`

Número de telefone no formato E.164. Pode ser `null`.

**sex** `integer`

Sexo biológico segundo a norma ISO/IEC 5218. Pode ser `null`.

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

Data de nascimento no formato `YYYY-MM-DD`. Pode ser `null`.

**height** `number`

Altura em centímetros. Pode ser `null`.

**weight** `number`

Peso em quilogramas. Pode ser `null`.

**language** `string`

Idioma preferido: um dos 32 códigos em [Criar perfil](https://docs.anivahealth.com/pt/api/profiles/create-profile.md).

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

Indica se este perfil recebe e-mails transacionais (programáticos). Pode ser `null`.

**panels** `AppointmentPanel[]` *required*

Painéis atualmente associados a esta marcação. Vazio em marcações recém-criadas — associa através
de [Adicionar painéis](https://docs.anivahealth.com/pt/api/appointments/add-panels.md). Consulta os detalhes dos painéis (nome,
biomarcadores) em [Listar painéis](https://docs.anivahealth.com/pt/api/panels/list-panels.md).

**Campos de associação de painel**

**panel\_id** `string`

UUID do painel — cruza com [Listar painéis](https://docs.anivahealth.com/pt/api/panels/list-panels.md).

**added\_at** `string`

Data e hora ISO 8601 em que o painel foi associado pela primeira vez a esta marcação.

**individual\_biomarkers** `AppointmentIndividualBiomarker[]` *required*

Biomarcadores avulsos associados a esta marcação fora de qualquer painel. Vazio em marcações
recém-criadas — associa através de
[Adicionar biomarcadores individuais](https://docs.anivahealth.com/pt/api/appointments/add-individual-biomarkers.md). Cruza cada
`biomarker_id` com [Listar biomarcadores](https://docs.anivahealth.com/pt/api/biomarkers/list-biomarkers.md) para obter os dados de
apresentação.

**Campos de biomarcador individual**

**biomarker\_id** `integer`

Identificador do biomarcador — cruza com
[Listar biomarcadores](https://docs.anivahealth.com/pt/api/biomarkers/list-biomarkers.md).

**added\_at** `string`

Data e hora ISO 8601 em que o biomarcador foi associado pela primeira vez a esta marcação.

**shipments** `AppointmentShipmentLink[]` *required*

Envios associados a esta marcação, começando pela associação mais antiga. Vazio em marcações
recém-criadas — associa através de [Criar envio](https://docs.anivahealth.com/pt/api/shipments/create-shipment.md) (com
`appointment_id`) ou
[Associar marcações a um envio](https://docs.anivahealth.com/pt/api/shipments/attach-appointments-to-shipment.md).

**Campos de associação de envio**

**id** `string`

Identificador de referência do envio — cruza com
[Obter envio](https://docs.anivahealth.com/pt/api/shipments/get-shipment.md).

**added\_at** `string`

Data e hora ISO 8601 em que o envio foi associado pela primeira vez a esta marcação.

**lab\_codes** `string[]` *required*

Códigos de laboratório (códigos de barras dos tubos) registados para esta marcação, por ordem de leitura. Vazio até a colheita de sangue
ser confirmada. Uma colheita venosa tem um código impresso em todos os tubos; uma colheita capilar tem um
código por microtubo. Os resultados e documentos em [Obter resultados](https://docs.anivahealth.com/pt/api/appointments/get-results.md) referenciam
estes códigos através de `lab_code`.

## Antecedência mínima

As marcações em locais geridos pela Aniva têm de ser feitas com pelo menos **12 horas** de
antecedência; marcar dentro desse prazo devolve `400`.
[Obter disponibilidade](https://docs.anivahealth.com/pt/api/locations/get-availability.md) já omite esses horários, pelo que tudo o
que leres nessa grelha pode ser marcado.

Os locais que geres diretamente não têm antecedência mínima — as marcações para o próprio dia e na hora mantêm-se inalteradas.

## Marcações duplicadas

Um perfil pode ter no máximo uma marcação não cancelada por local e instante — uma pessoa não pode
fazer duas colheitas de sangue no mesmo local ao mesmo tempo, por muitas cadeiras que o local tenha.

Criar uma marcação para um horário que o perfil já ocupa devolve `409` com um `appointment_id` que
indica a marcação já existente:

```json theme={null}
{
  "error": "This profile already has an appointment at this location and time. Reschedule or cancel the existing appointment instead of creating a second one.",
  "appointment_id": "03e916d2-7fd6-4414-8276-8532a105edc3"
}
```

Trata o erro considerando o pedido já aplicado: obtém a marcação com
[Obter marcação](https://docs.anivahealth.com/pt/api/appointments/get-appointment.md), altera-a com
[Atualizar marcação](https://docs.anivahealth.com/pt/api/appointments/update-appointment.md) ou cancela-a com
[Cancelar marcação](https://docs.anivahealth.com/pt/api/appointments/cancel-appointment.md). Não voltes a tentar a criação — vai
continuar a devolver `409`.

Isto torna seguras as criações repetidas: um pedido que reenvies após um timeout, ou um formulário
submetido duas vezes, não pode gerar duas marcações para o mesmo paciente à mesma hora.

> [!NOTE]
>
> `appointment_id` só está presente no `409` de duplicado. O `409` de capacidade — o horário está
> cheio porque *outros* pacientes o ocupam — devolve apenas `error`, e a solução correta nesse caso
> é escolher outro horário em [Obter disponibilidade](https://docs.anivahealth.com/pt/api/locations/get-availability.md).

## Respostas de erro

| Estado | Descrição |
| - | - |
| `400` | Erro de validação — por ex., `scheduled_at` está no passado, tem menos de 12 horas de antecedência num local operado pela Aniva, não corresponde ao início exato de um horário na grelha do local, ou o local não tem recipientes em stock para `draw_method`. |
| `403` | Proibido — a tua chave API não tem acesso a esta operação, ou `results_ready_emails` está definido sem acesso `results_view` ao paciente. |
| `404` | Perfil ou local não encontrado, ou o local está inativo. |
| `409` | Este perfil já tem uma marcação neste local e horário (inclui `appointment_id`), o horário atingiu a capacidade máxima, o local está fechado nessa data, a `Idempotency-Key` foi reutilizada com um corpo diferente, ou o pedido original ainda não foi concluído. |
| `500` | Erro interno do servidor. |

```bash cURL theme={null}
curl --request POST \
  --url https://anivahealth.com/api/v1/appointments \
  --header 'x-api-key: YOUR_API_KEY' \
  --header 'Content-Type: application/json' \
  --data '{
    "profile_id": "a3f1c2d4-8b7e-4f2a-9c1d-2e3f4a5b6c7d",
    "location_id": "b7e2d1f5-3c4a-4e8b-a2f1-9d0c1e2f3a4b",
    "scheduled_at": "2026-05-15T10:30:00Z"
  }'
```

```json 201 theme={null}
{
  "id": "c9f3e2a1-7d6b-4c5e-b3a2-1f0e9d8c7b6a",
  "profile_id": "a3f1c2d4-8b7e-4f2a-9c1d-2e3f4a5b6c7d",
  "location_id": "b7e2d1f5-3c4a-4e8b-a2f1-9d0c1e2f3a4b",
  "scheduled_at": "2026-05-15T10:30:00Z",
  "status": "confirmed",
  "cancellation_reason": null,
  "results_ready_emails": [],
  "draw_method": "venous",
  "created_at": "2026-04-01T09:45:00Z",
  "updated_at": null,
  "profile": {
    "id": "a3f1c2d4-8b7e-4f2a-9c1d-2e3f4a5b6c7d",
    "handle": null,
    "first_name": "Maria",
    "last_name": "Schmidt",
    "email": "maria.schmidt@example.com",
    "phone": "+4930123456789",
    "sex": 2,
    "date_of_birth": "1985-03-22",
    "height": 168,
    "weight": 65,
    "language": "de",
    "transactional_emails_enabled": true,
    "created_at": "2026-04-01T09:14:32Z",
    "updated_at": null
  },
  "panels": [],
  "individual_biomarkers": [],
  "shipments": [],
  "lab_codes": []
}
```

```json 400 theme={null}
{
  "error": "Appointments must be booked at least 12 hours in advance. Please pick a later time."
}
```

```json 404 theme={null}
{
  "error": "Location not found or inactive"
}
```

```json 409 theme={null}
{
  "error": "This profile already has an appointment at this location and time. Reschedule or cancel the existing appointment instead of creating a second one.",
  "appointment_id": "03e916d2-7fd6-4414-8276-8532a105edc3"
}
```


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