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

# Confirmar colheita de sangue

> Registar que a colheita de sangue foi feita e acionar o fluxo de pedido laboratorial

Regista que uma colheita de sangue foi concluída e aciona o fluxo de pedidos ao laboratório. Envia os códigos de laboratório (códigos de barras dos tubos) do kit de colheita de sangue para associar as amostras físicas à marcação.

Uma colheita de sangue tem os seus códigos de uma de duas formas:

* **Um código para toda a colheita** — uma colheita venosa, em que o mesmo código de barras está impresso em todos os tubos. Envia-o em `lab_code`.
* **Um código por microtubo** — uma colheita capilar, em que cada microtubo tem o seu próprio código de barras. Envia-os em `lab_codes`, uma entrada por código com os `panel_ids` que esse microtubo contém. Cada código torna-se a sua própria requisição laboratorial — o código de barras no tubo é o número de pedido do laboratório. Uma entrada sem `panel_ids` é uma entrada geral para todos os painéis não indicados noutras entradas. Uma colheita venosa tem, no máximo, uma.

Envia exatamente um dos dois. Cada painel associado tem de ficar sob exatamente um código (a sua própria entrada ou a entrada geral). Numa colheita venosa, os biomarcadores avulsos precisam da entrada geral. Numa colheita capilar, indica cada painel no código do respetivo microtubo. Os biomarcadores avulsos preenchem o espaço livre dos microtubos dos painéis e só abrem novos microtubos quando necessário. Distribuímo-los uniformemente. Cada microtubo comporta no máximo 150 µl destes biomarcadores. Envia uma entrada sem `panel_ids` por cada microtubo de que precisem só para si, e não mais. Um código que fique sem nenhum painel nem biomarcador é recusado com `409` e `reason: "panel_coverage"`. Todos os códigos são validados antes de qualquer escrita; se algum código não puder ser utilizado ou algum painel ficar por cobrir, nada é registado e a resposta indica o problema.

Requer o âmbito `appointments_schedule`, `appointments_manage` ou `appointments_operate`.

> [!WARNING]
>
> Esta ação é irreversível. Depois de confirmares a colheita de sangue, a marcação fica bloqueada — não são
> possíveis mais alterações, incluindo adicionar painéis.

## Pedido

### Parâmetros de caminho

**id** `string` *required*

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

### Parâmetros do corpo

**lab\_code** `string`

Código numérico de laboratório impresso no kit de colheita de sangue, quando um código abrange todos os tubos. Mutuamente
exclusivo com `lab_codes`.

**lab\_codes** `object[]`

Todos os códigos de laboratório da colheita, por ordem de leitura (pelo menos uma entrada). Mutuamente exclusivo com `lab_code`. Um
código só pode aparecer uma vez; um painel só pode ser indicado numa única entrada.

**entrada de código de laboratório**

**lab\_code** `string` *required*

Código numérico de laboratório impresso nos tubos destes painéis.

**panel\_ids** `string[]`

Os painéis associados cujos tubos têm este código — valores `panel_id` do campo `panels`
da marcação. Omite ou envia `[]` para a entrada geral que abrange todos os painéis não indicados noutras entradas, mais
os biomarcadores avulsos. Uma colheita venosa tem, no máximo, uma entrada geral. Numa colheita capilar, uma entrada geral
contém apenas biomarcadores avulsos e envias uma por cada microtubo de que precisem.

## Resposta

Em caso de sucesso, a API devolve `200 OK` a confirmar que o fluxo de pedidos ao laboratório foi acionado.

**success** `boolean`

`true` quando a colheita de sangue foi registada e o fluxo de pedidos ao laboratório foi acionado.

**warning** `string`

Presente apenas quando a colheita de sangue foi registada num dia diferente do dia da marcação.
As chaves comuns não o podem fazer — recebem um `409` com `reason: "appointment_not_today"`.
Reagenda a marcação para o dia da colheita e depois confirma.

