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

# Crea una cita

> Programa una cita d'extracció de sang per a un perfil en un centre d'anàlisis

Programa una cita d'extracció de sang per a un perfil de pacient en una ubicació de proves concreta. Un cop creada, la cita passa a l'estat `confirmed` per defecte (algunes ubicacions poden fer servir `pending` per defecte — és una configuració específica de cada ubicació). Fes servir [Afegeix panells](https://docs.anivahealth.com/ca/api/appointments/add-panels.md) per associar panells d'anàlisi de sang abans de [confirmar l'extracció de sang](https://docs.anivahealth.com/ca/api/appointments/confirm-blood-draw.md).

> [!NOTE]
>
> Un perfil pot tenir com a màxim **una** cita per ubicació i hora. Crear una cita per a una franja
> que el perfil ja ocupa retorna `409` amb l'`appointment_id` existent en lloc d'una segona cita —
> així una sol·licitud reintentada o repetida per error no pot duplicar mai una reserva. Consulta
> [Cites duplicades](#cites-duplicades).

Envia una capçalera opcional `Idempotency-Key` perquè aquesta creació es pugui reintentar amb seguretat — repetir la mateixa clau retorna la resposta original en lloc de crear-ne una segona. Consulta [Idempotència](https://docs.anivahealth.com/ca/concepts/idempotency.md).

Requereix l'abast `appointments_schedule`.

## Sol·licitud

### Paràmetres del cos

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

UUID del perfil del pacient per al qual es crea la cita.

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

UUID de la ubicació de proves on es farà l'extracció de sang. Fes servir [Llista les
ubicacions](https://docs.anivahealth.com/ca/api/locations/list-locations.md) per trobar els ID d'ubicació disponibles.

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

Data i hora de la cita en format ISO 8601 (p. ex., `2026-05-15T10:30:00Z` o
`2026-05-15T12:30:00+02:00`). **Ha d'incloure un indicador de fus horari** — 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.

Ha de coincidir exactament amb l'inici d'una franja de la graella de la ubicació, i la franja encara
ha de tenir capacitat — consulta [Obtén la disponibilitat](https://docs.anivahealth.com/ca/api/locations/get-availability.md) primer.
Les hores fora de graella retornen `400`; una franja plena retorna `409`. A les ubicacions gestionades
per Aniva també ha de ser amb un mínim de 12 hores d'antelació — consulta
[Antelació mínima](#antelacio-minima).

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

Fins a 5 adreces que reben cadascuna un correu un cop tots els resultats del laboratori són
definitius. El correu enllaça a la pàgina de resultats del panell d'administració d'Aniva. La teva
clau necessita accés `results_view` per al pacient; si no, retorna `403`. Omet-lo per fer servir les
adreces per defecte configurades per al grup del pacient. Una llista buida desactiva els correus.
Consulta [Correus de resultats disponibles](https://docs.anivahealth.com/ca/concepts/results.md#correus-d-avis-de-resultats-a-punt).

**draw\_method** `string`

Com es fa l'extracció de sang: `capillary` o `venous`. Omet-lo per fer servir el
`default_draw_method` de la ubicació. La ubicació ha d'incloure el mètode a `draw_methods`; si no,
retorna `400`.

## Resposta

Si té èxit, l'API retorna `201 Created` amb la nova cita.

**id** `string` *required*

Identificador únic de la cita (UUID).

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

UUID del perfil al qual pertany aquesta cita.

**location\_id** `string`

UUID de la ubicació de proves on es fa l'extracció de sang.

**scheduled\_at** `string`

Data i hora programades de la cita com a instant UTC (ISO 8601 amb el sufix `Z`, p. ex.,
`2026-05-15T10:30:00Z`). Pot ser `null`.

**status** `string` *required*

Estat actual de la cita. Pot ser `pending`, `confirmed`, `blood_drawn` o `cancelled`. El detall de
compleció dels resultats de laboratori s'obté mitjançant [Obtén els resultats](https://docs.anivahealth.com/ca/api/appointments/get-results.md);
el progrés detallat de l'enviament, a partir de cada entrada de la matriu `shipments` inclosa aquí
(més avall) seguida a [Obtén l'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.

**profile** `object` *required*

El perfil del pacient associat a aquesta cita.

**profile**

**id** `string`

Identificador únic del perfil (UUID).

**handle** `string`

Àlies o nom d'usuari del perfil. Pot ser `null`.

**first\_name** `string`

Nom. Pot ser `null`.

**last\_name** `string`

Cognom. Pot ser `null`.

**email** `string`

Adreça electrònica. Pot ser `null`.

**phone** `string`

Número de telèfon en format E.164. Pot ser `null`.

**sex** `integer`

Sexe biològic segons ISO/IEC 5218. Pot ser `null`.

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

Data de naixement en format `YYYY-MM-DD`. Pot ser `null`.

**height** `number`

Alçada en centímetres. Pot ser `null`.

**weight** `number`

Pes en quilograms. Pot ser `null`.

**language** `string`

Idioma preferit: un dels 32 codis de [Crea un perfil](https://docs.anivahealth.com/ca/api/profiles/create-profile.md).

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

Indica si aquest perfil rep correus transaccionals (programàtics). Pot ser `null`.

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

Panells associats actualment a aquesta cita. Buit en cites acabades de crear — associa'ls amb
[Afegeix panells](https://docs.anivahealth.com/ca/api/appointments/add-panels.md). Consulta els detalls dels panells (nom,
biomarcadors) amb [Llista els panells](https://docs.anivahealth.com/ca/api/panels/list-panels.md).

**Camps d'associació del panell**

**panel\_id** `string`

UUID del panell — contrasta'l amb [Llista els panells](https://docs.anivahealth.com/ca/api/panels/list-panels.md).

**added\_at** `string`

Marca de temps ISO 8601 de quan es va associar el panell a aquesta cita per primera vegada.

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

Biomarcadors a la carta associats a aquesta cita fora de qualsevol panell. Buit en cites acabades
de crear — associa'ls amb [Afegeix biomarcadors individuals](https://docs.anivahealth.com/ca/api/appointments/add-individual-biomarkers.md).
Creua cada `biomarker_id` amb [Llista els biomarcadors](https://docs.anivahealth.com/ca/api/biomarkers/list-biomarkers.md) per
obtenir les dades de visualització.

**Camps de biomarcadors individuals**

**biomarker\_id** `integer`

Identificador del biomarcador — contrasta'l amb
[Llista els biomarcadors](https://docs.anivahealth.com/ca/api/biomarkers/list-biomarkers.md).

**added\_at** `string`

Marca de temps ISO 8601 de quan es va associar el biomarcador a aquesta cita per primera vegada.

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

Enviaments vinculats a aquesta cita, primer el vincle més antic. Buit en cites acabades de crear —
vincula'ls amb [Crea un enviament](https://docs.anivahealth.com/ca/api/shipments/create-shipment.md) (amb `appointment_id`) o
[Adjunta cites a un enviament](https://docs.anivahealth.com/ca/api/shipments/attach-appointments-to-shipment.md).

**Camps de vinculació de l'enviament**

**id** `string`

Identificador de referència de l'enviament — contrasta'l amb
[Obtén l'enviament](https://docs.anivahealth.com/ca/api/shipments/get-shipment.md).

**added\_at** `string`

Marca de temps ISO 8601 de quan es va vincular l'enviament a aquesta cita per primera vegada.

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

Codis de laboratori (codis de barres dels tubs) registrats per a aquesta cita, per ordre d'escaneig. Buit fins que es confirmi l'extracció
de sang. Una extracció venosa porta un sol codi imprès a cada tub; una extracció capil·lar porta un
codi per microtub. Els resultats i documents a [Obtén els resultats](https://docs.anivahealth.com/ca/api/appointments/get-results.md) fan referència
a aquests codis mitjançant `lab_code`.

## Antelació mínima

Les cites a les ubicacions gestionades per Aniva s'han de reservar com a mínim amb **12 hores**
d'antelació; reservar dins d'aquest marge retorna `400`. [Obtén la disponibilitat](https://docs.anivahealth.com/ca/api/locations/get-availability.md)
ja exclou aquestes franges, així que tot el que llegeixis d'aquesta graella es pot reservar.

Les ubicacions que gestiones directament no tenen antelació mínima — les reserves per al mateix dia i sense cita prèvia no canvien.

## Cites duplicades

Un perfil pot tenir com a màxim una cita no cancel·lada per ubicació i instant — una persona no pot
fer-se dues extraccions al mateix lloc i al mateix moment, per moltes cadires que tingui la ubicació.

Crear una cita per a una franja que el perfil ja ocupa retorna `409` amb un `appointment_id` que
indica la cita que ja existeix:

```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"
}
```

Gestiona-ho tractant la sol·licitud com si ja s'hagués aplicat: recupera la cita amb
[Obtén la cita](https://docs.anivahealth.com/ca/api/appointments/get-appointment.md), mou-la amb
[Actualitza la cita](https://docs.anivahealth.com/ca/api/appointments/update-appointment.md) o descarta-la amb
[Cancel·la la cita](https://docs.anivahealth.com/ca/api/appointments/cancel-appointment.md). No reintentis la creació — continuarà
retornant `409`.

Això fa que les creacions repetides siguin segures: una sol·licitud que reenviïs després d'un temps
d'espera exhaurit, o un formulari enviat dues vegades, no pot generar dues cites per al mateix
pacient a la mateixa hora.

> [!NOTE]
>
> `appointment_id` només és present al `409` per duplicat. El `409` de capacitat — la franja és
> plena perquè l'ocupen *altres* pacients — retorna només `error`, i en aquest cas la solució
> correcta és triar una altra franja a [Obtén la disponibilitat](https://docs.anivahealth.com/ca/api/locations/get-availability.md).

## Respostes d'error

| Estat | Descripció |
| - | - |
| `400` | Error de validació — p. ex., `scheduled_at` ja ha passat, és d'aquí a menys de 12 hores en una ubicació gestionada per Aniva, no és l'inici exacte d'una franja de la graella de la ubicació o la ubicació no té recipients en estoc per a `draw_method`. |
| `403` | Prohibit — la teva clau API no té accés a aquesta operació, o `results_ready_emails` està definit sense accés `results_view` al pacient. |
| `404` | No s'ha trobat el perfil o la ubicació, o la ubicació està inactiva. |
| `409` | Aquest perfil ja té una cita en aquesta ubicació i hora (inclou `appointment_id`), la franja és plena, la ubicació està tancada en aquesta data, o s'ha reutilitzat `Idempotency-Key` amb un cos diferent o la seva sol·licitud original encara no s'ha completat. |
| `500` | Error intern del 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.