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

# Programa una cita

> Guia pas a pas: troba una ubicació d'anàlisi, consulta la disponibilitat i reserva una cita d'extracció de sang amb l'API d'Aniva.

Fes servir aquesta guia per trobar un centre de proves, crear una cita per a un perfil de pacient i afegir els panells de proves que cal analitzar. Completa aquests passos abans que el pacient arribi a la seva extracció de sang.

**1. Consulta els centres disponibles**

Obtén la llista de centres de proves disponibles al teu compte enviant una petició `GET` a `/api/v1/locations`.

```bash cURL theme={null}
curl --request GET \
  --url https://anivahealth.com/api/v1/locations \
  --header 'x-api-key: YOUR_API_KEY'
```

```javascript JavaScript theme={null}
const response = await fetch('https://anivahealth.com/api/v1/locations', {
  headers: {
    'x-api-key': 'YOUR_API_KEY',
  },
});

const locations = await response.json();
```

La resposta és una matriu d'objectes de centre:

```json theme={null}
[
  {
    "id": "b7e2d914-1c3a-4f08-9e5b-6d0f7a83c421",
    "name": "Aniva Berlin Mitte",
    "company_name": "Aniva GmbH",
    "street": "Friedrichstraße",
    "house_number": "112",
    "address_line_2": null,
    "city": "Berlin",
    "state": "Berlin",
    "postal_code": "10117",
    "country_name": "Germany",
    "country_code": "DE",
    "timezone": "Europe/Berlin",
    "contact_phone": "+4930987654321",
    "email": "berlin-mitte@anivahealth.com",
    "website": "https://anivahealth.com",
    "google_maps_url": null,
    "image_url": null,
    "open_hours": {
      "monday": [{ "open": "08:00", "close": "17:00" }],
      "tuesday": [{ "open": "08:00", "close": "17:00" }],
      "wednesday": [{ "open": "08:00", "close": "17:00" }],
      "thursday": [{ "open": "08:00", "close": "17:00" }],
      "friday": [{ "open": "08:00", "close": "15:00" }],
      "saturday": [],
      "sunday": []
    }
  }
]
```

> [!TIP]
>
> Fes servir el camp `timezone` de l'objecte del centre quan construeixis la marca de temps `scheduled_at`. Convertir l'hora de la cita al fus horari local del centre t'ajuda a evitar programar fora de l'horari d'obertura.

