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

# Cites

> Com funcionen les cites d'extracció de sang a l'API d'anàlisis de laboratori d'Aniva: reserva, panells, biomarcadors, canvis d'estat i cancel·lació.

Una cita és una extracció de sang programada per a un perfil de pacient en una ubicació de proves física, feta per un professional sanitari. Els kits enviats per correu a un pacient no són cites — consulta [Comandes de kits de prova a casa](https://docs.anivahealth.com/ca/concepts/home-kit-orders.md).

## Camps

**id** `string` *required*

UUID generat automàticament per Aniva. Fes-lo servir per afegir panells, confirmar l'extracció
de sang i obtenir resultats.

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

L'UUID del perfil al qual pertany aquesta cita.

**location\_id** `string`

L'UUID de la ubicació de proves on es farà l'extracció de sang. Els kits de prova a casa no són
cites — consulta [Comandes de kits de prova a casa](https://docs.anivahealth.com/ca/concepts/home-kit-orders.md).

**scheduled\_at** `string`

Data i hora programades de l'extracció de sang en format ISO 8601. Sempre es retorna com un
instant UTC amb el sufix `Z` (p. ex., `2026-04-15T08:30:00Z`). En crear o actualitzar, el valor
**ha d'incloure un indicador de fus horari** (ja sigui `Z` o un desplaçament explícit com
`+02:00`) — les dates i hores sense fus horari es rebutgen. Ha de ser en el futur i, a les
ubicacions gestionades per Aniva, amb almenys 12 hores d'antelació ([antelació
mínima](https://docs.anivahealth.com/ca/api/appointments/create-appointment.md#antelacio-minima)).

**status** `string` *required*

Estat actual del cicle de vida. Pot ser `pending`, `confirmed`, `blood_drawn` o `cancelled`.
Consulta [Cicle de vida](#cicle-de-vida) més avall. El detall sobre la finalització dels resultats
de laboratori (`in_progress` o `completed`) s'obté a [Obtenir
resultats](https://docs.anivahealth.com/ca/api/appointments/get-results.md); l'evolució més detallada dels enviaments (en trànsit,
lliurat, etc.) s'obté seguint cada entrada de la matriu `shipments` inclosa a [Obtenir
enviament](https://docs.anivahealth.com/ca/api/shipments/get-shipment.md).

**cancellation\_reason** `string`

Motiu en text lliure registrat en cancel·lar la cita (p. ex., absència, cancel·lació tardana,
«Error. Cal repetir»). `null` llevat que `status` sigui `cancelled`.

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

Adreces que reben un correu electrònic cadascuna quan tots els resultats del laboratori són definitius, en minúscules. Buit quan està desactivat. Consulta
[Correus electrònics de resultats a punt](https://docs.anivahealth.com/ca/concepts/results.md#correus-d-avis-de-resultats-a-punt).

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

Com es fa l'extracció de sang: `capillary` (de la punta del dit o de la part superior del braç, en microtubs) o `venous` (de la vena,
en tubs). És el mètode definit a la cita o, si no n'hi ha, el `default_draw_method` de la seva
[ubicació](https://docs.anivahealth.com/ca/concepts/locations.md). Després de l'extracció de sang, és el mètode que s'ha fet servir.

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

Marca de temps ISO 8601 de quan es va crear la cita.

**updated\_at** `string`

Marca de temps ISO 8601 de l'actualització més recent. Nul si la cita no s'ha actualitzat mai.

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

Codis de laboratori (codis de barres dels tubs) registrats a [Confirmar l'extracció de
sang](https://docs.anivahealth.com/ca/api/appointments/confirm-blood-draw.md), en ordre d'escaneig. Buit fins que es confirma
l'extracció. Una extracció venosa té un únic codi imprès a cada tub; una extracció capil·lar té
un codi per microtub. Els resultats i els documents hi fan referència mitjançant `lab_code`.

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

Panells associats a aquesta cita, com a entrades `{ panel_id, added_at }`. Consulta
[Afegir panells](#afegir-panells).

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

Biomarcadors a la carta associats a aquesta cita, com a entrades `{ biomarker_id, added_at }`.
Consulta [Biomarcadors individuals](#biomarcadors-individuals).

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

Enviaments vinculats a aquesta cita, com a entrades `{ id, added_at }`, començant pel vincle més
antic. Consulta [Vincular enviaments](#vincular-enviaments).

**profile** `object` *required*

L'objecte de perfil complet del pacient, inclòs en cada resposta de cita. Els camps següents en
són un subconjunt. [Obtenir cita](https://docs.anivahealth.com/ca/api/appointments/get-appointment.md) els llista tots.

**propietats**

**id** `string`

UUID del perfil associat.

**first\_name** `string`

Nom del pacient.

**last\_name** `string`

Cognom del pacient.

**email** `string`

Adreça electrònica del pacient.

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

Data de naixement en format `YYYY-MM-DD`.

**sex** `integer`

Sexe biològic segons la norma ISO/IEC 5218.

## Cicle de vida

Les cites exposen quatre estats del cicle de vida:

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

| Estat | Significat |
| - | - |
| `pending` | La cita està programada i pendent de confirmació. Es pot [actualitzar](https://docs.anivahealth.com/ca/api/appointments/update-appointment.md) o [cancel·lar](https://docs.anivahealth.com/ca/api/appointments/cancel-appointment.md). |
| `confirmed` | La programació s'ha confirmat (p. ex., per la consulta), però encara no s'ha fet l'extracció de sang. Encara es pot actualitzar o cancel·lar. |
| `blood_drawn` | Els codis de laboratori s'han enviat mitjançant [Confirmar l'extracció de sang](https://docs.anivahealth.com/ca/api/appointments/confirm-blood-draw.md) i s'ha activat el flux de comanda al laboratori. Els panells queden congelats i la cita no es pot reprogramar ni cancel·lar. |
| `cancelled` | La cita s'ha cancel·lat. Estat final — no hi ha més transicions. |

> [!NOTE]
>
> El conjunt d'estats de la cita és intencionadament general — el progrés més detallat s'exposa
> mitjançant endpoints dedicats:
>
> * **Finalització dels resultats de laboratori** →
>   [Obtenir resultats](https://docs.anivahealth.com/ca/api/appointments/get-results.md) — el camp `status` de nivell superior és
>   `in_progress` o `completed`.
> * **Progrés de l'enviament** (en trànsit, lliurat, etc.) → segueix cada entrada de la matriu
>   `shipments` inclosa a la cita cap a [Obtenir enviament](https://docs.anivahealth.com/ca/api/shipments/get-shipment.md) — cada
>   enviament té el seu propi `status` i un registre d'esdeveniments `status_updates`.
>
> Cada canvi d'estat envia un [webhook](https://docs.anivahealth.com/ca/concepts/webhooks.md) `appointment.*`, per exemple
> `appointment.confirmed`. Una nova hora o ubicació envia `appointment.rescheduled`.

> [!WARNING]
>
> Confirmar una cita (passar-la a `blood_drawn`) és **irreversible**. Un cop enviïs el codi o els
> codis de laboratori, s'activa el flux de comanda al laboratori i no es pot desfer. Només es
> permeten actualitzacions i cancel·lacions mentre la cita està en estat `pending` o `confirmed`.

## Llistar cites

Obtén totes les cites accessibles amb la teva clau API:

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

Opcionalment, passa `?profile_id={uuid}` per filtrar per un perfil concret. Sense aquest paràmetre, s'aplica una finestra de temps predeterminada (dels últims 2 mesos fins a 1 mes en el futur).

## Actualitzar una cita

Abans que es confirmi l'extracció de sang, pots reprogramar la cita o canviar la ubicació de proves:

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

Passa qualsevol combinació de `scheduled_at`, `location_id`, `draw_method` i `results_ready_emails` per actualitzar-la. Inclou només els camps que vulguis canviar.

## Mètode d'extracció

Cada cita té un `draw_method`: `capillary` (del dit o de la part superior del braç, en microtubs)
o `venous` (de la vena, en tubs). Només s'aplica a l'extracció de sang. Les mostres d'orina,
d'escovilló i altres mostres que no són de sang es recullen de la mateixa manera amb qualsevol
dels dos mètodes.

Per defecte, és el `default_draw_method` de la ubicació. Defineix `draw_method` en crear o
actualitzar per fer servir un altre mètode, o assigna-li `null` per tornar al valor per defecte de
la ubicació. La ubicació ha d'incloure el mètode a `draw_methods` i les proves reservades s'han de
poder fer amb aquest mètode; si no, la sol·licitud retorna `400`. No el pots canviar després de
l'extracció de sang. Després de l'extracció, `draw_method` és el mètode que s'ha fet servir.

## Una cita per perfil, ubicació i hora

Un perfil pot tenir com a màxim una cita no cancel·lada per cada parell
`(location_id, scheduled_at)` — a una persona no se li pot fer l'extracció dues vegades al mateix
lloc i en el mateix moment, independentment de quantes reserves paral·leles accepti la ubicació.

Tant [Crear cita](https://docs.anivahealth.com/ca/api/appointments/create-appointment.md) com
[Actualitzar cita](https://docs.anivahealth.com/ca/api/appointments/update-appointment.md) apliquen aquesta regla i retornen `409`
amb un `appointment_id` que apunta a la cita que ja existeix. Tracta aquesta resposta com una cita
ja reservada i no com un error que calgui reintentar: obtén, reprograma o cancel·la la cita que
indica.

L'efecte pràctic és que les creacions repetides són segures. Una creació que tornis a enviar després que s'esgoti el temps d'espera de la xarxa,
o que un usuari activi dues vegades, es resol en una sola cita en lloc de dues — i això també vol dir que
no hauràs de conciliar mai reserves duplicades per al mateix pacient a posteriori.

> [!NOTE]
>
> Les actualitzacions només es permeten abans de l'extracció de sang — és a dir, mentre la cita està en estat `pending` o
> `confirmed`. Un cop la cita passa a `blood_drawn` o ha quedat en `cancelled`, no es pot
> modificar. L'única excepció és `results_ready_emails`: encara el pots canviar sol després de
> l'extracció de sang.

## Cancel·lar una cita

Cancel·la una cita que ja no cal:

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

Això canvia l'estat de la cita a `cancelled`. La cita cancel·lada es retorna a la resposta.

Opcionalment, envia un `cancellation_reason` (fins a 500 caràcters) al cos per registrar-ne el motiu. Es
desa a la cita i es retorna com a `cancellation_reason` en lectures posteriors.

> [!NOTE]
>
> La cancel·lació només es permet abans de l'extracció de sang — és a dir, mentre la cita està en estat `pending` o
> `confirmed`. Les cites que ja han passat a `blood_drawn` no es poden cancel·lar.

## Afegir panells

Abans de confirmar l'extracció de sang, afegeix els panells d'anàlisi de sang que vulguis fer cridant:

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

Passa una matriu d'UUID de panells al camp `panel_ids`. Aniva proporciona els ID de panell per al teu compte de col·laborador.

> [!NOTE]
>
> Els panells s'han d'afegir abans de l'extracció de sang — és a dir, mentre la cita està en estat `pending` o
> `confirmed`. No pots afegir ni canviar panells un cop la cita ha passat a
> `blood_drawn`.

## Eliminar panells

Si necessites eliminar panells abans de l'extracció de sang, crida:

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

Passa una matriu d'UUID de panells al camp `panel_ids`. L'eliminació és idempotent: un panell que no estigui vinculat s'ignora.

> [!NOTE]
>
> Igual que afegir panells, eliminar-los només es permet abans de l'extracció de sang — és a dir, mentre la cita està
> en estat `pending` o `confirmed`. Els panells no es poden eliminar un cop la cita ha passat a
> `blood_drawn`.

## Biomarcadors individuals

Pots vincular biomarcadors individuals a una cita com a proves a la carta, fora de qualsevol panell preconfigurat. Això és útil quan un professional vol una selecció a mida en lloc d'un paquet predefinit. Els biomarcadors vinculats apareixen a la resposta de la cita com una matriu `individual_biomarkers` (al mateix nivell que `panels`). Les decisions d'encaminament es prenen posteriorment al flux de logística de comandes segons les correspondències per laboratori de cada biomarcador.

Afegeix biomarcadors (idempotent — els biomarcadors ja vinculats es conserven):

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

Elimina biomarcadors (idempotent — els biomarcadors que no estiguin vinculats s'ignoren):

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

Tots dos endpoints accepten una matriu `biomarker_ids` i validen el conjunt resultant segons les regles de tancament de cada laboratori — una comanda que no es pugui cursar correctament (p. ex., una relació CRP/HDL sense CRP ni HDL) retorna `400` amb els biomarcadors que hauries d'afegir, i no desa res. Fes servir [Llista els biomarcadors](https://docs.anivahealth.com/ca/api/biomarkers/list-biomarkers.md) per descobrir els ID de biomarcador.

> [!NOTE]
>
> Igual que les modificacions de panells, els biomarcadors individuals només es poden afegir o eliminar abans de l'extracció de sang
> — és a dir, mentre la cita està en estat `pending` o `confirmed`. Un cop la cita passa a
> `blood_drawn`, la instantània personalitzada queda congelada.

## Previsualitzar els requisits de contenidors

Després d'afegir panells o biomarcadors individuals, previsualitza els contenidors físics de recollida de mostres que caldran per a la presa de mostres:

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

La matriu `containers` de la resposta inclou el tipus, el nom, el color del tap, el volum, el número d'article del fabricant i la quantitat de cada contenidor necessari. Això ajuda els professionals a preparar el material correcte abans de l'extracció de sang. La resposta també inclou un objecte `pricing` — la factura de tota la cistella de la cita (les posicions que s'han aplicat, els panells vinculats i una fila per cada biomarcador lliurat, amb el preu de la teva tarifa i el preu de venda al públic al costat; consulta [Preus](https://docs.anivahealth.com/ca/concepts/pricing.md)), que s'emplena quan la cita té proves vinculades i la teva clau té l'àmbit `prices_view`; en cas contrari, és `null`. De manera intencionada, `routing` no s'exposa mai i sempre és `null`.

> [!NOTE]
>
> La previsualització reflecteix els panells i biomarcadors vinculats actualment. Si afegeixes o elimines panells
> després de previsualitzar-los, torna a cridar l'endpoint de previsualització per obtenir els requisits de contenidors actualitzats.

## Confirmar l'extracció de sang

Un cop feta l'extracció de sang, envia els codis de laboratori (codis de barres dels tubs) per activar el flux de comandes de laboratori:

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

Envia `lab_code` quan hi ha un sol codi imprès a cada tub (extracció venosa), o `lab_codes` amb una entrada
per codi — cadascuna amb els `panel_ids` que cobreix — quan cada panell s'extreu als seus propis tubs amb
el seu propi codi (extracció capil·lar). Aleshores, cada panell és la seva pròpia sol·licitud de laboratori amb el seu codi. Els
codis es retornen com a `lab_codes` a la cita.

En una extracció capil·lar, l'extracció s'envasa en microtubs. Els panells van primer, per ordre de reserva. Els biomarcadors
individuals omplen després l'espai lliure dels microtubs dels panells. Quan necessiten més espai, obren
nous microtubs. Els repartim de manera uniforme. Cada microtub admet com a màxim 150 µl de biomarcadors
individuals. Les crides que canvien panells o biomarcadors responen amb `400` quan el conjunt resultant incompleix
aquesta regla.

Això canvia l'estat de la cita a `blood_drawn` i inicia el processament al laboratori. Aquesta acció és irreversible.

## Recollida de l'enviament

> [!WARNING]
>
> `POST /api/v1/appointments/pickup` s'ha **eliminat**, juntament amb l'estat de cita
> `shipment_picked_up`. Ara respon `405 Method Not Allowed`, perquè el camí acaba a la
> ruta de cita per ID. L'endpoint va passar la seva fase final com una operació sense efecte que acceptava la crida i
> no feia res, així que eliminar-lo no canvia cap comportament del qual depenguessis.

Per fer el seguiment de l'evolució posterior a l'extracció de sang, segueix cada entrada de la matriu `shipments`
integrada a la cita fins a [Obtén l'enviament](https://docs.anivahealth.com/ca/api/shipments/get-shipment.md) — cada enviament té el seu propi `status`
i un historial `status_updates`.

## Vincular enviaments

Una cita es pot vincular a un o més enviaments (i viceversa — la relació és
de molts a molts). El conjunt actual de vincles apareix integrat a tots dos costats:

* a la cita, com una matriu `shipments` d'entrades `{ id, added_at }`;
* a l'enviament, com una matriu `appointments` d'entrades `{ id, added_at }`.

Totes dues matrius van del vincle més antic al més recent. Cada `id` remet a l'endpoint canònic de detall
([Obtén l'enviament](https://docs.anivahealth.com/ca/api/shipments/get-shipment.md) /
[Obtén la cita](https://docs.anivahealth.com/ca/api/appointments/get-appointment.md)) per obtenir el contingut complet.

Els enviaments es vinculen en el moment de la creació mitjançant el camp `appointment_id` de
[Crea un enviament](https://docs.anivahealth.com/ca/api/shipments/create-shipment.md). Després de crear-los, gestiona els vincles des de l'enviament
amb [Vincula cites a un enviament](https://docs.anivahealth.com/ca/api/shipments/attach-appointments-to-shipment.md) i
[Desvincula cites d'un enviament](https://docs.anivahealth.com/ca/api/shipments/detach-appointments-from-shipment.md); cadascun retorna
la llista de cites posterior a la modificació per a aquell enviament. Per llegir els paquets d'una cita al complet,
fes servir [Llista els enviaments](https://docs.anivahealth.com/ca/api/shipments/list-shipments.md) amb `?appointment_id=`.

La regla de modificació és: els vincles es poden crear o eliminar quan O BÉ

* la cita ja ha passat l'extracció de sang (`blood_drawn`), o
* l'enviament es va crear fa menys de 24 hores.

Fora d'aquest marge, el vincle queda bloquejat perquè els registres històrics es mantinguin estables.

## Recuperació dels resultats de laboratori

Un cop el laboratori hagi processat les mostres de sang, recupera els resultats clínics i genètics:

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

La resposta inclou les proves planificades (estat `planned`) juntament amb els resultats rebuts, perquè
puguis fer el seguiment del que encara està pendent. El camp `status` de nivell superior és
`in_progress` fins que es tanquen totes les trameses, i aleshores passa a `completed` (o `fault` quan
cap no ha informat) — fes-lo servir per determinar si la feina de laboratori de la cita ha acabat.
Un [webhook](https://docs.anivahealth.com/ca/concepts/webhooks.md) `appointment.results.completed` t'avisa quan això passa, de manera
que no cal que facis consultes periòdiques. La matriu `submissions` ho desglossa per petició de
laboratori, cadascuna amb el seu `lab_code`. Cada resultat i document rebut porta el `lab_code` amb
què es va registrar. Els PDF dels informes de laboratori es referencien a la matriu `documents` —
fes servir `GET /api/v1/documents/{id}` per descarregar-los.

## Exemple de cita

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