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

# Marcações

> Como funcionam as marcações de colheita de sangue na API de análises laboratoriais da Aniva: agendamento, painéis, biomarcadores, alterações de estado e cancelamento.

Uma marcação é uma colheita de sangue agendada para um perfil de paciente num local de teste físico, realizada por um profissional de saúde. Os kits enviados por correio a um paciente não são marcações — vê [Encomendas de kits de teste em casa](https://docs.anivahealth.com/pt/concepts/home-kit-orders.md).

## Campos

**id** `string` *required*

UUID gerado automaticamente pela Aniva. Usa-o para adicionar painéis, confirmar a colheita de sangue e obter resultados.

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

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

**location\_id** `string`

O UUID do local de teste onde a colheita de sangue vai decorrer. Os kits de teste em casa não são marcações — vê
[Encomendas de kits de teste em casa](https://docs.anivahealth.com/pt/concepts/home-kit-orders.md).

**scheduled\_at** `string`

Data e hora agendadas para a colheita de sangue no formato ISO 8601. Devolvida sempre como um instante UTC com um
sufixo `Z` (p. ex., `2026-04-15T08:30:00Z`). Na criação / atualização, o valor **tem de incluir um indicador
de fuso horário** (`Z` ou um desvio explícito como `+02:00`) — datas e horas sem fuso horário são rejeitadas. Tem
de estar no futuro e, nos locais geridos pela Aniva, com pelo menos 12 horas de antecedência ([antecedência
mínima](https://docs.anivahealth.com/pt/api/appointments/create-appointment.md#antecedencia-minima)).

**status** `string` *required*

Estado atual do ciclo de vida. Um de `pending`, `confirmed`, `blood_drawn` ou `cancelled`. Vê
[Ciclo de vida](#ciclo-de-vida) abaixo. O detalhe da conclusão dos resultados laboratoriais (`in_progress` vs. `completed`)
obtém-se em [Obter resultados](https://docs.anivahealth.com/pt/api/appointments/get-results.md); a progressão mais detalhada do envio (em
trânsito, entregue, etc.) obtém-se seguindo cada entrada no array `shipments` incorporado até
[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.

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

Data e hora ISO 8601 da criação da marcação.

**updated\_at** `string`

Timestamp ISO 8601 da atualização mais recente. Nulo se a marcação nunca tiver sido atualizada.

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

Códigos de laboratório (códigos de barras dos tubos) registados em [Confirmar colheita de sangue](https://docs.anivahealth.com/pt/api/appointments/confirm-blood-draw.md),
por ordem de leitura. Vazio até a colheita de sangue ser confirmada. Uma colheita de sangue venoso tem um código impresso em todos
os tubos; uma colheita capilar tem um código por microtubo. Os resultados e documentos referenciam-nos através de
`lab_code`.

**panels** `object[]` *required*

Painéis associados a esta marcação, como entradas `{ panel_id, added_at }`. Vê
[Adicionar painéis](#adicionar-paineis).

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

Biomarcadores avulsos associados a esta marcação, como entradas `{ biomarker_id, added_at }`. Vê
[Biomarcadores individuais](#biomarcadores-individuais).

**shipments** `object[]` *required*

Envios associados a esta marcação, como entradas `{ id, added_at }`, com a associação mais antiga primeiro. Vê
[Associar envios](#associar-envios).

**profile** `object` *required*

O objeto completo do perfil do paciente, incorporado em todas as respostas de marcação. Os campos abaixo
são um subconjunto. [Obter marcação](https://docs.anivahealth.com/pt/api/appointments/get-appointment.md) lista todos.

**propriedades**

**id** `string`

UUID do perfil associado.

**first\_name** `string`

Nome próprio do paciente.

**last\_name** `string`

Apelido do paciente.

**email** `string`

Endereço de email do paciente.

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

Data de nascimento no formato `YYYY-MM-DD`.

**sex** `integer`

Sexo biológico segundo a norma ISO/IEC 5218.

## Ciclo de vida

As marcações expõem quatro estados de ciclo de vida:

```
pending → confirmed → blood_drawn
   │          │             │
   └──────────┴─────────────┴──→ cancelled
```

| Estado | Significado |
| - | - |
| `pending` | A marcação está agendada e aguarda confirmação. Pode ser [atualizada](https://docs.anivahealth.com/pt/api/appointments/update-appointment.md) ou [cancelada](https://docs.anivahealth.com/pt/api/appointments/cancel-appointment.md). |
| `confirmed` | O agendamento foi confirmado (p. ex., pela clínica), mas a colheita de sangue ainda não foi feita. Ainda pode ser atualizada ou cancelada. |
| `blood_drawn` | Os códigos de laboratório foram submetidos através de [Confirmar colheita de sangue](https://docs.anivahealth.com/pt/api/appointments/confirm-blood-draw.md) e o fluxo de pedidos laboratoriais foi acionado. Os painéis ficam bloqueados e a marcação não pode ser reagendada nem cancelada. |
| `cancelled` | A marcação foi cancelada. Estado terminal — sem mais transições. |

> [!NOTE]
>
> O estado da marcação é intencionalmente abrangente — a progressão mais detalhada é exposta
> através de endpoints dedicados:
>
> * **Conclusão dos resultados laboratoriais** →
>   [Obter resultados](https://docs.anivahealth.com/pt/api/appointments/get-results.md) — o campo `status` de nível superior é `in_progress` ou
>   `completed`.
> * **Progressão do envio** (em trânsito, entregue, etc.) → segue cada entrada no array
>   `shipments` incorporado na marcação até [Obter envio](https://docs.anivahealth.com/pt/api/shipments/get-shipment.md) — cada
>   envio tem o seu próprio `status` e um registo de eventos `status_updates`.
>
> Cada alteração de estado envia um [webhook](https://docs.anivahealth.com/pt/concepts/webhooks.md) `appointment.*`, por exemplo
> `appointment.confirmed`. Uma nova hora ou local envia `appointment.rescheduled`.

> [!WARNING]
>
> Confirmar uma marcação (passá-la para `blood_drawn`) é **irreversível**. Assim que submeteres o(s)
> código(s) de laboratório, o fluxo de pedidos laboratoriais é acionado e não pode ser revertido. As atualizações e os cancelamentos
> só são permitidos enquanto a marcação estiver no estado `pending` ou `confirmed`.

## Listar marcações

Obtém todas as marcações acessíveis à tua chave API:

```
GET /api/v1/appointments
```

Passa opcionalmente `?profile_id={uuid}` para filtrar por um perfil específico. Sem este parâmetro, é aplicada uma janela temporal predefinida (dos últimos 2 meses até daqui a 1 mês).

## Atualizar uma marcação

Antes de a colheita de sangue ser confirmada, podes reagendar ou alterar o local de teste:

```
PATCH /api/v1/appointments/{id}
```

Passa qualquer combinação de `scheduled_at`, `location_id`, `draw_method` e `results_ready_emails` para atualizar. Inclui apenas os campos que queres alterar.

## Método de colheita

Cada marcação tem um `draw_method`: `capillary` (ponta do dedo ou parte superior do braço, para microtubos) ou
`venous` (da veia, para tubos). Aplica-se apenas à colheita de sangue. Urina, zaragatoa e outras
amostras não sanguíneas são recolhidas da mesma forma com qualquer um dos métodos.

Por predefinição, é o `default_draw_method` do local. Define `draw_method` na criação ou atualização para
usar outro método, ou define-o como `null` para voltar à predefinição do local. O local tem de listar
o método nos seus `draw_methods` e os testes marcados têm de ser possíveis com esse método; caso contrário, o pedido
devolve `400`. Não podes alterá-lo após a colheita de sangue. Após a colheita de sangue, `draw_method` é o
método que foi usado.

## Uma marcação por perfil, local e hora

Um perfil tem, no máximo, uma marcação não cancelada por par `(location_id, scheduled_at)` — uma
pessoa não pode fazer duas colheitas de sangue no mesmo local ao mesmo tempo, independentemente de quantas marcações paralelas o
local aceite.

Tanto [Criar marcação](https://docs.anivahealth.com/pt/api/appointments/create-appointment.md) como
[Atualizar marcação](https://docs.anivahealth.com/pt/api/appointments/update-appointment.md) aplicam esta regra, devolvendo `409` com um
`appointment_id` que aponta para a marcação já existente. Trata essa resposta como uma marcação já
existente em vez de um erro para tentar novamente: obtém, reagenda ou cancela a marcação indicada.

O efeito prático é que criações repetidas são seguras. Uma criação que reenvies após um timeout de rede,
ou que um utilizador acione duas vezes, resulta numa única marcação em vez de duas — o que também
significa que nunca precisas de reconciliar marcações duplicadas para o mesmo paciente mais tarde.

> [!NOTE]
>
> As atualizações só são permitidas antes da colheita de sangue — ou seja, enquanto a marcação
> estiver no estado `pending` ou `confirmed`. Assim que a marcação passa para `blood_drawn` ou fica
> `cancelled`, não pode ser modificada. A única exceção é `results_ready_emails`: ainda podes
> alterá-lo isoladamente após a colheita de sangue.

## Cancelar uma marcação

Cancela uma marcação que já não é necessária:

```
DELETE /api/v1/appointments/{id}
```

Isto define o estado da marcação como `cancelled`. A marcação cancelada é devolvida na resposta.

Opcionalmente, envia um `cancellation_reason` (até 500 caracteres) no corpo para registar o motivo.
É guardado na marcação e devolvido como `cancellation_reason` em leituras posteriores.

> [!NOTE]
>
> O cancelamento só é permitido antes da colheita de sangue — ou seja, enquanto a marcação estiver
> no estado `pending` ou `confirmed`. As marcações que já passaram para `blood_drawn` não podem ser
> canceladas.

## Adicionar painéis

Antes de confirmares a colheita de sangue, adiciona os painéis de análises ao sangue que queres realizar chamando:

```
POST /api/v1/appointments/{id}/panels
```

Passa um array de UUIDs de painéis no campo `panel_ids`. Os IDs dos painéis são fornecidos pela Aniva para a tua conta de parceiro.

> [!NOTE]
>
> Os painéis têm de ser adicionados antes da colheita de sangue — ou seja, enquanto a marcação
> estiver no estado `pending` ou `confirmed`. Não podes adicionar nem alterar painéis depois de a
> marcação passar para `blood_drawn`.

## Remover painéis

Se precisares de remover painéis antes da colheita de sangue, chama:

```
DELETE /api/v1/appointments/{id}/panels
```

Passa um array de UUIDs de painéis no campo `panel_ids`. A remoção é idempotente: um painel que não esteja associado é ignorado.

> [!NOTE]
>
> Tal como a adição de painéis, a remoção só é permitida antes da colheita de sangue — ou seja,
> enquanto a marcação estiver no estado `pending` ou `confirmed`. Os painéis não podem ser removidos
> depois de a marcação passar para `blood_drawn`.

## Biomarcadores individuais

Podes associar biomarcadores individuais a uma marcação como análises à la carte, fora de qualquer painel pré-configurado. Isto é útil quando um profissional de saúde quer uma seleção à medida em vez de um pacote pré-definido. Os biomarcadores associados aparecem na resposta da marcação como um array `individual_biomarkers` (ao mesmo nível de `panels`). As decisões de encaminhamento são tomadas a jusante pelo pipeline de logística de pedidos com base nos mapeamentos por laboratório de cada biomarcador.

Adiciona biomarcadores (idempotente — os biomarcadores já associados são mantidos):

```
PATCH /api/v1/appointments/{id}/biomarkers
```

Remove biomarcadores (idempotente — os biomarcadores que não estejam associados são ignorados):

```
DELETE /api/v1/appointments/{id}/biomarkers
```

Ambos os endpoints aceitam um array `biomarker_ids` e validam o conjunto resultante segundo as regras de fecho de cada laboratório — um pedido que não possa ser submetido corretamente (p. ex., um rácio CRP/HDL sem CRP e HDL) devolve `400` com os biomarcadores que terias de adicionar e não guarda nada. Usa [Listar biomarcadores](https://docs.anivahealth.com/pt/api/biomarkers/list-biomarkers.md) para descobrir os IDs dos biomarcadores.

> [!NOTE]
>
> Tal como as alterações de painéis, os biomarcadores individuais só podem ser adicionados ou
> removidos antes da colheita de sangue — ou seja, enquanto a marcação estiver no estado `pending` ou
> `confirmed`. Assim que a marcação passa para `blood_drawn`, o snapshot personalizado fica congelado.

## Pré-visualizar requisitos de recipientes

Depois de adicionares painéis ou biomarcadores individuais, pré-visualiza os recipientes físicos de colheita de espécimes que serão necessários para a recolha da amostra:

```
GET /api/v1/appointments/{id}/preview
```

O array `containers` da resposta inclui o tipo, nome, cor da tampa, volume, número de artigo do fabricante e quantidade de cada recipiente necessário. Isto ajuda os profissionais de saúde a preparar os materiais corretos antes da colheita de sangue. A resposta inclui também um objeto `pricing` — a conta total do carrinho da marcação (as posições aplicadas, os painéis associados e uma linha por biomarcador entregue, com o preço da tua tabela e o preço de retalho ao lado; consulta [Preços](https://docs.anivahealth.com/pt/concepts/pricing.md)), preenchido quando a marcação tem análises associadas e a tua chave tem o scope `prices_view`, caso contrário `null`. De forma intencional, `routing` nunca é exposto e é sempre `null`.

> [!NOTE]
>
> A pré-visualização reflete os painéis e biomarcadores associados no momento. Se adicionares ou
> removeres painéis após a pré-visualização, volta a chamar o endpoint de pré-visualização para
> obteres os requisitos de recipientes atualizados.

## Confirmar a colheita de sangue

Depois da colheita de sangue, submete os códigos de laboratório (códigos de barras dos tubos) para acionar o pipeline de pedidos de laboratório:

```
POST /api/v1/appointments/{id}/confirm
```

Envia `lab_code` quando o mesmo código está impresso em todos os tubos (colheita venosa), ou
`lab_codes` com uma entrada por código — cada uma com os `panel_ids` que abrange — quando cada
painel é colhido nos seus próprios tubos com o seu próprio código (colheita capilar). Cada painel
passa então a ser a sua própria requisição de laboratório sob o respetivo código. Os códigos são
devolvidos como `lab_codes` na marcação.

Numa colheita capilar, a colheita é acondicionada em microtainers. Os painéis vão primeiro, por ordem
de marcação. Os biomarcadores individuais preenchem depois o espaço livre dos microtainers dos
painéis. Quando precisam de mais espaço, abrem novos microtainers. Distribuímo-los de forma uniforme.
Cada microtainer suporta no máximo 150 µl de biomarcadores individuais. As chamadas que alteram
painéis ou biomarcadores respondem `400` quando o conjunto resultante viola esta regra.

Isto altera o estado da marcação para `blood_drawn` e inicia o processamento em laboratório. Esta ação é irreversível.

## Recolha do envio

> [!WARNING]
>
> `POST /api/v1/appointments/pickup` foi **removido**, juntamente com o estado de marcação
> `shipment_picked_up`. Agora responde `405 Method Not Allowed`, porque o caminho cai na rota de
> marcação por ID. O endpoint passou a sua fase final como um no-op que aceitava a chamada e não
> fazia nada, pelo que a sua remoção não altera nenhum comportamento de que dependesses.

Para acompanhares a progressão após a colheita de sangue, segue cada entrada do array `shipments`
inline da marcação até [Obter envio](https://docs.anivahealth.com/pt/api/shipments/get-shipment.md) — cada envio tem o seu próprio
`status` e um histórico `status_updates`.

## Associar envios

Uma marcação pode estar associada a um ou mais envios (e vice-versa — a relação é
de muitos para muitos). O conjunto atual de associações aparece inline em ambos os lados:

* na marcação, como um array `shipments` de entradas `{ id, added_at }`;
* no envio, como um array `appointments` de entradas `{ id, added_at }`.

Ambos os arrays apresentam primeiro a associação mais antiga. Cada `id` remete para o endpoint
canónico de detalhes ([Obter envio](https://docs.anivahealth.com/pt/api/shipments/get-shipment.md) /
[Obter marcação](https://docs.anivahealth.com/pt/api/appointments/get-appointment.md)) para obter o payload completo.

Os envios são associados no momento da criação através do campo `appointment_id` em
[Criar envio](https://docs.anivahealth.com/pt/api/shipments/create-shipment.md). Após a criação, gere as associações a partir do envio
com [Associar marcações ao envio](https://docs.anivahealth.com/pt/api/shipments/attach-appointments-to-shipment.md) e
[Desassociar marcações do envio](https://docs.anivahealth.com/pt/api/shipments/detach-appointments-from-shipment.md); cada um devolve
a lista de marcações após a alteração para esse envio. Para leres na íntegra as encomendas de uma
marcação, usa [Listar envios](https://docs.anivahealth.com/pt/api/shipments/list-shipments.md) com `?appointment_id=`.

A regra de alteração é: as associações podem ser criadas ou removidas quando se verifica QUALQUER UMA das condições

* a marcação já passou pela colheita de sangue (`blood_drawn`), ou
* o envio foi criado há menos de 24 horas.

Fora dessa janela, a associação fica bloqueada para que os registos históricos se mantenham estáveis.

## Obter resultados de laboratório

Assim que o laboratório tiver processado as amostras de sangue, obtém os resultados clínicos e genéticos:

```
GET /api/v1/appointments/{id}/results
```

A resposta inclui análises planeadas (estado `planned`) juntamente com os resultados recebidos, para poderes
acompanhar o que ainda está pendente. O campo `status` de nível superior é `in_progress` até todas as submissões
fecharem, passando depois a `completed` (ou `fault` quando nenhuma reportou) — usa-o para determinar se o
trabalho de laboratório da marcação terminou. Um [webhook](https://docs.anivahealth.com/pt/concepts/webhooks.md) `appointment.results.completed`
avisa-te quando isso acontece, para não precisares de fazer polling. O
array `submissions` detalha isto por requisição de laboratório, cada uma com o seu `lab_code`. Cada
resultado e documento recebido inclui o `lab_code` sob o qual foi registado. Os PDFs dos relatórios de laboratório estão
referenciados no array `documents` — usa `GET /api/v1/documents/{id}` para os transferir.

## Exemplo de marcação

```json theme={null}
{
  "id": "b2c3d4e5-f6a7-8901-bcde-f12345678901",
  "profile_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "location_id": "c3d4e5f6-a7b8-9012-cdef-123456789012",
  "scheduled_at": "2026-04-15T08:30:00Z",
  "status": "confirmed",
  "cancellation_reason": null,
  "results_ready_emails": [],
  "draw_method": "venous",
  "created_at": "2026-04-01T10:00:00Z",
  "updated_at": null,
  "profile": {
    "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    "handle": null,
    "first_name": "Jane",
    "last_name": "Doe",
    "email": "jane.doe@example.com",
    "phone": "+4930123456789",
    "sex": 2,
    "date_of_birth": "1990-06-15",
    "height": 170,
    "weight": 62,
    "language": "en",
    "transactional_emails_enabled": true,
    "created_at": "2026-04-01T09:55:00Z",
    "updated_at": null
  },
  "panels": [
    {
      "panel_id": "f1c2d4a3-7b8e-4f2a-9c1d-2e3f4a5b6c7d",
      "added_at": "2026-04-01T10:05:00Z"
    }
  ],
  "individual_biomarkers": [
    {
      "biomarker_id": 42,
      "added_at": "2026-04-01T10:07:00Z"
    }
  ],
  "shipments": [
    {
      "id": "P2611194821",
      "added_at": "2026-04-15T07:00:00Z"
    }
  ],
  "lab_codes": []
}
```


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