> [!WARNING]
>
> No dedueixis els horaris reservables només a partir de `open_hours`. Crida [Obtén la disponibilitat](https://docs.anivahealth.com/ca/api/locations/get-availability.md) i reserva l'inici d'una franja que retorni — aquesta graella també té en compte les reserves existents, les excepcions per data i l'antelació mínima.

**2. Crea la cita**

Envia una petició `POST` a `/api/v1/appointments` amb l'ID del perfil, l'ID del centre i l'hora desitjada per a la cita. L'hora ha de ser l'inici d'una franja retornada per [Obtén la disponibilitat](https://docs.anivahealth.com/ca/api/locations/get-availability.md).

> [!NOTE]
>
> `scheduled_at` ha de ser una data i hora futura en format ISO 8601, per exemple `2026-05-12T07:30:00Z`. Les marques de temps passades es rebutgen amb un error `400`, igual que les hores dins de l'[antelació mínima de 12 hores](https://docs.anivahealth.com/ca/api/appointments/create-appointment.md#antelacio-minima) als centres gestionats per Aniva.

> [!TIP]
>
> Repetir aquesta petició és segur. Un perfil només pot tenir una cita per centre i hora, de manera que una creació reenviada o duplicada retorna `409` amb l'`appointment_id` existent en lloc de reservar dues vegades per al pacient.

```bash cURL theme={null}
curl --request POST \
  --url https://anivahealth.com/api/v1/appointments \
  --header 'Content-Type: application/json' \
  --header 'x-api-key: YOUR_API_KEY' \
  --data '{
    "profile_id": "a3f1c2e4-58b7-4d9e-b012-3c7f8a2e1d56",
    "location_id": "b7e2d914-1c3a-4f08-9e5b-6d0f7a83c421",
    "scheduled_at": "2026-05-12T07:30:00Z"
  }'
```

```javascript JavaScript theme={null}
const response = await fetch('https://anivahealth.com/api/v1/appointments', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
    'x-api-key': 'YOUR_API_KEY',
  },
  body: JSON.stringify({
    profile_id: 'a3f1c2e4-58b7-4d9e-b012-3c7f8a2e1d56',
    location_id: 'b7e2d914-1c3a-4f08-9e5b-6d0f7a83c421',
    scheduled_at: '2026-05-12T07:30:00Z',
  }),
});

const appointment = await response.json();
```

Una petició correcta retorna `201 Created` amb l'objecte de la cita:

```json theme={null}
{
  "id": "c9d4e827-3b6f-4a1c-8d2e-5f0b9c7e3a12",
  "profile_id": "a3f1c2e4-58b7-4d9e-b012-3c7f8a2e1d56",
  "location_id": "b7e2d914-1c3a-4f08-9e5b-6d0f7a83c421",
  "scheduled_at": "2026-05-12T07:30:00Z",
  "status": "confirmed",
  "cancellation_reason": null,
  "results_ready_emails": [],
  "created_at": "2026-04-01T11:02:47Z",
  "updated_at": null,
  "profile": {
    "id": "a3f1c2e4-58b7-4d9e-b012-3c7f8a2e1d56",
    "handle": null,
    "first_name": "Emma",
    "last_name": "Müller",
    "email": "emma.muller@example.com",
    "phone": null,
    "sex": 2,
    "date_of_birth": "1990-04-15",
    "height": null,
    "weight": null,
    "language": "de",
    "transactional_emails_enabled": null,
    "created_at": "2026-04-01T09:14:22Z",
    "updated_at": null
  },
  "panels": [],
  "individual_biomarkers": [],
  "shipments": [],
  "lab_codes": []
}
```

Desa l'`id` de la cita — el necessitaràs per afegir panells i confirmar l'extracció de sang.

**3. Afegeix panells de proves**

Afegeix els panells de proves que vulguis analitzar a la mostra de sang enviant una petició `POST` a `/api/v1/appointments/{id}/panels`.

Els ID dels panells són UUID. Crida [Llista els panells](https://docs.anivahealth.com/ca/api/panels/list-panels.md) per obtenir els panells que pot demanar la teva clau API.

> [!WARNING]
>
> No es poden afegir panells després d'haver confirmat l'extracció de sang. Afegeix tots els panells necessaris abans de la confirmació — consulta [Confirma l'extracció de sang](https://docs.anivahealth.com/ca/guides/confirm-blood-draw.md) per obtenir-ne més detalls.

```bash cURL theme={null}
curl --request POST \
  --url https://anivahealth.com/api/v1/appointments/c9d4e827-3b6f-4a1c-8d2e-5f0b9c7e3a12/panels \
  --header 'Content-Type: application/json' \
  --header 'x-api-key: YOUR_API_KEY' \
  --data '{
    "panel_ids": [
      "d1f5a302-7c8e-4b2d-9f1a-0e3c6d4b8a27",
      "e2a7b491-5d9f-4c3e-8a2b-1f4d7e5c9b38"
    ]
  }'
```

```javascript JavaScript theme={null}
const response = await fetch(
  'https://anivahealth.com/api/v1/appointments/c9d4e827-3b6f-4a1c-8d2e-5f0b9c7e3a12/panels',
  {
    method: 'POST',
    headers: {
      'Content-Type': 'application/json',
      'x-api-key': 'YOUR_API_KEY',
    },
    body: JSON.stringify({
      panel_ids: [
        'd1f5a302-7c8e-4b2d-9f1a-0e3c6d4b8a27',
        'e2a7b491-5d9f-4c3e-8a2b-1f4d7e5c9b38',
      ],
    }),
  }
);

const result = await response.json();
```

Una petició correcta retorna `200 OK` per confirmar que els panells s'han afegit:

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

## Reprogramació o cancel·lació

Després de crear una cita, encara la pots modificar abans que es confirmi l'extracció de sang:

* **Reprograma o canvia de centre** — Envia una petició `PATCH` a `/api/v1/appointments/{id}` amb els camps que cal actualitzar. Consulta [Actualitza la cita](https://docs.anivahealth.com/ca/api/appointments/update-appointment.md).
* **Cancel·la** — Envia una petició `DELETE` a `/api/v1/appointments/{id}`. Consulta [Cancel·la la cita](https://docs.anivahealth.com/ca/api/appointments/cancel-appointment.md).

> [!NOTE]
>
> Totes dues operacions només estan disponibles 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`, ja no es poden fer
> més modificacions.

## Gestió d'errors

| Estat | Causa | Solució |
| - | - | - |
| `400 Bad Request` | Falta un camp obligatori, `scheduled_at` és al passat, no correspon a la graella de franges o és dins de l'antelació mínima de 12 hores, o `panel_ids` està buit. | Consulta el cos de l'error per veure el missatge de validació i corregeix la petició. Per a l'antelació mínima, tria una franja posterior a [Obtén la disponibilitat](https://docs.anivahealth.com/ca/api/locations/get-availability.md). |
| `403 Forbidden` | La teva clau API no té accés a aquesta operació. | Contacta amb Aniva per confirmar els permisos de la teva clau API. |
| `404 Not Found` | `profile_id` o `location_id` no existeixen, o l'ID de la cita no és vàlid en afegir panells. | Comprova que els ID siguin correctes i pertanyin al teu compte. |
| `409 Conflict` | Has intentat afegir panells o modificar una cita que ja està en estat `blood_drawn` o `cancelled`. | No es poden fer més canvis després de la confirmació. |
| `409 Conflict` | Aquest perfil ja té una cita en aquell centre i a aquella hora, o la franja està completa. | El cas duplicat inclou l'`appointment_id` existent — fes servir aquella cita en lloc de tornar-ho a intentar. Si no, tria una altra franja. |


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