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

# Bokningar

> Så fungerar bokningar för blodprovstagning i Anivas API för labbtester: bokning, paneler, biomarkörer, statusändringar och avbokning.

En bokning är en planerad blodprovstagning för en patientprofil på en fysisk testplats, utförd av vårdpersonal. Kit som skickas med post till en patient är inte bokningar – se [Beställningar av hemtestkit](https://docs.anivahealth.com/sv/concepts/home-kit-orders.md).

## Fält

**id** `string` *required*

UUID som genereras automatiskt av Aniva. Använd det för att lägga till paneler, bekräfta blodprovstagningen och hämta resultat.

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

UUID för den profil som bokningen tillhör.

**location\_id** `string`

UUID för den testplats där blodprovstagningen ska ske. Hemtestkit är inte bokningar – se
[Beställningar av hemtestkit](https://docs.anivahealth.com/sv/concepts/home-kit-orders.md).

**scheduled\_at** `string`

Planerat datum och tid för blodprovstagningen i ISO 8601-format. Returneras alltid som en
UTC-tidpunkt med suffixet `Z` (t.ex. `2026-04-15T08:30:00Z`). Vid skapande / uppdatering **måste
värdet innehålla en tidszonsangivelse** (antingen `Z` eller en uttrycklig förskjutning som
`+02:00`) – datum och tider utan tidszon avvisas. Måste ligga i framtiden, och på platser som drivs
av Aniva minst 12 timmar framåt ([minsta
framförhållning](https://docs.anivahealth.com/sv/api/appointments/create-appointment.md#minsta-framfoerhallning)).

**status** `string` *required*

Aktuell livscykelstatus. Ett av värdena `pending`, `confirmed`, `blood_drawn` eller `cancelled`. Se
[Livscykel](#livscykel) nedan. Detaljstatus för färdiga labbresultat (`in_progress` respektive
`completed`) hämtas från [Hämta resultat](https://docs.anivahealth.com/sv/api/appointments/get-results.md); mer detaljerad
försändelsestatus (på väg, levererad osv.) får du genom att följa varje post i den inbäddade
`shipments`-arrayen till [Hämta försändelse](https://docs.anivahealth.com/sv/api/shipments/get-shipment.md).

**cancellation\_reason** `string`

Orsak i fritext som registrerades när bokningen avbokades (t.ex. uteblivet besök, sen avbokning,
'Misslyckades. Behöver göras om'). `null` om inte `status` är `cancelled`.

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

Adresser som var och en får ett mejl när alla labbresultat är slutgiltiga, i gemener. Tom när funktionen är avstängd. Se
[Mejl när resultat är klara](https://docs.anivahealth.com/sv/concepts/results.md#mejl-naer-resultat-aer-klara).

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

Hur blodet tas: `capillary` (fingertopp eller överarm, i mikrorör) eller `venous` (från ven,
i provrör). Det är metoden som bokningen anger, annars `default_draw_method` för dess
[provtagningsställe](https://docs.anivahealth.com/sv/concepts/locations.md). Efter blodprovstagningen är det den metod som användes.

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

ISO 8601-tidsstämpel för när bokningen skapades.

**updated\_at** `string`

ISO 8601-tidsstämpel för den senaste uppdateringen. Null om bokningen aldrig har uppdaterats.

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

Labbkoder (streckkoder på provrör) som registreras vid [Bekräfta blodprovstagning](https://docs.anivahealth.com/sv/api/appointments/confirm-blood-draw.md),
i skanningsordning. Tom tills blodprovstagningen är bekräftad. En venös blodprovstagning har en kod
tryckt på varje rör; en kapillär blodprovstagning har en kod per mikrorör. Resultat och dokument
refererar till dessa via `lab_code`.

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

Paneler kopplade till den här bokningen, som `{ panel_id, added_at }`-poster. Se
[Lägga till paneler](#laegga-till-paneler).

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

Enskilda biomarkörer kopplade till den här bokningen, som `{ biomarker_id, added_at }`-poster. Se
[Enskilda biomarkörer](#enskilda-biomarkoerer).

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

Försändelser kopplade till den här bokningen, som `{ id, added_at }`-poster, med äldsta kopplingen
först. Se [Koppla försändelser](#koppla-foersaendelser).

**profile** `object` *required*

Det fullständiga profilobjektet för patienten, inbäddat i varje bokningssvar. Fälten nedan är ett
urval. [Hämta bokning](https://docs.anivahealth.com/sv/api/appointments/get-appointment.md) listar alla fält.

**egenskaper**

**id** `string`

UUID för den kopplade profilen.

**first\_name** `string`

Patientens förnamn.

**last\_name** `string`

Patientens efternamn.

**email** `string`

Patientens e-postadress.

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

Födelsedatum i formatet `YYYY-MM-DD`.

**sex** `integer`

Biologiskt kön enligt ISO/IEC 5218.

## Livscykel

Bokningar har fyra livscykeltillstånd:

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

| Status | Betydelse |
| - | - |
| `pending` | Bokningen är planerad och väntar på bekräftelse. Kan [uppdateras](https://docs.anivahealth.com/sv/api/appointments/update-appointment.md) eller [avbokas](https://docs.anivahealth.com/sv/api/appointments/cancel-appointment.md). |
| `confirmed` | Bokningen har bekräftats (t.ex. av mottagningen), men blodprovstagningen har ännu inte genomförts. Kan fortfarande uppdateras eller avbokas. |
| `blood_drawn` | Labbkoderna har skickats in via [Bekräfta blodprovstagning](https://docs.anivahealth.com/sv/api/appointments/confirm-blood-draw.md) och labbeställningsflödet har startats. Paneler är låsta och bokningen kan inte ombokas eller avbokas. |
| `cancelled` | Bokningen har avbokats. Slutstatus – inga fler övergångar. |

> [!NOTE]
>
> Bokningsstatusen är medvetet grovkornig – mer detaljerad status visas via särskilda
> endpoints:
>
> * **Färdiga labbresultat** →
>   [Hämta resultat](https://docs.anivahealth.com/sv/api/appointments/get-results.md) – `status`-fältet på toppnivå är `in_progress` eller
>   `completed`.
> * **Försändelsestatus** (på väg, levererad osv.) → följ varje post i den inbäddade
>   `shipments`-arrayen på bokningen till [Hämta försändelse](https://docs.anivahealth.com/sv/api/shipments/get-shipment.md) – varje
>   försändelse har sin egen `status` och en `status_updates`-händelselogg.
>
> Varje statusändring skickar en `appointment.*`-[webhook](https://docs.anivahealth.com/sv/concepts/webhooks.md), till exempel
> `appointment.confirmed`. En ny tid eller plats skickar `appointment.rescheduled`.

> [!WARNING]
>
> Att bekräfta en bokning (ändra den till `blood_drawn`) är **oåterkalleligt**. När du har skickat
> in labbkod(er) startas labbeställningsflödet och det kan inte ångras. Uppdateringar och
> avbokningar är bara tillåtna medan bokningen har statusen `pending` eller `confirmed`.

## Lista bokningar

Hämta alla bokningar som din API-nyckel har åtkomst till:

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

Skicka eventuellt med `?profile_id={uuid}` för att filtrera på en specifik profil. Utan den här parametern används ett standardtidsfönster (de senaste 2 månaderna till 1 månad framåt).

## Uppdatera en bokning

Innan blodprovstagningen har bekräftats kan du boka om tiden eller byta testplats:

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

Skicka med valfri kombination av `scheduled_at`, `location_id`, `draw_method` och `results_ready_emails` för att uppdatera. Inkludera bara de fält du vill ändra.

## Provtagningsmetod

Varje bokning har en `draw_method`: `capillary` (fingertopp eller överarm, i mikrorör) eller
`venous` (från ven, i provrör). Den gäller bara själva blodprovstagningen. Urinprov, pinnprov och andra
prover som inte är blodprover tas på samma sätt oavsett metod.

Som standard används platsens `default_draw_method`. Ange `draw_method` vid skapande eller uppdatering för att
använda en annan metod, eller sätt värdet till `null` för att återgå till platsens standard. Platsen måste
lista metoden i `draw_methods`, och de bokade testerna måste kunna tas med den, annars returnerar
förfrågan `400`. Du kan inte ändra den efter blodprovstagningen. Efter blodprovstagningen visar `draw_method`
vilken metod som användes.

## En bokning per profil, plats och tid

En profil kan högst ha en icke-avbokad bokning per `(location_id, scheduled_at)`-par – en
person kan inte lämna blodprov två gånger på samma plats vid samma tidpunkt, oavsett hur många parallella bokningar
platsen tar emot.

Både [Skapa bokning](https://docs.anivahealth.com/sv/api/appointments/create-appointment.md) och
[Uppdatera bokning](https://docs.anivahealth.com/sv/api/appointments/update-appointment.md) tillämpar detta och returnerar `409` med ett
`appointment_id` som pekar på den bokning som redan finns. Hantera det svaret som att bokningen redan
finns snarare än ett fel som ska försökas igen: hämta, boka om eller avboka den angivna bokningen.

Den praktiska effekten är att upprepade create-anrop är säkra. Ett create-anrop du skickar igen efter en nätverkstimeout,
eller som en användare utlöser två gånger, blir till en enda bokning i stället för två – vilket också innebär att du
aldrig behöver reda ut dubblettbokningar för samma patient i efterhand.

> [!NOTE]
>
> Uppdateringar är bara tillåtna före blodprovstagningen – alltså medan bokningen har status
> `pending` eller `confirmed`. När bokningen har gått över till `blood_drawn` eller är `cancelled`
> kan den inte ändras. Det enda undantaget är `results_ready_emails`: du kan fortfarande ändra
> enbart det efter blodprovstagningen.

## Avboka en bokning

Avboka en bokning som inte längre behövs:

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

Detta sätter bokningens status till `cancelled`. Den avbokade bokningen returneras i svaret.

Du kan valfritt skicka med `cancellation_reason` (upp till 500 tecken) i anropets body för att ange orsaken. Den
sparas på bokningen och returneras som `cancellation_reason` vid senare läsningar.

> [!NOTE]
>
> Avbokning är bara tillåten före blodprovstagningen – alltså medan bokningen har status `pending`
> eller `confirmed`. Bokningar som redan har gått över till `blood_drawn` kan inte avbokas.

## Lägga till paneler

Innan du bekräftar blodprovstagningen lägger du till de blodprovspaneler du vill köra genom att anropa:

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

Skicka en array med panel-UUID:er i fältet `panel_ids`. Panel-ID:n får du från Aniva för ditt partnerkonto.

> [!NOTE]
>
> Paneler måste läggas till före blodprovstagningen – alltså medan bokningen har status `pending`
> eller `confirmed`. Du kan inte lägga till eller ändra paneler när bokningen väl har gått över
> till `blood_drawn`.

## Ta bort paneler

Om du behöver ta bort paneler före blodprovstagningen, anropa:

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

Skicka en array med panel-UUID:er i fältet `panel_ids`. Borttagningen är idempotent: en panel som inte är kopplad ignoreras.

> [!NOTE]
>
> Precis som tillägg av paneler är borttagning bara tillåten före blodprovstagningen – alltså medan
> bokningen har status `pending` eller `confirmed`. Paneler kan inte tas bort när bokningen har
> gått över till `blood_drawn`.

## Enskilda biomarkörer

Du kan koppla enskilda biomarkörer till en bokning som fristående tester, utanför en färdig panel. Det är användbart när en behandlare vill ha ett skräddarsytt urval i stället för ett fördefinierat paket. De kopplade biomarkörerna syns i svaret för bokningen som en `individual_biomarkers`-array (på samma nivå som `panels`). Routingbeslut fattas längre fram i order- och logistikflödet utifrån varje biomarkörs mappning per laboratorium.

Lägg till biomarkörer (idempotent – biomarkörer som redan är kopplade behålls):

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

Ta bort biomarkörer (idempotent – biomarkörer som inte är kopplade ignoreras):

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

Båda endpoints tar en `biomarker_ids`-array och validerar den resulterande uppsättningen mot varje laboratoriums beroenderegler – en beställning som inte kan läggas på ett giltigt sätt (t.ex. en CRP/HDL-kvot utan CRP och HDL) returnerar `400` med de biomarkörer du behöver lägga till, och sparar ingenting. Använd [Lista biomarkörer](https://docs.anivahealth.com/sv/api/biomarkers/list-biomarkers.md) för att hitta biomarkör-ID:n.

> [!NOTE]
>
> Precis som ändringar av paneler kan enskilda biomarkörer bara läggas till eller tas bort före
> blodprovstagningen – alltså medan bokningen har status `pending` eller `confirmed`. När bokningen
> går över till `blood_drawn` fryses den anpassade snapshoten.

## Förhandsgranska krav på behållare

När du har lagt till paneler eller enskilda biomarkörer, förhandsgranska de fysiska provtagningsbehållare som behövs för provtagningen:

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

Svarets `containers`-array innehåller typ, namn, korkfärg, volym, tillverkarens artikelnummer och antal för varje behållare som krävs. Det hjälper behandlare att förbereda rätt material före blodprovstagningen. Svaret innehåller också ett `pricing`-objekt – bokningens samlade prisunderlag (de poster som aktiverades, de kopplade panelerna och en rad per levererad biomarkör, prissatt enligt din prislista med ordinarie pris bredvid; se [Prissättning](https://docs.anivahealth.com/sv/concepts/pricing.md)), som fylls i när bokningen har kopplade tester och din nyckel har scopet `prices_view`, annars `null`. `routing` exponeras medvetet aldrig och är alltid `null`.

> [!NOTE]
>
> Förhandsgranskningen återspeglar de paneler och biomarkörer som är kopplade just nu. Om du lägger
> till eller tar bort paneler efter förhandsgranskningen anropar du förhandsgransknings-endpointen
> igen för att få uppdaterade krav på behållare.

## Bekräfta blodprovstagningen

Efter blodprovstagningen skickar du in labbkoderna (rörens streckkoder) för att starta orderflödet till laboratoriet:

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

Skicka `lab_code` när en och samma kod är tryckt på varje rör (venös blodprovstagning), eller `lab_codes` med en post
per kod – var och en med de `panel_ids` den täcker – när varje panel tas i egna rör med
egen kod (kapillär blodprovstagning). Varje panel blir då en egen laboratorieremiss under sin kod.
Koderna returneras som `lab_codes` på bokningen.

Vid en kapillär blodprovstagning fördelas provet i mikrorör. Paneler kommer först, i bokningsordning. Enskilda
biomarkörer fyller sedan det lediga utrymmet i panelernas mikrorör. När de behöver mer plats öppnas
nya mikrorör. Vi fördelar dem jämnt. Varje mikrorör rymmer högst 150 µl av enskilda
biomarkörer. De anrop som ändrar paneler eller biomarkörer svarar med `400` när den resulterande uppsättningen bryter mot
den här regeln.

Detta ändrar bokningens status till `blood_drawn` och startar bearbetningen på laboratoriet. Åtgärden kan inte ångras.

## Upphämtning av försändelse

> [!WARNING]
>
> `POST /api/v1/appointments/pickup` har **tagits bort**, tillsammans med bokningsstatusen
> `shipment_picked_up`. Den svarar nu med `405 Method Not Allowed`, eftersom sökvägen faller igenom
> till routen för bokning per ID. Endpointen fungerade under sin sista fas som en no-op som tog emot
> anropet utan att göra något, så borttagningen ändrar inget beteende som du förlitade dig på.

För att spåra förloppet efter blodprovstagningen följer du varje post i bokningens inbäddade `shipments`-array
till [Hämta försändelse](https://docs.anivahealth.com/sv/api/shipments/get-shipment.md) – varje försändelse har sin egen `status`
och en `status_updates`-historik.

## Koppla försändelser

En bokning kan kopplas till en eller flera försändelser (och vice versa – relationen är
många-till-många). De aktuella kopplingarna visas inbäddat på båda sidor:

* på bokningen, som en `shipments`-array med `{ id, added_at }`-poster;
* på försändelsen, som en `appointments`-array med `{ id, added_at }`-poster.

Båda arrayerna har den äldsta kopplingen först. Varje `id` hänvisar till den kanoniska detalj-endpointen
([Hämta försändelse](https://docs.anivahealth.com/sv/api/shipments/get-shipment.md) /
[Hämta bokning](https://docs.anivahealth.com/sv/api/appointments/get-appointment.md)) för hela payloaden.

Försändelser kopplas när de skapas via fältet `appointment_id` i
[Skapa försändelse](https://docs.anivahealth.com/sv/api/shipments/create-shipment.md). Efter skapandet hanterar du kopplingar från försändelsen
med [Koppla bokningar till försändelse](https://docs.anivahealth.com/sv/api/shipments/attach-appointments-to-shipment.md) och
[Koppla bort bokningar från försändelse](https://docs.anivahealth.com/sv/api/shipments/detach-appointments-from-shipment.md); båda returnerar
försändelsens bokningslista efter ändringen. För att läsa en boknings paket i sin helhet
använder du [Lista försändelser](https://docs.anivahealth.com/sv/api/shipments/list-shipments.md) med `?appointment_id=`.

Ändringsregeln är: kopplingar kan skapas eller tas bort när ANTINGEN

* bokningen har passerat blodprovstagning (`blood_drawn`), eller
* försändelsen skapades för mindre än 24 timmar sedan.

Utanför det fönstret är kopplingen låst så att historiska poster förblir stabila.

## Hämta labbresultat

När labbet har analyserat blodproverna hämtar du kliniska och genetiska resultat:

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

Svaret innehåller planerade tester (status `planned`) tillsammans med mottagna resultat, så att du kan
följa vad som fortfarande väntar. Fältet `status` på toppnivå är `in_progress` tills varje inlämning
avslutas, därefter `completed` (eller `fault` om ingen av dem rapporterade) — använd detta för att avgöra om
bokningens labbarbete är klart. En [webhook](https://docs.anivahealth.com/sv/concepts/webhooks.md) för `appointment.results.completed`
meddelar dig när det sker, så du behöver inte polla. Arrayen
`submissions` delar upp detta per laboratorieremiss, var och en med sin `lab_code`. Varje
mottaget resultat och dokument har den `lab_code` det registrerades under. PDF-filer med labbrapporter
refereras i arrayen `documents` — använd `GET /api/v1/documents/{id}` för att ladda ner dem.

## Exempel på bokning

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