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

# Actualitza una cita

> Modifica els detalls d'una cita abans de l'extracció de sang

Actualitza els detalls d'una cita, com ara l'hora programada o la ubicació de l'anàlisi. Només es poden modificar les cites que encara no tenen confirmada l'extracció de sang.

> [!WARNING]
>
> Les cites no es poden modificar després de confirmar l'extracció de sang ni si ja estan
> cancel·lades. Intentar actualitzar una cita així retorna `409 Conflict`. L'única excepció és
> `results_ready_emails`, que encara pots canviar després de l'extracció de sang.

Requereix l'àmbit `appointments_schedule` o `appointments_manage`.

## Sol·licitud

### Paràmetres de ruta

**id** `string` *required*

Identificador únic (UUID) de la cita que vols actualitzar.

### Paràmetres del cos

Tots els paràmetres del cos són opcionals — inclou només els camps que vulguis canviar.

**scheduled\_at** `string`

Nova data i hora de la cita en format ISO 8601 (p. ex., `2026-05-20T14:00:00Z` o
`2026-05-20T16:00:00+02:00`). **Ha d'incloure un indicador de fus horari** — o bé `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 ser l'inici exacte d'una franja amb capacitat disponible — consulta
[Obtén la disponibilitat](https://docs.anivahealth.com/ca/api/locations/get-availability.md). La cita que es reprograma no compta mai
contra la seva pròpia franja de destinació, però moure-la a una franja on el mateix perfil ja té una
*altra* cita retorna `409` amb l'`appointment_id` d'aquella cita.

Si la ubicació de *destinació* està gestionada per Aniva, la nova hora també ha de ser amb almenys
12 hores d'antelació — consulta [Avís
mínim](https://docs.anivahealth.com/ca/api/appointments/create-appointment.md#antelacio-minima).

**location\_id** `string`

UUID de la nova ubicació de l'anàlisi. La ubicació ha d'existir i estar activa. Utilitza [Llista
les ubicacions](https://docs.anivahealth.com/ca/api/locations/list-locations.md) per trobar els ID de les ubicacions disponibles.

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

Substitueix la llista de fins a 5 adreces que reben un correu electrònic cadascuna quan tots els
resultats del laboratori són definitius. Envia `[]` per desactivar els correus. Aquest camp
continua sent editable després de l'extracció de sang; només una cita cancel·lada el rebutja.
Després de l'extracció de sang, envia'l sol: amb `scheduled_at` o `location_id` al mateix cos, la
sol·licitud retorna `409`. La teva clau necessita accés `results_view` al pacient; si no, retorna
`403`. Consulta [Correus de resultats disponibles](https://docs.anivahealth.com/ca/concepts/results.md#correus-d-avis-de-resultats-a-punt).

**draw\_method** `string | null`

Nou mètode d'extracció: `capillary` o `venous`, o `null` per tornar a utilitzar el
`default_draw_method` de la ubicació. La ubicació ha d'incloure el mètode a `draw_methods`, i les
anàlisis reservades han de ser possibles amb aquest mètode; si no, retorna `400`. Quan mous una
cita a una altra ubicació, s'hi executa la mateixa comprovació: sobre el seu propi `draw_method`
o, si no, sobre el `default_draw_method` de la nova ubicació.

## Resposta

Si té èxit, l'API retorna `200 OK` amb la cita actualitzada i el seu perfil integrat.

**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-20T14:00: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.

**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'última actualització. Pot ser `null`.

**profile** `object` *required*

El perfil del pacient associat a aquesta cita.

**perfil**

**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 a [Crea un perfil](https://docs.anivahealth.com/ca/api/profiles/create-profile.md).

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

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

**created\_at** `string`

Marca de temps ISO 8601 de quan es va crear el perfil.

**updated\_at** `string`

Marca de temps ISO 8601 de l'última actualització del perfil. Pot ser `null`.

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

Panells associats actualment a aquesta cita. Exclou les associacions cancel·lades. Consulta els detalls del panell
(nom, biomarcadors) mitjançant [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 (consulta [Afegeix biomarcadors
personalitzats](https://docs.anivahealth.com/ca/api/appointments/add-individual-biomarkers.md)). Contrasta 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, ordenats pel vincle més antic primer. Matriu buida quan no hi
ha cap enviament vinculat. Consulta cada `id` a [Obtén l'enviament](https://docs.anivahealth.com/ca/api/shipments/get-shipment.md)
per obtenir el contingut complet de l'enviament.

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

## Respostes d'error

| Estat | Descripció |
| - | - |
| `400` | Error de validació — p. ex., `scheduled_at` és en el passat, falten menys de 12 hores en un centre gestionat per Aniva, el format d'UUID no és vàlid, el centre no disposa d'envasos per al `draw_method`, o les proves reservades no es poden fer amb el `draw_method`. |
| `403` | Prohibit — la teva clau d'API no té accés a aquesta operació, la cita o el centre són fora del teu context d'accés, o `results_ready_emails` està definit sense accés `results_view` al pacient. |
| `404` | No s'ha trobat la cita o el centre. |
| `409` | No es pot modificar la cita (l'extracció de sang ja està confirmada o la cita està cancel·lada), la franja horària està completa, el centre està tancat en aquella data, o aquest perfil ja té una altra cita al centre i a l'hora triats (inclou `appointment_id`). |
| `500` | Error intern del servidor. |

```bash cURL theme={null}
curl --request PATCH \
  --url https://anivahealth.com/api/v1/appointments/c9f3e2a1-7d6b-4c5e-b3a2-1f0e9d8c7b6a \
  --header 'x-api-key: YOUR_API_KEY' \
  --header 'Content-Type: application/json' \
  --data '{
    "scheduled_at": "2026-05-20T14:00:00Z",
    "location_id": "d8f3e1a2-4c5b-6d7e-8f9a-0b1c2d3e4f5a"
  }'
```

```json 200 theme={null}
{
  "id": "c9f3e2a1-7d6b-4c5e-b3a2-1f0e9d8c7b6a",
  "profile_id": "a3f1c2d4-8b7e-4f2a-9c1d-2e3f4a5b6c7d",
  "location_id": "d8f3e1a2-4c5b-6d7e-8f9a-0b1c2d3e4f5a",
  "scheduled_at": "2026-05-20T14:00:00Z",
  "status": "confirmed",
  "cancellation_reason": null,
  "results_ready_emails": [],
  "draw_method": "venous",
  "created_at": "2026-04-01T09:45:00Z",
  "updated_at": "2026-04-10T11:30:00Z",
  "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": [
    {
      "panel_id": "f1c2d4a3-7b8e-4f2a-9c1d-2e3f4a5b6c7d",
      "added_at": "2026-04-01T09:50:00Z"
    }
  ],
  "individual_biomarkers": [],
  "shipments": [],
  "lab_codes": []
}
```

```json 409 theme={null}
{
  "error": "Appointment cannot be modified after blood draw has been confirmed"
}
```

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


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