Os códigos registados são devolvidos como `lab_codes` em [Obter marcação](https://docs.anivahealth.com/pt/api/appointments/get-appointment.md), e cada resultado e documento em [Obter resultados](https://docs.anivahealth.com/pt/api/appointments/get-results.md) inclui o `lab_code` com que foi arquivado.

## Respostas de erro

| Estado | Descrição |
| - | - |
| `400` | Erro de validação — nenhum ou ambos os campos `lab_code` e `lab_codes` foram fornecidos, um código não é numérico, ou um código ou painel está repetido. |
| `403` | Proibido — a tua chave de API não tem acesso a esta operação. |
| `404` | Marcação não encontrada. |
| `409` | Um código não pode ser utilizado (`reason`: `unregistered`, `already_assigned`, `home_kit_code`, `location_unknown`, `cross_location`), um painel fica sem código, um `panel_id` não está associado, uma colheita venosa tem duas entradas sem `panel_ids`, uma colheita capilar tem mais entradas do que microtubos ou mais entradas sem `panel_ids` do que microtubos apenas para marcadores, ou um código capilar não corresponde aos respetivos microtubos (todos `panel_coverage`), um código registado antes de uma reposição indica agora outros painéis (`remapped`) ou tem de permanecer nesta colheita porque o laboratório pode ter o respetivo pedido (`sent_to_lab`, `order_in_flight`), um código indica um painel que não está previsto na marcação (`unknown_panel`), ou a marcação não pode ser confirmada (`appointment_cancelled`, `appointment_already_drawn`, `appointment_not_ready`, `appointment_not_today`). `lab_code` indica o código em causa quando existe um código com erro. |
| `500` | Erro interno do servidor. |

```bash cURL (one code, every tube) theme={null}
curl --request POST \
  --url https://anivahealth.com/api/v1/appointments/c9f3e2a1-7d6b-4c5e-b3a2-1f0e9d8c7b6a/confirm \
  --header 'x-api-key: YOUR_API_KEY' \
  --header 'Content-Type: application/json' \
  --data '{
    "lab_code": "7642001234"
  }'
```

```bash cURL (one code per panel) theme={null}
curl --request POST \
  --url https://anivahealth.com/api/v1/appointments/c9f3e2a1-7d6b-4c5e-b3a2-1f0e9d8c7b6a/confirm \
  --header 'x-api-key: YOUR_API_KEY' \
  --header 'Content-Type: application/json' \
  --data '{
    "lab_codes": [
      { "lab_code": "7642001234", "panel_ids": ["f1c2d4a3-7b8e-4f2a-9c1d-2e3f4a5b6c7d"] },
      { "lab_code": "7642001235", "panel_ids": ["0a9b8c7d-6e5f-4a3b-2c1d-0e9f8a7b6c5d"] }
    ]
  }'
```

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

```json 400 theme={null}
{
  "error": "lab_codes: Provide exactly one of `lab_code` or `lab_codes`"
}
```

```json 404 theme={null}
{
  "error": "Appointment not found"
}
```

```json 409 theme={null}
{
  "error": "This barcode has already been assigned to another patient. Please use a different tube.",
  "reason": "already_assigned",
  "lab_code": "7642001235"
}
```

```json 409 (capillary empty code) theme={null}
{
  "error": "Barcode 7642001236 carries no panel and no biomarker.",
  "reason": "panel_coverage",
  "lab_code": null
}
```

```json 409 (cancelled) theme={null}
{
  "error": "This appointment was cancelled, so a blood draw can’t be recorded for it. Reactivate the appointment first if this is a mistake.",
  "reason": "appointment_cancelled",
  "lab_code": "7642001234"
}
```

```json 409 (wrong day) theme={null}
{
  "error": "Recording a blood draw is only available on the appointment day (Oct 13, 2026). Reschedule the appointment to today, then confirm.",
  "reason": "appointment_not_today",
  "lab_code": null
}
```


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