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

# Termin vereinbaren

> Schritt-für-Schritt-Anleitung: Finde einen Teststandort, prüfe die Verfügbarkeit und buche einen Blutabnahmetermin mit der Aniva API.

Mit dieser Anleitung findest du einen Teststandort, erstellst einen Termin für ein Patientenprofil und fügst die gewünschten Test-Panels hinzu. Schließe diese Schritte ab, bevor der Patient zur Blutabnahme erscheint.

**1. Verfügbare Standorte durchsuchen**

Rufe die Liste der für dein Konto verfügbaren Teststandorte mit einer `GET`-Anfrage an `/api/v1/locations` ab.

```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();
```

Die Antwort ist ein Array aus Standortobjekten:

```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]
>
> Nutze das Feld `timezone` aus dem Standortobjekt, wenn du deinen `scheduled_at`-Zeitstempel erstellst. Wenn du die Terminzeit in die lokale Zeitzone des Standorts umrechnest, vermeidest du Buchungen außerhalb der Öffnungszeiten.

> [!WARNING]
>
> Leite buchbare Zeiten nicht allein aus `open_hours` ab. Rufe [Verfügbarkeit abrufen](https://docs.anivahealth.com/de/api/locations/get-availability.md) auf und buche eine dort zurückgegebene Startzeit – dieses Raster berücksichtigt auch bestehende Buchungen, Ausnahmen für einzelne Tage und die Mindestvorlaufzeit.

**2. Termin erstellen**

Sende eine `POST`-Anfrage an `/api/v1/appointments` mit der Profil-ID, der Standort-ID und deiner gewünschten Terminzeit. Die Zeit muss eine Startzeit aus [Verfügbarkeit abrufen](https://docs.anivahealth.com/de/api/locations/get-availability.md) sein.

> [!NOTE]
>
> `scheduled_at` muss ein künftiger Zeitpunkt im ISO-8601-Format sein, zum Beispiel `2026-05-12T07:30:00Z`. Zeitstempel in der Vergangenheit werden mit einem `400`-Fehler abgelehnt, ebenso Zeiten innerhalb der [12-stündigen Mindestvorlaufzeit](https://docs.anivahealth.com/de/api/appointments/create-appointment.md#mindestvorlaufzeit) an von Aniva betriebenen Standorten.

> [!TIP]
>
> Du kannst diese Anfrage sicher wiederholen. Ein Profil kann pro Standort und Uhrzeit nur einen Termin haben, daher gibt eine erneut oder doppelt gesendete Anfrage `409` mit der bestehenden `appointment_id` zurück, statt den Patienten doppelt zu buchen.

```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();
```

Eine erfolgreiche Anfrage gibt `201 Created` mit dem Terminobjekt zurück:

```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": []
}
```

Speichere die Termin-`id` – du brauchst sie, um Panels hinzuzufügen und die Blutabnahme zu bestätigen.

**3. Test-Panels hinzufügen**

Füge die Test-Panels hinzu, die für die Blutprobe durchgeführt werden sollen, indem du eine `POST`-Anfrage an `/api/v1/appointments/{id}/panels` sendest.

Panel-IDs sind UUIDs. Rufe [Panels auflisten](https://docs.anivahealth.com/de/api/panels/list-panels.md) auf, um die Panels abzurufen, die dein API-Key bestellen kann.

> [!WARNING]
>
> Nach der Bestätigung der Blutabnahme können keine Panels mehr hinzugefügt werden. Füge alle benötigten Panels vor der Bestätigung hinzu – Details findest du unter [Blutabnahme bestätigen](https://docs.anivahealth.com/de/guides/confirm-blood-draw.md).

```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();
```

Eine erfolgreiche Anfrage gibt `200 OK` zurück und bestätigt, dass die Panels hinzugefügt wurden:

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

## Verschieben oder stornieren

Nach dem Erstellen kannst du einen Termin noch ändern, bevor die Blutabnahme bestätigt wird:

* **Verschieben oder Standort ändern** – Sende eine `PATCH`-Anfrage an `/api/v1/appointments/{id}` mit den zu ändernden Feldern. Siehe [Termin aktualisieren](https://docs.anivahealth.com/de/api/appointments/update-appointment.md).
* **Stornieren** – Sende eine `DELETE`-Anfrage an `/api/v1/appointments/{id}`. Siehe [Termin stornieren](https://docs.anivahealth.com/de/api/appointments/cancel-appointment.md).

> [!NOTE]
>
> Beide Vorgänge sind nur vor der Blutabnahme möglich – also solange der Termin den Status
> `pending` oder `confirmed` hat. Sobald der Termin auf `blood_drawn` wechselt, sind keine
> weiteren Änderungen mehr möglich.

## Fehlerbehandlung

| Status | Ursache | Lösung |
| - | - | - |
| `400 Bad Request` | Ein Pflichtfeld fehlt, `scheduled_at` liegt in der Vergangenheit, nicht im Zeitraster oder innerhalb der 12-stündigen Mindestvorlaufzeit, oder `panel_ids` ist leer. | Prüfe den Fehler-Body auf die Validierungsmeldung und korrigiere die Anfrage. Bei der Mindestvorlaufzeit wähle ein späteres Zeitfenster aus [Verfügbarkeit abrufen](https://docs.anivahealth.com/de/api/locations/get-availability.md). |
| `403 Forbidden` | Dein API-Key hat keinen Zugriff auf diesen Vorgang. | Kontaktiere Aniva, um die Berechtigungen deines API-Keys bestätigen zu lassen. |
| `404 Not Found` | Die `profile_id` oder `location_id` existiert nicht oder die Termin-ID ist beim Hinzufügen von Panels ungültig. | Prüfe, ob die IDs korrekt sind und zu deinem Konto gehören. |
| `409 Conflict` | Du hast versucht, Panels hinzuzufügen oder einen Termin zu ändern, der bereits `blood_drawn` oder `cancelled` ist. | Nach der Bestätigung sind keine weiteren Änderungen mehr möglich. |
| `409 Conflict` | Dieses Profil hat bereits einen Termin an diesem Standort und zu dieser Uhrzeit, oder das Zeitfenster ist ausgebucht. | Bei einem Duplikat enthält die Antwort die bestehende `appointment_id` – nutze diesen Termin, statt es erneut zu versuchen. Wähle andernfalls ein anderes Zeitfenster. |


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